looping on A Scripter's Notes

Org: Show only Post subtree headings

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Thu, 16 Jun 2022 00:21:00 -0400

How to define a custom org-global-cycle-like command that collapses only the Org subtrees with specific properties.

Table of Contents

Org Global Cycle
Skeleton of only Post headings
The “Collapse All Posts” function
Binding with C-u C-c TAB
Result

I start this post by introducing what the Org mode global cycling command does, what kind of subtree folding I actually need, and then share the solution with code snippets.

Org Global Cycle #

Org mode has a built-in org-global-cycle command that you might be familiar with. It’s bound by default to the S-TAB key. Each time this command is called, the Org buffer will cycle through these states:

Overview: Show only the Level 1 headings and collapse everything underneath.
Contents: Show only the Org headings and collapse all the content.
Show All: Expand all the headings and show their contents too.

If a numeric prefix N is used with this command, it will show only the Org headings up to Level N. For example, C-2 S-TAB will show only the headings up to Level 2.

This is a really helpful command, but I needed something different ..

Skeleton of only Post headings #

I maintain most of this website’s content in a single Org file. I have dozens of blog posts organized in Org subtrees, which I further organize under “category” headings .. It kind of looks like the below mock-up: It’s amazing how many features PlantUML has. If you are interested in creating diagrams like these, check out the PlantUML Salt syntax.

Figure 1: Post Subtrees at arbitrary heading levels

As we can see,

All the post subtrees are not at Level 1 headings.
They are also not at a fixed Level N.
The heading level of the post depends on how many parent categories that post has (and that will also change over time).

I needed to basically show everything leading up to a post subtree heading, and then collapse all the content under that post; even the sub-headings.

The “Collapse All Posts” function #

The modi/org-hugo-collapse-all-posts function defined below meets the above requirement:

It first widens the whole buffer and expands all the headings.
Then it loops through all the headings and collapses all the post subtrees i.e. all the subtrees that have the EXPORT_FILE_NAME property set. This is where I use the org-map-entries magic.
Finally it looks for Org headings that begin with “Footnotes” or “COMMENT” and collapses them as well.

I am using the development version of Org mode (version 9.6, yet to be released as of <2022-06-15 Wed>) which has the new org-fold library. This library obsoletes the use of outline.el library and other code-folding related functions in Org mode. So cl-flet is used to create function symbol aliases that use the org-fold-* functions if available, otherwise they fall back to the legacy functions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


