Re: [PATCH] Add styles for listings from tcolorbox.sty

[Arash Esbati]

Hi Dario,

Dario Gjorgjevski <dario.gjorgjevski@gmail.com> writes:

> Please find attached a patch adding styles for listings from
> tcolorbox.sty.  All three libraries---listings, listingsutf8, and
> minted---are supported as well as the common environments and macros.

First of all, my sincere apologies for the late response, I somehow
managed to miss your patch.  But I found it now as I touched
tcolorbox.el myself.

I will add some comments below, but in general, please have a look at
commit 7c4147b296.  I changed some internals in tcolorbox.el which also
affect the libraries, most notably:

-- `LaTeX-tcolorbox-keyval-options-local' is gone.  Now we have a
   function called `LaTeX-tcolorbox-keyval-options' which returns
   updated key=vals.

-- `LaTeX-tcolorbox-keyval-options-full' now contains symbols.
   Libraries should add symbols the this var.  The value can be
   retrieved with the function `LaTeX-tcolorbox-keyval-options-full'.

> From 1620aa6ede738004244dc0dd9f8749459771ddea Mon Sep 17 00:00:00 2001
>
> diff --git a/style/tcolorbox-tcblisting.el b/style/tcolorbox-tcblisting.el
> new file mode 100644
> index 00000000..e0cce69c
> --- /dev/null
> +++ b/style/tcolorbox-tcblisting.el
> @@ -0,0 +1,335 @@
> +;;; tcolorbox-tcblisting.el --- AUCTeX style for listings from 
> `tcolorbox.sty' (v4.00)  -*- lexical-binding: t; -*-
> +
> +;;; Commentary:
> +
> +;; This file adds support for listings from `tcolorbox.sty'.  It
> +;; contains the common style shared among the `listings',
> +;; `listingsutf8', and `minted' libraries.
> +
> +;;; Code:
> +
> +;; Needed for compiling `cl-pushnew':
> +(eval-when-compile
> +  (require 'cl-lib))
> +
> +(require 'tex)
> +(require 'latex)
> +
> +(defvar LaTeX-tcolorbox-keyval-options-local)

See above, this variable is now gone.

> +(defvar LaTeX-tcolorbox-keyval-options-full)
> +(defvar LaTeX-tcolorbox-init-options)
> +(declare-function font-latex-add-keywords "font-latex" (keywords class))
> +
> +;; 16.6 Common Option Keys of all Libraries
> +(defvar LaTeX-tcolorbox-tcblisting-keyval-options
> +  (append
> +   '(("listing engine" ("listings" "minted"))
> +     ("listing file")
> +     ("comment")
> +     ("comment style")
> +     ("image comment")
> +     ("tcbimage comment")
> +     ("pdf comment")
> +     ("pdf extension"))
> +   (mapcar (lambda (type)
> +             `(,(format "%s only" type)))
> +           '("listing" "text" "comment"))
> +   (mapcan (lambda (type)

`mapcan' was introduced with Emacs 26.1.  AUCTeX still supports 24.3,
hence this should be avoided.

> +             (mapcan (lambda (prep)
> +                       `((,(format "listing %s %s" prep type))
> +                         (,(format "%s %s listing" type prep))))
> +                     '("and" "side" "outside" "above" "above*")))
> +           '("text" "comment")))
> +  "Key-value options for listings from `tcolorbox.sty'.")
> +
> +(defvar-local LaTeX-tcolorbox-tcblisting-keyval-options-local nil
> +  "Buffer-local version of `LaTeX-tcolorbox-tcblisting-keyval-options'.")

I'd suggest to write a function for all styles and don't add your
key=vals to a -local var.  Maybe something like this:

