From c21b18475dd154eed8d3f2489daa5a468531dc82 Mon Sep 17 00:00:00 2001 From: Alexander Adolf Date: Sun, 14 Apr 2024 18:14:05 +0200 Subject: [PATCH 1/2] lisp/org-colview.el: add formatter parameter to colview dynamic block * lisp/org-colview.el (org-dblock-write:column view): Factor out the existing formatting code to new function org-columns-dblock-write-default, and honour new dblock parameter :formatter for specifying a different formatting function. (org-columns-dblock-write-default): New function with current formatting code. (org-columns--capture-view): Amend docstring to better explain the format of the data being passed to the formatting function. (org-clock-clocktable-formatter): New option to define a global default formatting function, defaulting to the current behaviour. * doc/org-manual.org (Capturing column view): Describe new :formatter parameter. * etc/ORG-NEWS (New option ~org-columns-dblock-formatter~): Announce new option. (=colview= dynamic block supports custom formatting function): Describe new custom formatting function feature. --- doc/org-manual.org | 6 ++++++ etc/ORG-NEWS | 26 ++++++++++++++++++++++++++ lisp/org-colview.el | 38 ++++++++++++++++++++++++++++++++------ 3 files changed, 64 insertions(+), 6 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 6c699ae1e..e66e48cda 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -6012,6 +6012,12 @@ This dynamic block has the following parameters: Specify a column attribute (see [[*Column attributes]]) for the dynamic block. +- =:formatter= :: + + A function for formatting the data in the dynamic block, overriding + the default formatting function set in + ~org-columns-dblock-formatter~. + The following commands insert or update the dynamic block: - ~org-columns-insert-dblock~ :: diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index e61bd6988..eab181bc3 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -999,6 +999,16 @@ even though it does not have its own ID. By giving files top-level id properties, links to headlines in the file can also be made more robust by using the file id instead of the file path. +*** New option ~org-columns-dblock-formatter~ + +=colview= dynamic blocks now understand a new ~:formatter~ parameter +to use a specific function for formatting the contents of the dynamic +block. This new option can be used to set the global default +formatting function that will be used for =colview= dynamic blocks +that do not specify any ~:formatter~ parameter. Its default value (the +new function ~org-columns-dblock-write-default~) yields the previous +(fixed) formatting behaviour. + ** New features *** =colview= dynamic block now writes column width specifications @@ -1030,6 +1040,22 @@ Example: : | PROYECTO EMACS | : #+END: +*** =colview= dynamic block supports custom formatting function + +The =colview= dynamic block understands a new ~:formatter~ parameter, +which specifies a user-supplied function to format the data in the +dynamic block. + +A global default formatting function for =colview= dynamic blocks can +be set via the new option ~org-columns-dblock-formatter~ which +defaults to the new function ~org-columns-dblock-write-default~, that +implements the previous (fixed) formatting behaviour. Hence, the +default behaviour is identical to previous versions. + +The global default function can be overridden for any given =colview= +dynamic block individually by specifying a custom formatter function +using the new ~:formatter~ parameter on the block's =BEGIN= line. + *** =ob-tangle.el=: New flag to remove tangle targets before writing When ~org-babel-tangle-remove-file-before-write~ is set to ~t~ the diff --git a/lisp/org-colview.el b/lisp/org-colview.el index 4718d1db7..5c908affe 100644 --- a/lisp/org-colview.el +++ b/lisp/org-colview.el @@ -123,6 +123,13 @@ in `org-columns-summary-types-default', which see." (function :tag "Summarize") (function :tag "Collect"))))) +(defcustom org-columns-dblock-formatter #'org-columns-dblock-write-default + "Function to format data in column view dynamic blocks. +For more information, see `org-columns-dblock-write-default'." + :group 'org-properties + :version "30.0" + :package-version '(Org . "9.7") + :type 'function) ;;; Column View @@ -1442,9 +1449,13 @@ that will be excluded from the resulting view. FORMAT is a format string for columns, or nil. When LOCAL is non-nil, only capture headings in current subtree. -This function returns a list containing the title row and all -other rows. Each row is a list of fields, as strings, or -`hline'." +This function returns a list containing the title row and all other +rows. Each row is either a list, or the symbol `hline'. The first list +is the heading row as a list of strings with the column titles according +to FORMAT. All subsequent lists each represent a body row as a list +whose first element is an integer indicating the outline level of the +entry, and whose remaining elements are strings with the contents for +the columns according to FORMAT." (org-columns (not local) format) (goto-char org-columns-top-level-marker) (let ((columns (length org-columns-current-fmt-compiled)) @@ -1545,8 +1556,13 @@ PARAMS is a property list of parameters: `:vlines' When non-nil, make each column a column group to enforce - vertical lines." - (let ((table + vertical lines. + +`:formatter' + + A function to format the data and insert it into the buffer." + (let ((insert-pos (point)) + (table (let ((id (plist-get params :id)) view-file view-pos) (pcase id @@ -1573,7 +1589,17 @@ PARAMS is a property list of parameters: (plist-get params :exclude-tags) (plist-get params :format) view-pos))))) - (width-specs + (formatter (or (plist-get params :formatter) + org-columns-dblock-formatter + #'org-columns-dblock-write-default))) + (funcall formatter insert-pos table params))) + +(defun org-columns-dblock-write-default (ipos table params) + "Write out a columnview table at position IPOS in the current buffer. +TABLE is a table with data as produced by `org-columns--capture-view'. +PARAMS is the parameter property list obtained from the dynamic block +definition." + (let ((width-specs (mapcar (lambda (spec) (nth 2 spec)) org-columns-current-fmt-compiled))) (when table -- 2.39.3 (Apple Git-146)