Add: (org-dblock-write:org-ql) Custom column headers

README.org

@@ -404,6 +404,7 @@ Org QL provides a dynamic block that lists entries in the current document match
 
 +  ~:query~: An Org QL query expression in either sexp or non-sexp form.
 +  ~:columns~ A list of columns, including ~heading~, ~todo~, ~priority~, ~deadline~, ~scheduled~.
+     -  Each column may also be specified as a list with the second element being a header string.  For example, to abbreviate the priority column: ~(priority "P")~
 +  ~:sort~ One or a list of Org QL sorting methods (see ~org-ql-select~).
 +  ~:take~ Optionally take a number of results from the front (a positive number) or the end (a negative number) of the results.
 +  ~:ts-format~ Optional format string used to format timestamp-based columns.
@@ -415,9 +416,9 @@ For example, this dynamic block shows the first seven headings that are to-do it
 # NOTE: These results are edited manually because the Org links don't display well in the Info manual.
 
 #+BEGIN_SRC org
-  ,#+BEGIN: org-ql :query "todo: priority:A,B" :columns (todo priority deadline heading) :sort (deadline priority) :take 7 :ts-format "%Y-%m-%d %H:%M"
+  ,#+BEGIN: org-ql :query "todo: priority:A,B" :columns (todo (priority "P") deadline heading) :sort (deadline priority) :take 7 :ts-format "%Y-%m-%d %H:%M"
-  | Todo | Priority | Deadline         | Heading                               |
+  | Todo | P | Deadline         | Heading                               |
-  |------+----------+------------------+---------------------------------------|
+  |------+---+------------------+---------------------------------------|
   | TODO | A | 2017-07-07 00:00 | Take over the world                   |
   | TODO | B | 2017-07-10 00:00 | Renew membership in supervillain club |
   | TODO | A | 2017-07-15 00:00 | Take over the universe                |

notes.org

@@ -20,9 +20,9 @@
 
 [[org-ql-search:%2528todo%2520%2522UNDERWAY%2522%2529?sort=%2528priority%2529&title=%2522Underway%2522][org-ql-search: Underway]]
 
-#+BEGIN: org-ql :query (todo "UNDERWAY") :columns (priority todo heading) :sort (priority date) :ts-format "%Y-%m-%d %H:%M"
+#+BEGIN: org-ql :query (todo "UNDERWAY") :columns ((priority "P") (todo "Keyword") heading) :sort (priority date) :ts-format "%Y-%m-%d %H:%M"
-| Priority | Todo     | Heading                                                            |
+| P | Keyword  | Heading                                                            |
-|----------+----------+--------------------------------------------------------------------|
+|---+----------+--------------------------------------------------------------------|
 | A | UNDERWAY | [[Tools%20for%20saving%20queries%20and%20accessing%20them%20%5B3/4%5D][Tools for saving queries and accessing them {3/4}]]                  |
 | A | UNDERWAY | [[Org%20link%20types%20%5B2/3%5D][Org link types {2/3}]]                                               |
 | A | UNDERWAY | [[Outline path predicate][Outline path predicate]]                                             |
