Add: (:ancestor-with-todo)

README.org

@@ -188,6 +188,7 @@ Every selector requires an argument, even if it's just ~t~, e.g. ~:anything~, ~:
 
 These selectors take one argument alone, or multiple arguments in a list. 
 
++  ~:ancestor-with-todo~ :: Group items whose ancestor (up to ~:limit~ hops, or with ~:nearestp~, their nearest) has the given to-do keyword.  (For example, ~(:ancestor-with-todo ("PROJECT" :nearestp t))~ to group by the nearest ancestor project heading.)
 +  =:category= :: Group items that match any of the given categories.  Argument may be a string or list of strings.
 +  =:children= :: Select any item that has child entries.  Argument may be ~t~ to match if it has any children, ~nil~ to match if it has no children, ~todo~ to match if it has children with any to-do keywords, or a string to match if it has children with certain to-do keywords.  You might use this to select items that are project top-level headings.  Be aware that this may be very slow in non-daily/weekly agenda views because of its recursive nature.
 +  =:date= :: Group items that have a date associated. Argument can be =t= to match items with any date, =nil= to match items without a date, or =today= to match items with today’s date. The =ts-date= text-property is matched against.
@@ -240,6 +241,7 @@ As explained in the usage instructions and shown in the example, items are colle
 ** 1.4-pre
 
 *Additions*
++ Selector ~:ancestor-with-todo~, which groups items by their ancestor having a certain to-do keyword (up to a ~:limit~ number of hops, or with ~:nearestp~, the nearest one).  (Useful, for example, to group items by their parent or ancestor project.)
 + Option ~org-super-agenda-show-message~ allows disabling of the message shown when the mode is enabled.  (Thanks to [[https://github.com/hpfr][Liam Hupfer]].)
 
 ** 1.3

org-super-agenda.el

@@ -104,6 +104,7 @@
 
 ;;;; Requirements
 
+(require 'map)
 (require 'subr-x)
 (require 'org)
 (require 'org-agenda)
@@ -1099,6 +1100,38 @@ key and as the header for its group."
               (when (org-up-heading-safe)
                 (org-entry-get nil "ITEM"))))
 
+(org-super-agenda--def-auto-group ancestor-with-todo
+  "their earliest ancestor having the to-do keyword"
+  ;; TODO: Add tests.
+  :keyword :ancestor-with-todo
+  ;; FIXME: It's very awkward that for a single argument `args' is
+  ;; that argument, while multiple ones are provided as a list.
+  :key-form (let* ((keyword (cl-typecase (car args)
+                              (atom (car args))
+                              (cons (caar args))))
+                   (limit (cl-typecase (car args)
+                            (cons (plist-get (cdar args) :limit))))
+                   (nearestp (cl-typecase (car args)
+                               (cons (plist-get (cdar args) :nearestp)))))
+              (org-super-agenda--when-with-marker-buffer (org-super-agenda--get-marker item)
+                (cl-loop with ancestor
+                         while (and (or (not limit)
+                                        (natnump (cl-decf limit)))
+                                    (org-up-heading-safe))
+                         when (equal keyword (org-get-todo-state))
+                         do (setf ancestor (org-entry-get nil "ITEM"))
+                         when (and nearestp ancestor)
+                         return ancestor
+                         finally return ancestor)))
+  :header-form (let ((keyword (cl-typecase (car args)
+                                (atom (car args))
+                                (cons (caar args))))
+                     (prefix (if (cl-typecase (car args)
+                                   (cons (plist-get (cdar args) :nearestp)))
+                                 "Nearest"
+                               "Ancestor")))
+                 (format "%s %s: %s" prefix keyword key)))
+
 ;;;;; Dispatchers
 
 (defun org-super-agenda--get-selector-fn (selector)

org-super-agenda.info

@@ -389,6 +389,11 @@ File: README.info,  Node: Normal selectors,  Prev: Special selectors,  Up: Group
 These selectors take one argument alone, or multiple arguments in a
 list.
 
+‘:ancestor-with-todo’
+     Group items whose ancestor (up to ‘:limit’ hops, or with
+     ‘:nearestp’, their nearest) has the given to-do keyword.  (For
+     example, ‘(:ancestor-with-todo ("PROJECT" :nearestp t))’ to group
+     by the nearest ancestor project heading.)
 ‘:category’
      Group items that match any of the given categories.  Argument may
      be a string or list of strings.
@@ -564,6 +569,10 @@ File: README.info,  Node: 14-pre,  Next: 13,  Up: Changelog
 ===========
 
 *Additions*
+   • Selector ‘:ancestor-with-todo’, which groups items by their
+     ancestor having a certain to-do keyword (up to a ‘:limit’ number of
+     hops, or with ‘:nearestp’, the nearest one).  (Useful, for example,
+     to group items by their parent or ancestor project.)
    • Option ‘org-super-agenda-show-message’ allows disabling of the
      message shown when the mode is enabled.  (Thanks to Liam Hupfer
      (https://github.com/hpfr).)
@@ -819,24 +828,24 @@ Node: Group selectors8016
 Node: Keywords8978
 Node: Special selectors9707
 Node: Normal selectors13986
-Node: Tips18866
-Node: FAQ19747
-Node: Why are some items not displayed even though I used group selectors for them?19997
-Node: Why did a group disappear when I moved it to the end of the list?20892
-Node: Changelog21473
-Node: 14-pre21711
-Node: 1321988
-Node: 1223551
-Node: 11126221
-Node: 1126396
-Node: 10327980
-Node: 10228191
-Node: 10128325
-Node: 10028663
-Node: Development28768
-Node: Bugs29170
-Node: Tests29864
-Node: Credits30201
+Node: Tips19152
+Node: FAQ20033
+Node: Why are some items not displayed even though I used group selectors for them?20283
+Node: Why did a group disappear when I moved it to the end of the list?21178
+Node: Changelog21759
+Node: 14-pre21997
+Node: 1322557
+Node: 1224120
+Node: 11126790
+Node: 1126965
+Node: 10328549
+Node: 10228760
+Node: 10128894
+Node: 10029232
+Node: Development29337
+Node: Bugs29739
+Node: Tests30433
+Node: Credits30770
 
 End Tag Table