From 75fd46022f46c547c1b8f21da803f72ed84b756b Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Tue, 1 Oct 2019 01:33:03 -0500
Subject: [PATCH] Fix: (org-ql-block-header, org-ql-search-block)

Omitted this feature when I refactored the -agenda file.  Also, put
back the improved docstring.

Fixes #32.  Thanks to Josiah Schwab (@jschwab).
---
 org-ql-search.el | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/org-ql-search.el b/org-ql-search.el
index 707ce9b..cbe1e5c 100644
--- a/org-ql-search.el
+++ b/org-ql-search.el
@@ -36,6 +36,11 @@
 (require 'org-ql)
 (require 'org-ql-view)
 
+;;;; Variables
+
+(defvar org-ql-block-header nil
+  "An optional string to override the default header in `org-ql-block' agenda blocks.")
+
 ;;;; Commands
 
 ;;;###autoload
@@ -158,12 +163,16 @@ necessary."
 
 (defun org-ql-search-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)))
@@ -171,8 +180,8 @@ after the block."
     (org-agenda-prepare)
     ;; FIXME: `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-search--header-line-format from query))
-    (insert (org-add-props (org-ql-view--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-view--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.