Org Element API

Resources

Local Parsing

Local parsing gives information about the element at point. Local parsing gives you information, but you cannot alter the structure of the AST.

Two functions you can use:

  1. org-element-at-point
  2. org-element-context

org-element-at-point

(pprint (org-element-at-point))
#+RESULTS:

(src-block (:language "emacs-lisp" :switches nil :parameters nil :begin 776 :end 853 :number-lines nil :preserve-indent nil :retain-labels t :use-labels t :label-fmt nil :value "     (pprint (org-element-at-point))
" :post-blank 1 :post-affiliated 776 :parent nil))
(pp (save-excursion
   (goto-char (point-min))
   (org-element-at-point)))
#+RESULTS:
(keyword
 (:key "TITLE" :value "Org Element Api" :begin 1 :end 26 :post-blank 0 :post-affiliated 1 :parent nil))

org-element-context

(pprint (org-element-context))
#+RESULTS:

(src-block (:language "emacs-lisp" :switches nil :parameters nil :begin 1079 :end 1155 :number-lines nil :preserve-indent nil :retain-labels t :use-labels t :label-fmt nil :value "     (pprint (org-element-context))
" :post-blank 1 :post-affiliated 1079 :parent nil))
(save-excursion
  (goto-char (point-min))
  (org-element-context))
keyword (:key TITLE :value Org Element Api :begin 1 :end 26 :post-blank 0 :post-affiliated 1 :parent nil)

Examining Element

(org-element-type (org-element-at-point))
#+RESULTS:
src-block
(org-element-property :language (org-element-at-point))
#+RESULTS:
emacs-lisp

Note: You can't use org-element-contents with local parsing.

(org-element-contents (org-element-at-point))

Global Parsing

Use org-element-parse-buffer to return a full AST of the buffer. You may modify this AST using setters.

(pp (org-element-parse-buffer (current-buffer)))
(pp (org-element-parse-buffer 'headline))
#+RESULTS:
(org-data nil
          (headline
           (:raw-value "Resources" :begin 56 :end 137 :pre-blank 1 :contents-begin 69 :contents-end 136 :level 1 :priority nil :tags nil :todo-keyword nil :todo-type nil :post-blank 1 :footnote-section-p nil :archivedp nil :commentedp nil :post-affiliated 56 :title "Resources" :parent #0))
          (headline
           (:raw-value "Local Parsing" :begin 137 :end 2149 :pre-blank 1 :contents-begin 154 :contents-end 2148 :level 1 :priority nil :tags nil :todo-keyword nil :todo-type nil :post-blank 1 :footnote-section-p nil :archivedp nil :commentedp nil :post-affiliated 137 :title "Local Parsing" :parent #0)
           (headline
            (:raw-value "org-element-at-point" :begin 389 :end 1055 :pre-blank 1 :contents-begin 414 :contents-end 1054 :level 2 :priority nil :tags nil :todo-keyword nil :todo-type nil :post-blank 1 :footnote-section-p nil :archivedp nil :commentedp nil :post-affiliated 389 :title "org-element-at-point" :parent #1))
           (headline
            (:raw-value "org-element-context" :begin 1055 :end 1705 :pre-blank 1 :contents-begin 1079 :contents-end 1704 :level 2 :priority nil :tags nil :todo-keyword nil :todo-type nil :post-blank 1 :footnote-section-p nil :archivedp nil :commentedp nil :post-affiliated 1055 :title "org-element-context" :parent #1))
           (headline
            (:raw-value "Examining Element" :begin 1705 :end 2148 :pre-blank 1 :contents-begin 1727 :contents-end 2148 :level 2 :priority nil :tags nil :todo-keyword nil :todo-type nil :post-blank 0 :footnote-section-p nil :archivedp nil :commentedp nil :post-affiliated 1705 :title "Examining Element" :parent #1)))
          (headline
           (:raw-value "Global Parsing" :begin 2149 :end 10183 :pre-blank 1 :contents-begin 2167 :contents-end 10183 :level 1 :priority nil :tags nil :todo-keyword nil :todo-type nil :post-blank 0 :footnote-section-p nil :archivedp nil :commentedp nil :post-affiliated 2149 :title "Global Parsing" :parent #0)
           (headline
            (:raw-value "Accessors" :begin 9799 :end 10036 :pre-blank 1 :contents-begin 9813 :contents-end 10035 :level 2 :priority nil :tags nil :todo-keyword nil :todo-type nil :post-blank 1 :footnote-section-p nil :archivedp nil :commentedp nil :post-affiliated 9799 :title "Accessors" :parent #1))
           (headline
            (:raw-value "This Heading" :begin 10036 :end 10183 :pre-blank 1 :contents-begin 10053 :contents-end 10183 :level 2 :priority nil :tags nil :todo-keyword nil :todo-type nil :post-blank 0 :footnote-section-p nil :archivedp nil :commentedp nil :post-affiliated 10036 :title "This Heading" :parent #1))))
(org-element-parse-buffer 'title)

Accessors

Three functions:

  1. org-element-type
  2. org-element-property
  3. org-element-contents
(org-element-contents
 (org-element-parse-buffer (current-buffer)))

This Heading

(org-heading-components)
2 2 nil nil This Heading nil

Get Title

(cadar (org-collect-keywords '("TITLE")))
#+RESULTS:
"Org Element Api"
(cdr (assoc "TITLE" (org-collect-keywords '("TITLE"))))
#+RESULTS:
("Org Element Api")

Get List of H1