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 (see 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 (see Overview), rgxp should instead be a cons cell:

     (rx . group)

where rx is a regexp that contains at least one group (see 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. See 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.