From 13d3c1c4d92bc4e564d94b82f16e4a98036ca7e1 Mon Sep 17 00:00:00 2001 From: Adam Porter Date: Sat, 8 Jun 2019 04:45:14 -0500 Subject: [PATCH] Docs: Queries, etc. --- README.org | 59 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 34 insertions(+), 25 deletions(-) diff --git a/README.org b/README.org index ead7d66..670864d 100644 --- a/README.org +++ b/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) - ;; Comparing the symbol itself doesn't work for some reason. - (string= (symbol-name it) "--cl-rest--")))))) + (--replace-where (eq it '&rest) '&optional) + ;; Comparing the `--cl-rest--' symbol itself doesn't work for some reason. + (--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