Using the Mapping API (The Org Manual)

Previous: Using the Property API, Up: Hacking [Contents][Index]

### A.11 Using the Mapping API

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

  Call FUNC at each headline selected by MATCH in SCOPE.

  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 FUNC in `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 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.

  `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.

  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:

  `archive`

    Skip trees with the ‘`ARCHIVE`’ tag.

  `comment`

    Skip trees with the COMMENT keyword.

  function or Lisp form

    Used as value for `org-agenda-skip-function`, so whenever the function returns `t`, 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 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` does 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-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))

Previous: Using the Property API, Up: Hacking [Contents][Index]