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. This documentation is an extract from the extensive Auto Overlays Manual that comes with the package. For more detailed information and examples, please read the manual. 1 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. 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 (*note Defining Regexps::). This allows different Emacs modes to simultaneously make use of auto-overlays in the same buffer. 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 (*note 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: `word', `line', `self', `nested' and `flat', but the auto-overlay package can easily be extended with new classes. `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. `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. `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 `""'. Note that for efficiency reasons, `self' overlays are _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 _up to_ that position. The update occurs just _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 (*note To-Do::). `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 `{}'. `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 `/*' and `*/'. By default, the entire text matching a regexp acts as the "delimeter". For example, a `word' overlay will cover all the text matching its regexp, and a `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 (*note 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. `priority' This is a standard Emacs overlay property (*note Overlay Properties: (elisp)Overlay Properties.), 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. `exclusive' Normally, different auto-overlay regexps coexist, and act completely independently of one-another. However, if an auto-overlay has non-nil `exclusive' and `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. 2 Auto-Overlay Functions ************************ To use auto-overlays in an Elisp package, you must load the overlay classes that you require by including lines of the form (require 'auto-overlay-CLASS) near the beginning of your package, where CLASS is the class name. The standard classes are: `word', `line', `self', `nested' and `flat' (*note Overview::), though new classes can easily be added (*note Extending the Auto-Overlays Package::). Sometimes it is useful for a package to make use of auto-overlays if any are defined, without necessarily requiring them. To facilitate this, the relevant functions can be loaded separately from the rest of the auto-overlays package with the line (require 'auto-overlay-common) This provides all the functions related to searching for overlays and retrieving overlay properties. *Note Searching for Overlays::. Note that there is no need to include this line if any auto-overlay classes are `require'd, though it will do no harm. This section describes the functions that are needed in order to make use of auto-overlays in an Elisp package. It does _not_ describe functions related to extending the auto-overlays package. *Note Extending the Auto-Overlays Package::. 2.1 Defining Regexps ==================== An auto-overlay definition is a list of the form: (CLASS &optional :id ENTRY-ID REGEXP1 REGEXP2 ...) CLASS is one of the regexp classes described in the previous section (*note Overview::). The optional `:id' property should be a symbol that can be used to uniquely identify the auto-overlay definition. Each REGEXP defines one of the regexps that make up the auto-overlay definition. It should be a list of the form (RGXP &optional :edge EDGE :id SUBENTRY-ID @rest PROPERTY1 PROPERTY2 ...) The `:edge' property should be one of the symbols `'start' or `'end', and determines which edge of the auto-overlay this regexp corresponds to. If `:edge' is not specified, it is assumed to be `'start'. Auto-overlay classes that do not require separate `start' and `end' regexps ignore this property. The `:id' property should be a symbol that can be used to uniquely identify the regexp. Any further elements in the list are cons cells of the form `(property . value)', where PROPERTY is an overlay property name (a symbol) and VALUE its value. In its simplest form, RGXP is a single regular expression. If only part of the regexp should act as the delimeter (*note Overview::), RGXP should instead be a cons cell: (RX . GROUP) where RX is a regexp that contains at least one group (*note Regular Expressions: (elisp)Regular Expressions.), and GROUP is an integer identifying which group should act as the delimeter. If the overlay class requires additional groups to be specified, RGXP should instead be a list: (RX GROUP0 GROUP1 ...) where RX is a regexp. The first GROUP0 still specifies the part that acts as the delimeter, as before. If the entire regexp should act as the delimeter, 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. *Note Extending the Auto-Overlays Package::. The following functions are used to load and unload regexp definitions: `(auto-overlay-load-definition SET-ID DEFINITION &optional POS)' Load a new auto-overlay DEFINITION, which should be a list of the form described above, into the set identified by the symbol SET-ID. The optional parameter POS determines where in the set's regexp list the new regexp is inserted. If it is `nil', the regexp is added at the end. If it is `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. `(auto-overlay-load-regexp SET-ID ENTRY-ID REGEXP &optional POS)' Load a new REGEXP, which should be a list of the form described above, into the auto-overlay definition identified by the symbol ENTRY-ID, in the set identified by the symbol SET-ID. REGEXP should be a list of the form described above. The optional 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. `(auto-overlay-unload-set SET-ID)' Unload the entire regexp set identified by the symbol SET-ID. `(auto-overlay-unload-definition SET-ID ENTRY-ID)' Unload the auto-overlay definition identified by the symbol ENTRY-ID from the set identified by the symbol SET-ID. `(auto-overlay-unload-regexp SET-ID ENTRY-ID SUBENTRY-ID)' Unload the auto-overlay regexp identified by the symbol SUBENTRY-ID from the auto-overlay definition identified by the symbol ENTRY-ID in the set identified by the symbol SET-ID. `(auto-overlay-share-regexp-set SET-ID FROM-BUFFER @optional TO-BUFFER)' Share the set of regexp definitions identified by the symbol SET-ID in buffer `from-buffer' with the buffer TO-BUFFER, or the current buffer if 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 `auto-overlay-unload-regexp'. The regexp set will remain defined in all the other buffers it was shared with. 2.2 Starting and Stopping Auto-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 _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 the text in the buffer is modified whilst the regexp set is disabled, or the regexp definitions differ from those that were active when the overlay data was saved, the saved data will be out of date. Auto-overlays automatically checks if the text has been modified and, if it has, ignores the saved data and re-scans the buffer. However, no check is made to ensure the regexp definitions used in the buffer and saved data are consistent (*note To-Do::); the saved data will be used even if the definitions have changed. 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. `(auto-overlay-start SET-ID @optional BUFFER SAVE-FILE NO-REGEXP-CHECK)' Activate the auto-overlay regexp set identified by the symbol SET-ID in BUFFER, or the current buffer if the latter is `nil'. If there is an file called `auto-overlay-'BUFFER-NAME`-'SET-ID in the containing up-to-date overlay data, it will be used to restore the auto-overlays (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 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 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. `(auto-overlay-stop SET-ID @optional BUFFER SAVE-FILE LEAVE-OVERLAYS)' Deactivate the auto-overlay regexp set identified by the symbol SET-ID in BUFFER, or the current buffer if the latter is `nil'. All corresponding overlays will be deleted (unless the 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 SAVE-FILE is non-nil, overlay data will be saved in an auxilliary file called `auto-overlay-'BUFFER-NAME`-'SET-ID in the current directory, to speed up subsequent reactivation of the regexp set in the same buffer (BUFFER-NAME is the name of the file visited by the buffer, or the buffer name itself if there is none). If 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 file name, or both. `(auto-overlay-save-overlays SET-ID @optional BUFFER FILE)' Save auto-overlay data for the regexp set identified by the symbol SET-ID in BUFFER, or the current buffer if `nil', to an auxilliary file called FILE. If FILE is nil, the overlay data are saved to a file called `auto-overlay-'BUFFER-NAME`-'SET-ID in the current directory (BUFFER-NAME is the name of the file visited by the buffer, or the buffer name itself if there is none). Note that this is the only name that will be recognized by `auto-overlay-start'. `(auto-overlay-load-overlays SET-ID @optional BUFFER FILE NO-REGEXP-CHECK)' Load auto-overlay data for the regexp set identified by the symbol SET-ID into BUFFER, or the current buffer if `nil', from an auxilliary file called FILE. If FILE is nil, it attempts to load the overlay data from a file called `auto-overlay-'BUFFER-NAME`-'SET-ID in the current directory (BUFFER-NAME is the name of the file visited by the buffer, or the buffer name itself if there is none). If 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 `t' if the overlays were successfully loaded, `nil' otherwise. 2.3 Searching for Overlays ========================== 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. `(auto-overlays-at-point @optional POINT PROP-TEST INACTIVE)' Return a list of overlays overlapping POINT, or the point if POINT is null. The list includes _all_ overlays, not just auto-overlays (but see below). The list can be filtered to only return overlays with properties matching criteria specified by PROP-TEST. 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): (FUNCTION PROPERTY) (FUNCTION PROPERTY VALUE) (FUNCTION (PROPERTY1 PROPERTY2 ...) (VALUE1 VALUE2 ...)) where FUNCTION is a function, PROPERTY is an overlay property name (a symbol), and VALUE can be any value or lisp expression. For each overlay, first the values corresponding to the PROPERTY names are retrieved from the overlay and any VALUEs that are lisp expressions are evaluated. Then 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. All auto-overlays are given a non-nil `auto-overlay' property, so to restrict the list to auto-overlays, PROP-TEST should include the following property test: ('identity 'auto-overlay) 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 `inactive' property. By default, `auto-overlays-at-point' ignores these. A non-nil INACTIVE will override this, causing inactive overlays to be included in the returned list (assuming they pass all property tests). `(auto-overlays-in START END @optional PROP-TEST WITHIN INACTIVE)' Return a list of overlays overlapping the region between START and END. The PROP-TEST and INACTIVE arguments have the same behaviour as in `auto-overlays-at-point', above. If WITHIN is non-nil, only overlays that are entirely within the region from START to END will be returned, not overlays that extend outside that region. `(auto-overlay-highest-priority-at-point @optional POINT PROP-TEST)' Return the highest priority overlay at POINT (or the point, of POINT is null). The PROP-TEST argument has the same behaviour as in `auto-overlays-at-point', above. An overlay's priority is determined by the value of its `priority' property (*note Overlay Properties: (elisp)Overlay Properties.). 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). `(auto-overlay-local-binding SYMBOL @optional POINT)' Return the "overlay-local" binding of SYMBOL at POINT (or the point if POINT is null), or the current local binding if there is no overlay binding. An "overlay-local" binding for SYMBOL is the value of the overlay property called SYMBOL. If more than one overlay at POINT has a non-nil SYMBOL property, the value from the highest priority overlay is returned (see `auto-overlay-highest-priority-at-point', above, for an explanation of "highest priority").