1 |
@c -*-texinfo-*- |
@c -*-texinfo-*- |
2 |
@c This is part of the GNU Emacs Lisp Reference Manual. |
@c This is part of the GNU Emacs Lisp Reference Manual. |
3 |
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, |
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, |
4 |
@c 2003, 2004, 2005 Free Software Foundation, Inc. |
@c 2003, 2004, 2005 Free Software Foundation, Inc. |
5 |
@c See the file elisp.texi for copying conditions. |
@c See the file elisp.texi for copying conditions. |
6 |
@setfilename ../info/modes |
@setfilename ../info/modes |
2111 |
each element, it finds and handles all matches. Ordinarily, once |
each element, it finds and handles all matches. Ordinarily, once |
2112 |
part of the text has been fontified already, this cannot be overridden |
part of the text has been fontified already, this cannot be overridden |
2113 |
by a subsequent match in the same text; but you can specify different |
by a subsequent match in the same text; but you can specify different |
2114 |
behavior using the @var{override} element of a @var{highlighter}. |
behavior using the @var{override} element of a @var{subexp-highlighter}. |
2115 |
|
|
2116 |
Each element of @code{font-lock-keywords} should have one of these |
Each element of @code{font-lock-keywords} should have one of these |
2117 |
forms: |
forms: |
2122 |
@code{font-lock-keyword-face}. For example, |
@code{font-lock-keyword-face}. For example, |
2123 |
|
|
2124 |
@example |
@example |
2125 |
;; @r{Highlight discrete occurrences of @samp{foo}} |
;; @r{Highlight occurrences of the word @samp{foo}} |
2126 |
;; @r{using @code{font-lock-keyword-face}.} |
;; @r{using @code{font-lock-keyword-face}.} |
2127 |
"\\<foo\\>" |
"\\<foo\\>" |
2128 |
@end example |
@end example |
2129 |
|
|
2130 |
The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is useful for |
The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful |
2131 |
calculating optimal regular expressions to match a number of different |
for calculating optimal regular expressions to match a number of |
2132 |
keywords. |
different keywords. |
2133 |
|
|
2134 |
@item @var{function} |
@item @var{function} |
2135 |
Find text by calling @var{function}, and highlight the matches |
Find text by calling @var{function}, and highlight the matches |
2146 |
@var{function} fails. On failure, @var{function} need not reset point |
@var{function} fails. On failure, @var{function} need not reset point |
2147 |
in any particular way. |
in any particular way. |
2148 |
|
|
2149 |
@item (@var{matcher} . @var{match}) |
@item (@var{matcher} . @var{subexp}) |
2150 |
In this kind of element, @var{matcher} is either a regular |
In this kind of element, @var{matcher} is either a regular |
2151 |
expression or a function, as described above. The @sc{cdr}, |
expression or a function, as described above. The @sc{cdr}, |
2152 |
@var{match}, specifies which subexpression of @var{matcher} should be |
@var{subexp}, specifies which subexpression of @var{matcher} should be |
2153 |
highlighted (instead of the entire text that @var{matcher} matched). |
highlighted (instead of the entire text that @var{matcher} matched). |
2154 |
|
|
2155 |
@example |
@example |
2159 |
@end example |
@end example |
2160 |
|
|
2161 |
If you use @code{regexp-opt} to produce the regular expression |
If you use @code{regexp-opt} to produce the regular expression |
2162 |
@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax |
@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Regexp |
2163 |
of Regexps}) to calculate the value for @var{match}. |
Functions}) to calculate the value for @var{subexp}. |
2164 |
|
|
2165 |
@item (@var{matcher} . @var{facespec}) |
@item (@var{matcher} . @var{facespec}) |
2166 |
In this kind of element, @var{facespec} is an object which specifies |
In this kind of element, @var{facespec} is an object which specifies |
2173 |
("fubar" . fubar-face) |
("fubar" . fubar-face) |
2174 |
@end example |
@end example |
2175 |
|
|
2176 |
However, @var{facespec} can also be a list of the form |
However, @var{facespec} can also be a list of the form: |
2177 |
|
|
2178 |
@example |
@example |
2179 |
(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) |
(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) |
2180 |
@end example |
@end example |
2181 |
|
|
2182 |
to specify various text properties to put on the text that matches. |
to specify the face @var{face} and various additional text properties |
2183 |
If you do this, be sure to add the other text property names that you |
to put on the text that matches. If you do this, be sure to add the |
2184 |
set in this way to the value of @code{font-lock-extra-managed-props} |
other text property names that you set in this way to the value of |
2185 |
so that the properties will also be cleared out when they are no longer |
@code{font-lock-extra-managed-props} so that the properties will also |
2186 |
appropriate. |
be cleared out when they are no longer appropriate. Alternatively, |
2187 |
|
you can set the variable @code{font-lock-unfontify-region-function} to |
2188 |
|
a function that clears these properties. |
2189 |
|
|
2190 |
@item (@var{matcher} . @var{highlighter}) |
@item (@var{matcher} . @var{subexp-highlighter}) |
2191 |
In this kind of element, @var{highlighter} is a list |
In this kind of element, @var{subexp-highlighter} is a list |
2192 |
which specifies how to highlight matches found by @var{matcher}. |
which specifies how to highlight matches found by @var{matcher}. |
2193 |
It has the form |
It has the form: |
2194 |
|
|
2195 |
@example |
@example |
2196 |
(@var{subexp} @var{facespec} @var{override} @var{laxmatch}) |
(@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]]) |
2197 |
@end example |
@end example |
2198 |
|
|
2199 |
The @sc{car}, @var{subexp}, is an integer specifying which subexpression |
The @sc{car}, @var{subexp}, is an integer specifying which subexpression |
2200 |
of the match to fontify (0 means the entire matching text). The second |
of the match to fontify (0 means the entire matching text). The second |
2201 |
subelement, @var{facespec}, specifies the face, as described above. |
subelement, @var{facespec}, specifies the face, as described above. |
2202 |
|
|
2203 |
The last two values in @var{highlighter}, @var{override} and |
The last two values in @var{subexp-highlighter}, @var{override} and |
2204 |
@var{laxmatch}, are flags. If @var{override} is @code{t}, this |
@var{laxmatch}, are optional flags. If @var{override} is @code{t}, |
2205 |
element can override existing fontification made by previous elements |
this element can override existing fontification made by previous |
2206 |
of @code{font-lock-keywords}. If it is @code{keep}, then each |
elements of @code{font-lock-keywords}. If it is @code{keep}, then |
2207 |
character is fontified if it has not been fontified already by some |
each character is fontified if it has not been fontified already by |
2208 |
other element. If it is @code{prepend}, the face specified by |
some other element. If it is @code{prepend}, the face specified by |
2209 |
@var{facespec} is added to the beginning of the @code{font-lock-face} |
@var{facespec} is added to the beginning of the @code{font-lock-face} |
2210 |
property. If it is @code{append}, the face is added to the end of the |
property. If it is @code{append}, the face is added to the end of the |
2211 |
@code{font-lock-face} property. |
@code{font-lock-face} property. |
2221 |
Here are some examples of elements of this kind, and what they do: |
Here are some examples of elements of this kind, and what they do: |
2222 |
|
|
2223 |
@smallexample |
@smallexample |
2224 |
;; @r{Highlight occurrences of either @samp{foo} or @samp{bar},} |
;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using} |
2225 |
;; @r{using @code{foo-bar-face}, even if they have already been highlighted.} |
;; @r{@code{foo-bar-face}, even if they have already been highlighted.} |
2226 |
;; @r{@code{foo-bar-face} should be a variable whose value is a face.} |
;; @r{@code{foo-bar-face} should be a variable whose value is a face.} |
2227 |
("foo\\|bar" 0 foo-bar-face t) |
("foo\\|bar" 0 foo-bar-face t) |
2228 |
|
|
2232 |
(fubar-match 1 fubar-face) |
(fubar-match 1 fubar-face) |
2233 |
@end smallexample |
@end smallexample |
2234 |
|
|
2235 |
|
@item (@var{matcher} . @var{anchored-highlighter}) |
2236 |
|
In this kind of element, @var{anchored-highlighter} specifies how to |
2237 |
|
highlight text that follows a match found by @var{matcher}. So a |
2238 |
|
match found by @var{matcher} acts as the anchor for further searches |
2239 |
|
specified by @var{anchored-highlighter}. @var{anchored-highlighter} |
2240 |
|
is a list of the following form: |
2241 |
|
|
2242 |
|
@example |
2243 |
|
(@var{anchored-matcher} @var{pre-form} @var{post-form} |
2244 |
|
@var{subexp-highlighters}@dots{}) |
2245 |
|
@end example |
2246 |
|
|
2247 |
|
Here, @var{anchored-matcher}, like @var{matcher}, is either a regular |
2248 |
|
expression or a function. After a match of @var{matcher} is found, |
2249 |
|
point is at the end of the match. Now, Font Lock evaluates the form |
2250 |
|
@var{pre-form}. Then it searches for matches of |
2251 |
|
@var{anchored-matcher} and uses @var{subexp-highlighters} to highlight |
2252 |
|
these. A @var{subexp-highlighter} is as described above. Finally, |
2253 |
|
Font Lock evaluates @var{post-form}. |
2254 |
|
|
2255 |
|
The forms @var{pre-form} and @var{post-form} can be used to initialize |
2256 |
|
before, and cleanup after, @var{anchored-matcher} is used. Typically, |
2257 |
|
@var{pre-form} is used to move point to some position relative to the |
2258 |
|
match of @var{matcher}, before starting with @var{anchored-matcher}. |
2259 |
|
@var{post-form} might be used to move back, before resuming with |
2260 |
|
@var{matcher}. |
2261 |
|
|
2262 |
|
After Font Lock evaluates @var{pre-form}, it does not search for |
2263 |
|
@var{anchored-matcher} beyond the end of the line. However, if |
2264 |
|
@var{pre-form} returns a buffer position that is greater than the |
2265 |
|
position of point after @var{pre-form} is evaluated, then the position |
2266 |
|
returned by @var{pre-form} is used as the limit of the search instead. |
2267 |
|
It is generally a bad idea to return a position greater than the end |
2268 |
|
of the line; in other words, the @var{anchored-matcher} search should |
2269 |
|
not span lines. |
2270 |
|
|
2271 |
|
For example, |
2272 |
|
|
2273 |
|
@smallexample |
2274 |
|
;; @r{Highlight occurrences of the word @samp{item} following} |
2275 |
|
;; @r{an occurrence of the word @samp{anchor} (on the same line)} |
2276 |
|
;; @r{in the value of @code{item-face}.} |
2277 |
|
("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face)) |
2278 |
|
@end smallexample |
2279 |
|
|
2280 |
|
Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore |
2281 |
|
searching for @samp{item} starts at the end of the match of |
2282 |
|
@samp{anchor}, and searching for subsequent instances of @samp{anchor} |
2283 |
|
resumes from where searching for @samp{item} concluded. |
2284 |
|
|
2285 |
@item (@var{matcher} @var{highlighters}@dots{}) |
@item (@var{matcher} @var{highlighters}@dots{}) |
2286 |
This sort of element specifies several @var{highlighter} lists for a |
This sort of element specifies several @var{highlighter} lists for a |
2287 |
single @var{matcher}. In order for this to be useful, each |
single @var{matcher}. A @var{highlighter} list can be of the type |
2288 |
@var{highlighter} should have a different value of @var{subexp}; that is, |
@var{subexp-highlighter} or @var{anchored-highlighter} as described |
2289 |
each one should apply to a different subexpression of @var{matcher}. |
above. |
2290 |
|
|
2291 |
@ignore |
For example, |
|
@item (@var{matcher} . @var{anchored}) |
|
|
In this kind of element, @var{anchored} acts much like a |
|
|
@var{highlighter}, but it is more complex and can specify multiple |
|
|
successive searches. |
|
|
|
|
|
For highlighting single items, typically only @var{highlighter} is |
|
|
required. However, if an item or (typically) items are to be |
|
|
highlighted following the instance of another item (the anchor) then |
|
|
@var{anchored} may be required. |
|
|
|
|
|
It has this format: |
|
|
|
|
|
@example |
|
|
(@var{submatcher} @var{pre-match-form} @var{post-match-form} @var{highlighters}@dots{}) |
|
|
@end example |
|
|
|
|
|
@c I can't parse this text -- rms |
|
|
where @var{submatcher} is much like @var{matcher}, with one |
|
|
exception---see below. @var{pre-match-form} and @var{post-match-form} |
|
|
are evaluated before the first, and after the last, instance |
|
|
@var{anchored}'s @var{submatcher} is used. Therefore they can be used |
|
|
to initialize before, and cleanup after, @var{submatcher} is used. |
|
|
Typically, @var{pre-match-form} is used to move to some position |
|
|
relative to the original @var{submatcher}, before starting with |
|
|
@var{anchored}'s @var{submatcher}. @var{post-match-form} might be used |
|
|
to move, before resuming with @var{anchored}'s parent's @var{matcher}. |
|
|
|
|
|
For example, an element of the form highlights (if not already highlighted): |
|
|
|
|
|
@example |
|
|
("\\<anchor\\>" (0 anchor-face) ("\\<item\\>" nil nil (0 item-face))) |
|
|
@end example |
|
|
|
|
|
Discrete occurrences of @samp{anchor} in the value of |
|
|
@code{anchor-face}, and subsequent discrete occurrences of @samp{item} |
|
|
(on the same line) in the value of @code{item-face}. (Here |
|
|
@var{pre-match-form} and @var{post-match-form} are @code{nil}. |
|
|
Therefore @samp{item} is initially searched for starting from the end of |
|
|
the match of @samp{anchor}, and searching for subsequent instance of |
|
|
@samp{anchor} resumes from where searching for @samp{item} concluded.) |
|
|
|
|
|
The above-mentioned exception is as follows. The limit of the |
|
|
@var{submatcher} search defaults to the end of the line after |
|
|
@var{pre-match-form} is evaluated. However, if @var{pre-match-form} |
|
|
returns a position greater than the position after @var{pre-match-form} |
|
|
is evaluated, that position is used as the limit of the search. It is |
|
|
generally a bad idea to return a position greater than the end of the |
|
|
line; in other words, the @var{submatcher} search should not span lines. |
|
2292 |
|
|
2293 |
@item (@var{matcher} @var{highlighters-or-anchoreds} ...) |
@smallexample |
2294 |
@end ignore |
;; @r{Highlight occurrences of the word @samp{anchor} in the value} |
2295 |
|
;; @r{of @code{anchor-face}, and subsequent occurrences of the word} |
2296 |
|
;; @r{@samp{item} (on the same line) in the value of @code{item-face}.} |
2297 |
|
("\\<anchor\\>" (0 anchor-face) |
2298 |
|
("\\<item\\>" nil nil (0 item-face))) |
2299 |
|
@end smallexample |
2300 |
|
|
2301 |
@item (eval . @var{form}) |
@item (eval . @var{form}) |
2302 |
Here @var{form} is an expression to be evaluated the first time |
Here @var{form} is an expression to be evaluated the first time |
2310 |
updating when you edit the buffer does not, since it considers text one |
updating when you edit the buffer does not, since it considers text one |
2311 |
line at a time. If you have patterns that typically only span one |
line at a time. If you have patterns that typically only span one |
2312 |
line but can occasionally span two or three, such as |
line but can occasionally span two or three, such as |
2313 |
@samp{<title>...</title>}, you can ask font-lock to be more careful by |
@samp{<title>...</title>}, you can ask Font Lock to be more careful by |
2314 |
setting @code{font-lock-multiline} to @code{t}. But it still will not |
setting @code{font-lock-multiline} to @code{t}. But it still will not |
2315 |
work in all cases. |
work in all cases. |
2316 |
|
|