[elpa] externals/auto-overlays 5996143 73/93: Refactor auto-overlays-(in|[highest-priority-]at-point) search functions:

[Stefan Monnier]

branch: externals/auto-overlays
commit 59961432b875a7257c687723c7f409d1517f5c37
Author: Toby S. Cubitt <toby-predictive@dr-qubit.org>
Commit: Toby S. Cubitt <toby-predictive@dr-qubit.org>

    Refactor auto-overlays-(in|[highest-priority-]at-point) search functions:
    
    - rationalise function arguments (breaks backwards-compatibility)
    - update overlays in region being queried before querying
    - default to only including auto-overlays
---
 auto-overlay-common.el                             | 123 +++++++++-------
 auto-overlay-flat.el                               |  34 ++---
 auto-overlay-nested.el                             |   6 +-
 auto-overlay-self.el                               |  21 +--
 auto-overlays.el                                   | 157 +++++++++++----------
 .../auto-overlay-manual.texinfo                    |  55 ++++----
 6 files changed, 202 insertions(+), 194 deletions(-)

diff --git a/auto-overlay-common.el b/auto-overlay-common.el
index 994b20d..777f2ef 100644
--- a/auto-overlay-common.el
+++ b/auto-overlay-common.el
@@ -29,13 +29,41 @@
 (provide 'auto-overlay-common)
 
 
+(defun auto-o--plist-delete (plist &rest keys)
+  ;; Destructively delete KEYS from PLIST
+  (while (memq (car plist) keys)
+    (setq plist (cddr plist)))
+  (let ((el (cdr plist)))
+    (while el
+      (when (memq (cadr el) keys)
+       (setcdr el (cdddr el)))
+      (setq el (cddr el))))
+  plist)
+
+
+(defun auto-overlay-< (a b)
+  "Return non-nil iff overlay A comes before overlay B in buffer."
+  (and (eq (overlay-buffer a) (overlay-buffer b))
+       (or (< (overlay-start a) (overlay-start b))
+          (and (= (overlay-start a) (overlay-start b))
+               (> (overlay-end a) (overlay-end b))))))
+
+
 ;;;###autoload
-(defun auto-overlays-at-point (&optional point prop-test inactive)
-  "Return overlays overlapping POINT
-(or the point, if POINT is null). If PROP-TEST is supplied, it
-should be a list which specifies a property test with one of the
-following forms (or a list of such lists if more than one
-property test is required):
+(cl-defun auto-overlays-at-point (&optional point
+                                 &rest prop-tests
+                                 &key inactive all-overlays &allow-other-keys)
+  "Return overlays overlapping POINT, defaulting to the point.
+
+If keyword argument :inactive is non-nil, both active and
+inactive overlays are returned (usually inactive ones are
+ignored).
+
+If keyword argument :all-overlays is non-nil, all overlays are
+returned, not just auto-overlays.
+
+Any remaining arguments specify property tests, each of which
+should be a list with one of the following forms:
 
   (FUNCTION PROPERTY)
 
@@ -46,49 +74,53 @@ property test is required):
 where PROPERTY indicates an overlay property name (a symbol), and
 VALUE indicates an arbitrary value or lisp expression.
 
-For each overlay overlapping POINT, first the values
+For each overlay between START and END, first the values
 corresponding to the property names are retrieved from the
 overlay, then FUNCTION is called with the properties 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.
-
-If INACTIVE is non-nil, both active and inactive overlays are
-returned (usually inactive ones are ignored).
+overlays that satisfy all property tests are returned."
 
-Note that this function returns any overlay. If you want to
-restrict it to auto overlays, include '(identity auto-overlay) in
-PROP-TEST."
   (when (null point) (setq point (point)))
+  (auto-overlay-trigger-update point)
 
   (let (overlay-list)
     ;; get overlays overlapping POINT and zero-length overlays at POINT
     (setq overlay-list
-         (auto-overlays-in point point prop-test nil inactive))
+         (apply #'auto-overlays-in point point prop-tests))
     ;; get overlays that end at POINT
-    (dolist (o (auto-overlays-in (1- point) point prop-test nil inactive))
+    (dolist (o (apply #'auto-overlays-in (1- point) point prop-tests))
       (when (and (< (overlay-start o) point)
                 (= (overlay-end o) point))
        (push o overlay-list)))
     ;; get overlays that start at POINT
-    (dolist (o (auto-overlays-in point (1+ point) prop-test nil inactive))
+    (dolist (o (apply #'auto-overlays-in point (1+ point) prop-tests))
       (when (and (> (overlay-end o) point)
                 (= (overlay-start o) point))
        (push o overlay-list)))
-
-    overlay-list))
+    (sort overlay-list #'auto-overlay-<)))
 
 
 
 ;;;###autoload
-(defun auto-overlays-in (start end &optional prop-test within inactive)
+(cl-defun auto-overlays-in (start end &rest prop-tests
+                                 &key within inactive all-overlays 
&allow-other-keys)
 ;; FIXME: get rid of INACTIVE argument?
   "Return auto overlays overlapping region between START and END.
 
-If PROP-TEST is supplied, it should be a list which specifies a
-property test with one of the following forms (or a list of such
-lists if more than one property test is required):
+If keyword argument :within is non-nil, only overlays entirely
+within START and END are returned.
+
+If keyword argument :inactive is non-nil, both active and
+inactive overlays are returned (usually inactive ones are
+ignored).
+
+If keyword argument :all-overlays is non-nil, all overlays are
+returned, not just auto-overlays.
+
+Any remaining arguments specify property tests, each of which
+should be a list with one of the following forms:
 
   (FUNCTION PROPERTY)
 
@@ -105,27 +137,19 @@ overlay, then FUNCTION is called with the properties 
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.
+overlays that satisfy all property tests are returned."
 
-If WITHIN is non-nil, only overlays entirely within START and END
-are returned. If INACTIVE is non-nil, both active and inactive
-overlays are returned (usually inactive ones are ignored).
-
-Note that this function returns any overlay. If you want to
-restrict it to auto overlays, include '(identity auto-overlay) in
-PROP-TEST."
-
-  ;; make sure prop-test is a list of lists, even if there's only one, and
+  ;; remove any keyword arguments from PROP-TESTS
+  (setq prop-tests
+       (auto-o--plist-delete prop-tests :within :inactive :all-overlays))
   ;; exclude inactive overlays unless told not to
-  (cond
-   ((null prop-test)
-    (unless inactive (setq prop-test '((null inactive)))))
-   ((functionp (car prop-test))
-    (if inactive
-       (setq prop-test (list prop-test))
-      (setq prop-test (list '(null inactive) prop-test))))
-   (t
-    (unless inactive (setq prop-test (push '(null inactive) prop-test)))))
+  (unless inactive (push '(null inactive) prop-tests))
+  ;; exclude non-auto-overlays unless told not to
+  (unless all-overlays (push '(identity auto-overlay) prop-tests))
+
+  ;; FIXME: Is updating just START and END enough to trigger all updates?
+  (auto-overlay-trigger-update start)
+  (unless (= start end) (auto-overlay-trigger-update end))
 
   (let (overlay-list function prop-list value-list result)
     ;; check properties of each overlay in region
@@ -139,7 +163,7 @@ PROP-TEST."
        (setq result t)
        (catch 'failed
          ;; check if properties match
-         (dolist (test prop-test)
+         (dolist (test prop-tests)
            ;; (Note: the whole thing would be neater with something like
            ;; (apply 'and (map ...)) but 'and is a special form, not a
            ;; function, so can't be applied)
@@ -164,24 +188,27 @@ PROP-TEST."
       ;; add overlay to result list if its properties matched
       (when result (push o overlay-list)))
     ;; return result list
-    overlay-list))
+    (nreverse overlay-list)))
 
 
 
 ;;;###autoload
-(defun auto-overlay-highest-priority-at-point (&optional point proptest)
-  "Return highest priority overlay at POINT (defaults to the point).
+(cl-defun auto-overlay-highest-priority-at-point (&optional point
+                                                 &rest prop-tests
+                                                 &key inactive all-overlays
+                                                 &allow-other-keys)
+  "Return highest priority overlay at POINT, defaulting to the point.
 
 If two overlays have the same priority, the innermost one takes
 precedence (i.e. the one that begins later, or if they begin at
 the same point the one that ends earlier).
 
-See `auto-overlays-at' for ane explanation of the PROPTEST argument."
+The remaining arguments are as for `auto-overlays-at' (which see)."
 
   (unless point (setq point (point)))
 
   ;; get all overlays at point with a non-nil SYMBOL property
-  (let* ((overlay-list (auto-overlays-at-point point proptest))
+  (let* ((overlay-list (apply #'auto-overlays-at-point point prop-tests))
         (overlay (pop overlay-list))
         p p1)
 
diff --git a/auto-overlay-flat.el b/auto-overlay-flat.el
index c790059..e7dc8e6 100644
--- a/auto-overlay-flat.el
+++ b/auto-overlay-flat.el
@@ -50,9 +50,8 @@
       ;; if match is within an existing overlay, ignore match
       (unless (auto-overlays-at-point
               (overlay-get o-match 'delim-end)  ; FIXME: is this right?
-              `((identity auto-overlay)
-                (eq set-id ,(overlay-get o-match 'set-id))
-                (eq definition-id ,(overlay-get o-match 'definition-id))))
+              `(eq set-id ,(overlay-get o-match 'set-id))
+              `(eq definition-id ,(overlay-get o-match 'definition-id)))
 
        ;; otherwise, look for next end-match...
        (let ((o-end (auto-o-next-flat-match o-match 'end)))
@@ -93,9 +92,8 @@
                (car  ; FIXME: is this right?
                 (auto-overlays-at-point
                  (overlay-get o-match 'delim-start)  ; FIXME: is this right?
-                 `((identity auto-overlay)
-                   (eq set-id ,(overlay-get o-match 'set-id))
-                   (eq definition-id ,(overlay-get o-match 'definition-id))))))
+                 `(eq set-id ,(overlay-get o-match 'set-id))
+                 `(eq definition-id ,(overlay-get o-match 'definition-id)))))
 
        ;; if overlay can simply be re-matched with new end-match, do so
        (let ((o-end (overlay-get o-parent 'end))
@@ -172,21 +170,19 @@
   ;; O-MATCH in buffer, with same set-id and definition-id as O-MATCH.
 
   ;; get sorted list of matching overlays after O-MATCH
-  (let ((o-list
-        (sort (auto-overlays-in
-               (overlay-start o-match) (point-max)  ; FIXME: is start right?
-               `((identity auto-overlay-match)
-                 (eq set-id ,(overlay-get o-match 'set-id))
-                 (eq definition-id ,(overlay-get o-match 'definition-id))
-                 (,(lambda (set-id definition-id regexp-id edge)
-                     (eq (auto-o-entry-edge set-id definition-id regexp-id)
-                         edge))
-                  (set-id definition-id regexp-id) (,edge))))
-              (lambda (a b) (<= (overlay-start a) (overlay-start b))))))
+  (let ((o-list (auto-overlays-in
+                (overlay-start o-match) (point-max)  ; FIXME: is start right?
+                '(identity auto-overlay-match)
+                `(eq set-id ,(overlay-get o-match 'set-id))
+                `(eq definition-id ,(overlay-get o-match 'definition-id))
+                (list (lambda (set-id definition-id regexp-id edge)
+                        (eq (auto-o-entry-edge set-id definition-id regexp-id)
+                            edge))
+                      '(set-id definition-id regexp-id)
+                      (list edge)))))
     ;; if searching for same EDGE as O-MATCH, first overlay in list is always
     ;; O-MATCH itself, so we drop it
-    (if (eq (auto-o-edge o-match) edge) (nth 1 o-list) (car o-list)))
-)
+    (if (eq (auto-o-edge o-match) edge) (nth 1 o-list) (car o-list))))
 
 
 
diff --git a/auto-overlay-nested.el b/auto-overlay-nested.el
index c9a72f1..5d5fc72 100644
--- a/auto-overlay-nested.el
+++ b/auto-overlay-nested.el
@@ -199,10 +199,8 @@
                        (if (eq (auto-o-edge o-match) 'start)
                            (overlay-get o-match 'delim-end)
                          (overlay-get o-match 'delim-start))
-                       (list '(eq auto-overlay t)
-                             (list 'eq 'set-id (overlay-get o-match 'set-id))
-                             (list 'eq 'definition-id
-                                   (overlay-get o-match 'definition-id)))))
+                       `(eq set-id ,(overlay-get o-match 'set-id))
+                       `(eq definition-id ,(overlay-get o-match 
'definition-id))))
        (o-parent (overlay-get o-match 'parent)))
     ;; sort the list by overlay length, i.e. from innermost to outermose
     (sort overlay-stack
diff --git a/auto-overlay-self.el b/auto-overlay-self.el
index 72c86e6..4a506b7 100644
--- a/auto-overlay-self.el
+++ b/auto-overlay-self.el
@@ -197,8 +197,7 @@
   ;; buffer is modified. Called from `before-change-functions'.
 
   ;; check all overlays waiting to be cascaded, from first in buffer to last
-  (dolist (o (sort auto-o-pending-self-cascade
-                  (lambda (a b) (< (overlay-start a) (overlay-start b)))))
+  (dolist (o (sort auto-o-pending-self-cascade #'auto-overlay-<))
     ;; if buffer modification occurs after the end of an overlay waiting to be
     ;; cascaded, cascade all overlays between it and the modified text
     (when (and (overlay-start o) (<= (overlay-start o) beg))
@@ -286,14 +285,9 @@
 ;;                     (push o overlay-list)))
 ;;       (auto-overlays-in
 ;;        (point-min) (point-max)
-;;        (list
 ;;         '(identity auto-overlay)
-;;         (list 'eq 'set-id (overlay-get o-start 'set-id))
-;;         (list 'eq 'definition-id (overlay-get o-start 'definition-id)))))
-;;     ;; sort the list by start position, from first to last
-;;     (sort overlay-list
-;;       (lambda (a b) (< (overlay-start a) (overlay-start b)))))
-;; )
+;;         `(eq set-id ,(overlay-get o-start 'set-id))
+;;         `(eq definition-id ,(overlay-get o-start 'definition-id))))))
 
 
 
@@ -313,13 +307,8 @@
          ;;       (above) in all circumstances.
          (auto-overlays-in
           (1- (overlay-get o-start 'delim-start)) (1+ end)
-          `((identity auto-overlay)
-            (eq set-id ,(overlay-get o-start 'set-id))
-            (eq definition-id ,(overlay-get o-start 'definition-id)))))
-    ;; sort the list by start position, from first to last
-    (sort overlay-list
-         (lambda (a b) (< (overlay-start a) (overlay-start b))))
-    ))
+          `(eq set-id ,(overlay-get o-start 'set-id))
+          `(eq definition-id ,(overlay-get o-start 'definition-id))))))
 
 
 ;;; auto-overlay-self.el ends here
diff --git a/auto-overlays.el b/auto-overlays.el
index db050b4..aebaabc 100644
--- a/auto-overlays.el
+++ b/auto-overlays.el
@@ -586,9 +586,10 @@ from the current buffer. Returns the deleted definition."
       (set-buffer buff)
       (when (auto-o-enabled-p set-id)
        (mapc (lambda (o) (auto-o-suicide o 'force))
-             (auto-overlays-in (point-min) (point-max)
-                               `((eq set-id ,set-id)
-                                 (eq definition-id ,definition-id))))))
+             (auto-overlays-in (point-min) (point-max) :all-overlays t
+                               '(identity auto-overlay-match)
+                               `(eq set-id ,set-id)
+                               `(eq definition-id ,definition-id)))))
     ;; delete definition
     (let ((olddef (assq definition-id (auto-o-get-regexps set-id)))
           def-id class regexps regexp edge regexp-id props)
@@ -629,11 +630,11 @@ Returns the deleted regexp."
       (set-buffer buff)
       (when (auto-o-enabled-p set-id)
        (mapc (lambda (o) (auto-o-suicide o 'force))
-             (auto-overlays-in (point-min) (point-max)
-                               `((identity auto-overlay-match)
-                                 (eq set-id ,set-id)
-                                 (eq definition-id ,definition-id)
-                                 (eq regexp-id ,regexp-id))))))
+             (auto-overlays-in (point-min) (point-max) :all-overlays t
+                               '(identity auto-overlay-match)
+                               `(eq set-id ,set-id)
+                               `(eq definition-id ,definition-id)
+                               `(eq regexp-id ,regexp-id)))))
     ;; delete regexp entry
     (let* ((def (cdr (assq definition-id (auto-o-get-regexps set-id))))
           (oldregexp (assq regexp-id def))
@@ -765,12 +766,10 @@ is about to be killed in which case it speeds things up a 
bit\)."
     (unless leave-overlays
       (mapc 'delete-overlay
            (auto-overlays-in
-            (point-min) (point-max)
-            (list
-             (list (lambda (overlay match) (or overlay match))
-                   '(auto-overlay auto-overlay-match))
-             (list 'eq 'set-id set-id))
-            nil 'inactive)))
+            (point-min) (point-max) :all-overlays t :inactive t
+            (list (lambda (overlay match) (or overlay match))
+                  '(auto-overlay auto-overlay-match))
+            `(eq set-id ,set-id))))
 
     ;; if there are no more active auto-overlay definitions...
     (unless (catch 'enabled
@@ -831,15 +830,9 @@ The overlays can be loaded again later using
 
       ;; get sorted list of all match overlays in set SET-ID
       (setq overlay-list
-           (auto-overlays-in (point-min) (point-max)
-                             (list '(identity auto-overlay-match)
-                                   (list 'eq 'set-id set-id))))
-      (setq overlay-list
-           (sort overlay-list
-                 (lambda (a b)
-                   (or (< (overlay-start a) (overlay-start b))
-                       (and (= (overlay-start a) (overlay-start b))
-                            (> (overlay-end a) (overlay-end b)))))))
+           (auto-overlays-in (point-min) (point-max) :all-overlays t
+                             '(identity auto-overlay-match)
+                             `(eq set-id ,set-id)))
 
       ;; write overlay data to temporary buffer
       (mapc (lambda (o)
@@ -1087,7 +1080,8 @@ overlays were saved."
   ;; in front or behind it, to simulate missing `delete-in-front-hooks' and
   ;; `delete-behind-hooks' overlay properties
   (unless (= len 0)
-    (dolist (o (auto-overlays-at-point nil '(identity auto-overlay-match)))
+    (dolist (o (auto-overlays-at-point nil :all-overlays t
+                                      '(identity auto-overlay-match)))
       (when (or (= (overlay-end o) start) (= (overlay-start o) end))
        (auto-o-adjoin o auto-o-pending-suicides)))))
 
@@ -1238,6 +1232,21 @@ overlays were saved."
        ))))
 
 
+(defun auto-overlay-trigger-update (&optional point)
+  "Trigger auto-overlay update at POINT, defaulting to the point."
+  ;; FIXME: Inserting and deleting to trigger change hooks is hacky. But some
+  ;;        updates are triggered by overlay change hooks (e.g. self overlay
+  ;;        cascades), and auto-overlays doesn't know about these. Would need
+  ;;        to refactor how class-specific updates are performed.
+  (unless point (setq point (point)))
+  (let ((inhibit-read-only t))
+    (with-silent-modifications
+      (save-excursion
+       (goto-char point)
+       (insert " ")
+       (backward-delete-char 1)))))
+
+
 
 (defun auto-o-suicide (o-self &optional force)
   ;; This function is assigned to all match overlay modification hooks, and
@@ -1303,18 +1312,16 @@ overlays were saved."
       ;; matched and have priority lower than NEW-PRIORITY
       (setq overlay-list
            (auto-overlays-in
-            beg end
-            (list '(identity auto-overlay)
-                  (list 'eq 'set-id set-id)
-                  '(identity start)
-                  (list (lambda (definition-id start end)
-                          (or (null (auto-o-entry-complex-class-p
-                                     set-id definition-id))
-                              (and start end)))
-                        '(definition-id start end))
-                  (list (lambda (pri new) (or (null pri) (< pri new)))
-                        'priority new-priority))
-            'within))
+            beg end :within t
+            `(eq set-id ,set-id)
+            '(identity start)
+            (list (lambda (definition-id start end)
+                    (or (null (auto-o-entry-complex-class-p
+                               set-id definition-id))
+                        (and start end)))
+                  '(definition-id start end))
+            (list (lambda (pri new) (or (null pri) (< pri new)))
+                  'priority new-priority)))
       ;; mark overlays in list as inactive (more efficient than calling
       ;; suicide functions or deleting the overlays, and leaves them intact in
       ;; case the exclusivity of the region is later reduced - see below)
@@ -1324,23 +1331,23 @@ overlays were saved."
       ;; NEW-PRIORITY but still have an active parent overlay
       (setq overlay-list
            (auto-overlays-in
-            beg end
-            (list '(identity auto-overlay-match)
-                  (list 'eq 'set-id set-id)
-                  ;; note: parentless overlays are possible if a suicide is
-                  ;; in progress, so need to check overlay has a parent first
-                  '(identity parent)
-                  (list (lambda (parent)
-                          (not (overlay-get parent 'inactive)))
-                        'parent)
-                  (list (lambda (set-id definition-id regexp-id new-pri)
-                          (let ((pri (cdr (assq
-                                           'priority
-                                           (auto-o-entry-props
-                                            set-id definition-id regexp-id)))))
-                            (or (null pri) (< pri new-pri))))
-                        '(set-id definition-id regexp-id)
-                        (list new-priority)))))
+            beg end :all-overlays t
+            '(identity auto-overlay-match)
+            `(eq set-id ,set-id)
+            ;; note: parentless overlays are possible if a suicide is in
+            ;; progress, so need to check overlay has a parent first
+            '(identity parent)
+            (list (lambda (parent)
+                    (not (overlay-get parent 'inactive)))
+                  'parent)
+            (list (lambda (set-id definition-id regexp-id new-pri)
+                    (let ((pri (cdr (assq
+                                     'priority
+                                     (auto-o-entry-props
+                                      set-id definition-id regexp-id)))))
+                      (or (null pri) (< pri new-pri))))
+                  '(set-id definition-id regexp-id)
+                  (list new-priority))))
       ;; call appropriate suicide function for each match overlay in list
       (dolist (o overlay-list) (funcall (auto-o-suicide-function o) o)))
 
@@ -1352,13 +1359,11 @@ overlays were saved."
       ;; higher or equal to NEW-PRIORITY
       (setq overlay-list
            (auto-overlays-in
-            beg end
-            (list '(identity auto-overlay)
-                  (list 'eq 'set-id set-id)
-                  '(identity inactive)
-                  (list (lambda (pri new) (or (null new) (>= pri new)))
-                        'priority new-priority))
-            'within 'inactive))
+            beg end :within t :inactive t
+            `(eq set-id ,set-id)
+            '(identity inactive)
+            (list (lambda (pri new) (or (null new) (>= pri new)))
+                  'priority new-priority)))
       ;; mark overlays in list as active again
       (dolist (o overlay-list) (overlay-put o 'inactive nil))
 
@@ -1366,18 +1371,18 @@ overlays were saved."
       ;; equal to NEW-PRIORITY but no parent overlay
       (setq overlay-list
            (auto-overlays-in
-            beg end
-            (list '(identity auto-overlay-match)
-                  (list 'eq 'set-id set-id)
-                  '(null parent)
-                  (list (lambda (set-id definition-id regexp-id new-pri)
-                          (let ((pri (cdr (assq
-                                           'priority
-                                           (auto-o-entry-props
-                                            set-id definition-id regexp-id)))))
-                            (or (null new-pri) (>= pri new-pri))))
-                        '(set-id definition-id regexp-id)
-                        (list new-priority)))))
+            beg end :all-overlays t
+            '(identity auto-overlay-match)
+            `(eq set-id ,set-id)
+            '(null parent)
+            (list (lambda (set-id definition-id regexp-id new-pri)
+                    (let ((pri (cdr (assq
+                                     'priority
+                                     (auto-o-entry-props
+                                      set-id definition-id regexp-id)))))
+                      (or (null new-pri) (>= pri new-pri))))
+                  '(set-id definition-id regexp-id)
+                  (list new-priority))))
       ;; call appropriate parse function for each match overlay in list
       (dolist (o-match overlay-list)
        (when (not (auto-o-within-exclusive-p o-match))
@@ -1663,11 +1668,9 @@ overlay changes."
   ;; look for higher priority exclusive overlays
   (auto-overlays-in
    match end
-   (list '(identity auto-overlay)
-        '(identity exclusive)
-        (list (lambda (p q) (and p (or (null q) (> p q))))
-              'priority priority)))
-)
+   '(identity exclusive)
+   (list (lambda (p q) (and p (or (null q) (> p q))))
+        'priority priority)))
 
 
 
diff --git a/docs/auto-overlay-manual/auto-overlay-manual.texinfo 
b/docs/auto-overlay-manual/auto-overlay-manual.texinfo
index 18e208c..7b87388 100644
--- a/docs/auto-overlay-manual/auto-overlay-manual.texinfo
+++ b/docs/auto-overlay-manual/auto-overlay-manual.texinfo
@@ -564,13 +564,12 @@ properties. The auto-overlays package provides some 
additional
 functions.
 
 @table @code
-@item (auto-overlays-at-point @@optional @var{point} @var{prop-test} 
@var{inactive})
+@item (auto-overlays-at-point @@optional @var{point} @@key @var{inactive} 
@var{all-overlays} @@rest @var{prop-tests})
 @findex auto-overlays-at-point
-Return a list of overlays overlapping @var{point}, or the point if
-@var{point} is null. The list includes @emph{all} overlays, not just
-auto-overlays (but see below). The list can be filtered to only return
+Return a list of auto-overlays overlapping @var{point}, or the point if
+@var{point} is null. The list can be filtered to only return
 overlays with properties matching criteria specified by
-@var{prop-test}. This should be a list defining a property test, with
+@var{prop-tests}. 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):
 @lisp
@@ -588,44 +587,40 @@ 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 @code{auto-overlay} property, so
-to restrict the list to auto-overlays, @var{prop-test} should include
-the following property test:
-@lisp
-('identity 'auto-overlay)
-@end lisp
 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 @code{inactive} property. By
 default, @command{auto-overlays-at-point} ignores these. A non-nil
-@var{inactive} will override this, causing inactive overlays to be
-included in the returned list (assuming they pass all property tests).
+@var{inactive} keyword argument will override this, causing inactive
+overlays to be included in the returned list (assuming they pass all
+property tests).
 
+By default, @command{auto-overlays-at-point} only returns overlays
+created by the auto-overlays package. If you want to include @emph{all}
+overlays, pass a non-nil @var{all-overlays} keyword argument.
 
-@item (auto-overlays-in @var{start} @var{end} @@optional @var{prop-test} 
@var{within} @var{inactive})
+@item (auto-overlays-in @var{start} @var{end} @@key @var{within} 
@var{inactive} @var{all-overlays} @@rest @var{prop-tests})
 @findex auto-overlays-in
 Return a list of overlays overlapping the region between @var{start} and
-@var{end}. The @var{prop-test} and @var{inactive} arguments have the
-same behaviour as in @command{auto-overlays-at-point}, above. If
-@var{within} is non-nil, only overlays that are entirely within the
-region from @var{start} to @var{end} will be returned, not overlays that
-extend outside that region.
+@var{end}. A non-nil @var{within} keyword argument, restricts the
+results to overlays that are entirely within the region from @var{start}
+to @var{end}, not overlays that extend outside that region. The
+remaining arguments are as for @command{auto-overlays-at-point}, above.
 
-
-@item (auto-overlay-highest-priority-at-point @@optional @var{point} 
@var{prop-test})
+@item (auto-overlay-highest-priority-at-point @@optional @var{point} @@key 
@var{inactive} @var{all-overlays} @@rest @var{prop-tests})
 @findex auto-overlay-highest-priority-at-point
 @cindex overlays, priority
 @cindex highest priority overlay
 Return the highest priority overlay at @var{point} (or the point, if
-@var{point} is null). The @var{prop-test} argument has the same
-behaviour as in @command{auto-overlays-at-point}, above. An overlay's
-priority is determined by the value of its @code{priority} property
-(@pxref{Overlay Properties,,,elisp, GNU Emacs Lisp Reference
-Manual}). 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).
+@var{point} is null). An overlay's priority is determined by the value
+of its @code{priority} property (@pxref{Overlay Properties,,,elisp, GNU
+Emacs Lisp Reference Manual}). 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).
+The remaining arguments are as for @command{auto-overlays-at-point}.
+
 
 @item (auto-overlay-local-binding @var{symbol} @@optional @var{point})
 @findex auto-overlay-local-binding