18.3.3.2 org-element-map—Examples

This function allows applying a function on elements or objects matching some type, and accumulating the resulting values, and can be used to find specific elements or objects within the parse tree.

This function can be used to collect data from an AST.

Function: org-element-map DATA TYPES FUN &optional INFO FIRST-MATCH NO-RECURSION WITH-AFFILIATED ¶

• DATA : a parse tree, an element, an object, a string, or a list of such.
• TYPES : a symbol or list of symbols of elements or object types.
• FUN : the function called on the matching element or object.

&optional

• INFO : a plist holding export options; parts of the parse tree not exportable according to this plist will be skipped
• FIRST-MATCH : when non-nil stop at the first match for which FUN returns non-nil value
• NO-RECURSION : a symbol or list of symbols representing elements or object types into which org-element-map won’t enter recursively
• WITH-AFFILIATED : when non-nil, FUN will also apply to matching objects within parsed affiliated keywords.

Some Examples

Assume TREE is a variable containing an Org buffer parse tree.

Return a flat list of all src-block and example-block elements

• #'identity

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

Find the first headline with a level of 1 and a "phone" tag

• org-element-property
• member

It 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-property :begin hl)))
 nil t)

Return a flat list of all ‘plain-list’ type elements in TREE that are not a sub-list themselves

This example makes use of the NO-RECURSION optional argument. org-element-map will not recurse into any ‘plain-list’ types.

• #'identity function

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

Return a flat list of all ‘bold’ type objects containing a ‘latex-snippet’ type object

even looking into captions. This example uses org-element-map inside of itself to further examine the current object.

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

Returns all paragraphs beginning a section in the current document:

• org-element-property
• org-element-type
• org-element-contents
• first-child

(org-element-map (org-element-parse-buffer) 'paragraph
  (lambda (paragraph)
    (let ((parent (org-element-property :parent paragraph)))
      (and (eq (org-element-type parent) 'section)
           (let ((first-child (car (org-element-contents parent))))
             (eq first-child paragraph))
           ;; Return value.
           paragraph))))

It can also be used as a predicate.

The following snippet returns a non-nil value when the document contains a checked item.

• org-element-property

(org-element-map (org-element-parse-buffer) 'item
  (lambda (item) (eq (org-element-property :checkbox item) 'on))
  nil t)