Add: org-ql-block-header

Closes #32.

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.

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")
+            ((org-ql-block '(and (tags "@project")
-                                (not (done))
+                                 (not (done))
-                                (not (descendants (todo "NEXT")))
+                                 (not (descendants (todo "NEXT")))
-                                (not (descendants (scheduled)))))))))
+                                 (not (descendants (scheduled))))
+                           ((org-ql-block-header "Stuck Projects")))))))
 #+END_SRC
 
 * Listing bills coming due

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
+QUERY should be an `org-ql' query form.  Intended to be used as a
-commands, it searches files returned by function
+user-defined function in `org-agenda-custom-commands'.  QUERY
-`org-agenda-files'.  Intended to be used as a user-defined
+corresponds to the `match' item in the custom command form.
-function in `org-agenda-custom-commands'.  QUERY corresponds to
+
-the `match' item in the custom command form.  Inserts a newline
+Like other agenda block commands, it searches files returned by
-after the block."
+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))
+    ;;  (org-agenda--insert-overriding-header (or org-ql-block-header (org-ql-agenda--header-line-format from query)))
-    (insert (org-add-props (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.