branch: externals/auctex commit 4eaed332ba600d8fc90d2177815597e9407c3f2b Author: Arash Esbati <ar...@gnu.org> Commit: Arash Esbati <ar...@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'