Org has sophisticated mapping capabilities to find all entries satisfying certain criteria. Internally, this functionality is used to produce agenda views, but there is also an API that can be used to execute arbitrary functions for each or selected entries. The main entry point for this API is:
function org-map-entries func \&optional match scope \&rest skip
FUNC at each headline selected by
FUNC is a function or a Lisp form. With point positioned at the beginning of the headline, call the function without arguments. Org returns an alist of return values of calls to the function.
To avoid preserving point, Org wraps the call to
save-excursion form. After evaluation, Org moves point to the end of the line that was just processed. Search continues from that point forward. This may not always work as expected under some conditions, such as if the current sub-tree was removed by a previous archiving operation. In such rare circumstances, Org skips the next entry entirely when it should not. To stop Org from such skips, make
FUNC set the variable
org-map-continue-from to a specific buffer position.
MATCH is a tags/property/TODO match. Org iterates only matched headlines. Org iterates over all headlines when
SCOPE determines the scope of this command. It can be any of:
The current buffer, respecting the restriction, if any.
The subtree started with the entry at point.
The entries within the active region, if any.
The current buffer, without restriction.
The current buffer, and any archives associated with it.
All agenda files.
All agenda files with any archive files associated with them.
list of filenames
If this is a list, all files in the list are scanned.
The remaining arguments are treated as settings for the scanner’s skipping facilities. Valid arguments are:
Skip trees with the ‘
Skip trees with the COMMENT keyword.
function or Lisp form
Used as value for
org-agenda-skip-function, so whenever the function returns
FUNC is called for that entry and search continues from the point where the function leaves it.
The mapping routine can call any arbitrary function, even functions that change meta data or query the property API (see Using the Property API). Here are some handy functions:
function org-todo \&optional arg
Change the TODO state of the entry. See the docstring of the functions for the many possible values for the argument
function org-priority \&optional action
Change the priority of the entry. See the docstring of this function for the possible values for
function org-toggle-tag tag \&optional onoff
Toggle the tag
TAG in the current entry. Setting
ONOFF to either
off does not toggle tag, but ensure that it is either on or off.
Promote the current entry.
Demote the current entry.
This example turns all entries tagged with ‘
TOMORROW’ into TODO entries with keyword ‘
UPCOMING’. Org ignores entries in comment trees and archive trees.
(org-map-entries '(org-todo "UPCOMING")
"+TOMORROW" 'file 'archive 'comment)
The following example counts the number of entries with TODO keyword ‘
WAITING’, in all agenda files.
(length (org-map-entries t "/+WAITING" 'agenda))