Docs: Queries, etc.

README.org

@@ -107,6 +107,32 @@ Here are some other examples:
              (closed = today))))
 #+END_SRC
 
+** Queries
+
+A query is a lisp form which may contain arbitrary lisp forms, as well as certain built-in predicates.  It is byte-compiled into a predicate function which is tested with point on each heading in an Org buffer; when it returns non-nil, the heading matches the query.
+
+*** Predicates
+
+Arguments are listed next to predicate names, when applicable.
+
+Note that, for convenience, standard numeric comparator function symbols (~<~, ~=~, etc.) do not need to be quoted when passed as an argument to these predicates.  See examples in documentation.
+
++  ~category (&optional categories)~ :: Return non-nil if current heading is in one or more of ~CATEGORIES~ (a list of strings).
++  ~closed (&optional comparator target-date)~ :: Return non-nil if entry's closed date compares with ~TARGET-DATE~ using ~COMPARATOR~.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
++  ~date (&optional comparator target-date &optional)~ :: Return non-nil if Org entry at point has date of ~TYPE~ that compares with ~TARGET-DATE~ using ~COMPARATOR~.  Checks all Org-formatted timestamp strings in entry.  ~TYPE~ may be ~active~, ~inactive~, or ~all~, to control whether active, inactive, or all timestamps are checked.  Ranges of each type are also checked.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
++  ~deadline (&optional comparator target-date)~ :: Return non-nil if entry's deadline compares with ~TARGET-DATE~ using ~COMPARATOR~.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
++  ~done~ :: Return non-nil if entry's ~TODO~ keyword is in ~org-done-keywords~.
++  ~habit~ :: Return non-nil if entry is a habit.
++  ~heading (regexp)~ :: Return non-nil if current entry's heading matches ~REGEXP~ (a regexp string).
++  ~level (level-or-comparator &optional level)~ :: Return non-nil if current heading's outline level matches ~LEVEL~ with ~COMPARATOR~.  If ~LEVEL~ is nil, ~LEVEL-OR-COMPARATOR~ should be an integer level, which will be tested for equality to the heading's outline level.  If ~LEVEL~ is non-nil, ~LEVEL-OR-COMPARATOR~ should be a comparator function (like ~<=~).
++  ~planning (&optional comparator target-date)~ :: Return non-nil if entry's planning date (deadline or scheduled) compares with ~TARGET-DATE~ using ~COMPARATOR~.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
++  ~priority (&optional comparator-or-priority priority)~ :: Return non-nil if current heading has a certain priority.  ~COMPARATOR-OR-PRIORITY~ should be either a comparator function, like ~<=~, or a priority string, like "A" (in which case (~=~ will be the comparator).  If ~COMPARATOR-OR-PRIORITY~ is a comparator, ~PRIORITY~ should be a priority string.
++  ~property (property &optional value)~ :: Return non-nil if current entry has ~PROPERTY~ (a string), and optionally ~VALUE~ (a string).
++  ~regexp (regexp)~ :: Return non-nil if current entry matches ~REGEXP~ (a regexp string).
++  ~scheduled (&optional comparator target-date)~ :: Return non-nil if entry's scheduled date compares with ~TARGET-DATE~ using ~COMPARATOR~.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
++  ~tags (&optional tags)~ :: Return non-nil if current heading has one or more of ~TAGS~ (a list of strings).
++  ~todo (&optional keywords)~ :: Return non-nil if current heading is a ~TODO~ item.  With ~KEYWORDS~, return non-nil if its keyword is one of ~KEYWORDS~ (a list of strings).
+
 ** Functions / Macros
 
 *** Macro: ~org-ql~
@@ -143,26 +169,6 @@ If ~NARROW~ is non-nil, buffers are not widened.
 
 ~SORT~ is either nil, in which case items are not sorted; or one or a list of defined ~org-ql~ sorting methods: ~date~, ~deadline~, ~scheduled~, ~todo~, and ~priority~.
 
-** Predicates
-
-Arguments are listed next to predicate names, when applicable.
-
-+  ~category (categories)~ :: Return non-nil if current heading is in one or more of ~CATEGORIES~ (a list of strings).
-+  ~closed (&optional comparator target-date)~ :: Return non-nil if entry's closed date compares with ~TARGET-DATE~ using ~COMPARATOR~.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
-+  ~date (&optional comparator target-date)~ :: Return non-nil if Org entry at point has date of ~TYPE~ that compares with ~TARGET-DATE~ using ~COMPARATOR~.  Checks all Org-formatted timestamp strings in entry.  ~TYPE~ may be ~active~, ~inactive~, or ~all~, to control whether active, inactive, or all timestamps are checked.  Ranges of each type are also checked.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
-+  ~deadline (&optional comparator target-date)~ :: Return non-nil if entry's deadline compares with ~TARGET-DATE~ using ~COMPARATOR~.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
-+  ~done~ :: Return non-nil if entry's ~TODO~ keyword is in ~org-done-keywords~.
-+  ~habit~ :: Return non-nil if entry is a habit.
-+  ~heading (regexp)~ :: Return non-nil if current entry's heading matches ~REGEXP~ (a regexp string).
-+  ~level (level-or-comparator &optional level)~ :: Return non-nil if current heading's outline level matches ~LEVEL~ with ~COMPARATOR~.  If ~LEVEL~ is nil, ~LEVEL-OR-COMPARATOR~ should be an integer level, which will be tested for equality to the heading's outline level.  If ~LEVEL~ is non-nil, ~LEVEL-OR-COMPARATOR~ should be a comparator function (like ~<=~).
-+  ~planning (&optional comparator target-date)~ :: Return non-nil if entry's planning date (deadline or scheduled) compares with ~TARGET-DATE~ using ~COMPARATOR~.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
-+  ~priority (&optional comparator-or-priority priority)~ :: Return non-nil if current heading has a certain priority.  ~COMPARATOR-OR-PRIORITY~ should be either a comparator function, like ~<=~, or a priority string, like "A" (in which case (~=~ will be the comparator).  If ~COMPARATOR-OR-PRIORITY~ is a comparator, ~PRIORITY~ should be a priority string.
-+  ~property (property &optional value)~ :: Return non-nil if current entry has ~PROPERTY~ (a string), and optionally ~VALUE~ (a string).
-+  ~regexp (regexp)~ :: Return non-nil if current entry matches ~REGEXP~ (a regexp string).
-+  ~scheduled (&optional comparator target-date)~ :: Return non-nil if entry's scheduled date compares with ~TARGET-DATE~ using ~COMPARATOR~.  ~TARGET-DATE~ should be a string parseable by ~date-to-day~.  ~COMPARATOR~ should be a function (like ~<=~).
-+  ~tags (tags)~ :: Return non-nil if current heading has one or more of ~TAGS~ (a list of strings).
-+  ~todo (keywords)~ :: Return non-nil if current heading is a ~TODO~ item.  With ~KEYWORDS~, return non-nil if its keyword is one of ~KEYWORDS~ (a list of strings).
-
 * Notes
 
 ** Comparison with Org Agenda searches
@@ -200,15 +206,18 @@ Generates the predicate subtree.
 #+BEGIN_SRC elisp
   (defun org-ql--readme-predicate-list ()
     "Return an Org list string documenting predicates."
-    (concat "Arguments are listed next to predicate names, when applicable.\n\n"
+    (concat (unpackaged/docstring-to-org
+             "Arguments are listed next to predicate names, when applicable.
+
+  Note that, for convenience, standard numeric comparator function symbols (`<', `=', etc.) do not need to be quoted when passed as an argument to these predicates.  See examples in documentation.\n\n")
             (s-join "\n" (->> org-ql-predicates
                               (--sort (string< (symbol-name (plist-get it :name))
                                                (symbol-name (plist-get other :name))))
                               (--map (-let* (((&plist :name name :docstring docstring :fn fn) it)
                                              (args (->> (help-function-arglist fn)
-                                                        (--remove (or (eq it '&rest)
+                                                        (--replace-where (eq it '&rest) '&optional)
-                                                                      ;; Comparing the symbol itself doesn't work for some reason.
+                                                        ;; Comparing the `--cl-rest--' symbol itself doesn't work for some reason.
-                                                                      (string= (symbol-name it) "--cl-rest--"))))))
+                                                        (--remove (string= (symbol-name it) "--cl-rest--")))))
                                        (if docstring
                                            (progn
                                              (setq docstring (s-replace "\n" "  " docstring))
@@ -236,5 +245,5 @@ Generates the predicate subtree.
   (defun org-ql--readme-update-predicates ()
     "Update predicate subtree in current document."
     (interactive)
-    (org-ql--readme-replace-node '("Usage" "Predicates") (org-ql--readme-predicate-list)))
+    (org-ql--readme-replace-node '("Usage" "Queries" "Predicates") (org-ql--readme-predicate-list)))
 #+END_SRC