GNU Info

(elisp)Search-based Fontification

---

Next: Other Font Lock Variables Prev: Font Lock Basics Up: Font Lock Mode

---

Enter node , (file) or (file)node

Search-based Fontification
--------------------------

   The most important variable for customizing Font Lock mode is
`font-lock-keywords'.  It specifies the search criteria for
search-based fontification.

 - Variable: font-lock-keywords
     This variable's value is a list of the keywords to highlight.  Be
     careful when composing regular expressions for this list; a poorly
     written pattern can dramatically slow things down!

   Each element of `font-lock-keywords' specifies how to find certain
cases of text, and how to highlight those cases.  Font Lock mode
processes the elements of `font-lock-keywords' one by one, and for each
element, it finds and handles all matches.  Ordinarily, once part of
the text has been fontified already, this cannot be overridden by a
subsequent match in the same text; but you can specify different
behavior using the OVERRIDE element of a HIGHLIGHTER.

   Each element of `font-lock-keywords' should have one of these forms:

`REGEXP'
     Highlight all matches for REGEXP using `font-lock-keyword-face'.
     For example,

          ;; Highlight discrete occurrences of `foo'
          ;; using `font-lock-keyword-face'.
          "\\<foo\\>"

     The function `regexp-opt' (Note: Syntax of Regexps) is useful for
     calculating optimal regular expressions to match a number of
     different keywords.

`FUNCTION'
     Find text by calling FUNCTION, and highlight the matches it finds
     using `font-lock-keyword-face'.

     When FUNCTION is called, it receives one argument, the limit of
     the search.  It should return non-`nil' if it succeeds, and set the
     match data to describe the match that was found.

`(MATCHER . MATCH)'
     In this kind of element, MATCHER is either a regular expression or
     a function, as described above.  The CDR, MATCH, specifies which
     subexpression of MATCHER should be highlighted (instead of the
     entire text that MATCHER matched).

          ;; Highlight the `bar' in each occurrence of `fubar',
          ;; using `font-lock-keyword-face'.
          ("fu\\(bar\\)" . 1)

     If you use `regexp-opt' to produce the regular expression MATCHER,
     then you can use `regexp-opt-depth' (Note: Syntax of Regexps) to
     calculate the value for MATCH.

`(MATCHER . FACENAME)'
     In this kind of element, FACENAME is an expression whose value
     specifies the face name to use for highlighting.

          ;; Highlight occurrences of `fubar',
          ;; using the face which is the value of `fubar-face'.
          ("fubar" . fubar-face)

`(MATCHER . HIGHLIGHTER)'
     In this kind of element, HIGHLIGHTER is a list which specifies how
     to highlight matches found by MATCHER.  It has the form

          (SUBEXP FACENAME OVERRIDE LAXMATCH)

     The CAR, SUBEXP, is an integer specifying which subexpression of
     the match to fontify (0 means the entire matching text).  The
     second subelement, FACENAME, specifies the face, as described
     above.

     The last two values in HIGHLIGHTER, OVERRIDE and LAXMATCH, are
     flags.  If OVERRIDE is `t', this element can override existing
     fontification made by previous elements of `font-lock-keywords'.
     If it is `keep', then each character is fontified if it has not
     been fontified already by some other element.  If it is `prepend',
     the face FACENAME is added to the beginning of the `face'
     property.  If it is `append', the face FACENAME is added to the
     end of the `face' property.

     If LAXMATCH is non-`nil', it means there should be no error if
     there is no subexpression numbered SUBEXP in MATCHER.  Obviously,
     fontification of the subexpression numbered SUBEXP will not occur.
     However, fontification of other subexpressions (and other
     regexps) will continue.  If LAXMATCH is `nil', and the specified
     subexpression is missing, then an error is signalled which
     terminates search-based fontification.

     Here are some examples of elements of this kind, and what they do:

          ;; Highlight occurrences of either `foo' or `bar',
          ;; using `foo-bar-face', even if they have already been highlighted.
          ;; `foo-bar-face' should be a variable whose value is a face.
          ("foo\\|bar" 0 foo-bar-face t)
          
          ;; Highlight the first subexpression within each occurrence
          ;; that the function `fubar-match' finds,
          ;; using the face which is the value of `fubar-face'.
          (fubar-match 1 fubar-face)

`(MATCHER HIGHLIGHTERS...)'
     This sort of element specifies several HIGHLIGHTER lists for a
     single MATCHER.  In order for this to be useful, each HIGHLIGHTER
     should have a different value of SUBEXP; that is, each one should
     apply to a different subexpression of MATCHER.

`(eval . FORM)'
     Here FORM is an expression to be evaluated the first time this
     value of `font-lock-keywords' is used in a buffer.  Its value
     should have one of the forms described in this table.

   *Warning:* Do not design an element of `font-lock-keywords' to match
text which spans lines; this does not work reliably.  While
`font-lock-fontify-buffer' handles multi-line patterns correctly,
updating when you edit the buffer does not, since it considers text one
line at a time.