Function: org-element-map

org-element-map is a byte-compiled function defined in org-element.el.gz.

Signature

(org-element-map DATA TYPES FUN &optional INFO FIRST-MATCH NO-RECURSION WITH-AFFILIATED NO-UNDEFER)

Documentation

Map a function on selected elements or objects.

DATA is a parse tree (for example, returned by org-element-parse-buffer), an element, an object, a string, or a list of such constructs. TYPES is a symbol or list of symbols of elements or object types (see org-element-all-elements and org-element-all-objects for a complete list of types). FUN is the function called on the matching element or object. It has to accept one argument: the element or object itself.

When TYPES is t, call FUN for all the elements and objects.

FUN can also be a Lisp form. The form will be evaluated as function with symbol node bound to the current node.

When optional argument INFO is non-nil, it should be a plist holding export options. In that case, elements of the parse tree
\(compared with eq) not exportable according to :ignore-list
property in that property list will be skipped.

When optional argument FIRST-MATCH is non-nil, stop at the first match for which FUN doesn't return nil, and return that value.

Optional argument NO-RECURSION is a symbol or a list of symbols representing elements or objects types. org-element-map won't enter any recursive element or object whose type belongs to that list. Though, FUN can still be applied on them.

When optional argument WITH-AFFILIATED is non-nil, FUN will also apply to matching objects within parsed affiliated keywords (see org-element-parsed-keywords).

When optional argument NO-UNDEFER is non-nil, do not resolve deferred values.

FUN may throw :org-element-skip signal. Then, org-element-map will not recurse into the current element.

Nil values returned from FUN do not appear in the results.

When buffer parse tree is used, elements and objects are generally traversed in the same order they appear in text with a single exception of dual keywords where secondary value is traversed after the mail value.

Examples:
---------

Assuming TREE is a variable containing an Org buffer parse tree, the following example will return a flat list of all src-block and example-block elements in it:

  (setq tree (org-element-parse-buffer))
  (org-element-map tree '(example-block src-block) #'identity)

The following snippet will find the first headline with a level of 1 and a "phone" tag, and will return its beginning position:

  (org-element-map tree 'headline
   (lambda (hl)
     (and (= (org-element-property :level hl) 1)
          (member "phone" (org-element-property :tags hl))
          (org-element-begin hl)))
   nil t)

The next example will return a flat list of all plain-list type elements in TREE that are not a sub-list themselves:

  (org-element-map tree 'plain-list #'identity nil nil 'plain-list)

Eventually, this example will return a flat list of all bold type objects containing a latex-snippet type object, even looking into captions:

  (org-element-map tree 'bold
   (lambda (b)
     (and (org-element-map b 'latex-snippet #'identity nil t) b))
   nil nil nil t)

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-element.el.gz
(defun org-element-map
    ( data types fun
      &optional
      info first-match no-recursion
      with-affiliated no-undefer)
  "Map a function on selected elements or objects.

DATA is a parse tree (for example, returned by
`org-element-parse-buffer'), an element, an object, a string, or a
list of such constructs.  TYPES is a symbol or list of symbols of
elements or object types (see `org-element-all-elements' and
`org-element-all-objects' for a complete list of types).  FUN is the
function called on the matching element or object.  It has to accept
one argument: the element or object itself.

When TYPES is t, call FUN for all the elements and objects.

FUN can also be a Lisp form.  The form will be evaluated as function
with symbol `node' bound to the current node.

When optional argument INFO is non-nil, it should be a plist
holding export options.  In that case, elements of the parse tree
\\(compared with `eq') not exportable according to `:ignore-list'
property in that property list will be skipped.

When optional argument FIRST-MATCH is non-nil, stop at the first
match for which FUN doesn't return nil, and return that value.

Optional argument NO-RECURSION is a symbol or a list of symbols
representing elements or objects types.  `org-element-map' won't
enter any recursive element or object whose type belongs to that
list.  Though, FUN can still be applied on them.

When optional argument WITH-AFFILIATED is non-nil, FUN will also
apply to matching objects within parsed affiliated keywords (see
`org-element-parsed-keywords').

When optional argument NO-UNDEFER is non-nil, do not resolve deferred
values.

FUN may throw `:org-element-skip' signal.  Then, `org-element-map'
will not recurse into the current element.

Nil values returned from FUN do not appear in the results.

When buffer parse tree is used, elements and objects are generally
traversed in the same order they appear in text with a single
exception of dual keywords where secondary value is traversed after
the mail value.

Examples:
---------

Assuming TREE is a variable containing an Org buffer parse tree,
the following example will return a flat list of all `src-block'
and `example-block' elements in it:

  (setq tree (org-element-parse-buffer))
  (org-element-map tree \\='(example-block src-block) #\\='identity)

The following snippet will find the first headline with a level
of 1 and a \"phone\" tag, and will return its beginning position:

  (org-element-map tree \\='headline
   (lambda (hl)
     (and (= (org-element-property :level hl) 1)
          (member \"phone\" (org-element-property :tags hl))
          (org-element-begin hl)))
   nil t)

The next example will return a flat list of all `plain-list' type
elements in TREE that are not a sub-list themselves:

  (org-element-map tree \\='plain-list #\\='identity nil nil \\='plain-list)

Eventually, this example will return a flat list of all `bold'
type objects containing a `latex-snippet' type object, even
looking into captions:

  (org-element-map tree \\='bold
   (lambda (b)
     (and (org-element-map b \\='latex-snippet #\\='identity nil t) b))
   nil nil nil t)"
  (declare (indent 2))
  ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
  (when (and types data)
    (let* ((ignore-list (plist-get info :ignore-list))
	   (objects?
            (or (eq types t)
                (cl-intersection
                 (cons 'plain-text org-element-all-objects)
                 (if (listp types) types (list types)))))
           (no-recursion
            (append
             (if (listp no-recursion) no-recursion
	       (list no-recursion))
             (unless objects?
               org-element-all-objects)
             (unless objects?
               ;; Do not recurse into elements that can only contain
               ;; objects.
               (cl-set-difference
                org-element-all-elements
                org-element-greater-elements)))))
      (org-element-ast-map
          data types fun
          ignore-list first-match
          no-recursion
          ;; Affiliated keywords may only contain objects.
          (when (and with-affiliated objects?)
            (mapcar #'cdr org-element--parsed-properties-alist))
          ;; Secondary strings may only contain objects.
          (not objects?)
          no-undefer))))