Update predicate naming scheme

1 files changed, 24 insertions, 15 deletions

diff --git a/org-urgency.el b/org-urgency.el
index f03efd1..85c0bec 100644
--- a/org-urgency.el
+++ b/org-urgency.el
@@ -35,6 +35,15 @@
 ;; slightly less verbose, and `org-urgency-define' for how to define your own
 ;; predicates.
 
+;; Note on the naming scheme of the `org-urgency-by-' functions:
+
+;; Functions ending in "?" or "=" will return the number passed to them if the
+;; heading matches.  Functions not ending in "?" or "=" will use the number
+;; passed to them to multiply the relevant value of the heading.
+;; E.g. `org-urgency-by-state?' will return the number passed if the heading
+;; is of the given state, whereas `org-urgency-by-effort' will multiply the
+;; effort of the heading by the number passed, and return that.
+
 ;;; Code:
 
 (require 'org)
@@ -59,18 +68,18 @@ argument being the heading in question (as passed to the function in
 
 If, then, `org-urgency-functions' were set to
 
- '((org-urgency-priority 10)
-   (org-urgency-state \"TODO\"))
+ '((org-urgency-by-priority 10)
+   (org-urgency-by-state? \"TODO\"))
 
 then the urgency of a heading H would be equivalent to
 
  (apply #\\='+
         (seq-remove #\\='null
                     (list
-                     (org-urgency-priority h 10)
-                     (org-urgency-state h \"TODO\" 10))))
+                     (org-urgency-by-priority h 10)
+                     (org-urgency-by-state? h \"TODO\" 10))))
 
-See the relevant `org-urgency-' functions for details.
+See the definitions of the relevant `org-urgency-by-' functions for details.
 
 Also see the function `org-urgency-list' for a shorthand way to assemble
 an appropriate list for this variable."
@@ -82,7 +91,7 @@ an appropriate list for this variable."
 
 ;;;###autoload
 (defmacro org-urgency-define (name args &rest body)
-  "Define `org-urgency-NAME' as a function.
+  "Define `org-urgency-by-NAME' as a function.
 
 Its lambda-list will be `(H ,@ARGS N), and BODY is the body of the
 function.  (H is the heading, as passed to
@@ -96,7 +105,7 @@ H.
 BODY should evaluate to a number, which will be added to the heading's
 total urgency, or nil."
   (declare (indent 2))
-  `(defun ,(intern (format "org-urgency-%s" name)) (h ,@args n)
+  `(defun ,(intern (format "org-urgency-by-%s" name)) (h ,@args n)
      "Weight function for use in `org-urgency-functions'."
      (cl-flet ((get (prop)
                  (org-urgency--get h prop)))
@@ -110,24 +119,24 @@ total urgency, or nil."
 (org-urgency-define priority ()
   (* (get 'priority) n))
 
-(org-urgency-define scheduled ()
+(org-urgency-define scheduled? ()
   (when (org-get-scheduled-time (get 'org-marker))
     n))
 
-(org-urgency-define deadline ()
+(org-urgency-define deadline? ()
   (when (org-get-deadline-time (get 'org-marker))
     n))
 
-(org-urgency-define tag (tag)
+(org-urgency-define tag? (tag)
   (when (member tag (get 'tags))
     n))
 
-(org-urgency-define habit ()
+(org-urgency-define habit? ()
   (require 'org-habit)
   (when (org-is-habit-p (get 'org-marker))
     n))
 
-(org-urgency-define state (state)
+(org-urgency-define state? (state)
   (when (equal (get 'todo-state) state)
     n))
 
@@ -141,14 +150,14 @@ total urgency, or nil."
 LIST should be a list of lists whose `car' is a symbol and whose `cdr'
 is a list of arguments.  An element such as
 
- (tag \"@home\" 10)
+ (tag? \"@home\" 10)
 
 will become
 
- (org-urgency-tag \"@home\" 10)"
+ (org-urgency-by-tag? \"@home\" 10)"
   (mapcar
    (lambda (x)
-     (cons (intern (format "org-urgency-%s" (car x)))
+     (cons (intern (format "org-urgency-by-%s" (car x)))
            (cdr x)))
    list))