Previous: Using the property API, Up: Hacking

A.12 Using the mapping API

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:

— Function: org-map-entries func &optional match scope &rest skip

Call ‘FUNC’ at each headline selected by MATCH in SCOPE.

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 FUNC in 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-from to a specific buffer position.

MATCH’ is a tags/property/TODO match. Org iterates only matched headlines. Org iterates over all headlines when MATCH is nil or t.

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
                  the current buffer, and any archives associated with it
          agenda  all agenda files
                  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:

— 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 ARG.

— Function: org-priority &optional action

Change the priority of the entry. See the docstring of this function for the possible values for ACTION.

— Function: org-toggle-tag tag &optional onoff

Toggle the tag TAG in the current entry. Setting ONOFF to either on or off will not toggle tag, but ensure that it is either on or off.

— Function: org-promote

Promote the current entry.

— Function: org-demote

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-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))