4.2 Integrating New Overlay Classes

To add a new overlay class, all that is required is to write new “parse” and “suicide” functions, and inform the auto-overlays package of their existence. A “match” function can also optionally be defined. It is called whenever a match overlay in the class becomes matched with the edge of an auto-overlay (see Functions for Modifying Overlays). The parse, suicide and match functions are conventionally called auto-o-parse-class-match, auto-o-class-suicide and auto-o-match-class, where class is the name of the class, though the convention is not enforced in any way.

parse function

A parse function is passed a single argument containing a match overlay. It should return a list containing any new auto-overlays it creates, or nil if none were created.

          o-list = (auto-o-parse-class-match o-match)

Note that the parse function itself is responsible for calling the auto-o-update-exclusive function if a new exclusive overlay is created. See Functions for Modifying Overlays.

suicide function

A suicide function is passed a single argument containing a match overlay. Its return value is ignored.

          (auto-o-class-suicide o-match)

The text covered by the match overlay should be considered to no longer match its regexp, although in certain cases matches are ignored for other reasons and this may not really be the case (for example if a new, higher-priority, exclusive overlay overlaps the match, see Overview).

match function

A match function is passed a single argument containing a match overlay that has just been matched with an edge of an auto-overlay (see Functions for Modifying Overlays). Its return value is ignored.

          (auto-o-match-class o-match)

The auto-overlay it is matched with is stored in the match overlay's parent property.

To integrate the new class into the auto-overlays package, the parse and suicide functions must be added to the property list of the symbol used to refer to the new class, denoted here by class:

     (put 'class 'auto-overlay-parse-function
          'auto-o-parse-class-match)
     (put 'class 'auto-overlay-suicide-function
          'auto-o-class-suicide)

If the optional match function is defined, it should similarly be added to the symbol's property list:

     (put 'class 'auto-overlay-match-function
          'auto-o-match-class)