\input texinfo @c -*-texinfo-*- @comment Documentation for the Emacs auto-overlays package @c %**start of header @setfilename auto-overlay-manual.info @settitle Emacs Auto-Overlays Manual @c %**end of header @dircategory Emacs @direntry * auto-overlays: (auto-overlay-manual). Automatic regexp-delimited overlays @end direntry @copying This manual describes the Emacs Auto-Overlays package, version 0.10.9 @c --version-- Copyright @copyright{} 2007-2015 Free Software Foundation, Inc @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". @end quotation @end copying @titlepage @title Emacs Auto-Overlays Manual @subtitle Version 0.10.9 @c --version-- @author Toby Cubitt @c Start copyright page @page @vskip 0pt plus 1filll @insertcopying @end titlepage @ifnottex @node Top @top Emacs Auto-Overlays Manual @insertcopying An Emacs overlay demarcates a region of text in a buffer, often giving it a different face or changing other properties for that region. There are many circumstance in which it might be useful to create, update, and delete overlays automatically when text matches some criterion, specified for example by regular expressions. This is what the auto-overlays package addresses. It is intended as an Elisp library, providing functions to be used by other Elisp packages, so does not itself define any new interactive commands or minor modes. @menu * Overview:: * Auto-Overlay Functions:: * Worked Example:: * Extending the Auto-Overlays Package:: * To-Do:: * Function Index:: * Variable Index:: * Concept Index:: * Copying this Manual:: @detailmenu --- The Detailed Node Listing --- Emacs Auto-Overlays Manual * Overview:: * Auto-Overlay Functions:: * Worked Example:: * Extending the Auto-Overlays Package:: * To-Do:: Auto-Overlay Functions * Defining Regexps:: * Starting and Stopping Auto-Overlays:: * Searching for Overlays:: Extending the Auto-Overlays Package * Auto-Overlays in Depth:: * Integrating New Overlay Classes:: * Functions for Writing New Overlay Classes:: * Auto-Overlay Hooks:: * Auto-Overlay Modification Pseudo-Hooks:: Functions for Writing New Overlay Classes * Functions for Modifying Overlays:: * Functions for Querying Overlays:: Copying this Manual * GNU Free Documentation License:: @end detailmenu @end menu @end ifnottex @contents @node Overview @chapter Overview @cindex Overview The auto-overlays package automatically creates, updates and destroys overlays based on regular expression matches in the buffer text. The overlay is created when text is typed that matches an auto-overlay regexp, and is destroyed if and when the matching text is changed so that it no longer matches. @cindex regexp sets @cindex sets of regexps The regexps are grouped into sets, and any number of different sets of regexps can be active in the same buffer simultaneously. Regexps in different sets are completely independent, and each set can be activated and deactivated independently (@pxref{Defining Regexps}). This allows different Emacs modes to simultaneously make use of auto-overlays in the same buffer. @cindex overlay classes @cindex classes of overlay There are different ``classes'' of auto-overlay, used to define different kinds of overlay behaviour. Some classes only require a single regexp, others require separate regexps to define the start and end of the overlay (@pxref{Defining Regexps}). Any additional regexps, beyond the minimum requirements, act as alternatives; if more than one of the regexps matches overlapping regions of text, the one that appears earlier in the list will take precedence. The predefined regexp classes are: @code{word}, @code{line}, @code{self}, @code{nested} and @code{flat}, but the auto-overlays package can easily be extended with new classes. @table @code @item word @cindex word overlay class @cindex overlay class, word @cindex class, word These are used to define overlays that cover the text matched by the regexp itself, so require a single regexp. An example use would be to create overlays covering single words. @item line @cindex line overlay class @cindex overlay class, line @cindex class, line These are used to define overlays that stretch from the text matching the regexp to the end of the line, and require a single regexp to define the start of the overlay. An example use would be to create overlays covering single-line comments in programming languages such as c. @item self @cindex self overlay class @cindex overlay class, self @cindex class, self These are used to define overlays that stretch from one regexp match to the next match for the same regexp, so naturally require a single regexp. An example use would be to create overlays covering strings delimited by @samp{""}. Note that for efficiency reasons, @code{self} overlays are @emph{not} fully updated when a new match is found. Instead, when a modification is subsequently made at any position in the buffer after the new match, the overlays are updated @emph{up to} that position. The update occurs just @emph{before} the modification is made. Therefore, the overlays at a given buffer position will not necessarily be correct until a modification is made at or after that position (@pxref{To-Do}). @item nested @cindex nested overlay class @cindex overlay class, nested @cindex class, nested These are used to define overlays that start and end at different regexp matches, and that can be nested one inside another. This class requires separate start and end regexps. An example use would be to create overlays between matching braces @samp{@{@}}. @item flat @cindex flat overlay class @cindex overlay class, flat @cindex class, flat These are used to define overlays that start and end at different regexp matches, but that can not be nested. Extra start matches within one of these overlays are ignored. This class requires separate start and end regexps. An example use would be to create overlays covering multi-line comments in code, e.g. c++ block comments delimited by @samp{/*} and @samp{*/}. @end table @cindex delimeter @cindex regexp groups @cindex grouping in regexps By default, the entire text matching a regexp acts as the ``delimeter''. For example, a @code{word} overlay will cover all the text matching its regexp, and a @code{nested} overlay will start at the end of the text matching its start regexp. Sometimes it is useful to be able to have only part of the regexp match act as the delimeter. This can be done by grouping that part of the regexp (@pxref{Defining Regexps}). Overlays will then start and end at the text matching the group, instead of the text matching the entire regexp. Of course, automatically creating overlays isn't much use without some way of setting their properties too. Overlay properties can be defined along with the regexp, and are applied to any overlays created by a match to that regexp. Certain properties have implications for auto-overlay behaviour: @table @code @item priority @cindex priority property @cindex overlay property, priority This is a standard Emacs overlay property (@pxref{Overlay Properties,,,elisp, GNU Emacs Lisp Reference Manual}), but it is also used to determine which regexp takes precedence when two or more regexps in the same auto-overlay definition match overlapping regions of text. It is also used to determine which regexp's properties take precedence for overlays that are defined by separate start and end matches. @item exclusive @cindex exclusive property @cindex overlay property, exclusive Normally, different auto-overlay regexps coexist, and act completely independently of one-another. However, if an auto-overlay has non-nil @code{exclusive} and @code{priority} properties, regexp matches within the overlay are ignored if they have lower priority. An example use is ignoring other regexp matches within comments in code. @end table @cindex overlay properties @node Auto-Overlay Functions @chapter Auto-Overlay Functions @cindex functions @cindex package, loading @cindex loading the package @cindex require @cindex using auto-overlays To use auto-overlays in an Elisp package, you must load the package by including a line of the form @lisp (require 'auto-overlays) @end lisp @noindent near the beginning of your package. This section describes the functions that are needed in order to make use of auto-overlays in an Elisp package. Functions related to extending the auto-overlays package are explained in a later section. @xref{Extending the Auto-Overlays Package}. @menu * Defining Regexps:: * Starting and Stopping Auto-Overlays:: * Searching for Overlays:: @end menu @node Defining Regexps @section Defining Regexps @cindex defining regexps @cindex regexps, defining @cindex regexps, loading and unloading @cindex functions, defining regexps @cindex functions, loading and unloading regexps An auto-overlay definition is a list of the form: @lisp (@var{class} &optional :id @var{entry-id} @var{regexp1} @var{regexp2} ...) @end lisp @var{class} is one of the regexp classes described in the previous section (@pxref{Overview}). The optional @code{:id} property should be a symbol that can be used to uniquely identify the auto-overlay definition. Each @var{regexp} defines one of the regexps that make up the auto-overlay definition. It should be a list of the form @lisp (@var{rgxp} &optional :id @var{subentry-id} :edge @var{edge} :exclusitve @var{exclusive} @@rest @var{property1} @var{property2} ...) @end lisp The optional @code{:id} property should be a symbol that can be used to uniquely identify the regexp. The @code{:edge} property should be one of the symbols @code{'start} or @code{'end}, and determines which edge of the auto-overlay this regexp corresponds to. If @code{:edge} is not specified, it is assumed to be @code{'start}. Auto-overlay classes that do not require separate @code{start} and @code{end} regexps ignore this property. The optional @code{exclusive} property specifies that this regexp matches exclusively; no lower-priority regexp is allowed to match the same text. (Contrast with the @code{exclusive} overlay property, which prevents any auto-overlay matches @emph{within} the auto-overlay itself. @pxref{Overview}) Any further elements in the list are cons cells of the form @code{(property . value)}, where @var{property} is an overlay property name (a symbol) and @var{value} its value. In its simplest form, @var{rgxp} is a single regular expression. If only part of the regexp should act as the delimeter (@pxref{Overview}), @var{rgxp} should instead be a cons cell: @lisp (@var{rx} . @var{group}) @end lisp @noindent where @var{rx} is a regexp that contains at least one group (@pxref{Regular Expressions,,,elisp, GNU Emacs Lisp Reference Manual}), and @var{group} is an integer identifying which group should act as the delimeter. If the overlay class requires additional groups to be specified, @var{rgxp} should instead be a list: @lisp (@var{rx} @var{group0} @var{group1} ...) @end lisp @noindent where @var{rx} is a regexp. The first @var{group0} still specifies the part that acts as the delimeter, as before. If the entire regexp should act as the delimeter, @var{group0} must still be supplied but should be set to 0 (meaning the entire regexp). None of the standard classes make use of any additional groups, but extensions to the auto-overlays package that define new classes may. @xref{Extending the Auto-Overlays Package}. The following functions are used to load and unload regexp definitions: @cindex defining regexps @cindex regexps, defining @cindex regexps, loading and unloading @cindex functions, defining regexps @cindex functions, loading and unloading regexps @table @code @item (auto-overlay-load-set @var{definitions}) @findex auto-overlay-load-set @cindex auto-overlay definitions @cindex auto-overlays, defining @cindex auto-overlays, loading @cindex loading auto-overlay definitions @cindex defining auto-overlays Load a new set of auto-overlay @var{definitions} into the set identified by the symbol @var{set-id}. @var{definitions} should be a list of definitions, each element being a definition of the form described above. @item (auto-overlay-load-definition @var{set-id} @var{definition} &optional @var{pos}) @findex auto-overlay-load-definition @cindex auto-overlay definitions @cindex auto-overlays, defining @cindex auto-overlays, loading @cindex loading auto-overlay definitions @cindex defining auto-overlays Load a new auto-overlay @var{definition}, which should be a list of the form described above, into the set identified by the symbol @var{set-id}. The optional parameter @var{pos} determines where in the set's regexp list the new regexp is inserted. If it is @code{nil}, the regexp is added at the end. If it is @code{t}, the regexp is added at the beginning. If it is an integer, the regexp is added at that position in the list. Whilst the position in the list has no effect on overlay behaviour, it does determine the order in which regexps are checked, so can affect efficiency. @item (auto-overlay-load-regexp @var{set-id} @var{entry-id} @var{regexp} &optional @var{pos}) @findex auto-overlay-load-regexp @cindex defining regexps @cindex loading regexps @cindex regexps, defining @cindex regexps, loading Load a new @var{regexp}, which should be a list of the form described above, into the auto-overlay definition identified by the symbol @var{entry-id}, in the set identified by the symbol @var{set-id}. @var{regexp} should be a list of the form described above. The optional @var{pos} determines the position of the regexp in the list of regexps defining the auto-overlay, which can be significant for overlay behaviour since it determines which regexp takes precedence when two match the same text. @item (auto-overlay-unload-set @var{set-id}) @findex auto-overlay-unload-set @cindex unloading regexp sets @cindex regexp sets, unloading @cindex auto-overlay definitions, unloading Unload the entire regexp set identified by the symbol @var{set-id}. @item (auto-overlay-unload-definition @var{set-id} @var{entry-id}) @findex auto-overlay-unload-definition @cindex unloading regexp definitions @cindex regexp definitions, unloading Unload the auto-overlay definition identified by the symbol @var{entry-id} from the set identified by the symbol @var{set-id}. @item (auto-overlay-unload-regexp @var{set-id} @var{entry-id} @var{subentry-id}) @findex auto-overlay-unload-regexp @cindex unloading regexps @cindex regexps, unloading Unload the auto-overlay regexp identified by the symbol @var{subentry-id} from the auto-overlay definition identified by the symbol @var{entry-id} in the set identified by the symbol @var{set-id}. @item (auto-overlay-share-regexp-set @var{set-id} @var{from-buffer} @@optional @var{to-buffer}) @findex auto-overlay-share-regexp-set @cindex sharing regexp sets @cindex regexp sets, sharing between buffers @cindex buffers, sharing regexp sets between Share the set of regexp definitions identified by the symbol @var{set-id} in buffer @code{from-buffer} with the buffer @var{to-buffer}, or the current buffer if @var{to-buffer} is null. The regexp set becomes common to both buffers, and any changes made to it in one buffer, such as loading and unloading regexp definitions, are also reflected in the other buffer. However, the regexp set can still be enabled and disabled independently in both buffers. The same regexp set can be shared between any number of buffers. To remove a shared regexp set from one of the buffers, simply unload the entire set from that buffer using @command{auto-overlay-unload-regexp}. The regexp set will remain defined in all the other buffers it was shared with. @end table @node Starting and Stopping Auto-Overlays @section Starting and Stopping Auto-Overlays @cindex starting and stopping auto-overlays @cindex regexp sets, starting and stopping @cindex saving overlays @cindex loading overlays @cindex overlays, starting and stopping @cindex overlays, saving and loading @cindex functions, starting and stopping overlays @cindex functions, loading and saving overlays A set of regexps is not active until it has been ``started'', and can be deactivated by ``stopping'' it. When a regexp set is activated, the entire buffer is scanned for regexp matches, and the corresponding overlays created. Similarly, when a set is deactivated, all the overlays are deleted. Note that regexp definitions can be loaded and unloaded whether the regexp set is active or inactive, and that deactivating a regexp set does @emph{not} delete its regexp definitions. Since scanning the whole buffer for regexp matches can take some time, especially for large buffers, auto-overlay data can be saved to an auxiliary file so that the overlays can be restored more quickly if the same regexp set is subsequently re-activated. Of course, if either the text in the buffer or the overlay definitions are modified whilst the regexp set is disabled, then the saved data will be out of date. Auto-overlays automatically checks whether the text or overlay definitions have been modified since the data was saved. If so, it ignores the saved data and re-scans the buffer. The usual time to save and restore overlay data is when a regexp set is deactivated or activated. The auxilliary file name is then constructed automatically from the buffer name and the set-id. However, auto-overlays can also be saved and restored manually. @table @code @item (auto-overlay-start @var{set-id} @@optional @var{buffer} @var{save-file} @var{no-regexp-check}) @findex auto-overlay-start Activate the auto-overlay regexp set identified by the symbol @var{set-id} in @var{buffer}, or the current buffer if the latter is @code{nil}. If there is a file called @file{auto-overlay-}@var{buffer-name}@file{-}@var{set-id} containing up-to-date overlay data, it will be used to restore the auto-overlays (@var{buffer-name} is the name of the file visited by the buffer, or the buffer name itself if there is none). Otherwise, the entire buffer will be scanned for regexp matches. The string @var{save-file} specifies the where to look for the file of saved overlay data. If it is nil, it defaults to the current directory. If it is a string specifying a relative path, then it is relative to the current directory, whereas an absolute path specifies exactly where to look. If it is a string specifying a file name (with or without a full path, relative or absolute), then it overrides the default file name and/or location. Any other value of @var{save-file} will cause the file of overlay data to be ignored, even if it exists. If the overlays are being loaded from a file, but optional argument no-regexp-check is non-nil, the file of saved overlays will be used, but no check will be made to ensure regexp refinitions are the same as when the overlays were saved. @item (auto-overlay-stop @var{set-id} @@optional @var{buffer} @var{save-file} @var{leave-overlays}) @findex auto-overlay-stop Deactivate the auto-overlay regexp set identified by the symbol @var{set-id} in @var{buffer}, or the current buffer if the latter is @code{nil}. All corresponding overlays will be deleted (unless the @var{leave-overlays} option is non-nil, which should only be used if the buffer is about to be killed), but the regexp definitions are preserved and can be reactivated later. If @var{save-file} is non-nil, overlay data will be saved in an auxilliary file called @file{auto-overlay-}@var{buffer-name}@file{-}@var{set-id} in the current directory, to speed up subsequent reactivation of the regexp set in the same buffer (@var{buffer-name} is the name of the file visited by the buffer, or the buffer name itself if there is none). If @var{save-file} is a string, it overrides the default save location, overriding either the directory if it only specifies a path (relative paths are relative to the current directory), or the file name if it only specifies a filename, or both if it specifies a full path. @item (auto-overlay-save-overlays @var{set-id} @@optional @var{buffer} @var{file}) @findex auto-overlay-save-overlays Save auto-overlay data for the regexp set identified by the symbol @var{set-id} in @var{buffer}, or the current buffer if @code{nil}, to an auxilliary file called @var{file}. If @var{file} is nil, the overlay data are saved to a file called @file{auto-overlay-}@var{buffer-name}@file{-}@var{set-id} in the current directory (@var{buffer-name} is the name of the file visited by the buffer, or the buffer name itself if it's not visiting a file). If @file{file} is a directory name (either an absolute path or relative to the current directory), the overlay data are saved to the default file name under that directory. @item (auto-overlay-load-overlays @var{set-id} @@optional @var{buffer} @var{file} @var{no-regexp-check}) @findex auto-overlay-load-overlays Load auto-overlay data for the regexp set identified by the symbol @var{set-id} into @var{buffer}, or the current buffer if @code{nil}, from an auxilliary file called @var{file}. If @var{file} is nil, it attempts to load the overlay data from a file called @file{auto-overlay-}@var{buffer-name}@file{-}@var{set-id} in the current directory (@var{buffer-name} is the name of the file visited by the buffer, or the buffer name itself if it's not visiting a file). If @file{file} is a directory name (either an absolute path or relative to the current directory), it attempts to load the overlay data from the default file name under that directory. If @var{no-regexp-check} is no-nil, the saved overlays will be loaded even if different regexp definitions were active when the overlays were saved. Returns @code{t} if the overlays were successfully loaded, @code{nil} otherwise. @end table @node Searching for Overlays @section Searching for Overlays @cindex searching for overlays @cindex finding overlays @cindex functions, searching for overlays @cindex overlays, finding @cindex overlay properties Auto-overlays are just normal Emacs overlays, so any of the standard Emacs functions can be used to search for overlays and retrieve overlay properties. The auto-overlays package provides some additional functions. @table @code @item (auto-overlays-at-point @@optional @var{point} @@key @var{inactive} @var{all-overlays} @@rest @var{prop-tests}) @findex auto-overlays-at-point Return a list of auto-overlays overlapping @var{point}, or the point if @var{point} is null. The list can be filtered to only return overlays with properties matching criteria specified by @var{prop-tests}. This should be a list defining a property test, with one of the following forms (or a list of such lists, if more than one property test is required): @lisp (@var{function} @var{property}) (@var{function} @var{property} @var{value}) (@var{function} (@var{property1} @var{property2} ...) (@var{value1} @var{value2} ...)) @end lisp @noindent where @var{function} is a function, @var{property} is an overlay property name (a symbol), and @var{value} can be any value or lisp expression. For each overlay, first the values corresponding to the @var{property} names are retrieved from the overlay and any @var{value}s that are lisp expressions are evaluated. Then @var{function} is called with the property values followed by the other values as its arguments. The test is satisfied if the result is non-nil, otherwise it fails. Tests are evaluated in order, but only up to the first failure. Only overlays that satisfy all property tests are returned. For efficiency reasons, the auto-overlays package sometimes leaves overlays hanging around in the buffer even when they should have been deleted. These are marked with a non-nil @code{inactive} property. By default, @command{auto-overlays-at-point} ignores these. A non-nil @var{inactive} keyword argument will override this, causing inactive overlays to be included in the returned list (assuming they pass all property tests). By default, @command{auto-overlays-at-point} only returns overlays created by the auto-overlays package. If you want to include @emph{all} overlays, pass a non-nil @var{all-overlays} keyword argument. @item (auto-overlays-in @var{start} @var{end} @@key @var{within} @var{inactive} @var{all-overlays} @@rest @var{prop-tests}) @findex auto-overlays-in Return a list of overlays overlapping the region between @var{start} and @var{end}. A non-nil @var{within} keyword argument, restricts the results to overlays that are entirely within the region from @var{start} to @var{end}, not overlays that extend outside that region. The remaining arguments are as for @command{auto-overlays-at-point}, above. @item (auto-overlay-highest-priority-at-point @@optional @var{point} @@key @var{inactive} @var{all-overlays} @@rest @var{prop-tests}) @findex auto-overlay-highest-priority-at-point @cindex overlays, priority @cindex highest priority overlay Return the highest priority overlay at @var{point} (or the point, if @var{point} is null). An overlay's priority is determined by the value of its @code{priority} property (@pxref{Overlay Properties,,,elisp, GNU Emacs Lisp Reference Manual}). If two overlays have the same priority, the innermost one takes precedence (i.e. the one that begins later in the buffer, or if they begin at the same point the one that ends earlier; if two overlays have the same priority and extend over the same region, there is no way to predict which will be returned). The remaining arguments are as for @command{auto-overlays-at-point}. @item (auto-overlay-local-binding @var{symbol} @@optional @var{point}) @findex auto-overlay-local-binding @cindex overlays, local-binding @cindex overlay-local binding @cindex local-binding Return the ``overlay-local'' binding of @var{symbol} at @var{point} (or the point if @var{point} is null), or the current local binding if there is no overlay binding. An ``overlay-local'' binding for @var{symbol} is the value of the overlay property called @var{symbol}. If more than one overlay at @var{point} has a non-nil @var{symbol} property, the value from the highest priority overlay is returned (see @command{auto-overlay-highest-priority-at-point}, above, for an explanation of ``highest priority''). @end table @node Worked Example @chapter Worked Example @cindex worked example @cindex example @cindex LaTeX The interaction of all the different regexp definitions, overlay properties and auto-overlay classes provided by the auto-overlays package can be a little daunting. This section will go through an example of how the auto-overlay regexps could be defined to create overlays for a subset of @LaTeX{}, which is complex enough to demonstrate most of the features. @LaTeX{} is a markup language, so a @LaTeX{} document combines markup commands with normal text. Commands start with @samp{\}, and end at the first non-word-constituent character. We want to highlight all @LaTeX{} commands in blue. Two commands that will particularly interest us are @samp{\begin} and @samp{\end}, which begin and end a @LaTeX{} environment. The environment name is enclosed in braces: @samp{\begin@{@var{environment-name}@}}, and we want it to be highlighted in pink. @LaTeX{} provides many environments, used to create lists, tables, titles, etc. We will take the example of an @samp{equation} environment, used to typeset mathematical equations. Thus equations are enclosed by @samp{\begin@{equation@}} and @samp{\end@{equation@}}, and we would like to highlight these equations in yellow. Another example we will use is the @samp{$} delimiter. Pairs of @samp{$}s delimit mathematical expressions that appear in the middle of a paragraph of normal text (whereas @samp{equation} environments appear on their own, slightly separated from surrounding text). Again, we want to highlight these mathematical expressions, this time in green. The final piece of @LaTeX{} markup we will need to consider is the @samp{%} character, which creates a comment that lasts till the end of the line (i.e. text after the @samp{%} is ignored by the @LaTeX{} processor up to the end of the line). @cindex word overlay class example @cindex example, word class @cindex overlay class, word example @cindex class, word example @LaTeX{} commands are a good example of when to use @code{word} regular expressions (@pxref{Overview}). The appropriate regexp definition is loaded by @lisp (auto-overlay-load-definition 'latex '(word ("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" (face . (background-color . "blue"))))) @end lisp @noindent We have called the regexp set @code{latex}. The @code{face} property is a standard Emacs overlay property that sets font properties within the overlay. @xref{Overlay Properties,,,elisp, GNU Emacs Lisp Reference Manual}. @code{"\\\\"} is the string defining the regexp that matches a @emph{single} @samp{\}. (Note that the @samp{\} character has a special meaning in regular expressions, so to include a literal one it must be escaped: @samp{\\}. However, @samp{\} also has a special meaning in lisp strings, so both @samp{\} characters must be escaped there too, giving @code{\\\\}.) @code{[[:alpha:]]*?} matches a sequence of zero or more letter characters. The @code{?} ensures that it matches the @emph{shortest} sequence of letters consistent with matching the regexp, since we want the region to end at the first non-letter character, matched by @code{[^[:alpha:]]}. The @code{\|} defines an alternative, to allow the @LaTeX{} command to be terminated either by a non-letter character or by the end of the line (@code{$}). @xref{Regular Expressions,,,elisp, GNU Emacs Lisp Reference Manual}, for more details on Emacs regular expressions. However, there's a small problem. We only want the blue background to cover the characters making up a @LaTeX{} command. But as we've defined things so far, it will cover all the text matched by the regexp, which includes the leading @samp{\} and the trailing non-letter character. To rectify this, we need to group the part of the regexp that matches the command (i.e. by surround it with @samp{\(} and @samp{\)}), and put the regexp inside a cons cell containing the regexp in its @code{car} and a number indicating which subgroup to use in its @code{cdr}: @lisp (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) @end lisp @cindex self overlay class example @cindex overlay class, self example @cindex example, self class @cindex class, self example The @samp{$} delimiter is an obvious example of when to use a @code{self} regexp (@pxref{Overview}). We can update our example to include this (note that @samp{$} also has a special meaning in regular expressions, so it must be escaped with @samp{\} which itself must be escaped in lisp strings): @lisp (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) (auto-overlay-load-definition 'latex '(self ("\\$" (face . (background-color . "green"))))) @end lisp @noindent This won't quite work though. @LaTeX{} maths commands also start with a @samp{\} character, which will match the @code{word} regexp. For the sake of example we want the entire equation highlighted in green, without highlighting any @LaTeX{} maths commands it contains in blue. Since the @code{word} overlay will be within the @code{self} overlay, the blue highlighting will take precedence. We can change this by giving the @code{self} overlay a higher priority (any priority is higher than a non-existent one; we use 3 here for later convenience). For efficiency reasons, it's a good idea to put higher priority regexp definitions before lower priority ones, so we get: @lisp (auto-overlay-load-definition 'latex '(self ("\\$" (priority . 3) (face . (background-color . "green"))))) (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) @end lisp @cindex nested overlay class example @cindex overlay class, nested example @cindex example, nested class @cindex class, nested example The @samp{\begin@{equation@}} and @samp{\end@{equation@}} commands also enclose maths regions, which we would like to highlight in yellow. Since the opening and closing delimiters are different in this case, we must use @code{nested} overlays (@pxref{Overview}). Our example now looks like: @lisp (auto-overlay-load-definition 'latex '(self ("\\$" (priority . 3) (face . (background-color . "green"))))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{equation@}" :edge start (priority . 1) (face . (background-color . "yellow"))) ("\\end@{equation@}" :edge end (priority . 1) (face . (background-color . "yellow"))))) (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) @end lisp @noindent Notice how we've used separate @code{start} and @code{end} regexps to define the auto-overlay. Once again, we have had to escape the @samp{\} characters, and increase the priority of the new regexp definition to avoid any @LaTeX{} commands within the maths region being highlighted in blue. @cindex line overlay class example @cindex overlay class, line example @cindex example, line class @cindex class, line example @LaTeX{} comments start with @samp{%} and last till the end of the line: a perfect demonstration of a @code{line} regexp. Here's a first attempt: @lisp (auto-overlay-load-definition 'latex '(self ("\\$" (priority . 3) (face . (background-color . "green"))))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{equation@}" :edge start (priority . 1) (face . (background-color . "yellow"))) ("\\end@{equation@}" :edge end (priority . 1) (face . (background-color . "yellow"))))) (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) (auto-overlay-load-definition 'latex `(line ("%" (face . (background-color . ,(face-attribute 'default :background)))))) @end lisp @noindent We use the standard Emacs @command{face-attribute} function to retrieve the default background colour, which is evaluated before the regexp definition is loaded. (This will of course go wrong if the default background colour is subsequently changed, but it's sufficient for this example). Let's think about this a bit. We probably don't want anything within a comment to be highlighted at all, even if it matches one of the other regexps. In fact, creating overlays for @samp{\begin} and @samp{\end} commands which are within a comment could cause havoc! If they don't occur in pairs within the commented region, they will erroneously pair up with ones outside the comment. We need comments to take precedence over everything else, and we need them to block other regexp matches, so we boost the overlay's priority and set the exclusive property: @lisp (auto-overlay-load-definition 'latex `(line ("%" (priority . 4) (exclusive . t) (face . (background-color . ,(face-attribute 'default :background)))))) (auto-overlay-load-definition 'latex '(self ("\\$" (priority . 3) (face . (background-color . "green"))))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{equation@}" :edge start (priority . 1) (face . (background-color . "yellow"))) ("\\end@{equation@}" :edge end (priority . 1) (face . (background-color . "yellow"))))) (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) @end lisp @cindex nested overlay class example @cindex overlay class, nested example @cindex example, nested class @cindex class, nested example We're well on our way to creating a useful setup, at least for the @LaTeX{} commands we're considering in this example. There is one last type of overlay to create, but it is the most complicated. We want environment names to be highlighted in pink, i.e. the region between @samp{\begin@{} and @samp{@}}. A first attempt at this might result in: @lisp (auto-overlay-load-definition 'latex `(line ("%" (priority . 4) (exclusive . t) (face . (background-color . ,(face-attribute 'default :background)))))) (auto-overlay-load-definition 'latex '(self ("\\$" (priority . 3) (face . (background-color . "green"))))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("@}" :edge end (priority . 2) (face . (background-color . "pink"))))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{equation@}" :edge start (priority . 1) (face . (background-color . "yellow"))) ("\\end@{equation@}" :edge end (priority . 1) (face . (background-color . "yellow"))))) (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) @end lisp @noindent However, we'll hit a problem with this. The @samp{@}} character also closes the @samp{\end@{} command. Since we haven't told auto-overlays about @samp{\end@{}, every @samp{@}} that should close an @samp{\end@{} command will instead be interpreted as the end of a @samp{\start@{} command, probably resulting in lots of unmatched @samp{@}} characters, creating pink splodges everywhere! Clearly, since we also want environment names between @samp{\end@{} and @samp{@}} to be pink, we need something more along the lines of: @lisp (auto-overlay-load-definition 'latex `(line ("%" (priority . 4) (exclusive . t) (face . (background-color . ,(face-attribute 'default :background)))))) (auto-overlay-load-definition 'latex '(self ("\\$" (priority . 3) (face . (background-color . "green"))))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("\\end@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("@}" :edge end (priority . 2) (face . (background-color . "pink"))))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{equation@}" :edge start (priority . 1) (face . (background-color . "yellow"))) ("\\end@{equation@}" :edge end (priority . 1) (face . (background-color . "yellow"))))) (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) @end lisp @noindent We still haven't solved the problem though. The @samp{@}} character doesn't only close @samp{\begin@{} and @samp{\end@{} commands in @LaTeX{}. @emph{All} arguments to @LaTeX{} commands are surrounded by @samp{@{} and @samp{@}}. We could add all the commands that take arguments, but we don't really want to bother about any other commands (at least in this example). All we want to do is prevent predictive mode incorrectly pairing the @samp{@}} characters used for other commands. Instead, we can just add @samp{@{} to the list: @lisp (auto-overlay-load-definition 'latex `(line ("%" (priority . 4) (exclusive . t) (face . (background-color . ,(face-attribute 'default :background)))))) (auto-overlay-load-definition 'latex '(self ("\\$" (priority . 3) (face . (background-color . "green"))))) (auto-overlay-load-definition 'latex '(nested ("@{" :edge start (priority . 2)) ("\\begin@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("\\end@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("@}" :edge end (priority . 2)))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{equation@}" :edge start (priority . 1) (face . (background-color . "yellow"))) ("\\end@{equation@}" :edge end (priority . 1) (face . (background-color . "yellow"))))) (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) @end lisp @noindent Notice how the @code{@{} and @code{@}} regexps do not define a background colour (or indeed any other properties), so that any overlays they create will have no effect other than making sure all @samp{@{} and @samp{@}} characters are correctly paired. We've made one mistake though: by putting the @code{@{} regexp at the beginning of the list, it will take priority over any other regexp in the list that could match the same text. And since @code{@{} will match whenever @code{\begin@{} or @code{\end@{} matches, environments will never be highlighted! The @code{@{} regexp must come @emph{after} the @code{\begin@{} and @code{\end@{} regexps, to ensure it is only used if neither of them match (it doesn't matter whether it appears before or after the @code{@{} regexp, since the latter will never match the same text): @lisp (auto-overlay-load-definition 'latex `(line ("%" (priority . 4) (exclusive . t) (face . (background-color . ,(face-attribute 'default :background)))))) (auto-overlay-load-definition 'latex '(self ("\\$" (priority . 3) (face . (background-color . "green"))))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("\\end@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("@{" :edge start (priority . 2)) ("@}" :edge end (priority . 2)))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{equation@}" :edge start (priority . 1) (face . (background-color . "yellow"))) ("\\end@{equation@}" :edge end (priority . 1) (face . (background-color . "yellow"))))) (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) @end lisp There is one last issue. A literal @samp{@{} or @samp{@}} character can be included in a @LaTeX{} document by escaping it with @samp{\}: @samp{\@{} and @samp{\@}}. In this situation, the characters do not match anything and should not be treated as delimiters. We can modify the @code{@{} and @code{@}} regexps to exclude these cases: @lisp (auto-overlay-load-definition 'latex `(line ("%" (priority . 4) (exclusive . t) (face . (background-color . ,(face-attribute 'default :background)))))) (auto-overlay-load-definition 'latex '(self ("\\$" (priority . 3) (face . (background-color . "green"))))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("\\end@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("\\([^\\]\\|^\\)@{" :edge start (priority . 2)) ("\\([^\\]\\|^\\)@}" :edge end (priority . 2)))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{equation@}" :edge start (priority . 1) (face . (background-color . "yellow"))) ("\\end@{equation@}" :edge end (priority . 1) (face . (background-color . "yellow"))))) (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) @end lisp @noindent The new, complicated-looking regexps will only match @samp{@{} and @samp{@}} characters if they are @emph{not} preceded by a @samp{\} character (@pxref{Regular Expressions,,,elisp,GNU Emacs Lisp Reference Manual}). Note that the character alternative @code{[^\]\|^} can match any character that isn't a @samp{\} @emph{or} the start of a line. This is required because matches to auto-overlay regexps are not allowed to span more than one line. If @samp{@{} or @samp{@}} appear at the beginning of a line, there will be no character in front (the newline character doesn't count, since it isn't on the same line), so the @code{[^\]} will not match. However, when it does match, the @code{@}} regexp will now match an additional character before the @code{@}}, causing the overlay to end one character early. (The @code{@{} regexp will also match one additional character before the @code{@{}, but since the beginning of the overlay starts from the @emph{end} of the @code{start} delimiter, this poses less of a problem.) We need to group the part of the regexp that should define the delimiter, i.e. the @code{@}}, by surrounding it with @code{\(} and @code{\)}, and put the regexp in the @code{car} of a cons cell whose @code{cdr} specifies the new subgroup (i.e. the 2nd subgroup, since the regexp already included a group for other reasons; we could alternatively replace the original group by a shy-group, since we don't actually need to capture match data for that group). Our final version looks like this: @lisp (auto-overlay-load-definition 'latex `(line ("%" (priority . 4) (exclusive . t) (face . (background-color . ,(face-attribute 'default :background)))))) (auto-overlay-load-definition 'latex '(self ("\\$" (priority . 3) (face . (background-color . "green"))))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("\\end@{" :edge start (priority . 2) (face . (background-color . "pink"))) ("\\([^\\]\\|^\\)@{" :edge start (priority . 2)) (("\\([^\\]\\|^\\)\\(@}\\)" . 2) :edge end (priority . 2)))) (auto-overlay-load-definition 'latex '(nested ("\\begin@{equation@}" :edge start (priority . 1) (face . (background-color . "yellow"))) ("\\end@{equation@}" :edge end (priority . 1) (face . (background-color . "yellow"))))) (auto-overlay-load-definition 'latex '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1) (face . (background-color . "blue"))))) @end lisp With these regexp definitions, @LaTeX{} commands will automatically be highlighted in blue, equation environments in yellow, inline maths commands in green, and environment names in pink. @LaTeX{} markup within comments will be ignored. And @samp{@{} and @samp{@}} characters from other commands will be correctly taken into account. All this is done in ``real-time''; it doesn't wait until Emacs is idle to update the overlays. Not bad for a bundle of regexps! Of course, this could all be done more easily using Emacs' built-in syntax highlighting features, but the highlighting was only an example to show the location of the overlays. The main point is that the overlays are automatically created and kept up to date, and can be given any properties you like and used for whatever purpose is required by your Elisp package. @node Extending the Auto-Overlays Package @chapter Extending the Auto-Overlays Package @cindex extending the auto-overlays package @cindex adding new overlay classes @cindex package, extending @cindex classes, adding new The auto-overlays package can easily be extended by adding new overlay classes@footnote{Or rather, it is easy to integrate new overlay classes into the package. Whether writing a new overlay class is easy or not depends on what you're trying to do, and how good your coding skills are ;-)}. The next sections document the functions and interfaces provided by the auto-overlays package for this purpose. Often, a new class is a minor modification of one of the standard classes. For example, it may work exactly like one of the standard classes, but in addition call some function whenever an overlay is created or destroyed. In this case, it is far better to build the new class on top of the existing class, using functions from the class-specific Elisp files, rather than starting from scratch. @xref{Standard Parse and Suicide Functions}. @menu * Auto-Overlays in Depth:: * Integrating New Overlay Classes:: * Functions for Writing New Overlay Classes:: * Auto-Overlay Hooks:: * Auto-Overlay Modification Pseudo-Hooks:: @end menu @node Auto-Overlays in Depth @section Auto-Overlays in Depth @cindex auto-overlays in depth @cindex package, in depth In order to write new classes, a deeper understanding is required of how the auto-overlays package works. In fact, two kinds of overlays are automatically created, updated and destroyed when auto-overlays are active: the auto-overlays themselves, and ``match'' overlays, used to mark text that matches an auto-overlay regexp. For overlay classes that only require one regexp to fully define an overlay (the @code{word} and @code{line} classes are the only standard classes like this@footnote{Although the @code{self} class only requires one regexp definition, the auto-overlays themselves require two matches to that same regexp to set the start and end of the overlay.}), the auto-overlays are always matched with the corresponding match overlay. For classes that require two regexp matches to define the start and end of an overlay (all other standard classes), each edge of an auto-overlay can be matched with a match overlay. The match overlays define where the edge of the auto-overlay is located. There will always be at least one matched edge, since an auto-overlay is only created when a regexp match is found, but it is possible for the second edge to not yet be matched (for many classes, the unmatched edge will be located at the beginning or end of the buffer). If a match overlay delimits the start of an auto-overlay, the match overlay is stored in the auto-overlay's @code{start} property. The match overlay is also stored in the @code{start} property for auto-overlays that only require a single match. If a match overlay delimits the end of an auto-overlay, the match overlay is stored in the auto-overlay's @code{end} property. Conversely, a ``link'' to the auto-overlay is always stored in the match overlay's @code{parent} property@footnote{The ``parent'' terminology is admittedly very poor, and is a relic of a previous incarnation of the auto-overlays package, when it made more sense.}. Whenever a buffer is modified, the lines containing the modifications are scanned for new regexp matches. If one is found, a new match overlay is created covering the matching text, and then passed as an argument to the appropriate ``parse'' function@footnote{More bad terminology.} for its class. This deals with creating or updating the auto-overlays, as appropriate. If the text within a match overlay is modified, the match overlay checks whether the text it covers still matches the regexp. If it no longer matches, the match overlay is passed as an argument to the appropriate ``suicide'' function for its class, which deals with updating or deleting its parent auto-overlay (and possibly more besides). To summarise, the core of the auto-overlays package deals with searching for regexp matches, and creating or deleting the corresponding match overlays. It then hands over the task of creating, updating or deleting the auto-overlays themselves to class-specific functions, which implement the correct behaviour for that class. @node Integrating New Overlay Classes @section Integrating New Overlay Classes @cindex integrating new overlay classes @cindex overlay classes, integrating new @cindex classes, integrating new @cindex extending, integrating new overlay classes To add a new overlay class, all that is required is to write new ``parse'' and ``suicide'' functions, and inform the auto-overlays package of their existence. A ``match'' function can also optionally be defined. It is called whenever a match overlay in the class becomes matched with the edge of an auto-overlay (@pxref{Functions for Modifying Overlays}). The parse, suicide and match functions are conventionally called @code{auto-o-parse-}@var{class}@code{-match}, @code{auto-o-}@var{class}@code{-suicide} and @code{auto-o-match-}@var{class}, where @var{class} is the name of the class, though the convention is not enforced in any way. @table @asis @item parse function @cindex parse function @cindex overlay classes, parse function @cindex functions, parse function @cindex integrating new classes, parse function @findex auto-o-parse-@{class@}-match A parse function is passed a single argument containing a match overlay. It should return a list containing any new auto-overlays it creates, or @code{nil} if none were created. @lisp @var{o-list} = (auto-o-parse-@var{class}-match @var{o-match}) @end lisp @noindent Note that the parse function itself is responsible for calling the @command{auto-o-update-exclusive} function if a new exclusive overlay is created. @xref{Functions for Modifying Overlays}. @item suicide function @cindex suicide function @cindex overlay classes, suicide function @cindex functions, suicide function @cindex integrating new classes, suicide function @findex auto-o-@{class@}-suicide A suicide function is passed a single argument containing a match overlay. Its return value is ignored. @lisp (auto-o-@var{class}-suicide @var{o-match}) @end lisp The text covered by the match overlay should be considered to no longer match its regexp, although in certain cases matches are ignored for other reasons and this may not really be the case (for example if a new, higher-priority, exclusive overlay overlaps the match, @pxref{Overview}). @item match function @cindex match function @cindex overlay classes, match function @cindex functions, match function @cindex integrating new classes, match function @findex auto-o-match-@{class@} A match function is passed a single argument containing a match overlay that has just been matched with an edge of an auto-overlay (@pxref{Functions for Modifying Overlays}). Its return value is ignored. @lisp (auto-o-match-@var{class} @var{o-match}) @end lisp @noindent The auto-overlay it is matched with is stored in the match overlay's @code{parent} property. @end table To integrate the new class into the auto-overlays package, the parse and suicide functions must be added to the property list of the symbol used to refer to the new class, denoted here by @var{class}: @lisp (put '@var{class} 'auto-overlay-parse-function 'auto-o-parse-@var{class}-match) (put '@var{class} 'auto-overlay-suicide-function 'auto-o-@var{class}-suicide) @end lisp @noindent If the optional match function is defined, it should similarly be added to the symbol's property list: @lisp (put '@var{class} 'auto-overlay-match-function 'auto-o-match-@var{class}) @end lisp @node Functions for Writing New Overlay Classes @section Functions for Writing New Overlay Classes @cindex functions, writing new overlay classes @cindex overlay classes, functions for writing new @cindex extending, functions Some functions are provided by the auto-overlays package for use in new parse and suicide functions. The functions that modify overlays carry out tasks that require interaction with the core of the auto-overlays package, and provide the only reliable way of carrying out those tasks. The other functions are used to query various things about auto-overlays and match overlays. Again, they are the only reliable interface for this, since the internal implementation may change between releases of the auto-overlays package. @menu * Standard Parse and Suicide Functions:: * Functions for Modifying Overlays:: * Functions for Querying Overlays:: @end menu @node Standard Parse and Suicide Functions @subsection Standard Parse and Suicide Functions @cindex standard parse and suicide functions @cindex overlay classes, standard parse functions @cindex overlay classes, standard suicide functions @cindex class, standard parse functions @cindex class, standard suicide functions @cindex extending, standard parse functions @cindex extending, standard suicide functions All the standard overlay classes define their own parse and suicide functions (none of them require a match function), which can be used to create new ``derived'' classes based on the standard ones. This is the easiest and most common way to create a new class. For example, the new class may behave exactly like one of the standard classes, but perform some additional processing whenever an overlay is created, destroyed, or matched. The parse and suicide functions for the new class should perform whatever additional processing is required, and call the standard class functions to deal with creating and destroying the overlay. All the standard parse and suicide functions follow the same naming convention (@pxref{Integrating New Overlay Classes}), where @var{class} is the name of the overlay class (one of @code{word}, @code{line}, @code{self}, @code{nested} or @code{flat}, @pxref{Overview}): @table @code @item (auto-o-parse-@var{class}-match @var{o-match}) @findex auto-o-parse-@{class@}-match Parse a new match overlay @var{o-match} whose class is @var{class}. This will create or update auto-overlays, as appropriate for the class. @item (auto-o-@var{class}-suicide @var{o-match}) @findex auto-o-@{class@}-suicide Delete or update auto-overlays as appropriate for overlay class @var{class}, due to the match overlay @var{o-match} no longer matching. @end table @node Functions for Modifying Overlays @subsection Functions for Modifying Overlays @cindex functions, modifying overlays @cindex overlays, functions for modifying @cindex extending, functions for modifying overlays These functions modify auto-overlays and match overlays as necessary to perform a particular update. They should @emph{always} be used to carry out their corresponding tasks, rather than doing it separately, since these tasks require interaction with the core of the auto-overlays package. @table @code @item (auto-o-update-exclusive @var{set-id} @var{beg} @var{end} @var{old-priority} @var{new-priority}) @findex auto-o-update-exclusive @cindex overlay property, exclusive @cindex exclusive property @cindex extending, updating exclusive @cindex updating exclusive regions Update the region between @var{beg} and @var{end} in the current buffer as necessary due to the priority of an exclusive overlay overlapping the region changing from @var{old-priority} to @var{new-priority}. If the exclusive overlay did not previously overlap the region, @var{old-priority} should be null. If it no longer overlaps the region, @var{new-priority} should be null. (If both are null, nothing will happen!) The return value is meaningless. @item (auto-o-match-overlay @var{overlay} @var{start} @@optional @var{end} @var{no-props} @var{no-parse} @var{protect-match}) @findex auto-o-match-overlays @cindex overlays, matching @cindex matching overlays @cindex extending, matching overlays Match or unmatch the start and end of the auto-overlay @var{overlay}, update all appropriate properties (such as @code{parent}, @code{start} and @code{end} properties, and any properties specified in regexp definitions), and update other auto-overlays in the region covered by @var{overlay} as necessary (usually because the @code{exclusive} or @code{priority} properties of @var{overlay} have changed). If @var{start} or @var{end} are match overlays, match the corresponding edge of @var{overlay}. The edge is moved to the location defined by the match overlay, and the @code{parent} property of the match overlay and the @code{start} and @code{end} properties of @var{overlay} are updated accordingly. The @var{start} argument should be a match overlay corresponding either to the unique regexp if only one is needed for that overlay class, or to a start regexp if the overlay class uses separate start and end regexps. The @var{end} argument should then be a match overlay corresponding to an end regexp in the same class (@pxref{Overview}). You're responsible for enforcing this; no check is made. If @var{start} or @var{end} are numbers or markers, move the corresponding edge of @var{overlay} to that location and set it as unmatched. The @code{start} or @code{end} property of @var{overlay} and the @code{parent} property of any corresponding match overlay are set to @code{nil}. If @var{start} or @var{end} are non-nil but neither of the above, leave the corresponding edge of @var{overlay} where it is, but set it unmatched (as described above). If @var{start} or @var{end} are null, don't change the corresponding edge. However, for convenience, if @var{end} is null but @var{start} is a match overlay corresponding to a match for an end-regexp, match the end of @var{overlay} rather than the start. The remaining arguments disable some of the tasks normally carried out by @command{auto-o-match-overlay}. If @var{no-props} is non-nil, overlay properties specified in regexp definitions are ignored and not updated. If @var{no-parse} is non-nil, auto-overlays in the region covered by @var{overlay} are not updated, even if the @code{exclusive} or @code{priority} properties of @var{overlay} have changed. If @var{protect-match} is non-nil, the @code{parent} properties of the @var{start} and @var{end} match overlays are left alone. @item (auto-o-delete-overlay @var{overlay} @@optional @var{no-parse} @var{protect-match}) @findex auto-o-delete-overlay @cindex overlays, deleting @cindex deleting overlays @cindex extending, deleting overlays Delete auto-overlay @var{overlay} from the buffer, and update overlays and overlay properties as necessary. The optional arguments disable parts of the updating process, as for @command{auto-o-match-overlay}, above. @end table @node Functions for Querying Overlays @subsection Functions for Querying Overlays @cindex functions, querying overlays @cindex overlays, functions for querying @cindex extending, functions for querying overlays These functions query certain things about auto-overlays or match overlays, or retrieve certain values associated with them. A few are merely convenience functions, but most depend on the internal implementation details of the auto-overlays package, and provide the only reliable interface for whatever they return. @table @code @item (auto-o-class @var{o-match}) @findex auto-o-class Return the class of match overlay @var{o-match}. @item (auto-o-regexp @var{o-match}) @findex auto-o-regexp Return the regular expression matched by the text covered by match overlay @var{o-match}. @item (auto-o-regexp-group @var{o-match}) @findex auto-o-regexp-group Return the regexp group defined in the regexp definition corresponding to match overlay @var{o-match} (@pxref{Defining Regexps}). @c @item @c (auto-o-regexp-group-nth n @var{o-match}) @c @findex auto-o-regexp-group-nth @c Return match overlay @var{o-match}'s Nth regexp group entry, or 0 @c if there is no Nth entry. @item (auto-o-props @var{o-match}) @findex auto-o-props Return the list of overlay properties defined in the regexp definition corresponding to match overlay @var{o-match} (@pxref{Defining Regexps}). @item (auto-o-edge @var{o-match}) @findex auto-o-edge Return edge (the symbol @code{start} or @code{end}) of match overlay @var{o-match}. @item (auto-o-parse-function @var{o-match}) @findex auto-o-parse-function Return appropriate parse function for match overlay @var{o-match}. @item (auto-o-suicide-function @var{o-match}) @findex auto-o-suicide-function Return appropriate suicide function for match overlay @var{o-match}. @item (auto-o-match-function @var{o-match}) @findex auto-o-match-function Return match function for match overlay @var{o-match}, if any. @item (auto-o-edge-matched-p @var{overlay} @var{edge}) @findex auto-o-edge-matched-p Return non-nil if @var{edge} (the symbol @code{start} or @code{end}) of auto-overlay @code{overlay} is matched. @item (auto-o-start-matched-p @var{overlay}) @findex auto-o-start-matched-p Return non-nil if auto-overlay @var{overlay} is start-matched. @item (auto-o-end-matched-p @var{overlay}) @findex auto-o-end-matched-p Return non-nil if auto-overlay @var{overlay} is end-matched. @end table @node Auto-Overlay Hooks @section Auto-Overlay Hooks @cindex hooks @cindex package, hooks @cindex hooks, loading and unloading The auto-overlays package defines two hooks, that are called when auto-overlays are enabled and disabled in a buffer. These are intended to be used by overlay classes to set up any extra buffer-local variables and settings they require, and clean them up afterwards. (There is no point leaving auto-overlay variables and settings hanging around in a buffer when auto-overlays are not in use.) @vtable @env @item auto-overlay-load-hook This hook is run when the first auto-overlay regexp set in a buffer is started, using the @command{auto-overlay-start} function. @xref{Starting and Stopping Auto-Overlays}. @item auto-overlay-unload-hook This hook is run when the last auto-overlay regexp set in a buffer is stopped, using the @command{auto-overlay-stop} function. @xref{Starting and Stopping Auto-Overlays}. @end vtable @node Auto-Overlay Modification Pseudo-Hooks @section Auto-Overlay Modification Pseudo-Hooks @cindex modification pseudo-hooks @cindex hooks, modification @cindex scheduling functions after modification @cindex functions, scheduling The auto-overlays package adds functions to buffer and overlay modification hooks in order to update the overlays as the buffer text is modified (@pxref{Modification Hooks,,,elisp,GNU Emacs Lisp Reference Manual}). The order in which all these modification hooks are called is undefined in Emacs@footnote{Or at least undocumented, and therefore unreliable.}. Therefore, the auto-overlays package provides a mechanism to schedule functions to run at particular points during the overlay update process. There are two stages to the overlay update process: first, any match overlay suicide functions are called, then modified buffer lines are scanned for new regexp matches. Three pseudo-hooks are defined that are called before, after and in between these stages. Their values are lists containing elements of the form: @lisp (@var{function} @var{arg1} @var{arg2} ...) @end lisp @noindent where @var{function} is the function to be called by the hook, and the @var{arg}'s are the arguments to be passed to that function. The list elements are evaluated in order. The pseudo-hooks are cleared each time after they have been called. @vtable @env @item auto-o-pending-pre-suicide Pseudo-hook called before any suicide functions. @item auto-o-pending-post-suicide Pseudo-hook called after any suicide functions but before scanning for regexp matches. @item auto-o-pending-post-update Pseudo-hook called after scanning for regexp matches. @end vtable These pseudo-hooks can be used to ensure that a function that would normally be added to a modification hook will be called at a particular point in the auto-overlay update process. To achieve this, a helper function must be added to the modification hook instead. The helper function should add the function itself to the appropriate pseudo-hook by adding a list element with the form described above. The @command{push} and @command{add-to-list} Elisp functions are the most useful ways to add elements to the list. @node To-Do @chapter To-Do @cindex to-do Things that still need to be implemented (in no particular order): @enumerate @item There needs to be an @code{eager-self} overlay class, similar to the existing @code{self} class but updated immediately, rather than waiting for buffer modifications. This will be significantly less efficient, but is necessary for applications that require overlays to be up to date all the time, not just when the buffer is being modified. @item Currently, it's difficult to deal with @code{nested} class regexps for which the @code{end} regexps match some @code{start} regexps of interest but also others that are irrelevant. E.g. @samp{@{} and @samp{@}} in @LaTeX{} when you're only interested in @samp{\somecommand@{} @code{start} regexps. Or matching parens in LISP, when you're only interested in function bodies, say. The only solution is to include all @code{start} regexps, but not set any of their properties. This can end up creating a lot of overlays! A variant of the @code{nested} class that avoids this problem is needed. @end enumerate @node Function Index @appendix Function Index @printindex fn @node Variable Index @appendix Variable Index @printindex vr @node Concept Index @appendix Concept Index @printindex cp @node Copying this Manual @appendix Copying this Manual @menu * GNU Free Documentation License:: @end menu @include fdl.texi @bye @c Local Variables: @c mode: texinfo @c End: