[PATCH] org-agenda: Allow org-agenda-overriding-header to be a function

[Christopher League]

* org-agenda.el (org-agenda--insert-overriding-header): Allow
`org-agenda-overriding-header' to be a function in addition to a
string or nil. When the custom agenda is created or updated, call that
function and insert the string it returns as the agenda header.

This allows custom commands to produce dynamic headers that include
up-to-date information. For example, this produces a header with a
current timestamp:

(push '("DHD" "Dynamic header demo"
        ((alltodo
          ""
          ((org-agenda-overriding-header
            (lambda ()
              (propertize
               (format-time-string "-- Get crackin’, it’s %H:%M:%S!!\n")
               'face 'org-agenda-structure)))))))
      org-agenda-custom-commands)

User is free to add any face properties, use Org links, and include a
blank line or not. I am using this to count how many items are in
various inboxes and display them in an agenda.
---
 lisp/org-agenda.el | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index b4e5547d7..f5e332a29 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -2131,7 +2131,8 @@ works you probably want to add it to 
`org-agenda-custom-commands' for good."
 The inserted header depends on `org-agenda-overriding-header'.
 If the empty string, don't insert a header.  If any other string,
 insert it as a header.  If nil, insert DEFAULT, which should
-evaluate to a string."
+evaluate to a string.  If a function, call it and insert the
+string that it returns."
   (declare (debug (form)) (indent defun))
   `(cond
     ((not org-agenda-overriding-header) (insert ,default))
@@ -2140,6 +2141,8 @@ evaluate to a string."
      (insert (propertize org-agenda-overriding-header
                         'face 'org-agenda-structure)
             "\n"))
+    ((functionp org-agenda-overriding-header)
+     (insert (funcall org-agenda-overriding-header)))
     (t (user-error "Invalid value for `org-agenda-overriding-header': %S"
                   org-agenda-overriding-header))))
 
@@ -5046,10 +5049,11 @@ used by user-defined selections using 
`org-agenda-skip-function'.")
 (defvar org-agenda-overriding-header nil
   "When set during agenda, todo and tags searches it replaces the header.
 If an empty string, no header will be inserted.  If any other
-string, it will be inserted as a header.  If nil, a header will
-be generated automatically according to the command.  This
-variable should not be set directly, but custom commands can bind
-it in the options section.")
+string, it will be inserted as a header.  If a function, insert
+the string returned by the function as a header.  If nil, a
+header will be generated automatically according to the command.
+This variable should not be set directly, but custom commands can
+bind it in the options section.")
 
 (defun org-agenda-skip-entry-if (&rest conditions)
   "Skip entry if any of CONDITIONS is true.
-- 
2.31.1