(defun LaTeX-tcolorbox-tcblisting-keyval-options
    (append
     (when (boundp 'LaTeX-tcolorboxlib-listings-keyval-options)
       LaTeX-tcolorboxlib-listings-keyval-options)
     (when (boundp 'LaTeX-tcolorboxlib-listingsutf8-keyval-options)
       LaTeX-tcolorboxlib-listingsutf8-keyval-options)
     (when (boundp 'LaTeX-tcolorboxlib-minted-keyval-options)
       LaTeX-tcolorboxlib-minted-keyval-options)
     LaTeX-tcolorbox-tcblisting-keyval-options))

And then use the function in the hook with:

(TeX-arg-key-val (LaTeX-tcolorbox-tcblisting-keyval-options))

> +;; Setup for \newtcblisting:
> +(TeX-auto-add-type "tcolorbox-newtcblisting" "LaTeX")
> +
> +(defvar LaTeX-tcolorbox-newtcblisting-regexp
> +  `(,(concat (regexp-quote TeX-esc)
> +             "\\(re\\)?newtcblisting"
> +             "[ \t\n\r%]*"
> +             "\\(?:"
> +             (LaTeX-extract-key-value-label 'none)
> +             "\\)?"
> +             "[ \t\n\r%]*"
> +             "{\\([a-zA-Z0-9]+\\)}"
> +             "[ \t\n\r%]*"
> +             "\\(?:\\[\\([0-9]*\\)\\]\\)?"
> +             "[ \t\n\r%]*"
> +             "\\(\\[\\)?")
> +    (2 3 4 1) LaTeX-auto-tcolorbox-newtcblisting)
> +  "Matches the arguments of \\newtcblisting from `tcolorbox.sty'.")
> +
> +(defun LaTeX-tcolorbox-tcblisting-process-newtcblisting ()
> +  "Process new environments from \\newtcblisting."
> +  (let (to-add to-delete name arg opt renew nargs)
> +    (mapc
> +     (lambda (entry)
> +       (setq name (nth 0 entry)
> +             arg (nth 1 entry)
> +             opt (nth 2 entry)
> +             renew (string= (nth 3 entry) "re"))
> +       ;; when renewing, delete any old entries first
> +       (when renew
> +         (push name to-delete))
> +       (cond
> +        ;; optional 1st argument and mandatory argument(s)
> +        ((and arg (not (string= arg ""))
> +              opt (not (string= opt  "")))
> +         (setq nargs (1- (string-to-number arg)))
> +         (push
> +          `(,name LaTeX-env-args
> +                  [ TeX-arg-eval
> +                 TeX-read-key-val t
> +                    (append
> +                  LaTeX-tcolorbox-tcblisting-keyval-options-local
> +                  LaTeX-tcolorbox-keyval-options-local) ]
> +                  ,@(mapcar (lambda (i)
> +                              (format "Listing box arg %d/%d" i nargs))
> +                            (number-sequence 1 nargs)))
> +          to-add))
> +        ;; mandatory argument(s) only
> +        ((and arg (not (string= arg ""))
> +              opt (string= opt ""))
> +         (setq nargs (string-to-number arg))
> +         (push
> +          `(,name LaTeX-env-args
> +                  ,@(mapcar (lambda (i)
> +                              (format "Listing box arg %d/%d" i nargs))
> +                            (number-sequence 1 nargs)))
> +          to-add))
> +        ;; no arguments
> +        (t
> +         (push `(,name) to-add))))
> +     (LaTeX-tcolorbox-newtcblisting-list))
> +    (setq to-add (nreverse to-add)
> +          to-delete (nreverse to-delete))
> +    (make-local-variable 'LaTeX-environment-list)
> +    (make-local-variable 'LaTeX-indent-environment-list)
> +    ;; delete the environments that are being renewed
> +    (mapc
> +     (lambda (name)
> +       (setq LaTeX-environment-list (assoc-delete-all

`assoc-delete-all' was introduced back in 26.1.

> +                                     name LaTeX-environment-list)
> +             LaTeX-indent-environment-list (assoc-delete-all
> +                                            name 
> LaTeX-indent-environment-list)
> +             LaTeX-verbatim-environments-local (assoc-delete-all
> +                                                name 
> LaTeX-verbatim-environments-local)))
> +     to-delete)
> +    ;; add the environments that are being added
> +    (apply #'LaTeX-add-environments to-add)
> +    (mapc
> +     (lambda (name)
> +       (cl-pushnew `(,name current-indentation) 
> LaTeX-indent-environment-list)
> +       (cl-pushnew name LaTeX-verbatim-environments-local))
> +     (mapcar #'car to-add))))
> +
> +;; Setup for \newtcbinputlisting:
> +(TeX-auto-add-type "tcolorbox-newtcbinputlisting" "LaTeX")
> +(defvar LaTeX-tcolorbox-newtcbinputlisting-regexp
> +  `(,(concat (regexp-quote TeX-esc)
> +             "\\(re\\)?newtcbinputlisting"
> +             "[ \t\n\r%]*"
> +             "\\(?:"
> +             (LaTeX-extract-key-value-label 'none)
> +             "\\)?"
> +             "[ \t\n\r%]*"
> +             "{\\([a-zA-Z0-9]+\\)}"
> +             "[ \t\n\r%]*"
> +             "\\(?:\\[\\([0-9]*\\)\\]\\)?"
> +             "[ \t\n\r%]*"
> +             "\\(\\[\\)?")
> +    (2 3 4 1) LaTeX-auto-tcolorbox-newtcbinputlisting)
> +  "Matches the arguments of \\newtcbinputlisting from `tcolorbox.sty'.")
> +
> +(defun LaTeX-tcolorbox-tcblisting-process-newtcbinputlisting ()
> +  "Process new macros from \\newtcbinputlisting."
> +  (let (to-add to-delete name arg opt renew nargs)
> +    (mapc
> +     (lambda (entry)
> +       (setq name (nth 0 entry)
> +             arg (nth 1 entry)
> +             opt (nth 2 entry)
> +             renew (string= (nth 3 entry) "re"))
> +       ;; when renewing, delete any old entries first
> +       (when renew
> +         (push name to-delete))
> +       (cond
> +        ;; optional 1st argument and mandatory argument(s)
> +        ((and arg (not (string= arg ""))
> +              opt (not (string= opt  "")))
> +         (setq nargs (1- (string-to-number arg)))
> +         (push
> +          (cons
> +           `(,name [ TeX-arg-eval
> +                  TeX-read-key-val t
> +                     (append
> +                   LaTeX-tcolorbox-tcblisting-keyval-options-local
> +                   LaTeX-tcolorbox-keyval-options-local) ]
> +                   ,@(mapcar (lambda (i)
> +                               (format "Listing box arg %d/%d" i nargs))
> +                             (number-sequence 1 nargs)))
> +           `(,name ,(concat "[" (make-string nargs ?{))))
> +          to-add))
> +        ;; mandatory argument(s) only
> +        ((and arg (not (string= arg ""))
> +              opt (string= opt ""))
> +         (setq nargs (string-to-number arg))
> +         (push
> +          (cons
> +           `(,name ,@(mapcar (lambda (i)
> +                               (format "Listing box arg %d/%d" i nargs))
> +                             (number-sequence 1 nargs)))
> +           `(,name ,(make-string nargs ?{)))
> +          to-add))
> +        ;; no arguments
> +        (t
> +         (push
> +          (cons `(,name)
> +                `(,name ""))
> +          to-add))))
> +     (LaTeX-tcolorbox-newtcbinputlisting-list))
> +    (setq to-add (nreverse to-add)
> +          to-delete (nreverse to-delete))
> +    (make-local-variable 'TeX-symbol-list)

This is not needed.  `TeX-symbol-list' is generated via
`TeX-auto-add-type' and is passed to `make-variable-buffer-local'.

> +    ;; delete the macros that are being renewed
> +    (mapc
> +     (lambda (name)
> +       (setq TeX-symbol-list (assoc-delete-all

Again, `assoc-delete-all'.

> +                              name TeX-symbol-list)))
> +     to-delete)
> +    ;; add the macros that are being added
> +    (apply #'TeX-add-symbols (mapcar #'car to-add))
> +    (when (and (featurep 'font-latex)
> +               (eq TeX-install-font-lock 'font-latex-setup))
> +      (font-latex-add-keywords (mapcar #'cdr to-add)
> +                               'function))))
> +
> +(defun LaTeX-tcolorbox-tcblisting-auto-prepare ()
> +  "Clear various auto variables before parsing."
> +  (setq LaTeX-auto-tcolorbox-newtcblisting nil
> +        LaTeX-auto-tcolorbox-newtcbinputlisting nil))
> +
> +(defun LaTeX-tcolorbox-tcblisting-auto-cleanup ()
> +  "Process the parsed results."
> +  (LaTeX-tcolorbox-tcblisting-process-newtcblisting)
> +  (LaTeX-tcolorbox-tcblisting-process-newtcbinputlisting))
> +
> +(add-hook 'TeX-auto-prepare-hook #'LaTeX-tcolorbox-tcblisting-auto-prepare t)
> +(add-hook 'TeX-auto-cleanup-hook #'LaTeX-tcolorbox-tcblisting-auto-cleanup t)
> +
> +(TeX-add-style-hook
> + "tcolorbox-tcblisting"
> + (lambda ()
> +   (setq
> +    ;; activate the buffer-local key-value options
> +    LaTeX-tcolorbox-tcblisting-keyval-options-local
> +    (copy-alist LaTeX-tcolorbox-tcblisting-keyval-options)
> +    ;; append to `LaTeX-tcolorbox-keyval-options-full'
> +    LaTeX-tcolorbox-keyval-options-full
> +    (append (copy-alist LaTeX-tcolorbox-tcblisting-keyval-options-local)
> +            (copy-alist LaTeX-tcolorbox-keyval-options-full)))

This should now read:

(add-to-list 'LaTeX-tcolorbox-keyval-options-full
             'LaTeX-tcolorbox-tcblisting-keyval-options)

> +   ;; add environments
> +   (LaTeX-add-environments
> +    '("tcblisting" LaTeX-env-args
> +      (TeX-arg-eval
> +       TeX-read-key-val nil (append
> +                          LaTeX-tcolorbox-tcblisting-keyval-options-local
> +                             LaTeX-tcolorbox-keyval-options-local)))

You can now do:

    '("tcblisting" LaTeX-env-args
      (TeX-arg-eval
       TeX-read-key-val nil (append
                             LaTeX-tcolorbox-tcblisting-keyval-options
                             (LaTeX-tcolorbox-keyval-options))))

> +    '("tcboutputlisting"))
> +   (make-local-variable 'LaTeX-indent-environment-list)
> +   (mapc (lambda (name)
> +           (cl-pushnew name LaTeX-verbatim-environments-local)
> +           (cl-pushnew `(,name current-indentation) 
> LaTeX-indent-environment-list))
> +         '("tcblisting" "tcboutputlisting"))
> +   ;; add macros
> +   (TeX-add-symbols
> +    '("tcbinputlisting"
> +      (TeX-arg-eval
> +       TeX-read-key-val nil (append
> +                             LaTeX-tcolorbox-tcblisting-keyval-options-local
> +                          LaTeX-tcolorbox-keyval-options-local)))

See above.

> +    '("tcbuselistingtext")
> +    '("tcbuselistinglisting")
> +    '("tcbusetemplisting")
> +    '("newtcblisting"
> +      [ TeX-arg-key-val LaTeX-tcolorbox-init-options ]
> +      "Name"
> +      [ TeX-arg-define-macro-arguments ]
> +      (TeX-arg-eval
> +       TeX-read-key-val nil (append
> +                             LaTeX-tcolorbox-tcblisting-keyval-options-local
> +                          LaTeX-tcolorbox-keyval-options-local)))
> +    '("renewtcblisting"
> +      [ TeX-arg-key-val LaTeX-tcolorbox-init-options ]
> +      (TeX-arg-eval completing-read
> +                    (TeX-argument-prompt nil nil "Listing box")
> +                    (LaTeX-tcolorbox-newtcblisting-list))
> +      [ TeX-arg-define-macro-arguments ]
> +      (TeX-arg-eval
> +       TeX-read-key-val nil (append
> +                          LaTeX-tcolorbox-tcblisting-keyval-options-local
> +                             LaTeX-tcolorbox-keyval-options-local)))
> +    '("newtcbinputlisting"
> +      [ TeX-arg-key-val LaTeX-tcolorbox-init-options ]
> +      "Name"
> +      [ TeX-arg-define-macro-arguments ]
> +      (TeX-arg-eval
> +       TeX-read-key-val nil (append
> +                             LaTeX-tcolorbox-tcblisting-keyval-options-local
> +                          LaTeX-tcolorbox-keyval-options-local)))
> +    '("renewtcbinputlisting"
> +      [ TeX-arg-key-val LaTeX-tcolorbox-init-options ]
> +      (TeX-arg-eval completing-read
> +                    (TeX-argument-prompt nil nil "Listing box")
> +                    (LaTeX-tcolorbox-newtcblisting-list))
> +      [ TeX-arg-define-macro-arguments ]
> +      (TeX-arg-eval
> +       TeX-read-key-val nil (append
> +                          LaTeX-tcolorbox-tcblisting-keyval-options-local
> +                             LaTeX-tcolorbox-keyval-options-local))))
> +   (when (and (featurep 'font-latex)
> +              (eq TeX-install-font-lock 'font-latex-setup))
> +     (font-latex-add-keywords '(("tcbinputlisting" "{")
> +                                ("tcbuselistingtext" "")
> +                                ("tcbuselistinglisting" "")
> +                                ("tcbusetemplisting" "")
> +                                ("newtcblisting" "[{[[{")
> +                                ("renewtcblisting" "[{[[{")
> +                                ("newtcbinputlisting" "[{[[{")
> +                                ("renewtcbinputlisting" "[{[[{"))
> +                              'function))
> +   ;; add to the parser
> +   (TeX-auto-add-regexp LaTeX-tcolorbox-newtcblisting-regexp)
> +   (TeX-auto-add-regexp LaTeX-tcolorbox-newtcbinputlisting-regexp))
> + TeX-dialect)
> +
> +;;; tcolorbox-tcblisting.el ends here
> diff --git a/style/tcolorboxlib-listings.el b/style/tcolorboxlib-listings.el
> new file mode 100644
> index 00000000..08588b00
> --- /dev/null
> +++ b/style/tcolorboxlib-listings.el
> @@ -0,0 +1,66 @@
> +;;; tcolorboxlib-listings.el --- AUCTeX style for the `listings' library 
> from `tcolorbox.sty'  -*- lexical-binding: t; -*-
> +
> +;;; Code:
> +
> +(require 'tex)
> +(require 'latex)
> +
> +(defvar LaTeX-tcolorbox-keyval-options-full)
> +(defvar LaTeX-tcolorbox-tcblisting-keyval-options-local)

Not necessary now.

> +(defvar LaTeX-tcolorboxlib-listings-keyval-options
> +  '(;; 16.3 Option Keys of the `listings' Library
> +    ("listing options")
> +    ("no listing options")
> +    ("listing style")
> +    ("listing inputencoding")
> +    ("listing remove caption")
> +    ("every listing line")
> +    ("every listing line*"))
> +  "Key-value options for the `listings' library from `tcolorbox.sty'.")
> +
> +(TeX-add-style-hook
> + "tcolorboxlib-listings"
> + (lambda ()
> +   (TeX-run-style-hooks "tcolorbox-tcblisting")
> +   (setq
> +    ;; append to `LaTeX-tcolorbox-keyval-options-full'
> +    LaTeX-tcolorbox-keyval-options-full
> +    (append (copy-alist LaTeX-tcolorboxlib-listings-keyval-options)
> +            (copy-alist LaTeX-tcolorbox-keyval-options-full))

(add-to-list 'LaTeX-tcolorbox-keyval-options-full
             'LaTeX-tcolorboxlib-listings-keyval-options)


> +    ;; append to `LaTeX-tcolorbox-tcblisting-keyval-options-local'
> +    LaTeX-tcolorbox-tcblisting-keyval-options-local
> +    (append (copy-alist LaTeX-tcolorboxlib-listings-keyval-options)
> +            (copy-alist LaTeX-tcolorbox-tcblisting-keyval-options-local))))
> + TeX-dialect)
> +
> +;;; tcolorboxlib-listings.el ends here
> diff --git a/style/tcolorboxlib-listingsutf8.el 
> b/style/tcolorboxlib-listingsutf8.el
> new file mode 100644
> index 00000000..f4cf0d3f
> --- /dev/null
> +++ b/style/tcolorboxlib-listingsutf8.el
> @@ -0,0 +1,67 @@
> +;;; tcolorboxlib-listingsutf8.el --- AUCTeX style for the `listingsutf8' 
> library from `tcolorbox.sty'  -*- lexical-binding: t; -*-
> +
> +;;; Code:
> +
> +(require 'tex)
> +(require 'latex)
> +
> +(defvar LaTeX-tcolorbox-keyval-options-full)
> +(defvar LaTeX-tcolorbox-tcblisting-keyval-options-local)

Not necessary now.

> +(defvar LaTeX-tcolorboxlib-listingsutf8-keyval-options
> +  '(;; 16.4 Option Keys of the `listingsutf8' Library
> +    ("listing options")
> +    ("no listing options")
> +    ("listing style")
> +    ("listing inputencoding")
> +    ("listing remove caption")
> +    ("every listing line")
> +    ("every listing line*")
> +    ("listing utf8"))
> +  "Key-value options for the `listingsutf8' library from `tcolorbox.sty'.")
> +
> +(TeX-add-style-hook
> + "tcolorboxlib-listingsutf8"
> + (lambda ()
> +   (TeX-run-style-hooks "tcolorbox-tcblisting")
> +   (setq
> +    ;; append to `LaTeX-tcolorbox-keyval-options-full'
> +    LaTeX-tcolorbox-keyval-options-full
> +    (append (copy-alist LaTeX-tcolorboxlib-listingsutf8-keyval-options)
> +            (copy-alist LaTeX-tcolorbox-keyval-options-full))

(add-to-list 'LaTeX-tcolorbox-keyval-options-full
             'LaTeX-tcolorboxlib-listingsutf8-keyval-options)

> +    ;; append to `LaTeX-tcolorbox-tcblisting-keyval-options-local'
> +    LaTeX-tcolorbox-tcblisting-keyval-options-local
> +    (append (copy-alist LaTeX-tcolorboxlib-listingsutf8-keyval-options)
> +            (copy-alist LaTeX-tcolorbox-tcblisting-keyval-options-local))))
> + TeX-dialect)
> +
> +;;; tcolorboxlib-listingsutf8.el ends here
> diff --git a/style/tcolorboxlib-minted.el b/style/tcolorboxlib-minted.el
> new file mode 100644
> index 00000000..8aed40b3
> --- /dev/null
> +++ b/style/tcolorboxlib-minted.el
> @@ -0,0 +1,62 @@
> +;;; tcolorboxlib-minted.el --- AUCTeX style for the `minted' library from 
> `tcolorbox.sty'  -*- lexical-binding: t; -*-
> +
> +;;; Code:
> +
> +(require 'tex)
> +(require 'latex)
> +
> +(defvar LaTeX-tcolorbox-keyval-options-full)
> +(defvar LaTeX-tcolorbox-tcblisting-keyval-options-local)
> +
> +(defvar LaTeX-tcolorboxlib-minted-keyval-options
> +  '(;; 16.5 Option Keys of the `minted' Library
> +    ("minted language")
> +    ("minted options")
> +    ("minted style"))
> +  "Key-value options for the `minted' library from `tcolorbox.sty'.")
> +
> +(TeX-add-style-hook
> + "tcolorboxlib-minted"
> + (lambda ()
> +   (TeX-run-style-hooks "tcolorbox-tcblisting")
> +   (setq
> +    ;; append to `LaTeX-tcolorbox-keyval-options-full'
> +    LaTeX-tcolorbox-keyval-options-full
> +    (append (copy-alist LaTeX-tcolorboxlib-minted-keyval-options)
> +            (copy-alist LaTeX-tcolorbox-keyval-options-full))

(add-to-list 'LaTeX-tcolorbox-keyval-options-full
             'LaTeX-tcolorboxlib-minted-keyval-options)

> +    ;; append to `LaTeX-tcolorbox-tcblisting-keyval-options-local'
> +    LaTeX-tcolorbox-tcblisting-keyval-options-local
> +    (append (copy-alist LaTeX-tcolorboxlib-minted-keyval-options)
> +            (copy-alist LaTeX-tcolorbox-tcblisting-keyval-options-local))))
> + TeX-dialect)
> +
> +;;; tcolorboxlib-minted.el ends here

I hope you can incorporate the suggestions above.  Again, sorry for
missing you message in the first place.

Best, Arash