@@ -37,9 +37,9 @@
 
 [[org-ql-search:%2528and%2520%2528todo%2520%2522TODO%2522%2529%2520%2528priority%2520%2522A%2522%2529%2529?sort=%2528priority%2529&title=%2522To-do%2520%255B%2523A%255D%2522][org-ql-search: To-do {#A}]]
 
-#+BEGIN: org-ql :query "todo:TODO priority:A" :columns (priority todo heading) :sort (priority date) :take 7
+#+BEGIN: org-ql :query "todo:TODO priority:A" :columns ((priority "P") todo heading) :sort (priority date) :take 7
-| Priority | Todo | Heading                                                      |
+| P | Todo | Heading                                                      |
-|----------+------+--------------------------------------------------------------|
+|---+------+--------------------------------------------------------------|
 | A | TODO | [[Add ~:auto~ keyword to ~(planning)~ predicate][Add ~:auto~ keyword to ~(planning)~ predicate]]                    |
 | A | TODO | [[Document sorters][Document sorters]]                                             |
 | A | TODO | [[Org block to insert results of queries with links to entries][Org block to insert results of queries with links to entries]] |

org-ql-search.el

@@ -242,17 +242,24 @@ automatically from the query."
   "Insert content for org-ql dynamic block at point according to PARAMS.
 Valid parameters include:
 
-  :query  An Org QL query expression in either sexp or non-sexp form.
+  :query    An Org QL query expression in either sexp or non-sexp
+            form.
 
   :columns  A list of columns, including `heading', `todo',
-  `priority', `deadline', `scheduled'.
+            `priority', `deadline', `scheduled'.  Each column may
+            also be specified as a list with the second element
+            being a header string.  For example, to abbreviate
+            the priority column:  (priority \"P\")
 
-  :sort  One or a list of Org QL sorting methods (see `org-ql-select').
+  :sort     One or a list of Org QL sorting methods
+            (see `org-ql-select').
 
   :take     Optionally take a number of results from the front (a
-  positive number) or the end (a negative number) of the results.
+            positive number) or the end (a negative number) of
+            the results.
 
-  :ts-format  Optional format string used to format timestamp-based columns.
+  :ts-format  Optional format string used to format
+              timestamp-based columns.
 
 For example, an org-ql dynamic block header could look like:
 
@@ -261,7 +268,7 @@ For example, an org-ql dynamic block header could look like:
                (query (cl-etypecase query
                         (string (org-ql--plain-query query))
                         (t query)))
-               (columns (or columns '(heading todo priority)))
+               (columns (or columns '(heading todo (priority "P"))))
                ;; MAYBE: Custom column functions.
                (format-fns
                 ;; NOTE: Backquoting this alist prevents the lambdas from seeing
@@ -290,11 +297,15 @@ For example, an org-ql dynamic block header could look like:
                        (integer (-take take elements)))))
     (cl-labels ((format-element
                  (element) (string-join (cl-loop for column in columns
-                                                 for fn = (alist-get column format-fns)
+                                                 for fn = (cl-etypecase column
+                                                            (symbol (alist-get column format-fns))
+                                                            (list (alist-get (car column) format-fns)))
                                                  collect (or (funcall fn element) ""))
                                         " | ")))
       ;; Insert table header.
-      (insert "| " (string-join (--map (capitalize (symbol-name it))
+      (insert "| " (string-join (--map (pcase it
+                                         ((pred symbolp) (capitalize (symbol-name it)))
+                                         (`(,_ ,name) name))
                                        columns)
                                 " | ")
               " |" "\n")

org-ql.info

@@ -728,6 +728,9 @@ supported:
      form.
    • ‘:columns’ A list of columns, including ‘heading’, ‘todo’,
      ‘priority’, ‘deadline’, ‘scheduled’.
+        • Each column may also be specified as a list with the second
+          element being a header string.  For example, to abbreviate the
+          priority column: ‘(priority "P")’
    • ‘:sort’ One or a list of Org QL sorting methods (see
      ‘org-ql-select’).
    • ‘:take’ Optionally take a number of results from the front (a
@@ -742,9 +745,9 @@ in the following example).
 are to-do items with priority A or B, sorted by deadline then priority,
 with certain columns and timestamp format:
 
-     #+BEGIN: org-ql :query "todo: priority:A,B" :columns (todo priority deadline heading) :sort (deadline priority) :take 7 :ts-format "%Y-%m-%d %H:%M"
+     #+BEGIN: org-ql :query "todo: priority:A,B" :columns (todo (priority "P") deadline heading) :sort (deadline priority) :take 7 :ts-format "%Y-%m-%d %H:%M"
-     | Todo | Priority | Deadline         | Heading                               |
+     | Todo | P | Deadline         | Heading                               |
-     |------+----------+------------------+---------------------------------------|
+     |------+---+------------------+---------------------------------------|
      | TODO | A | 2017-07-07 00:00 | Take over the world                   |
      | TODO | B | 2017-07-10 00:00 | Renew membership in supervillain club |
      | TODO | A | 2017-07-15 00:00 | Take over the universe                |
@@ -1277,29 +1280,29 @@ Node: Functions / Macros19621
 Node: Agenda-like views19876
 Node: Listing / acting-on results21281
 Node: Dynamic block25883
-Node: Links27910
+Node: Links28046
-Node: Tips28597
+Node: Tips28733
-Node: Changelog28915
+Node: Changelog29051
-Node: 05-pre29554
+Node: 05-pre29690
-Node: 04630536
+Node: 04630672
-Node: 04530939
+Node: 04531075
-Node: 04431298
+Node: 04431434
-Node: 04331655
+Node: 04331791
-Node: 04231850
+Node: 04231986
-Node: 04132009
+Node: 04132145
-Node: 0432248
+Node: 0432384
-Node: 03236179
+Node: 03236315
-Node: 03136556
+Node: 03136692
-Node: 0336753
+Node: 0336889
-Node: 02339728
+Node: 02339864
-Node: 02239956
+Node: 02240092
-Node: 02140224
+Node: 02140360
-Node: 0240423
+Node: 0240559
-Node: 0144458
+Node: 0144594
-Node: Notes44559
+Node: Notes44695
-Node: Comparison with Org Agenda searches44721
+Node: Comparison with Org Agenda searches44857
-Node: org-sidebar45593
+Node: org-sidebar45729
-Node: License45872
+Node: License46008
 
 End Tag Table