[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/org 5a98b4c563 3/5: lisp/org-colview.el: Add formatter
From: |
ELPA Syncer |
Subject: |
[elpa] externals/org 5a98b4c563 3/5: lisp/org-colview.el: Add formatter parameter to colview dynamic block |
Date: |
Fri, 26 Apr 2024 10:05:34 -0400 (EDT) |
branch: externals/org
commit 5a98b4c563dc6e688e805e4ef8411c65f5d0471b
Author: Alexander Adolf <alexander.adolf@condition-alpha.com>
Commit: Ihor Radchenko <yantar92@posteo.net>
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.
* testing/lisp/test-org-colview.el (test-org-colview/dblock): New test
for formatting function.
(test-org-colview/dblock-formatter): New function used in formatting
test.
* 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 | 7 +++++++
etc/ORG-NEWS | 29 +++++++++++++++++++++++++++++
lisp/org-colview.el | 38 +++++++++++++++++++++++++++++++++-----
testing/lisp/test-org-colview.el | 20 ++++++++++++++++++++
4 files changed, 89 insertions(+), 5 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 786248af9a..aaeed11f88 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -6014,6 +6014,13 @@ This dynamic block has the following parameters:
Specify a column attribute (see [[*Column attributes]]) for the dynamic
block.
+- =:formatter= ::
+
+ #+cindex: @samp{formatter}, dynamic block parameter
+ #+vindex: org-columns-dblock-formatter
+ A function to format column view data and insert it into the buffer.
+ See the option ~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 fc5a86718e..827701835d 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1027,6 +1027,16 @@ When using =biblatex= to export bibliographies, you can
use the format
as specified in the =biblatex= package documentation as
=key=val,key=val,...=
+*** New option ~org-columns-dblock-formatter~
+
+=colview= dynamic blocks now understand a new ~:formatter~ parameter
+to use a specific function for formatting and inserting 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
*** =ob-lua=: Support all types and multiple values in results
@@ -1075,6 +1085,25 @@ 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 and insert 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.
+
+This new feature replicates the ~:formatter~ option already available
+for =clocktable= dynamic blocks.
+
*** =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 4718d1db7b..6241fa3ba0 100644
--- a/lisp/org-colview.el
+++ b/lisp/org-colview.el
@@ -123,6 +123,12 @@ 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
+ :package-version '(Org . "9.7")
+ :type 'function)
;;; Column View
@@ -1442,9 +1448,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,7 +1555,13 @@ PARAMS is a property list of parameters:
`:vlines'
When non-nil, make each column a column group to enforce
- vertical lines."
+ vertical lines.
+
+`:formatter'
+
+ A function to format the data and insert it into the
+ buffer. Overrides the default formatting function set in
+ `org-columns-dblock-formatter'."
(let ((table
(let ((id (plist-get params :id))
view-file view-pos)
@@ -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 (point) 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
@@ -1616,6 +1642,8 @@ PARAMS is a property list of parameters:
;; to the resulting table, adding alignment field as the first
;; row.
(push (mapcar (lambda (width) (when width (format "<%d>" width)))
width-specs) table))
+ ;; now insert the table into the buffer
+ (goto-char ipos)
(let ((content-lines (org-split-string (plist-get params :content) "\n"))
recalc)
;; Insert affiliated keywords before the table.
diff --git a/testing/lisp/test-org-colview.el b/testing/lisp/test-org-colview.el
index 7f0aa763ec..bcf4e897fa 100644
--- a/testing/lisp/test-org-colview.el
+++ b/testing/lisp/test-org-colview.el
@@ -1398,6 +1398,13 @@
;;; Dynamic block
+(defun test-org-colview/dblock-formatter (ipos table params)
+ "User-defined columnview dblock formatting function."
+ (goto-char ipos)
+ (insert-before-markers "Hello columnview!" "\n")
+ (insert-before-markers (format "table has %d rows" (length table)) "\n")
+ (insert-before-markers (format "there are %d parameters" (/ (length params)
2))))
+
(ert-deftest test-org-colview/dblock ()
"Test the column view table."
(should
@@ -1703,6 +1710,19 @@ SCHEDULED: <2020-05-11 Mon> DEADLINE: <2020-05-14 Thu>
(let ((org-columns-default-format
"%ITEM %DEADLINE(d) %SCHEDULED(s) %TIMESTAMP(t)"))
(org-update-dblock))
+ (buffer-substring-no-properties (point) (point-max)))))
+ ;; custom formatting function
+ (should
+ (equal
+ "#+BEGIN: columnview :formatter test-org-colview/dblock-formatter
+Hello columnview!
+table has 3 rows
+there are 4 parameters
+#+END:"
+ (org-test-with-temp-text
+ "* H\n<point>#+BEGIN: columnview :formatter
test-org-colview/dblock-formatter\n#+END:"
+ (let ((org-columns-default-format "%ITEM"))
+ (org-update-dblock))
(buffer-substring-no-properties (point) (point-max))))))
(provide 'test-org-colview)