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