1 This is auto-overlay-manual/auto-overlay-manual.info, produced by
2 makeinfo version 4.13 from
3 auto-overlay-manual/auto-overlay-manual.texinfo.
7 * auto-overlays: (auto-overlay-manual). Automatic regexp-delimited overlays
10 This manual describes the Emacs Auto-Overlays package, version 0.10.9
12 Copyright (C) 2007-2015 Free Software Foundation, Inc
14 Permission is granted to copy, distribute and/or modify this
15 document under the terms of the GNU Free Documentation License,
16 Version 1.2 or any later version published by the Free Software
17 Foundation; with no Invariant Sections, no Front-Cover Texts, and
18 no Back-Cover Texts. A copy of the license is included in the
19 section entitled "GNU Free Documentation License".
22 File: auto-overlay-manual.info, Node: Top, Next: Overview, Up: (dir)
24 Emacs Auto-Overlays Manual
25 **************************
27 This manual describes the Emacs Auto-Overlays package, version 0.10.9
29 Copyright (C) 2007-2015 Free Software Foundation, Inc
31 Permission is granted to copy, distribute and/or modify this
32 document under the terms of the GNU Free Documentation License,
33 Version 1.2 or any later version published by the Free Software
34 Foundation; with no Invariant Sections, no Front-Cover Texts, and
35 no Back-Cover Texts. A copy of the license is included in the
36 section entitled "GNU Free Documentation License".
38 An Emacs overlay demarcates a region of text in a buffer, often
39 giving it a different face or changing other properties for that
40 region. There are many circumstance in which it might be useful to
41 create, update, and delete overlays automatically when text matches
42 some criterion, specified for example by regular expressions. This is
43 what the auto-overlays package addresses. It is intended as an Elisp
44 library, providing functions to be used by other Elisp packages, so
45 does not itself define any new interactive commands or minor modes.
50 * Auto-Overlay Functions::
52 * Extending the Auto-Overlays Package::
57 * Copying this Manual::
59 --- The Detailed Node Listing ---
61 Emacs Auto-Overlays Manual
64 * Auto-Overlay Functions::
66 * Extending the Auto-Overlays Package::
69 Auto-Overlay Functions
72 * Starting and Stopping Auto-Overlays::
73 * Searching for Overlays::
75 Extending the Auto-Overlays Package
77 * Auto-Overlays in Depth::
78 * Integrating New Overlay Classes::
79 * Functions for Writing New Overlay Classes::
80 * Auto-Overlay Hooks::
81 * Auto-Overlay Modification Pseudo-Hooks::
83 Functions for Writing New Overlay Classes
85 * Functions for Modifying Overlays::
86 * Functions for Querying Overlays::
90 * GNU Free Documentation License::
93 File: auto-overlay-manual.info, Node: Overview, Next: Auto-Overlay Functions, Prev: Top, Up: Top
98 The auto-overlays package automatically creates, updates and destroys
99 overlays based on regular expression matches in the buffer text. The
100 overlay is created when text is typed that matches an auto-overlay
101 regexp, and is destroyed if and when the matching text is changed so
102 that it no longer matches.
104 The regexps are grouped into sets, and any number of different sets
105 of regexps can be active in the same buffer simultaneously. Regexps in
106 different sets are completely independent, and each set can be activated
107 and deactivated independently (*note Defining Regexps::). This allows
108 different Emacs modes to simultaneously make use of auto-overlays in the
111 There are different "classes" of auto-overlay, used to define
112 different kinds of overlay behaviour. Some classes only require a single
113 regexp, others require separate regexps to define the start and end of
114 the overlay (*note Defining Regexps::). Any additional regexps, beyond
115 the minimum requirements, act as alternatives; if more than one of the
116 regexps matches overlapping regions of text, the one that appears
117 earlier in the list will take precedence. The predefined regexp classes
118 are: `word', `line', `self', `nested' and `flat', but the auto-overlays
119 package can easily be extended with new classes.
122 These are used to define overlays that cover the text matched by
123 the regexp itself, so require a single regexp. An example use
124 would be to create overlays covering single words.
127 These are used to define overlays that stretch from the text
128 matching the regexp to the end of the line, and require a single
129 regexp to define the start of the overlay. An example use would be
130 to create overlays covering single-line comments in programming
134 These are used to define overlays that stretch from one regexp
135 match to the next match for the same regexp, so naturally require
136 a single regexp. An example use would be to create overlays
137 covering strings delimited by `""'.
139 Note that for efficiency reasons, `self' overlays are _not_ fully
140 updated when a new match is found. Instead, when a modification is
141 subsequently made at any position in the buffer after the new
142 match, the overlays are updated _up to_ that position. The update
143 occurs just _before_ the modification is made. Therefore, the
144 overlays at a given buffer position will not necessarily be
145 correct until a modification is made at or after that position
149 These are used to define overlays that start and end at different
150 regexp matches, and that can be nested one inside another. This
151 class requires separate start and end regexps. An example use
152 would be to create overlays between matching braces `{}'.
155 These are used to define overlays that start and end at different
156 regexp matches, but that can not be nested. Extra start matches
157 within one of these overlays are ignored. This class requires
158 separate start and end regexps. An example use would be to create
159 overlays covering multi-line comments in code, e.g. c++ block
160 comments delimited by `/*' and `*/'.
162 By default, the entire text matching a regexp acts as the
163 "delimeter". For example, a `word' overlay will cover all the text
164 matching its regexp, and a `nested' overlay will start at the end of
165 the text matching its start regexp. Sometimes it is useful to be able
166 to have only part of the regexp match act as the delimeter. This can be
167 done by grouping that part of the regexp (*note Defining Regexps::).
168 Overlays will then start and end at the text matching the group,
169 instead of the text matching the entire regexp.
171 Of course, automatically creating overlays isn't much use without
172 some way of setting their properties too. Overlay properties can be
173 defined along with the regexp, and are applied to any overlays created
174 by a match to that regexp. Certain properties have implications for
175 auto-overlay behaviour.
178 This is a standard Emacs overlay property (*note Overlay
179 Properties: (elisp)Overlay Properties.), but it is also used to
180 determine which regexp takes precedence when two or more regexps
181 in the same auto-overlay definition match overlapping regions of
182 text. It is also used to determine which regexp's properties take
183 precedence for overlays that are defined by separate start and end
187 Normally, different auto-overlay regexps coexist, and act
188 completely independently of one-another. However, if an
189 auto-overlay has non-nil `exclusive' and `priority' properties,
190 regexp matches within the overlay are ignored if they have lower
191 priority. An example use is ignoring other regexp matches within
195 File: auto-overlay-manual.info, Node: Auto-Overlay Functions, Next: Worked Example, Prev: Overview, Up: Top
197 2 Auto-Overlay Functions
198 ************************
200 To use auto-overlays in an Elisp package, you must load the overlay
201 classes that you require by including lines of the form
202 (require 'auto-overlay-CLASS)
203 near the beginning of your package, where CLASS is the class name.
204 The standard classes are: `word', `line', `self', `nested' and `flat'
205 (*note Overview::), though new classes can easily be added (*note
206 Extending the Auto-Overlays Package::).
208 Sometimes it is useful for a package to make use of auto-overlays if
209 any are defined, without necessarily requiring them. To facilitate
210 this, the relevant functions can be loaded separately from the rest of
211 the auto-overlays package with the line
212 (require 'auto-overlay-common)
213 This provides all the functions related to searching for overlays and
214 retrieving overlay properties. *Note Searching for Overlays::. Note that
215 there is no need to include this line if any auto-overlay classes are
216 `require'd, though it will do no harm.
218 This section describes the functions that are needed in order to make
219 use of auto-overlays in an Elisp package. It does _not_ describe
220 functions related to extending the auto-overlays package. *Note
221 Extending the Auto-Overlays Package::.
226 * Starting and Stopping Auto-Overlays::
227 * Searching for Overlays::
230 File: auto-overlay-manual.info, Node: Defining Regexps, Next: Starting and Stopping Auto-Overlays, Up: Auto-Overlay Functions
235 An auto-overlay definition is a list of the form:
236 (CLASS &optional :id ENTRY-ID REGEXP1 REGEXP2 ...)
237 CLASS is one of the regexp classes described in the previous section
238 (*note Overview::). The optional `:id' property should be a symbol that
239 can be used to uniquely identify the auto-overlay definition.
241 Each REGEXP defines one of the regexps that make up the auto-overlay
242 definition. It should be a list of the form
243 (RGXP &optional :edge EDGE :id SUBENTRY-ID @rest PROPERTY1 PROPERTY2 ...)
244 The `:edge' property should be one of the symbols `'start' or
245 `'end', and determines which edge of the auto-overlay this regexp
246 corresponds to. If `:edge' is not specified, it is assumed to be
247 `'start'. Auto-overlay classes that do not require separate `start' and
248 `end' regexps ignore this property. The `:id' property should be a
249 symbol that can be used to uniquely identify the regexp. Any further
250 elements in the list are cons cells of the form `(property . value)',
251 where PROPERTY is an overlay property name (a symbol) and VALUE its
252 value. In its simplest form, RGXP is a single regular expression.
254 If only part of the regexp should act as the delimeter (*note
255 Overview::), RGXP should instead be a cons cell:
257 where RX is a regexp that contains at least one group (*note Regular
258 Expressions: (elisp)Regular Expressions.), and GROUP is an integer
259 identifying which group should act as the delimeter.
261 If the overlay class requires additional groups to be specified,
262 RGXP should instead be a list:
263 (RX GROUP0 GROUP1 ...)
264 where RX is a regexp. The first GROUP0 still specifies the part that
265 acts as the delimeter, as before. If the entire regexp should act as
266 the delimeter, GROUP0 must still be supplied but should be set to 0
267 (meaning the entire regexp). None of the standard classes make use of
268 any additional groups, but extensions to the auto-overlays package that
269 define new classes may. *Note Extending the Auto-Overlays Package::.
271 The following functions are used to load and unload regexp
274 `(auto-overlay-load-definition SET-ID DEFINITION &optional POS)'
275 Load a new auto-overlay DEFINITION, which should be a list of the
276 form described above, into the set identified by the symbol
277 SET-ID. The optional parameter POS determines where in the set's
278 regexp list the new regexp is inserted. If it is `nil', the regexp
279 is added at the end. If it is `t', the regexp is added at the
280 beginning. If it is an integer, the regexp is added at that
281 position in the list. Whilst the position in the list has no
282 effect on overlay behaviour, it does determine the order in which
283 regexps are checked, so can affect efficiency.
285 `(auto-overlay-load-regexp SET-ID ENTRY-ID REGEXP &optional POS)'
286 Load a new REGEXP, which should be a list of the form described
287 above, into the auto-overlay definition identified by the symbol
288 ENTRY-ID, in the set identified by the symbol SET-ID. REGEXP
289 should be a list of the form described above. The optional POS
290 determines the position of the regexp in the list of regexps
291 defining the auto-overlay, which can be significant for overlay
292 behaviour since it determines which regexp takes precedence when
293 two match the same text.
295 `(auto-overlay-unload-set SET-ID)'
296 Unload the entire regexp set identified by the symbol SET-ID.
298 `(auto-overlay-unload-definition SET-ID ENTRY-ID)'
299 Unload the auto-overlay definition identified by the symbol
300 ENTRY-ID from the set identified by the symbol SET-ID.
302 `(auto-overlay-unload-regexp SET-ID ENTRY-ID SUBENTRY-ID)'
303 Unload the auto-overlay regexp identified by the symbol
304 SUBENTRY-ID from the auto-overlay definition identified by the
305 symbol ENTRY-ID in the set identified by the symbol SET-ID.
307 `(auto-overlay-share-regexp-set SET-ID FROM-BUFFER @optional TO-BUFFER)'
308 Share the set of regexp definitions identified by the symbol
309 SET-ID in buffer `from-buffer' with the buffer TO-BUFFER, or the
310 current buffer if TO-BUFFER is null. The regexp set becomes common
311 to both buffers, and any changes made to it in one buffer, such as
312 loading and unloading regexp definitions, are also reflected in
313 the other buffer. However, the regexp set can still be enabled and
314 disabled independently in both buffers. The same regexp set can be
315 shared between any number of buffers. To remove a shared regexp
316 set from one of the buffers, simply unload the entire set from that
317 buffer using `auto-overlay-unload-regexp'. The regexp set will
318 remain defined in all the other buffers it was shared with.
321 File: auto-overlay-manual.info, Node: Starting and Stopping Auto-Overlays, Next: Searching for Overlays, Prev: Defining Regexps, Up: Auto-Overlay Functions
323 2.2 Starting and Stopping Auto-Overlays
324 =======================================
326 A set of regexps is not active until it has been "started", and can be
327 deactivated by "stopping" it. When a regexp set is activated, the
328 entire buffer is scanned for regexp matches, and the corresponding
329 overlays created. Similarly, when a set is deactivated, all the overlays
330 are deleted. Note that regexp definitions can be loaded and unloaded
331 whether the regexp set is active or inactive, and that deactivating a
332 regexp set does _not_ delete its regexp definitions.
334 Since scanning the whole buffer for regexp matches can take some
335 time, especially for large buffers, auto-overlay data can be saved to an
336 auxiliary file so that the overlays can be restored more quickly if the
337 same regexp set is subsequently re-activated. Of course, if either the
338 text in the buffer or the overlay definitions are modified whilst the
339 regexp set is disabled, then the saved data will be out of date.
340 Auto-overlays automatically checks whether the text or overlay
341 definitions have been modified since the data was saved. If so, it
342 ignores the saved data and re-scans the buffer.
344 The usual time to save and restore overlay data is when a regexp set
345 is deactivated or activated. The auxilliary file name is then
346 constructed automatically from the buffer name and the set-id. However,
347 auto-overlays can also be saved and restored manually.
349 `(auto-overlay-start SET-ID @optional BUFFER SAVE-FILE NO-REGEXP-CHECK)'
350 Activate the auto-overlay regexp set identified by the symbol
351 SET-ID in BUFFER, or the current buffer if the latter is `nil'. If
352 there is a file called `auto-overlay-'BUFFER-NAME`-'SET-ID
353 containing up-to-date overlay data, it will be used to restore the
354 auto-overlays (BUFFER-NAME is the name of the file visited by the
355 buffer, or the buffer name itself if there is none). Otherwise,
356 the entire buffer will be scanned for regexp matches.
358 The string SAVE-FILE specifies the where to look for the file of
359 saved overlay data. If it is nil, it defaults to the current
360 directory. If it is a string specifying a relative path, then it is
361 relative to the current directory, whereas an absolute path
362 specifies exactly where to look. If it is a string specifying a
363 file name (with or without a full path, relative or absolute),
364 then it overrides the default file name and/or location. Any other
365 value of SAVE-FILE will cause the file of overlay data to be
366 ignored, even if it exists.
368 If the overlays are being loaded from a file, but optional argument
369 no-regexp-check is non-nil, the file of saved overlays will be
370 used, but no check will be made to ensure regexp refinitions are
371 the same as when the overlays were saved.
373 `(auto-overlay-stop SET-ID @optional BUFFER SAVE-FILE LEAVE-OVERLAYS)'
374 Deactivate the auto-overlay regexp set identified by the symbol
375 SET-ID in BUFFER, or the current buffer if the latter is `nil'.
376 All corresponding overlays will be deleted (unless the
377 LEAVE-OVERLAYS option is non-nil, which should only be used if the
378 buffer is about to be killed), but the regexp definitions are
379 preserved and can be reactivated later.
381 If SAVE-FILE is non-nil, overlay data will be saved in an
382 auxilliary file called `auto-overlay-'BUFFER-NAME`-'SET-ID in the
383 current directory, to speed up subsequent reactivation of the
384 regexp set in the same buffer (BUFFER-NAME is the name of the file
385 visited by the buffer, or the buffer name itself if there is
386 none). If SAVE-FILE is a string, it overrides the default save
387 location, overriding either the directory if it only specifies a
388 path (relative paths are relative to the current directory), or
389 the file name if it only specifies a filename, or both if it
390 specifies a full path.
392 `(auto-overlay-save-overlays SET-ID @optional BUFFER FILE)'
393 Save auto-overlay data for the regexp set identified by the symbol
394 SET-ID in BUFFER, or the current buffer if `nil', to an auxilliary
395 file called FILE. If FILE is nil, the overlay data are saved to a
396 file called `auto-overlay-'BUFFER-NAME`-'SET-ID in the current
397 directory (BUFFER-NAME is the name of the file visited by the
398 buffer, or the buffer name itself if it's not visiting a file). If
399 `file' is a directory name (either an absolute path or relative to
400 the current directory), the overlay data are saved to the default
401 file name under that directory.
403 `(auto-overlay-load-overlays SET-ID @optional BUFFER FILE NO-REGEXP-CHECK)'
404 Load auto-overlay data for the regexp set identified by the symbol
405 SET-ID into BUFFER, or the current buffer if `nil', from an
406 auxilliary file called FILE. If FILE is nil, it attempts to load
407 the overlay data from a file called
408 `auto-overlay-'BUFFER-NAME`-'SET-ID in the current directory
409 (BUFFER-NAME is the name of the file visited by the buffer, or the
410 buffer name itself if it's not visiting a file). If `file' is a
411 directory name (either an absolute path or relative to the current
412 directory), it attempts to load the overlay data from the default
413 file name under that directory. If NO-REGEXP-CHECK is no-nil, the
414 saved overlays will be loaded even if different regexp definitions
415 were active when the overlays were saved. Returns `t' if the
416 overlays were successfully loaded, `nil' otherwise.
419 File: auto-overlay-manual.info, Node: Searching for Overlays, Prev: Starting and Stopping Auto-Overlays, Up: Auto-Overlay Functions
421 2.3 Searching for Overlays
422 ==========================
424 Auto-overlays are just normal Emacs overlays, so any of the standard
425 Emacs functions can be used to search for overlays and retrieve overlay
426 properties. The auto-overlays package provides some additional
429 `(auto-overlays-at-point @optional POINT PROP-TEST INACTIVE)'
430 Return a list of overlays overlapping POINT, or the point if POINT
431 is null. The list includes _all_ overlays, not just auto-overlays
432 (but see below). The list can be filtered to only return overlays
433 with properties matching criteria specified by PROP-TEST. This
434 should be a list defining a property test, with one of the
435 following forms (or a list of such lists, if more than one
436 property test is required):
438 (FUNCTION PROPERTY VALUE)
439 (FUNCTION (PROPERTY1 PROPERTY2 ...) (VALUE1 VALUE2 ...))
440 where FUNCTION is a function, PROPERTY is an overlay property name
441 (a symbol), and VALUE can be any value or lisp expression. For
442 each overlay, first the values corresponding to the PROPERTY names
443 are retrieved from the overlay and any VALUEs that are lisp
444 expressions are evaluated. Then FUNCTION is called with the
445 property values followed by the other values as its arguments. The
446 test is satisfied if the result is non-nil, otherwise it fails.
447 Tests are evaluated in order, but only up to the first failure.
448 Only overlays that satisfy all property tests are returned.
450 All auto-overlays are given a non-nil `auto-overlay' property, so
451 to restrict the list to auto-overlays, PROP-TEST should include
452 the following property test:
453 ('identity 'auto-overlay)
454 For efficiency reasons, the auto-overlays package sometimes leaves
455 overlays hanging around in the buffer even when they should have
456 been deleted. These are marked with a non-nil `inactive' property.
457 By default, `auto-overlays-at-point' ignores these. A non-nil
458 INACTIVE will override this, causing inactive overlays to be
459 included in the returned list (assuming they pass all property
462 `(auto-overlays-in START END @optional PROP-TEST WITHIN INACTIVE)'
463 Return a list of overlays overlapping the region between START and
464 END. The PROP-TEST and INACTIVE arguments have the same behaviour
465 as in `auto-overlays-at-point', above. If WITHIN is non-nil, only
466 overlays that are entirely within the region from START to END
467 will be returned, not overlays that extend outside that region.
469 `(auto-overlay-highest-priority-at-point @optional POINT PROP-TEST)'
470 Return the highest priority overlay at POINT (or the point, if
471 POINT is null). The PROP-TEST argument has the same behaviour as
472 in `auto-overlays-at-point', above. An overlay's priority is
473 determined by the value of its `priority' property (*note Overlay
474 Properties: (elisp)Overlay Properties.). If two overlays have the
475 same priority, the innermost one takes precedence (i.e. the one
476 that begins later in the buffer, or if they begin at the same
477 point the one that ends earlier; if two overlays have the same
478 priority and extend over the same region, there is no way to
479 predict which will be returned).
481 `(auto-overlay-local-binding SYMBOL @optional POINT)'
482 Return the "overlay-local" binding of SYMBOL at POINT (or the
483 point if POINT is null), or the current local binding if there is
484 no overlay binding. An "overlay-local" binding for SYMBOL is the
485 value of the overlay property called SYMBOL. If more than one
486 overlay at POINT has a non-nil SYMBOL property, the value from the
487 highest priority overlay is returned (see
488 `auto-overlay-highest-priority-at-point', above, for an
489 explanation of "highest priority").
492 File: auto-overlay-manual.info, Node: Worked Example, Next: Extending the Auto-Overlays Package, Prev: Auto-Overlay Functions, Up: Top
497 The interaction of all the different regexp definitions, overlay
498 properties and auto-overlay classes provided by the auto-overlays
499 package can be a little daunting. This section will go through an
500 example of how the auto-overlay regexps could be defined to create
501 overlays for a subset of LaTeX, which is complex enough to demonstrate
502 most of the features.
504 LaTeX is a markup language, so a LaTeX document combines markup
505 commands with normal text. Commands start with `\', and end at the
506 first non-word-constituent character. We want to highlight all LaTeX
507 commands in blue. Two commands that will particularly interest us are
508 `\begin' and `\end', which begin and end a LaTeX environment. The
509 environment name is enclosed in braces: `\begin{ENVIRONMENT-NAME}', and
510 we want it to be highlighted in pink. LaTeX provides many environments,
511 used to create lists, tables, titles, etc. We will take the example of
512 an `equation' environment, used to typeset mathematical equations. Thus
513 equations are enclosed by `\begin{equation}' and `\end{equation}', and
514 we would like to highlight these equations in yellow. Another example
515 we will use is the `$' delimiter. Pairs of `$'s delimit mathematical
516 expressions that appear in the middle of a paragraph of normal text
517 (whereas `equation' environments appear on their own, slightly
518 separated from surrounding text). Again, we want to highlight these
519 mathematical expressions, this time in green. The final piece of LaTeX
520 markup we will need to consider is the `%' character, which creates a
521 comment that lasts till the end of the line (i.e. text after the `%' is
522 ignored by the LaTeX processor up to the end of the line).
524 LaTeX commands are a good example of when to use `word' regular
525 expressions (*note Overview::). The appropriate regexp definition is
528 (auto-overlay-load-definition
530 '(word ("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)"
531 (face . (background-color . "blue")))))
533 We have called the regexp set `latex'. The `face' property is a
534 standard Emacs overlay property that sets font properties within the
535 overlay. *Note Overlay Properties: (elisp)Overlay Properties. `"\\\\"'
536 is the string defining the regexp that matches a _single_ `\'. (Note
537 that the `\' character has a special meaning in regular expressions, so
538 to include a literal one it must be escaped: `\\'. However, `\' also
539 has a special meaning in lisp strings, so both `\' characters must be
540 escaped there too, giving `\\\\'.) `[[:alpha:]]*?' matches a sequence
541 of zero or more letter characters. The `?' ensures that it matches the
542 _shortest_ sequence of letters consistent with matching the regexp,
543 since we want the region to end at the first non-letter character,
544 matched by `[^[:alpha:]]'. The `\|' defines an alternative, to allow
545 the LaTeX command to be terminated either by a non-letter character or
546 by the end of the line (`$'). *Note Regular Expressions: (elisp)Regular
547 Expressions, for more details on Emacs regular expressions.
549 However, there's a small problem. We only want the blue background to
550 cover the characters making up a LaTeX command. But as we've defined
551 things so far, it will cover all the text matched by the regexp, which
552 includes the leading `\' and the trailing non-letter character. To
553 rectify this, we need to group the part of the regexp that matches the
554 command (i.e. by surround it with `\(' and `\)'), and put the regexp
555 inside a cons cell containing the regexp in its `car' and a number
556 indicating which subgroup to use in its `cdr':
558 (auto-overlay-load-definition
560 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
561 (face . (background-color . "blue")))))
563 The `$' delimiter is an obvious example of when to use a `self'
564 regexp (*note Overview::). We can update our example to include this
565 (note that `$' also has a special meaning in regular expressions, so it
566 must be escaped with `\' which itself must be escaped in lisp strings):
568 (auto-overlay-load-definition
570 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
571 (face . (background-color . "blue")))))
573 (auto-overlay-load-definition
575 '(self ("\\$" (face . (background-color . "green")))))
577 This won't quite work though. LaTeX maths commands also start with a
578 `\' character, which will match the `word' regexp. For the sake of
579 example we want the entire equation highlighted in green, without
580 highlighting any LaTeX maths commands it contains in blue. Since the
581 `word' overlay will be within the `self' overlay, the blue highlighting
582 will take precedence. We can change this by giving the `self' overlay a
583 higher priority (any priority is higher than a non-existent one; we use
584 3 here for later convenience). For efficiency reasons, it's a good idea
585 to put higher priority regexp definitions before lower priority ones,
588 (auto-overlay-load-definition
590 '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
592 (auto-overlay-load-definition
594 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
595 (face . (background-color . "blue")))))
597 The `\begin{equation}' and `\end{equation}' commands also enclose
598 maths regions, which we would like to highlight in yellow. Since the
599 opening and closing delimiters are different in this case, we must use
600 `nested' overlays (*note Overview::). Our example now looks like:
602 (auto-overlay-load-definition
604 '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
606 (auto-overlay-load-definition
612 (face . (background-color . "yellow")))
616 (face . (background-color . "yellow")))))
618 (auto-overlay-load-definition
620 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
621 (face . (background-color . "blue")))))
623 Notice how we've used separate `start' and `end' regexps to define the
624 auto-overlay. Once again, we have had to escape the `\' characters, and
625 increase the priority of the new regexp definition to avoid any LaTeX
626 commands within the maths region being highlighted in blue.
628 LaTeX comments start with `%' and last till the end of the line: a
629 perfect demonstration of a `line' regexp. Here's a first attempt:
631 (auto-overlay-load-definition
633 '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
635 (auto-overlay-load-definition
641 (face . (background-color . "yellow")))
645 (face . (background-color . "yellow")))))
647 (auto-overlay-load-definition
649 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
650 (face . (background-color . "blue")))))
652 (auto-overlay-load-definition
654 `(line ("%" (face . (background-color
655 . ,(face-attribute 'default :background))))))
657 We use the standard Emacs `face-attribute' function to retrieve the
658 default background colour, which is evaluated before the regexp
659 definition is loaded. (This will of course go wrong if the default
660 background colour is subsequently changed, but it's sufficient for this
661 example). Let's think about this a bit. We probably don't want anything
662 within a comment to be highlighted at all, even if it matches one of the
663 other regexps. In fact, creating overlays for `\begin' and `\end'
664 commands which are within a comment could cause havoc! If they don't
665 occur in pairs within the commented region, they will erroneously pair
666 up with ones outside the comment. We need comments to take precedence
667 over everything else, and we need them to block other regexp matches,
668 so we boost the overlay's priority and set the exclusive property:
670 (auto-overlay-load-definition
672 `(line ("%" (priority . 4) (exclusive . t)
673 (face . (background-color
674 . ,(face-attribute 'default :background))))))
676 (auto-overlay-load-definition
678 '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
680 (auto-overlay-load-definition
686 (face . (background-color . "yellow")))
690 (face . (background-color . "yellow")))))
692 (auto-overlay-load-definition
694 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
695 (face . (background-color . "blue")))))
697 We're well on our way to creating a useful setup, at least for the
698 LaTeX commands we're considering in this example. There is one last
699 type of overlay to create, but it is the most complicated. We want
700 environment names to be highlighted in pink, i.e. the region between
701 `\begin{' and `}'. A first attempt at this might result in:
703 (auto-overlay-load-definition
705 `(line ("%" (priority . 4) (exclusive . t)
706 (face . (background-color
707 . ,(face-attribute 'default :background))))))
709 (auto-overlay-load-definition
711 '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
713 (auto-overlay-load-definition
719 (face . (background-color . "pink")))
723 (face . (background-color . "pink")))))
725 (auto-overlay-load-definition
731 (face . (background-color . "yellow")))
735 (face . (background-color . "yellow")))))
737 (auto-overlay-load-definition
739 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
740 (face . (background-color . "blue")))))
742 However, we'll hit a problem with this. The `}' character also closes
743 the `\end{' command. Since we haven't told auto-overlays about `\end{',
744 every `}' that should close an `\end{' command will instead be
745 interpreted as the end of a `\start{' command, probably resulting in
746 lots of unmatched `}' characters, creating pink splodges everywhere!
747 Clearly, since we also want environment names between `\end{' and `}'
748 to be pink, we need something more along the lines of:
750 (auto-overlay-load-definition
752 `(line ("%" (priority . 4) (exclusive . t)
753 (face . (background-color
754 . ,(face-attribute 'default :background))))))
756 (auto-overlay-load-definition
758 '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
760 (auto-overlay-load-definition
766 (face . (background-color . "pink")))
770 (face . (background-color . "pink")))
774 (face . (background-color . "pink")))))
776 (auto-overlay-load-definition
782 (face . (background-color . "yellow")))
786 (face . (background-color . "yellow")))))
788 (auto-overlay-load-definition
790 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
791 (face . (background-color . "blue")))))
793 We still haven't solved the problem though. The `}' character doesn't
794 only close `\begin{' and `\end{' commands in LaTeX. _All_ arguments to
795 LaTeX commands are surrounded by `{' and `}'. We could add all the
796 commands that take arguments, but we don't really want to bother about
797 any other commands (at least in this example). All we want to do is
798 prevent predictive mode incorrectly pairing the `}' characters used for
799 other commands. Instead, we can just add `{' to the list:
801 (auto-overlay-load-definition
803 `(line ("%" (priority . 4) (exclusive . t)
804 (face . (background-color
805 . ,(face-attribute 'default :background))))))
807 (auto-overlay-load-definition
809 '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
811 (auto-overlay-load-definition
820 (face . (background-color . "pink")))
824 (face . (background-color . "pink")))
829 (auto-overlay-load-definition
835 (face . (background-color . "yellow")))
839 (face . (background-color . "yellow")))))
841 (auto-overlay-load-definition
843 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
844 (face . (background-color . "blue")))))
846 Notice how the `{' and `}' regexps do not define a background colour
847 (or indeed any other properties), so that any overlays they create will
848 have no effect other than making sure all `{' and `}' characters are
851 We've made one mistake though: by putting the `{' regexp at the
852 beginning of the list, it will take priority over any other regexp in
853 the list that could match the same text. And since `{' will match
854 whenever `\begin{' or `\end{' matches, environments will never be
855 highlighted! The `{' regexp must come _after_ the `\begin{' and `\end{'
856 regexps, to ensure it is only used if neither of them match (it doesn't
857 matter whether it appears before or after the `{' regexp, since the
858 latter will never match the same text):
860 (auto-overlay-load-definition
862 `(line ("%" (priority . 4) (exclusive . t)
863 (face . (background-color
864 . ,(face-attribute 'default :background))))))
866 (auto-overlay-load-definition
868 '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
870 (auto-overlay-load-definition
876 (face . (background-color . "pink")))
880 (face . (background-color . "pink")))
888 (auto-overlay-load-definition
894 (face . (background-color . "yellow")))
898 (face . (background-color . "yellow")))))
900 (auto-overlay-load-definition
902 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
903 (face . (background-color . "blue")))))
905 There is one last issue. A literal `{' or `}' character can be
906 included in a LaTeX document by escaping it with `\': `\{' and `\}'. In
907 this situation, the characters do not match anything and should not be
908 treated as delimiters. We can modify the `{' and `}' regexps to exclude
911 (auto-overlay-load-definition
913 `(line ("%" (priority . 4) (exclusive . t)
914 (face . (background-color
915 . ,(face-attribute 'default :background))))))
917 (auto-overlay-load-definition
919 '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
921 (auto-overlay-load-definition
927 (face . (background-color . "pink")))
931 (face . (background-color . "pink")))
939 (auto-overlay-load-definition
945 (face . (background-color . "yellow")))
949 (face . (background-color . "yellow")))))
951 (auto-overlay-load-definition
953 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
954 (face . (background-color . "blue")))))
956 The new, complicated-looking regexps will only match `{' and `}'
957 characters if they are _not_ preceded by a `\' character (*note Regular
958 Expressions: (elisp)Regular Expressions.). Note that the character
959 alternative `[^\]\|^' can match any character that isn't a `\' _or_ the
960 start of a line. This is required because matches to auto-overlay
961 regexps are not allowed to span more than one line. If `{' or `}'
962 appear at the beginning of a line, there will be no character in front
963 (the newline character doesn't count, since it isn't on the same line),
964 so the `[^\]' will not match.
966 However, when it does match, the `}' regexp will now match an
967 additional character before the `}', causing the overlay to end one
968 character early. (The `{' regexp will also match one additional
969 character before the `{', but since the beginning of the overlay starts
970 from the _end_ of the `start' delimiter, this poses less of a problem.)
971 We need to group the part of the regexp that should define the
972 delimiter, i.e. the `}', by surrounding it with `\(' and `\)', and put
973 the regexp in the `car' of a cons cell whose `cdr' specifies the new
974 subgroup (i.e. the 2nd subgroup, since the regexp already included a
975 group for other reasons; we could alternatively replace the original
976 group by a shy-group, since we don't actually need to capture match
977 data for that group). Our final version looks like this:
979 (auto-overlay-load-definition
981 `(line ("%" (priority . 4) (exclusive . t)
982 (face . (background-color
983 . ,(face-attribute 'default :background))))))
985 (auto-overlay-load-definition
987 '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
989 (auto-overlay-load-definition
995 (face . (background-color . "pink")))
999 (face . (background-color . "pink")))
1003 (("\\([^\\]\\|^\\)\\(}\\)" . 2)
1007 (auto-overlay-load-definition
1010 ("\\begin{equation}"
1013 (face . (background-color . "yellow")))
1017 (face . (background-color . "yellow")))))
1019 (auto-overlay-load-definition
1021 '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
1022 (face . (background-color . "blue")))))
1024 With these regexp definitions, LaTeX commands will automatically be
1025 highlighted in blue, equation environments in yellow, inline maths
1026 commands in green, and environment names in pink. LaTeX markup within
1027 comments will be ignored. And `{' and `}' characters from other
1028 commands will be correctly taken into account. All this is done in
1029 "real-time"; it doesn't wait until Emacs is idle to update the
1030 overlays. Not bad for a bundle of regexps!
1032 Of course, this could all be done more easily using Emacs' built-in
1033 syntax highlighting features, but the highlighting was only an example
1034 to show the location of the overlays. The main point is that the
1035 overlays are automatically created and kept up to date, and can be given
1036 any properties you like and used for whatever purpose is required by
1040 File: auto-overlay-manual.info, Node: Extending the Auto-Overlays Package, Next: To-Do, Prev: Worked Example, Up: Top
1042 4 Extending the Auto-Overlays Package
1043 *************************************
1045 The auto-overlays package can easily be extended by adding new overlay
1046 classes(1). The next sections document the functions and interfaces
1047 provided by the auto-overlays package for this purpose.
1049 Often, a new class is a minor modification of one of the standard
1050 classes. For example, it may work exactly like one of the standard
1051 classes, but in addition call some function whenever an overlay is
1052 created or destroyed. In this case, it is far better to build the new
1053 class on top of the existing class, using functions from the
1054 class-specific Elisp files, rather than starting from scratch. *Note
1055 Standard Parse and Suicide Functions::.
1059 * Auto-Overlays in Depth::
1060 * Integrating New Overlay Classes::
1061 * Functions for Writing New Overlay Classes::
1062 * Auto-Overlay Hooks::
1063 * Auto-Overlay Modification Pseudo-Hooks::
1065 ---------- Footnotes ----------
1067 (1) Or rather, it is easy to integrate new overlay classes into the
1068 package. Whether writing a new overlay class is easy or not depends on
1069 what you're trying to do, and how good your coding skills are ;-)
1072 File: auto-overlay-manual.info, Node: Auto-Overlays in Depth, Next: Integrating New Overlay Classes, Up: Extending the Auto-Overlays Package
1074 4.1 Auto-Overlays in Depth
1075 ==========================
1077 In order to write new classes, a deeper understanding is required of how
1078 the auto-overlays package works. In fact, two kinds of overlays are
1079 automatically created, updated and destroyed when auto-overlays are
1080 active: the auto-overlays themselves, and "match" overlays, used to
1081 mark text that matches an auto-overlay regexp.
1083 For overlay classes that only require one regexp to fully define an
1084 overlay (the `word' and `line' classes are the only standard classes
1085 like this(1)), the auto-overlays are always matched with the
1086 corresponding match overlay. For classes that require two regexp
1087 matches to define the start and end of an overlay (all other standard
1088 classes), each edge of an auto-overlay can be matched with a match
1089 overlay. The match overlays define where the edge of the auto-overlay
1090 is located. There will always be at least one matched edge, since an
1091 auto-overlay is only created when a regexp match is found, but it is
1092 possible for the second edge to not yet be matched (for many classes,
1093 the unmatched edge will be located at the beginning or end of the
1096 If a match overlay delimits the start of an auto-overlay, the match
1097 overlay is stored in the auto-overlay's `start' property. The match
1098 overlay is also stored in the `start' property for auto-overlays that
1099 only require a single match. If a match overlay delimits the end of an
1100 auto-overlay, the match overlay is stored in the auto-overlay's `end'
1101 property. Conversely, a "link" to the auto-overlay is always stored in
1102 the match overlay's `parent' property(2).
1104 Whenever a buffer is modified, the lines containing the modifications
1105 are scanned for new regexp matches. If one is found, a new match overlay
1106 is created covering the matching text, and then passed as an argument to
1107 the appropriate "parse" function(3) for its class. This deals with
1108 creating or updating the auto-overlays, as appropriate. If the text
1109 within a match overlay is modified, the match overlay checks whether
1110 the text it covers still matches the regexp. If it no longer matches,
1111 the match overlay is passed as an argument to the appropriate "suicide"
1112 function for its class, which deals with updating or deleting its
1113 parent auto-overlay (and possibly more besides).
1115 To summarise, the core of the auto-overlays package deals with
1116 searching for regexp matches, and creating or deleting the
1117 corresponding match overlays. It then hands over the task of creating,
1118 updating or deleting the auto-overlays themselves to class-specific
1119 functions, which implement the correct behaviour for that class.
1121 ---------- Footnotes ----------
1123 (1) Although the `self' class only requires one regexp definition,
1124 the auto-overlays themselves require two matches to that same regexp to
1125 set the start and end of the overlay.
1127 (2) The "parent" terminology is admittedly very poor, and is a relic
1128 of a previous incarnation of the auto-overlays package, when it made
1131 (3) More bad terminology.
1134 File: auto-overlay-manual.info, Node: Integrating New Overlay Classes, Next: Functions for Writing New Overlay Classes, Prev: Auto-Overlays in Depth, Up: Extending the Auto-Overlays Package
1136 4.2 Integrating New Overlay Classes
1137 ===================================
1139 To add a new overlay class, all that is required is to write new
1140 "parse" and "suicide" functions, and inform the auto-overlays package
1141 of their existence. A "match" function can also optionally be defined.
1142 It is called whenever a match overlay in the class becomes matched with
1143 the edge of an auto-overlay (*note Functions for Modifying Overlays::).
1144 The parse, suicide and match functions are conventionally called
1145 `auto-o-parse-'CLASS`-match', `auto-o-'CLASS`-suicide' and
1146 `auto-o-match-'CLASS, where CLASS is the name of the class, though the
1147 convention is not enforced in any way.
1150 A parse function is passed a single argument containing a match
1151 overlay. It should return a list containing any new auto-overlays
1152 it creates, or `nil' if none were created.
1153 O-LIST = (auto-o-parse-CLASS-match O-MATCH)
1154 Note that the parse function itself is responsible for calling the
1155 `auto-o-update-exclusive' function if a new exclusive overlay is
1156 created. *Note Functions for Modifying Overlays::.
1159 A suicide function is passed a single argument containing a match
1160 overlay. Its return value is ignored.
1161 (auto-o-CLASS-suicide O-MATCH)
1162 The text covered by the match overlay should be considered to no
1163 longer match its regexp, although in certain cases matches are
1164 ignored for other reasons and this may not really be the case (for
1165 example if a new, higher-priority, exclusive overlay overlaps the
1166 match, *note Overview::).
1169 A match function is passed a single argument containing a match
1170 overlay that has just been matched with an edge of an auto-overlay
1171 (*note Functions for Modifying Overlays::). Its return value is
1173 (auto-o-match-CLASS O-MATCH)
1174 The auto-overlay it is matched with is stored in the match
1175 overlay's `parent' property.
1177 To integrate the new class into the auto-overlays package, the parse
1178 and suicide functions must be added to the property list of the symbol
1179 used to refer to the new class, denoted here by CLASS:
1180 (put 'CLASS 'auto-overlay-parse-function
1181 'auto-o-parse-CLASS-match)
1182 (put 'CLASS 'auto-overlay-suicide-function
1183 'auto-o-CLASS-suicide)
1184 If the optional match function is defined, it should similarly be
1185 added to the symbol's property list:
1186 (put 'CLASS 'auto-overlay-match-function
1187 'auto-o-match-CLASS)
1190 File: auto-overlay-manual.info, Node: Functions for Writing New Overlay Classes, Next: Auto-Overlay Hooks, Prev: Integrating New Overlay Classes, Up: Extending the Auto-Overlays Package
1192 4.3 Functions for Writing New Overlay Classes
1193 =============================================
1195 Some functions are provided by the auto-overlays package for use in new
1196 parse and suicide functions. The functions that modify overlays carry
1197 out tasks that require interaction with the core of the auto-overlays
1198 package, and provide the only reliable way of carrying out those tasks.
1199 The other functions are used to query various things about
1200 auto-overlays and match overlays. Again, they are the only reliable
1201 interface for this, since the internal implementation may change between
1202 releases of the auto-overlays package.
1206 * Standard Parse and Suicide Functions::
1207 * Functions for Modifying Overlays::
1208 * Functions for Querying Overlays::
1211 File: auto-overlay-manual.info, Node: Standard Parse and Suicide Functions, Next: Functions for Modifying Overlays, Up: Functions for Writing New Overlay Classes
1213 4.3.1 Standard Parse and Suicide Functions
1214 ------------------------------------------
1216 All the standard overlay classes define their own parse and suicide
1217 functions (none of them require a match function), which can be used to
1218 create new "derived" classes based on the standard ones. This is the
1219 easiest and most common way to create a new class. For example, the new
1220 class may behave exactly like one of the standard classes, but perform
1221 some additional processing whenever an overlay is created, destroyed, or
1222 matched. The parse and suicide functions for the new class should
1223 perform whatever additional processing is required, and call the
1224 standard class functions to deal with creating and destroying the
1227 All the standard parse and suicide functions follow the same naming
1228 convention (*note Integrating New Overlay Classes::), where CLASS is
1229 the name of the overlay class (one of `word', `line', `self', `nested'
1230 or `flat', *note Overview::):
1232 `(auto-o-parse-CLASS-match O-MATCH)'
1233 Parse a new match overlay O-MATCH whose class is CLASS. This will
1234 create or update auto-overlays, as appropriate for the class.
1236 `(auto-o-CLASS-suicide O-MATCH)'
1237 Delete or update auto-overlays as appropriate for overlay class
1238 CLASS, due to the match overlay O-MATCH no longer matching.
1241 File: auto-overlay-manual.info, Node: Functions for Modifying Overlays, Next: Functions for Querying Overlays, Prev: Standard Parse and Suicide Functions, Up: Functions for Writing New Overlay Classes
1243 4.3.2 Functions for Modifying Overlays
1244 --------------------------------------
1246 These functions modify auto-overlays and match overlays as necessary to
1247 perform a particular update. They should _always_ be used to carry out
1248 their corresponding tasks, rather than doing it separately, since these
1249 tasks require interaction with the core of the auto-overlays package.
1251 `(auto-o-update-exclusive SET-ID BEG END OLD-PRIORITY NEW-PRIORITY)'
1252 Update the region between BEG and END in the current buffer as
1253 necessary due to the priority of an exclusive overlay overlapping
1254 the region changing from OLD-PRIORITY to NEW-PRIORITY. If the
1255 exclusive overlay did not previously overlap the region,
1256 OLD-PRIORITY should be null. If it no longer overlaps the region,
1257 NEW-PRIORITY should be null. (If both are null, nothing will
1258 happen!) The return value is meaningless.
1260 `(auto-o-match-overlay OVERLAY START @optional END NO-PROPS NO-PARSE PROTECT-MATCH)'
1261 Match or unmatch the start and end of the auto-overlay OVERLAY,
1262 update all appropriate properties (such as `parent', `start' and
1263 `end' properties, and any properties specified in regexp
1264 definitions), and update other auto-overlays in the region covered
1265 by OVERLAY as necessary (usually because the `exclusive' or
1266 `priority' properties of OVERLAY have changed).
1268 If START or END are match overlays, match the corresponding edge
1269 of OVERLAY. The edge is moved to the location defined by the match
1270 overlay, and the `parent' property of the match overlay and the
1271 `start' and `end' properties of OVERLAY are updated accordingly.
1272 The START argument should be a match overlay corresponding either
1273 to the unique regexp if only one is needed for that overlay class,
1274 or to a start regexp if the overlay class uses separate start and
1275 end regexps. The END argument should then be a match overlay
1276 corresponding to an end regexp in the same class (*note
1277 Overview::). You're responsible for enforcing this; no check is
1280 If START or END are numbers or markers, move the corresponding
1281 edge of OVERLAY to that location and set it as unmatched. The
1282 `start' or `end' property of OVERLAY and the `parent' property of
1283 any corresponding match overlay are set to `nil'. If START or END
1284 are non-nil but neither of the above, leave the corresponding edge
1285 of OVERLAY where it is, but set it unmatched (as described above).
1286 If START or END are null, don't change the corresponding edge.
1287 However, for convenience, if END is null but START is a match
1288 overlay corresponding to a match for an end-regexp, match the end
1289 of OVERLAY rather than the start.
1291 The remaining arguments disable some of the tasks normally carried
1292 out by `auto-o-match-overlay'. If NO-PROPS is non-nil, overlay
1293 properties specified in regexp definitions are ignored and not
1294 updated. If NO-PARSE is non-nil, auto-overlays in the region
1295 covered by OVERLAY are not updated, even if the `exclusive' or
1296 `priority' properties of OVERLAY have changed. If PROTECT-MATCH is
1297 non-nil, the `parent' properties of the START and END match
1298 overlays are left alone.
1300 `(auto-o-delete-overlay OVERLAY @optional NO-PARSE PROTECT-MATCH)'
1301 Delete auto-overlay OVERLAY from the buffer, and update overlays
1302 and overlay properties as necessary. The optional arguments disable
1303 parts of the updating process, as for `auto-o-match-overlay',
1307 File: auto-overlay-manual.info, Node: Functions for Querying Overlays, Prev: Functions for Modifying Overlays, Up: Functions for Writing New Overlay Classes
1309 4.3.3 Functions for Querying Overlays
1310 -------------------------------------
1312 These functions query certain things about auto-overlays or match
1313 overlays, or retrieve certain values associated with them. A few are
1314 merely convenience functions, but most depend on the internal
1315 implementation details of the auto-overlays package, and provide the
1316 only reliable interface for whatever they return.
1318 `(auto-o-class O-MATCH)'
1319 Return the class of match overlay O-MATCH.
1321 `(auto-o-regexp O-MATCH)'
1322 Return the regular expression matched by the text covered by match
1325 `(auto-o-regexp-group O-MATCH)'
1326 Return the regexp group defined in the regexp definition
1327 corresponding to match overlay O-MATCH (*note Defining Regexps::).
1329 `(auto-o-props O-MATCH)'
1330 Return the list of overlay properties defined in the regexp
1331 definition corresponding to match overlay O-MATCH (*note Defining
1334 `(auto-o-edge O-MATCH)'
1335 Return edge (the symbol `start' or `end') of match overlay O-MATCH.
1337 `(auto-o-parse-function O-MATCH)'
1338 Return appropriate parse function for match overlay O-MATCH.
1340 `(auto-o-suicide-function O-MATCH)'
1341 Return appropriate suicide function for match overlay O-MATCH.
1343 `(auto-o-match-function O-MATCH)'
1344 Return match function for match overlay O-MATCH, if any.
1346 `(auto-o-edge-matched-p OVERLAY EDGE)'
1347 Return non-nil if EDGE (the symbol `start' or `end') of
1348 auto-overlay `overlay' is matched.
1350 `(auto-o-start-matched-p OVERLAY)'
1351 Return non-nil if auto-overlay OVERLAY is start-matched.
1353 `(auto-o-end-matched-p OVERLAY)'
1354 Return non-nil if auto-overlay OVERLAY is end-matched.
1357 File: auto-overlay-manual.info, Node: Auto-Overlay Hooks, Next: Auto-Overlay Modification Pseudo-Hooks, Prev: Functions for Writing New Overlay Classes, Up: Extending the Auto-Overlays Package
1359 4.4 Auto-Overlay Hooks
1360 ======================
1362 The auto-overlays package defines two hooks, that are called when
1363 auto-overlays are enabled and disabled in a buffer. These are intended
1364 to be used by overlay classes to set up any extra buffer-local variables
1365 and settings they require, and clean them up afterwards. (There is no
1366 point leaving auto-overlay variables and settings hanging around in a
1367 buffer when auto-overlays are not in use.)
1369 `auto-overlay-load-hook'
1370 This hook is run when the first auto-overlay regexp set in a
1371 buffer is started, using the `auto-overlay-start' function. *Note
1372 Starting and Stopping Auto-Overlays::.
1374 `auto-overlay-unload-hook'
1375 This hook is run when the last auto-overlay regexp set in a buffer
1376 is stopped, using the `auto-overlay-stop' function. *Note Starting
1377 and Stopping Auto-Overlays::.
1380 File: auto-overlay-manual.info, Node: Auto-Overlay Modification Pseudo-Hooks, Prev: Auto-Overlay Hooks, Up: Extending the Auto-Overlays Package
1382 4.5 Auto-Overlay Modification Pseudo-Hooks
1383 ==========================================
1385 The auto-overlays package adds functions to buffer and overlay
1386 modification hooks in order to update the overlays as the buffer text is
1387 modified (*note Modification Hooks: (elisp)Modification Hooks.). The
1388 order in which all these modification hooks are called is undefined in
1389 Emacs(1). Therefore, the auto-overlays package provides a mechanism to
1390 schedule functions to run at particular points during the overlay
1393 There are two stages to the overlay update process: first, any match
1394 overlay suicide functions are called, then modified buffer lines are
1395 scanned for new regexp matches. Three pseudo-hooks are defined that are
1396 called before, after and in between these stages. Their values are lists
1397 containing elements of the form:
1398 (FUNCTION ARG1 ARG2 ...)
1399 where FUNCTION is the function to be called by the hook, and the
1400 ARG's are the arguments to be passed to that function. The list
1401 elements are evaluated in order. The pseudo-hooks are cleared each time
1402 after they have been called.
1404 `auto-o-pending-pre-suicide'
1405 Pseudo-hook called before any suicide functions.
1407 `auto-o-pending-post-suicide'
1408 Pseudo-hook called after any suicide functions but before scanning
1411 `auto-o-pending-post-update'
1412 Pseudo-hook called after scanning for regexp matches.
1414 These pseudo-hooks can be used to ensure that a function that would
1415 normally be added to a modification hook will be called at a particular
1416 point in the auto-overlay update process. To achieve this, a helper
1417 function must be added to the modification hook instead. The helper
1418 function should add the function itself to the appropriate pseudo-hook
1419 by adding a list element with the form described above. The `push' and
1420 `add-to-list' Elisp functions are the most useful ways to add elements
1423 ---------- Footnotes ----------
1425 (1) Or at least undocumented, and therefore unreliable.
1428 File: auto-overlay-manual.info, Node: To-Do, Next: Function Index, Prev: Extending the Auto-Overlays Package, Up: Top
1433 Things that still need to be implemented (in no particular order):
1435 1. There needs to be an `eager-self' overlay class, similar to the
1436 existing `self' class but updated immediately, rather than waiting
1437 for buffer modifications. This will be significantly less
1438 efficient, but is necessary for applications that require overlays
1439 to be up to date all the time, not just when the buffer is being
1442 2. Currently, it's difficult to deal with `nested' class regexps for
1443 which the `end' regexps match some `start' regexps of interest but
1444 also others that are irrelevant. E.g. `{' and `}' in LaTeX when
1445 you're only interested in `\somecommand{' `start' regexps. Or
1446 matching parens in LISP, when you're only interested in function
1447 bodies, say. The only solution is to include all `start' regexps,
1448 but not set any of their properties. This can end up creating a
1449 lot of overlays! A variant of the `nested' class that avoids this
1453 File: auto-overlay-manual.info, Node: Function Index, Next: Variable Index, Prev: To-Do, Up: Top
1455 Appendix A Function Index
1456 *************************