Org has sophisticated mapping capabilities for finding entries. Org uses this functionality internally for generating agenda views. Org also exposes an API for executing arbitrary functions for each selected entry. The API's main entry point is:
Call ‘FUNC’ at each headline selected by
‘FUNC’ is a function or a Lisp form. With the cursor 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
FUNCin save-excursion form. After evaluation, Org moves the cursor 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-fromto 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:nil the current buffer, respecting the restriction if any tree the subtree started with the entry at point region The entries within the active region, if any file the current buffer, without restriction file-with-archives the current buffer, and any archives associated with it agenda all agenda files agenda-with-archives all agenda files with any archive files associated with them (file1 file2 ...) if this is a list, all files in the list will be scanned
The remaining args are treated as settings for the scanner's skipping facilities. Valid args are:archive skip trees with the archive tag comment skip trees with the COMMENT keyword function or Lisp form will be used as value for
org-agenda-skip-function, so whenever the function returns t, FUNC will not be called for that entry and search will continue 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:
Change the TODO state of the entry. See the docstring of the functions for the many possible values for the argument
Change the priority of the entry. See the docstring of this function for the possible values for
Toggle the tag
TAGin the current entry. Setting
offwill not toggle tag, but ensure that it is either on or off.
This example turns all entries tagged with
TOMORROW into TODO entries
UPCOMING. Org ignores entries in comment trees and
(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))