From 3a036c3efb1b9143a59690188ba47440c7144620 Mon Sep 17 00:00:00 2001 From: Adam Porter Date: Sun, 9 Jun 2019 00:03:32 -0500 Subject: [PATCH] Fix: Predicate args in documentation --- README.org | 13 +++++++------ org-ql.el | 5 ++--- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.org b/README.org index ed32ece..15af222 100644 --- a/README.org +++ b/README.org @@ -88,8 +88,9 @@ 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. The resemblance to infix notation is coincidental. See examples in documentation. + ~category (&optional categories)~ :: Return non-nil if current heading is in one or more of ~CATEGORIES~ (a list of strings). ++ ~clocked (&key from to on)~ :: Return non-nil if current entry was clocked in given period. If no arguments are specified, return non-nil if entry was clocked at any time. If ~FROM~, return non-nil if entry was clocked on or after ~FROM~. If ~TO~, return non-nil if entry was clocked on or before ~TO~. If ~ON~, return non-nil if entry was clocked on date ~ON~. ~FROM~, ~TO~, and ~ON~ should be strings parseable by ~parse-time-string~ but may omit the time value. Note: See macrolet in ~org-ql-query~ which pre-processes arguments to this function, parsing timestamp strings into Unix timestamps and accepting `:on' keyword. + ~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 ~<=~). ++ ~date (&optional comparator target-date type)~ :: 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. @@ -103,6 +104,7 @@ Note that, for convenience, standard numeric comparator function symbols (~<~, ~ + ~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 :PROPERTIES: :TOC: ignore-children @@ -276,11 +278,10 @@ Generates the predicate subtree. (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) - (--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--"))))) + (--map (-let* (((&plist :name name :docstring docstring :fn fn :args args) it) + (args (->> args + (--replace-where (listp it) (car it)) + (--replace-where (eq '&rest it) '&optional)))) (if docstring (progn (setq docstring (s-replace "\n" " " docstring)) diff --git a/org-ql.el b/org-ql.el index 64c278b..4c28941 100644 --- a/org-ql.el +++ b/org-ql.el @@ -51,7 +51,7 @@ This list should not contain any duplicates.") (let ((fn-name (intern (concat "org-ql--predicate-" (symbol-name name)))) (pred-name (intern (symbol-name name)))) `(progn - (push (list :name ',pred-name :fn ',fn-name :docstring ,docstring) org-ql-predicates) + (push (list :name ',pred-name :fn ',fn-name :docstring ,docstring :args ',args) org-ql-predicates) (cl-defun ,fn-name ,args ,docstring ,@body)))) (cl-defmacro org-ql (buffers-or-files query &key sort narrow markers @@ -298,7 +298,7 @@ empty time values to 23:59:59; otherwise, to 00:00:00." ;;;;; Predicates -(org-ql--defpredicate clocked (&key from to) +(org-ql--defpredicate clocked (&key from to on) "Return non-nil if current entry was clocked in given period. If no arguments are specified, return non-nil if entry was clocked at any time. @@ -315,7 +315,6 @@ arguments to this function, parsing timestamp strings into Unix timestamps and accepting `:on' keyword." ;; NOTE: FROM and TO are actually expected to be Unix timestamps. The docstring is written ;; for end users, for which the arguments are pre-processed by `org-ql-query'. - (declare (advertised-calling-convention (&key from to on) nil)) ;; FIXME: This assumes every "clocked" entry is a range. Unclosed clock entries are not handled. (cl-macrolet ((next-timestamp () `(when (re-search-forward org-clock-line-re end-pos t)