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 (see 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 (see 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 (see 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 (see 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 (see 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.