[elpa] externals/auctex 4eaed332ba 26/48: Add new hooks for inserting environments with arguments

[Tassilo Horn]

branch: externals/auctex
commit 4eaed332ba600d8fc90d2177815597e9407c3f2b
Author: Arash Esbati <arash@gnu.org>
Commit: Arash Esbati <arash@gnu.org>

    Add new hooks for inserting environments with arguments
    
    * doc/auctex.texi (Adding Environments): Document new functions
    `LaTeX-env-item-args' and `LaTeX-env-label-args'.
    
    * latex.el (LaTeX--env-parse-args, LaTeX--env-item): New helper
    functions which contain body used be part of `LaTeX-env-args' and
    `LaTeX-env-item'.
    (LaTeX-env-item, LaTeX-env-args): Use new helpers.
    (LaTeX-env-item-args, LaTeX-env-label-args): New functions like
    their counterparts without '-args' but allowing additional
    arguments.
    
    * latex.el (LaTeX-completion-parse-args): Recognize new functions.
---
 doc/auctex.texi | 17 +++++++++++++++++
 latex.el        | 46 +++++++++++++++++++++++++++++++++++-----------
 2 files changed, 52 insertions(+), 11 deletions(-)

diff --git a/doc/auctex.texi b/doc/auctex.texi
index 682e4ed86c..f281352d24 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -5650,6 +5650,19 @@ Following is a list of available hooks for
 @item LaTeX-env-item
 Insert the given environment and the first item.
 
+@item LaTeX-env-item-args
+Insert the given environment plus further arguments, and the first item.
+You can use this as a hook in case you want to specify multiple complex
+arguments just like in elements of @code{TeX-add-symbols}.  Here is an
+example from @file{enumitem.el} in order to prompt for a @samp{key=value}
+list to be inserted as an optional argument to the @samp{itemize}
+environment:
+@lisp
+(LaTeX-add-environments
+    '("itemize" LaTeX-env-item-args
+      [TeX-arg-key-val (LaTeX-enumitem-key-val-options)]))
+@end lisp
+
 @item LaTeX-env-figure
 Insert the given figure-like environment with a caption and a label.
 
@@ -5660,6 +5673,10 @@ specifications.
 @item LaTeX-env-label
 Insert the given environment with a label.
 
+@item LaTeX-env-label-args
+Insert the given environment with a label and further arguments to the
+environment.
+
 @item LaTeX-env-list
 Insert the given list-like environment, a specifier for the label and
 the first item.
diff --git a/latex.el b/latex.el
index e096603b4e..9bb5e005c5 100644
--- a/latex.el
+++ b/latex.el
@@ -1061,9 +1061,18 @@ If nil, act like the empty string is given, but do not 
prompt."
   :group 'LaTeX-label
   :type 'string)
 
-(defun LaTeX-env-item (environment)
-  "Insert ENVIRONMENT and the first item."
-  (LaTeX-insert-environment environment)
+(defun LaTeX--env-parse-args (args)
+  "Helper function to insert arguments defined by ARGS."
+  (save-excursion
+    (LaTeX-find-matching-begin)
+    (end-of-line)
+    (let ((TeX-exit-mark (or TeX-exit-mark
+                             (make-marker))))
+      (TeX-parse-arguments args))))
+
+(defun LaTeX--env-item (environment)
+  "Helper function running inside `LaTeX-env-item'.
+The body of this function used to be part of `LaTeX-env-item'."
   (if (TeX-active-mark)
       (progn
         (LaTeX-find-matching-begin)
@@ -1088,6 +1097,19 @@ If nil, act like the empty string is given, but do not 
prompt."
                 (current-fill-column)))
     (LaTeX-fill-paragraph nil)))
 
+(defun LaTeX-env-item (environment)
+  "Insert ENVIRONMENT and the first item.
+The first item is inserted by the function `LaTeX--env-item'."
+  (LaTeX-insert-environment environment)
+  (LaTeX--env-item environment))
+
+(defun LaTeX-env-item-args (environment &rest args)
+  "Insert ENVIRONMENT followed by ARGS and first item.
+The first item is inserted by the function `LaTeX--env-item'."
+  (LaTeX-insert-environment environment)
+  (LaTeX--env-parse-args args)
+  (LaTeX--env-item environment))
+
 (defcustom LaTeX-label-alist
   '(("figure" . LaTeX-figure-label)
     ("table" . LaTeX-table-label)
@@ -1296,6 +1318,11 @@ Just like array and tabular."
     ;; Restore the positions of point and mark.
     (exchange-point-and-mark)))
 
+(defun LaTeX-env-label-args (environment &rest args)
+  "Run `LaTeX-env-label' on ENVIRONMENT and insert ARGS."
+  (LaTeX-env-label environment)
+  (LaTeX--env-parse-args args))
+
 (defun LaTeX-env-list (environment)
   "Insert ENVIRONMENT and the first item."
   (let ((label (TeX-read-string "Default Label: ")))
@@ -1422,12 +1449,7 @@ Just like array and tabular."
 (defun LaTeX-env-args (environment &rest args)
   "Insert ENVIRONMENT and arguments defined by ARGS."
   (LaTeX-insert-environment environment)
-  (save-excursion
-    (LaTeX-find-matching-begin)
-    (end-of-line)
-    (let ((TeX-exit-mark (or TeX-exit-mark
-                             (make-marker))))
-      (TeX-parse-arguments args))))
+  (LaTeX--env-parse-args args))
 
 (defun LaTeX-env-label-as-keyval (_optional &optional keyword keyvals 
environment)
   "Query for a label and insert it in the optional argument of an environment.
@@ -7458,10 +7480,12 @@ or `LaTeX-environment-list' and returns it."
                                         (TeX-symbol-list)
                                       (LaTeX-environment-list)))))
 
-    ;; Check if there is a `LaTeX-env-args' in the `arg-list' and
+    ;; Check if there is a `LaTeX-env-*-args' in the `arg-list' and
     ;; remove it:
     (when (and (eq mac-or-env 'env)
-               (eq (car arg-list) #'LaTeX-env-args))
+               (memq (car arg-list) '(LaTeX-env-args
+                                      LaTeX-env-item-args
+                                      LaTeX-env-label-args)))
       (pop arg-list))
 
     ;; Check for `TeX-arg-conditional' here and change `arg-list'