2 An Emacs overlay demarcates a region of text in a buffer, often
3 giving it a different face or changing other properties for that
4 region. There are many circumstance in which it might be useful to
5 create, update, and delete overlays automatically when text matches
6 some criterion, specified for example by regular expressions. This is
7 what the auto-overlays package addresses. It is intended as an Elisp
8 library, providing functions to be used by other Elisp packages, so
9 does not itself define any new interactive commands or minor modes.
11 This documentation is an extract from the extensive Auto Overlays
12 Manual that comes with the package. For more detailed information and
13 examples, please read the manual.
19 The auto-overlays package automatically creates, updates and destroys
20 overlays based on regular expression matches in the buffer text. The
21 overlay is created when text is typed that matches an auto-overlay
22 regexp, and is destroyed if and when the matching text is changed so
23 that it no longer matches.
25 The regexps are grouped into sets, and any number of different sets
26 of regexps can be active in the same buffer simultaneously. Regexps in
27 different sets are completely independent, and each set can be activated
28 and deactivated independently (*note Defining Regexps::). This allows
29 different Emacs modes to simultaneously make use of auto-overlays in the
32 There are different "classes" of auto-overlay, used to define
33 different kinds of overlay behaviour. Some classes only require a single
34 regexp, others require separate regexps to define the start and end of
35 the overlay (*note Defining Regexps::). Any additional regexps, beyond
36 the minimum requirements, act as alternatives; if more than one of the
37 regexps matches overlapping regions of text, the one that appears
38 earlier in the list will take precedence. The predefined regexp classes
39 are: `word', `line', `self', `nested' and `flat', but the auto-overlay
40 package can easily be extended with new classes.
43 These are used to define overlays that cover the text matched by
44 the regexp itself, so require a single regexp. An example use
45 would be to create overlays covering single words.
48 These are used to define overlays that stretch from the text
49 matching the regexp to the end of the line, and require a single
50 regexp to define the start of the overlay. An example use would be
51 to create overlays covering single-line comments in programming
55 These are used to define overlays that stretch from one regexp
56 match to the next match for the same regexp, so naturally require
57 a single regexp. An example use would be to create overlays
58 covering strings delimited by `""'.
60 Note that for efficiency reasons, `self' overlays are _not_ fully
61 updated when a new match is found. Instead, when a modification is
62 subsequently made at any position in the buffer after the new
63 match, the overlays are updated _up to_ that position. The update
64 occurs just _before_ the modification is made. Therefore, the
65 overlays at a given buffer position will not necessarily be
66 correct until a modification is made at or after that position
70 These are used to define overlays that start and end at different
71 regexp matches, and that can be nested one inside another. This
72 class requires separate start and end regexps. An example use
73 would be to create overlays between matching braces `{}'.
76 These are used to define overlays that start and end at different
77 regexp matches, but that can not be nested. Extra start matches
78 within one of these overlays are ignored. This class requires
79 separate start and end regexps. An example use would be to create
80 overlays covering multi-line comments in code, e.g. c++ block
81 comments delimited by `/*' and `*/'.
83 By default, the entire text matching a regexp acts as the
84 "delimeter". For example, a `word' overlay will cover all the text
85 matching its regexp, and a `nested' overlay will start at the end of
86 the text matching its start regexp. Sometimes it is useful to be able
87 to have only part of the regexp match act as the delimeter. This can be
88 done by grouping that part of the regexp (*note Defining Regexps::).
89 Overlays will then start and end at the text matching the group,
90 instead of the text matching the entire regexp.
92 Of course, automatically creating overlays isn't much use without
93 some way of setting their properties too. Overlay properties can be
94 defined along with the regexp, and are applied to any overlays created
95 by a match to that regexp. Certain properties have implications for
96 auto-overlay behaviour.
99 This is a standard Emacs overlay property (*note Overlay
100 Properties: (elisp)Overlay Properties.), but it is also used to
101 determine which regexp takes precedence when two or more regexps
102 in the same auto-overlay definition match overlapping regions of
103 text. It is also used to determine which regexp's properties take
104 precedence for overlays that are defined by separate start and end
108 Normally, different auto-overlay regexps coexist, and act
109 completely independently of one-another. However, if an
110 auto-overlay has non-nil `exclusive' and `priority' properties,
111 regexp matches within the overlay are ignored if they have lower
112 priority. An example use is ignoring other regexp matches within
116 2 Auto-Overlay Functions
117 ************************
119 To use auto-overlays in an Elisp package, you must load the overlay
120 classes that you require by including lines of the form
121 (require 'auto-overlay-CLASS)
122 near the beginning of your package, where CLASS is the class name.
123 The standard classes are: `word', `line', `self', `nested' and `flat'
124 (*note Overview::), though new classes can easily be added (*note
125 Extending the Auto-Overlays Package::).
127 Sometimes it is useful for a package to make use of auto-overlays if
128 any are defined, without necessarily requiring them. To facilitate
129 this, the relevant functions can be loaded separately from the rest of
130 the auto-overlays package with the line
131 (require 'auto-overlay-common)
132 This provides all the functions related to searching for overlays and
133 retrieving overlay properties. *Note Searching for Overlays::. Note that
134 there is no need to include this line if any auto-overlay classes are
135 `require'd, though it will do no harm.
137 This section describes the functions that are needed in order to make
138 use of auto-overlays in an Elisp package. It does _not_ describe
139 functions related to extending the auto-overlays package. *Note
140 Extending the Auto-Overlays Package::.
145 An auto-overlay definition is a list of the form:
146 (CLASS &optional :id ENTRY-ID REGEXP1 REGEXP2 ...)
147 CLASS is one of the regexp classes described in the previous section
148 (*note Overview::). The optional `:id' property should be a symbol that
149 can be used to uniquely identify the auto-overlay definition.
151 Each REGEXP defines one of the regexps that make up the auto-overlay
152 definition. It should be a list of the form
153 (RGXP &optional :edge EDGE :id SUBENTRY-ID @rest PROPERTY1 PROPERTY2 ...)
154 The `:edge' property should be one of the symbols `'start' or
155 `'end', and determines which edge of the auto-overlay this regexp
156 corresponds to. If `:edge' is not specified, it is assumed to be
157 `'start'. Auto-overlay classes that do not require separate `start' and
158 `end' regexps ignore this property. The `:id' property should be a
159 symbol that can be used to uniquely identify the regexp. Any further
160 elements in the list are cons cells of the form `(property . value)',
161 where PROPERTY is an overlay property name (a symbol) and VALUE its
162 value. In its simplest form, RGXP is a single regular expression.
164 If only part of the regexp should act as the delimeter (*note
165 Overview::), RGXP should instead be a cons cell:
167 where RX is a regexp that contains at least one group (*note Regular
168 Expressions: (elisp)Regular Expressions.), and GROUP is an integer
169 identifying which group should act as the delimeter.
171 If the overlay class requires additional groups to be specified,
172 RGXP should instead be a list:
173 (RX GROUP0 GROUP1 ...)
174 where RX is a regexp. The first GROUP0 still specifies the part that
175 acts as the delimeter, as before. If the entire regexp should act as
176 the delimeter, GROUP0 must still be supplied but should be set to 0
177 (meaning the entire regexp). None of the standard classes make use of
178 any additional groups, but extensions to the auto-overlays package that
179 define new classes may. *Note Extending the Auto-Overlays Package::.
181 The following functions are used to load and unload regexp
184 `(auto-overlay-load-definition SET-ID DEFINITION &optional POS)'
185 Load a new auto-overlay DEFINITION, which should be a list of the
186 form described above, into the set identified by the symbol
187 SET-ID. The optional parameter POS determines where in the set's
188 regexp list the new regexp is inserted. If it is `nil', the regexp
189 is added at the end. If it is `t', the regexp is added at the
190 beginning. If it is an integer, the regexp is added at that
191 position in the list. Whilst the position in the list has no
192 effect on overlay behaviour, it does determine the order in which
193 regexps are checked, so can affect efficiency.
195 `(auto-overlay-load-regexp SET-ID ENTRY-ID REGEXP &optional POS)'
196 Load a new REGEXP, which should be a list of the form described
197 above, into the auto-overlay definition identified by the symbol
198 ENTRY-ID, in the set identified by the symbol SET-ID. REGEXP
199 should be a list of the form described above. The optional POS
200 determines the position of the regexp in the list of regexps
201 defining the auto-overlay, which can be significant for overlay
202 behaviour since it determines which regexp takes precedence when
203 two match the same text.
205 `(auto-overlay-unload-set SET-ID)'
206 Unload the entire regexp set identified by the symbol SET-ID.
208 `(auto-overlay-unload-definition SET-ID ENTRY-ID)'
209 Unload the auto-overlay definition identified by the symbol
210 ENTRY-ID from the set identified by the symbol SET-ID.
212 `(auto-overlay-unload-regexp SET-ID ENTRY-ID SUBENTRY-ID)'
213 Unload the auto-overlay regexp identified by the symbol
214 SUBENTRY-ID from the auto-overlay definition identified by the
215 symbol ENTRY-ID in the set identified by the symbol SET-ID.
217 `(auto-overlay-share-regexp-set SET-ID FROM-BUFFER @optional TO-BUFFER)'
218 Share the set of regexp definitions identified by the symbol
219 SET-ID in buffer `from-buffer' with the buffer TO-BUFFER, or the
220 current buffer if TO-BUFFER is null. The regexp set becomes common
221 to both buffers, and any changes made to it in one buffer, such as
222 loading and unloading regexp definitions, are also reflected in
223 the other buffer. However, the regexp set can still be enabled and
224 disabled independently in both buffers. The same regexp set can be
225 shared between any number of buffers. To remove a shared regexp
226 set from one of the buffers, simply unload the entire set from that
227 buffer using `auto-overlay-unload-regexp'. The regexp set will
228 remain defined in all the other buffers it was shared with.
230 2.2 Starting and Stopping Auto-Overlays
231 =======================================
233 A set of regexps is not active until it has been "started", and can be
234 deactivated by "stopping" it. When a regexp set is activated, the
235 entire buffer is scanned for regexp matches, and the corresponding
236 overlays created. Similarly, when a set is deactivated, all the overlays
237 are deleted. Note that regexp definitions can be loaded and unloaded
238 whether the regexp set is active or inactive, and that deactivating a
239 regexp set does _not_ delete its regexp definitions.
241 Since scanning the whole buffer for regexp matches can take some
242 time, especially for large buffers, auto-overlay data can be saved to an
243 auxiliary file so that the overlays can be restored more quickly if the
244 same regexp set is subsequently re-activated. Of course, if the text in
245 the buffer is modified whilst the regexp set is disabled, or the regexp
246 definitions differ from those that were active when the overlay data was
247 saved, the saved data will be out of date. Auto-overlays automatically
248 checks if the text has been modified and, if it has, ignores the saved
249 data and re-scans the buffer. However, no check is made to ensure the
250 regexp definitions used in the buffer and saved data are consistent
251 (*note To-Do::); the saved data will be used even if the definitions
254 The usual time to save and restore overlay data is when a regexp set
255 is deactivated or activated. The auxilliary file name is then
256 constructed automatically from the buffer name and the set-id. However,
257 auto-overlays can also be saved and restored manually.
259 `(auto-overlay-start SET-ID @optional BUFFER SAVE-FILE NO-REGEXP-CHECK)'
260 Activate the auto-overlay regexp set identified by the symbol
261 SET-ID in BUFFER, or the current buffer if the latter is `nil'. If
262 there is an file called `auto-overlay-'BUFFER-NAME`-'SET-ID in the
263 containing up-to-date overlay data, it will be used to restore the
264 auto-overlays (BUFFER-NAME is the name of the file visited by the
265 buffer, or the buffer name itself if there is none). Otherwise, the
266 entire buffer will be scanned for regexp matches.
268 The string SAVE-FILE specifies the where to look for the file of
269 saved overlay data. If it is nil, it defaults to the current
270 directory. If it is a string specifying a relative path, then it is
271 relative to the current directory, whereas an absolute path
272 specifies exactly where to look. If it is a string specifying a
273 file name (with or without a full path, relative or absolute),
274 then it overrides the default file name and/or location. Any other
275 value of SAVE-FILE will cause the file of overlay data to be
276 ignored, even if it exists.
278 If the overlays are being loaded from a file, but optional argument
279 no-regexp-check is non-nil, the file of saved overlays will be
280 used, but no check will be made to ensure regexp refinitions are
281 the same as when the overlays were saved.
283 `(auto-overlay-stop SET-ID @optional BUFFER SAVE-FILE LEAVE-OVERLAYS)'
284 Deactivate the auto-overlay regexp set identified by the symbol
285 SET-ID in BUFFER, or the current buffer if the latter is `nil'.
286 All corresponding overlays will be deleted (unless the
287 LEAVE-OVERLAYS option is non-nil, which should only be used if the
288 buffer is about to be killed), but the regexp definitions are
289 preserved and can be reactivated later.
291 If SAVE-FILE is non-nil, overlay data will be saved in an
292 auxilliary file called `auto-overlay-'BUFFER-NAME`-'SET-ID in the
293 current directory, to speed up subsequent reactivation of the
294 regexp set in the same buffer (BUFFER-NAME is the name of the file
295 visited by the buffer, or the buffer name itself if there is
296 none). If SAVE-FILE is a string, it overrides the default save
297 location, overriding either the directory if it only specifies a
298 path (relative paths are relative to the current directory), or
299 the file name if it only specifies a file name, or both.
301 `(auto-overlay-save-overlays SET-ID @optional BUFFER FILE)'
302 Save auto-overlay data for the regexp set identified by the symbol
303 SET-ID in BUFFER, or the current buffer if `nil', to an auxilliary
304 file called FILE. If FILE is nil, the overlay data are saved to a
305 file called `auto-overlay-'BUFFER-NAME`-'SET-ID in the current
306 directory (BUFFER-NAME is the name of the file visited by the
307 buffer, or the buffer name itself if there is none). Note that
308 this is the only name that will be recognized by
309 `auto-overlay-start'.
311 `(auto-overlay-load-overlays SET-ID @optional BUFFER FILE NO-REGEXP-CHECK)'
312 Load auto-overlay data for the regexp set identified by the symbol
313 SET-ID into BUFFER, or the current buffer if `nil', from an
314 auxilliary file called FILE. If FILE is nil, it attempts to load
315 the overlay data from a file called
316 `auto-overlay-'BUFFER-NAME`-'SET-ID in the current directory
317 (BUFFER-NAME is the name of the file visited by the buffer, or the
318 buffer name itself if there is none). If NO-REGEXP-CHECK is
319 no-nil, the saved overlays will be loaded even if different regexp
320 definitions were active when the overlays were saved. Returns `t'
321 if the overlays were successfully loaded, `nil' otherwise.
323 2.3 Searching for Overlays
324 ==========================
326 Auto-overlays are just normal Emacs overlays, so any of the standard
327 Emacs functions can be used to search for overlays and retrieve overlay
328 properties. The auto-overlays package provides some additional
331 `(auto-overlays-at-point @optional POINT PROP-TEST INACTIVE)'
332 Return a list of overlays overlapping POINT, or the point if POINT
333 is null. The list includes _all_ overlays, not just auto-overlays
334 (but see below). The list can be filtered to only return overlays
335 with properties matching criteria specified by PROP-TEST. This
336 should be a list defining a property test, with one of the
337 following forms (or a list of such lists, if more than one
338 property test is required):
340 (FUNCTION PROPERTY VALUE)
341 (FUNCTION (PROPERTY1 PROPERTY2 ...) (VALUE1 VALUE2 ...))
342 where FUNCTION is a function, PROPERTY is an overlay property name
343 (a symbol), and VALUE can be any value or lisp expression. For
344 each overlay, first the values corresponding to the PROPERTY names
345 are retrieved from the overlay and any VALUEs that are lisp
346 expressions are evaluated. Then FUNCTION is called with the
347 property values followed by the other values as its arguments. The
348 test is satisfied if the result is non-nil, otherwise it fails.
349 Tests are evaluated in order, but only up to the first failure.
350 Only overlays that satisfy all property tests are returned.
352 All auto-overlays are given a non-nil `auto-overlay' property, so
353 to restrict the list to auto-overlays, PROP-TEST should include
354 the following property test:
355 ('identity 'auto-overlay)
356 For efficiency reasons, the auto-overlays package sometimes leaves
357 overlays hanging around in the buffer even when they should have
358 been deleted. These are marked with a non-nil `inactive' property.
359 By default, `auto-overlays-at-point' ignores these. A non-nil
360 INACTIVE will override this, causing inactive overlays to be
361 included in the returned list (assuming they pass all property
364 `(auto-overlays-in START END @optional PROP-TEST WITHIN INACTIVE)'
365 Return a list of overlays overlapping the region between START and
366 END. The PROP-TEST and INACTIVE arguments have the same behaviour
367 as in `auto-overlays-at-point', above. If WITHIN is non-nil, only
368 overlays that are entirely within the region from START to END
369 will be returned, not overlays that extend outside that region.
371 `(auto-overlay-highest-priority-at-point @optional POINT PROP-TEST)'
372 Return the highest priority overlay at POINT (or the point, of
373 POINT is null). The PROP-TEST argument has the same behaviour as
374 in `auto-overlays-at-point', above. An overlay's priority is
375 determined by the value of its `priority' property (*note Overlay
376 Properties: (elisp)Overlay Properties.). If two overlays have the
377 same priority, the innermost one takes precedence (i.e. the one
378 that begins later in the buffer, or if they begin at the same
379 point the one that ends earlier; if two overlays have the same
380 priority and extend over the same region, there is no way to
381 predict which will be returned).
383 `(auto-overlay-local-binding SYMBOL @optional POINT)'
384 Return the "overlay-local" binding of SYMBOL at POINT (or the
385 point if POINT is null), or the current local binding if there is
386 no overlay binding. An "overlay-local" binding for SYMBOL is the
387 value of the overlay property called SYMBOL. If more than one
388 overlay at POINT has a non-nil SYMBOL property, the value from the
389 highest priority overlay is returned (see
390 `auto-overlay-highest-priority-at-point', above, for an
391 explanation of "highest priority").