(defun modi/org-hugo-collapse-all-posts ()
 "Collapse all post subtrees in the current buffer.
Also collapse the Footnotes subtree and COMMENT subtrees if
present.

A post subtree is one that has the EXPORT_FILE_NAME property
set."
 (interactive)
 (cl-flet ((show-all (if (fboundp 'org-fold-show-all)
 #'org-fold-show-all
 #'org-show-all))
 (hide-subtree (if (fboundp 'org-fold-hide-subtree)
 #'org-fold-hide-subtree
 #'outline-hide-subtree)))
 (widen)
 (show-all '(headings))
 ;; Collapse all the post subtrees (ones with EXPORT_FILE_NAME
 ;; property set).
 (org-map-entries #'hide-subtree "EXPORT_FILE_NAME<>\"\"" 'file)
 ;; Also hide Footnotes and comments.
 (save-excursion
 (goto-char (point-min))
 (while (re-search-forward "^\\(\\* Footnotes\\|\\*+ COMMENT\\)"
 nil :noerror)
 (hide-subtree)))))

Code Snippet 1: Function that collapses all the post subtrees in the current buffer

Binding with `C-u C-c TAB` #

The function is ready, but let’s now add a bit of convenience to it.

If a point is under a subtree, C-c TAB will collapse that subtree while showing only Level 1 headings, and if a numeric prefix is used, it will show only those many levels of headings. I decided to bind the above function to C-u C-c TAB because,

The behavior of modi/org-hugo-collapse-all-posts falls in the same category as that of C-c TAB.
The C-u C-c .. binding rolls off the fingers pretty nicely 😃.

This binding is achieved using one of my favorite Emacs features .. the advice system. The :before-until Advice Combinator is used here, which means that if the advising function (below) returns a nil, the advised or the original function org-ctrl-c-tab is not called.

The advising function below detects if the C-u prefix argument is used. If it is, the modi/org-hugo-collapse-all-posts function is called, otherwise the original org-ctrl-c-tab function is called.

1
2
3
4
5
6
7
8
9


(defun modi/org-ctrl-c-tab-advice (&rest args)
 "Run `modi/org-hugo-collapse-all-posts' when
doing \\[universal-argument] \\[org-ctrl-c-tab]."
 (let ((do-not-run-orig-fn (equal '(4) current-prefix-arg)))
 (when do-not-run-orig-fn
 (modi/org-hugo-collapse-all-posts))
 do-not-run-orig-fn))

(advice-add 'org-ctrl-c-tab :before-until #'modi/org-ctrl-c-tab-advice)

Code Snippet 2: Bind C-u C-c TAB to call modi/org-hugo-collapse-all-posts

Result #

After evaluating the above two snippets, when I do C-u C-c TAB in my “blog posts” Org buffer, I see this:

Figure 2: My “blog posts” Org buffer showing only the Post subtree headings

It matches that earlier mockup — Mission accomplished! 💯

Looping through Org mode headings

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Wed, 18 May 2022 23:29:00 -0400

Using the org-map-entries API to loop through selected or all headings in an Org file.

Table of Contents

org-map-entries API
Example: Modifying a property in all headings
org-map-entries References

Below question on Mastodon by the user @postroutine inspired me to write this post:

I got a lot of Org-Mode headings and I want to modify their properties (add, remove, edit). Is there a function to do the same modifications on each heading?

I think that the best solution to that question is using the org-map-entries function.

But somehow when replying to that question then, that wasn’t what first came to my mind! .. when ironically that function is the main function that enables my preferred subtree-based flow in ox-hugo 😆. So I am writing this post to better ingrain the following concept in myself ..

If you need to loop through headings in an Org buffer, and especially if you need to modify that buffer in the process, use org-map-entries¹.

Next,

I will give a give introduction to the org-map-entries API.
Then provide a super-short solution to the above question.

`org-map-entries` API #

I will give only a broad level overview on how to use this function. I would encourage the reader to refer to the resources at the end of this post to learn more about it.

So let’s start by looking at this function’s signature:

(org-map-entries FUNC &optional MATCH SCOPE &rest SKIP)

Code Snippet 1: Signature of the org-map-entries function

The org-map-entries function iterates through all the headings meeting the MATCH criteria in the determined SCOPE, and then calls the specified function FUNC at each of those headings.

The FUNC function accepts no arguments and is called at the beginning of each Org heading.
The optional second argument MATCH is either nil, t or a search string.
- If MATCH is nil or t, all headings will be visited by the iteration and FUNC will be called on all of them.
- But if MATCH is a string, the headings will first be filtered based on that string and then the FUNC will be called on only those.
For explanations on the optional SCOPE and SKIP arguments, see Org Info: Using the Mapping API or C-h f org-map-entries from within Emacs.

Here’s a typical org-map-entries call that loops through all the headings in the visible buffer: (org-map-entries #'some-function) where all the optional argument values are nil. Next, we’ll see some examples of string-type MATCH arguments used for filtering the headings.

MATCH strings #

Below table shows few examples of match string patterns.

Table 1: String-type MATCH argument examples for org-map-entries

Search string	Description	Example
`"TAG"`	Tag name	`"foo"` matches all headings with that tag
`"{TAG REGEXP}"`	Regexp matching tags	`"{f.*}"` matches all headings whose tags match that regexp
`"TAG1+TAG2+.."`	Tag set intersection	`"foo+bar"` matches all headings with both of those tags
`"TAG1-TAG2+.."`	Tag set difference	`"foo-bar"` matches all headings with `foo` tag but without `bar` tag
`"TAG1`\|`TAG2`\|`.."`	Tag set union or boolean OR	`"foo`\|`bar"` matches all headings with either of those tags
`"TAG1&TAG2&.."`	Tag set intersection or boolean AND	`"foo&bar"` is same as `"foo+bar"`
`"PROP`=`\"STRVAL\""`	Specified property value matching a string	`"color`=`\"blue\""` matches all headings where `color` property is `blue`
`"PROP<>\"STRVAL\""`	Specified property value not matching a string	`"color<>\"blue\""` matches all headings where `color` property is not `blue`
`"PROP`=`{VAL REGEXP}"`	Specified property value matching a regexp	`"color={b.}"` matches all headings where `color` property value matches ‘`b.`’ regexp
`"PROP[OP]NUMVAL"`	Specified property value compared with a numeric value	`"some_num`>=`10"` matches all headings where `some_num` property is >=10
`"LEVEL[OP]VAL"`	Check value of headline’s special property LEVEL	`"level>2"` matches all headlines at levels greater than 2
`"TODO[OP]\"STRVAL\""`	Check value of headline’s TODO state	`"TODO`=`\"DONE\""` matches all headlines with TODO state set to ‘DONE’

Comparison Types #

If the comparison value is a plain number, a numerical comparison is done, and the allowed operators are ‘<’, ‘=’, ‘>’, ‘<=’, ‘>=’, and ‘<>’.
If the comparison value is enclosed in double quotes, a string comparison is done, and the same operators are allowed.
If the comparison value is enclosed in curly braces, a regexp match is performed. For this comparison, only ‘=’ (regexp matches) and ‘<>’ (regexp does not match) operators are allowed.
Comparison with dates and Group Tags is also possible. See Org Info: Matching tags and properties for more details.

Other notes #

The property names are case-insensitive. So these all work the same: "COLOR<>\"blue\"", "color<>\"blue\"", "Color<>\"blue\"".
The “tag” and “property” matches can be mixed up using the boolean ‘&’, ‘|’, ‘+’ and ‘-’ operators. So searching ‘+LEVEL=3+boss-TODO="DONE"’ lists all level three headlines that have the tag ‘boss’ and are not marked with the TODO keyword ‘DONE’.
‘&’ binds more strongly than ‘|’.
Grouping of match expressions using parentheses is not supported.

Example: Modifying a property in all headings #

Below is an example solution to the Mastoson question that I referenced in the beginning of this post.

(defun test/set-property-at-heading ()
 "Function to be called at the beginning of an Org heading."
 (let ((el (org-element-at-point)))
 (org-set-property "foo" (org-element-property :title el))))
(org-map-entries #'test/set-property-at-heading)

Code Snippet 2: Dummy example showing how to set a property for all Org headings using org-map-entries

It defines a function that parses the Org element at point using org-element-at-point, gets the title property of the element This function is designed to be called by org-map-entries and so the point at the time of calling this function will always be on a heading. , and sets that to the headline element’s foo property.
The org-map-entries call now simply calls this function on each heading in the visible scope of the Org buffer.

`org-map-entries` References #

Org mode has another popular mapping/looping API function org-element-map. I won’t go into much detail about that in this post — I’ll just mention that org-element-map is not the best choice if you need to modify the original Org buffer. It’s main use is to loop through a parsed AST of an Org buffer and optional modify those elements in memory. ↩︎