/[emacs]/emacs/lispref/modes.texi
ViewVC logotype

Diff of /emacs/lispref/modes.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.94 by lute, Tue Apr 5 15:21:56 2005 UTC revision 1.95 by lute, Fri Apr 8 09:28:08 2005 UTC
# Line 1  Line 1 
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
# Line 2111  processes the elements of @code{font-loc Line 2111  processes the elements of @code{font-loc
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:
# Line 2122  Highlight all matches for @var{regexp} u Line 2122  Highlight all matches for @var{regexp} u
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
# Line 2146  and with point where the previous invoca Line 2146  and with point where the previous invoca
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
# Line 2159  highlighted (instead of the entire text Line 2159  highlighted (instead of the entire text
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
# Line 2173  is a Lisp variable (a symbol), whose val Line 2173  is a Lisp variable (a symbol), whose val
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.
# Line 2219  terminates search-based fontification. Line 2221  terminates search-based fontification.
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    
# Line 2230  Here are some examples of elements of th Line 2232  Here are some examples of elements of th
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
# Line 2301  to match text which spans lines; this do Line 2310  to match text which spans lines; this do
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    

Legend:
Removed from v.1.94  
changed lines
  Added in v.1.95

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26