From eb722649c5f2897227aa8aef3a2b40c75b170377 Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Fri, 6 Sep 2019 12:26:06 -0500
Subject: [PATCH] Add: org-ql-block-header

Closes #32.
---
 README.org       |  6 +++++-
 examples.org     |  9 +++++----
 org-ql-agenda.el | 23 +++++++++++++++--------
 3 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/README.org b/README.org
index 7868580..05c6c03 100644
--- a/README.org
+++ b/README.org
@@ -270,7 +270,8 @@ For use as a custom agenda block type in ~org-agenda-custom-commands~.  For exam
         '(("ces" "Custom: Agenda and Emacs SOMEDAY [#A] items"
            ((org-ql-block '(and (todo "SOMEDAY")
                                 (tags "Emacs")
-                                (priority "A")))
+                                (priority "A"))
+                          ((org-ql-block-header "SOMEDAY :Emacs: High-priority")))
             (agenda)))))
 #+END_SRC
 
@@ -285,6 +286,8 @@ Which would be equivalent to a ~tags-todo~ search like this:
 
 However, the ~org-ql-block~ version runs in about 1/5th the time.
 
+The variable =org-ql-block-header= may be bound to a string to use as the block header, otherwise the header is formed automatically.
+
 **** Macro: ~org-ql-agenda~
 
 This macro is like ~org-ql~, but it presents matching entries in an Agenda-like view.  It's compatible with [[https://github.com/alphapapa/org-super-agenda][org-super-agenda]], which provides grouping.  For example:
@@ -464,6 +467,7 @@ Expands into a call to ~org-ql-select~ with the same arguments.  For convenience
      -  For inherited tags: =tags-inherited=, =inherited-tags=, =tags-i=, =itags=.
      -  For heading-local tags: =tags-local=, =local-tags=, =tags-l=, =ltags=.
      -  =tags-all=, =tags&=: Matches all given tags using boolean =AND= (rather than boolean =OR=, which the =tags= predicate uses).
++  Variable =org-ql-block-header=, which overrides the default header in =org-ql-block= agenda blocks.
 
 *Changed*
 +  Predicate =heading= now accepts multiple regexps.
diff --git a/examples.org b/examples.org
index fc08a2d..ea476a7 100644
--- a/examples.org
+++ b/examples.org
@@ -52,10 +52,11 @@ With this =org-ql-block= agenda view, like:
 #+BEGIN_SRC elisp
   (setq org-agenda-custom-commands
         '(("s" "Stuck Projects"
-           ((org-ql-block '(and (tags "@project")
-                                (not (done))
-                                (not (descendants (todo "NEXT")))
-                                (not (descendants (scheduled)))))))))
+            ((org-ql-block '(and (tags "@project")
+                                 (not (done))
+                                 (not (descendants (todo "NEXT")))
+                                 (not (descendants (scheduled))))
+                           ((org-ql-block-header "Stuck Projects")))))))
 #+END_SRC
 
 * Listing bills coming due
diff --git a/org-ql-agenda.el b/org-ql-agenda.el
index 33d3087..d8520ff 100644
--- a/org-ql-agenda.el
+++ b/org-ql-agenda.el
@@ -69,6 +69,9 @@
   "Keymap for `org-ql-agenda', `org-ql-search', and `org-ql-views' views.
 Based on `org-agenda-mode-map'.")
 
+(defvar org-ql-block-header nil
+  "A string to override the default header in `org-ql-block' agenda blocks.")
+
 ;; For refreshing results buffers.
 (defvar org-ql-buffers-files)
 (defvar org-ql-query)
@@ -408,12 +411,16 @@ Runs `org-occur-hook' after making the sparse tree."
 
 (defun org-ql-agenda-block (query)
   "Insert items for QUERY into current buffer.
-QUERY should be an `org-ql' query form.  Like other agenda block
-commands, it searches files returned by function
-`org-agenda-files'.  Intended to be used as a user-defined
-function in `org-agenda-custom-commands'.  QUERY corresponds to
-the `match' item in the custom command form.  Inserts a newline
-after the block."
+QUERY should be an `org-ql' query form.  Intended to be used as a
+user-defined function in `org-agenda-custom-commands'.  QUERY
+corresponds to the `match' item in the custom command form.
+
+Like other agenda block commands, it searches files returned by
+function `org-agenda-files'.  Inserts a newline after the block.
+
+If `org-ql-block-header' is non-nil, it is used as the header
+string for the block, otherwise a the header is formed
+automatically from the query."
   (when-let* ((from (org-agenda-files nil 'ifmode))
               (items (org-ql-select from
                        query :action 'element-with-markers)))
@@ -421,8 +428,8 @@ after the block."
     (org-agenda-prepare)
     ;; TODO: `org-agenda--insert-overriding-header' is from an Org version newer than
     ;; I'm using.  Should probably declare it as a minimum Org version after upgrading.
-    ;;  (org-agenda--insert-overriding-header (org-ql-agenda--header-line-format from query))
-    (insert (org-add-props (org-ql-agenda--header-line-format from query)
+    ;;  (org-agenda--insert-overriding-header (or org-ql-block-header (org-ql-agenda--header-line-format from query)))
+    (insert (org-add-props (or org-ql-block-header (org-ql-agenda--header-line-format from query))
 		nil 'face 'org-agenda-structure) "\n")
     ;; Calling `org-agenda-finalize' should be unnecessary, because in a "series" agenda,
     ;; `org-agenda-multi' is bound non-nil, in which case `org-agenda-finalize' does nothing.