font-lock-maximum-decoration API

["Paul W. Rankin" <hello@paulwrankin.com>]

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