23.5.2 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. "\\"

The function regexp-opt (see section 34.2.1 Syntax of Regular Expressions) 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 (see section 34.2.1 Syntax of Regular Expressions) 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.