font-lock-maximum-decoration API

[Paul W. Rankin]

wrt. 
http://lists.gnu.org/archive/html/help-gnu-emacs/2019-05/msg00022.html

There is a little-used Emacs feature to allow different levels of 
font-lock decoration via the variable 
font-lock-maximum-decoration:

> You can customize the variable ‘font-lock-maximum-decoration’ to 
> alter the amount of fontification applied by Font Lock mode, for 
> major modes that support this feature. The value should be a 
> number (with 1 representing a minimal amount of fontification; 
> some modes support levels as high as 3); or ‘t’, meaning “as 
> high as possible” (the default).[1]

I've noticed that few major modes implement multiple levels of 
font-lock decoration, which might be because it's more difficult 
to dynamically create different font-lock keywords, but it also 
could be because there seems to be no API for programmatically 
changing this value per major mode, as the variable permits:

> If a list, each element should be a cons pair of the form 
> (MAJOR-MODE . LEVEL),
> where MAJOR-MODE is a symbol or t (meaning the default).  For 
> example:
>  ((c-mode . t) (c++-mode . 2) (t . 1))
> means use the maximum decoration available for buffers in C 
> mode, level 2
> decoration for buffers in C++ mode, and level 1 decoration 
> otherwise.

When writing fountain-mode, I wanted several levels of font-lock, 
and so needed to implement a couple of functions to get and set 
this variable, but this felt a bit outside a major mode's bounds.

I'd love to see more major modes offering multiple levels of 
font-lock[3] so it would be nice if major modes could call a 
function to safely set this variable for themselves, without 
needing to handle the whole list.

If at all helpful, I've included the functions in fountain-mode. 
As this code is in GNU ELPA, it remains available to implement 
into Emacs if anyone wishes:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(defun fountain-get-font-lock-decoration ()
 "Return the value of `font-lock-maximum-decoration' for 
 `fountain-mode'."
 (let ((n (if (listp font-lock-maximum-decoration)
              (cdr (or (assq 'fountain-mode 
              font-lock-maximum-decoration)
                       (assq 't font-lock-maximum-decoration)))
            font-lock-maximum-decoration)))
   (cond ((null n) 2)
         ((eq n t) 3)
         ((integerp n) n)
         (t 2))))

(defun fountain-set-font-lock-decoration (n)
 "Set `font-lock-maximum-decoration' for `fountain-mode' to N."
 (interactive "NMaximum decoration (1-3): ")
 (if (and (integerp n)
          (<= 1 n 3))
     (let ((level (cond ((= n 1) 1)
                        ((= n 2) nil)
                        ((= n 3) t))))
       (cond ((listp font-lock-maximum-decoration)
              (setq font-lock-maximum-decoration
                    (assq-delete-all 'fountain-mode 
                    font-lock-maximum-decoration))
              (customize-set-variable 
              'font-lock-maximum-decoration
                                      (cons (cons 'fountain-mode 
                                      level)
                                            font-lock-maximum-decoration)))
             ((or (booleanp font-lock-maximum-decoration)
                  (integerp font-lock-maximum-decoration))
              (customize-set-variable 
              'font-lock-maximum-decoration
                                      (list (cons 'fountain-mode 
                                      level)
                                            (cons 't 
                                            font-lock-maximum-decoration)))))
       (message "Syntax highlighting is now: %s"
                (cond ((= n 1) "minimum")
                      ((= n 2) "default")
                      ((= n 3) "maximum")))
       (font-lock-refresh-defaults))
   (user-error "Decoration must be an integer 1-3")))
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


[1]: (info "(emacs) Font Lock")
[2]: Something a little silly about this option is that the 
defcustom includes this tag:

   (const :tag "default" nil)

Which implies to the user that nil or the 2nd highest level is 
default, despite t or 3rd highest being the Emacs default. The 
question of which level is the "default" is pretty inconsistent 
between the variable docstring, the manual, and the code 
implementation itself.

[3]: I'd also like to see more major modes correctly using 
font-lock rather than their own dysfunctional mutant 
abominations...

--
https://www.paulwrankin.com