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.
@optionalbuffer save-file no-regexp-check
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.
@optionalbuffer save-file leave-overlays
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.
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.
@optionalbuffer file no-regexp-check
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
tif the overlays were successfully loaded,