2.3 Searching for Overlays

Auto-overlays are just normal Emacs overlays, so any of the standard Emacs functions can be used to search for overlays and retrieve overlay properties. The auto-overlays package provides some additional functions.

(auto-overlays-at-point @optional point prop-test inactive)

Return a list of overlays overlapping point, or the point if point is null. The list includes all overlays, not just auto-overlays (but see below). The list can be filtered to only return overlays with properties matching criteria specified by prop-test. This should be a list defining a property test, with one of the following forms (or a list of such lists, if more than one property test is required):

          (function property)
          (function property value)
          (function (property1 property2 ...) (value1 value2 ...))

where function is a function, property is an overlay property name (a symbol), and value can be any value or lisp expression. For each overlay, first the values corresponding to the property names are retrieved from the overlay and any values that are lisp expressions are evaluated. Then function is called with the property values followed by the other values as its arguments. The test is satisfied if the result is non-nil, otherwise it fails. Tests are evaluated in order, but only up to the first failure. Only overlays that satisfy all property tests are returned.

All auto-overlays are given a non-nil auto-overlay property, so to restrict the list to auto-overlays, prop-test should include the following property test:

          ('identity 'auto-overlay)

For efficiency reasons, the auto-overlays package sometimes leaves overlays hanging around in the buffer even when they should have been deleted. These are marked with a non-nil inactive property. By default, auto-overlays-at-point ignores these. A non-nil inactive will override this, causing inactive overlays to be included in the returned list (assuming they pass all property tests).

(auto-overlays-in start end @optional prop-test within inactive)

Return a list of overlays overlapping the region between start and end. The prop-test and inactive arguments have the same behaviour as in auto-overlays-at-point, above. If within is non-nil, only overlays that are entirely within the region from start to end will be returned, not overlays that extend outside that region.

(auto-overlay-highest-priority-at-point @optional point prop-test)

Return the highest priority overlay at point (or the point, of point is null). The prop-test argument has the same behaviour as in auto-overlays-at-point, above. An overlay's priority is determined by the value of its priority property (see Overlay Properties). If two overlays have the same priority, the innermost one takes precedence (i.e. the one that begins later in the buffer, or if they begin at the same point the one that ends earlier; if two overlays have the same priority and extend over the same region, there is no way to predict which will be returned).

(auto-overlay-local-binding symbol @optional point)

Return the “overlay-local” binding of symbol at point (or the point if point is null), or the current local binding if there is no overlay binding. An “overlay-local” binding for symbol is the value of the overlay property called symbol. If more than one overlay at point has a non-nil symbol property, the value from the highest priority overlay is returned (see auto-overlay-highest-priority-at-point, above, for an explanation of “highest priority”).