Org API

Determine closest element around point.

Return value is a list like (TYPE PROPS) where TYPE is the type of the element and PROPS a plist of properties associated to the element. Possible types are defined in org-element-all-elements.

As a special case, if point is at the very beginning of a list or sub-list, returned element will be that list instead of the first item. In the same way, if point is at the beginning of the first row of a table, returned element will be the table instead of the first row.

If optional argument keep-trail is non-nil, the function returns a list of of elements leading to element at point. The list's CAR is always the element at point. Following positions contain element's siblings, then parents, siblings of parents, until the first element of current section.

Interpret babel-call element as Org syntax. contents is nil.

Parse a babel call.

Return a list whose CAR is babel-call and CDR is a plist containing :begin, :end, :info and :post-blank as keywords.

Move backward by one element. Move to the previous element at the same level, when possible.

Interpret bold object as Org syntax. contents is the contents of the object.

Parse bold object at point.

Return a list whose CAR is bold and CDR is a plist with :begin, :end, :contents-begin and :contents-end and :post-blank keywords.

Assume point is at the first star marker.

Interpret center-block element as Org syntax. contents is the contents of the element.

Parse a center block.

Return a list whose CAR is center-block and CDR is a plist containing :begin, :end, :hiddenp, :contents-begin, :contents-end and :post-blank keywords.

Assume point is at the beginning of the block.

Interpret clock element as Org syntax. contents is nil.

Parse a clock.

Return a list whose CAR is clock and CDR is a plist containing :status, :value, :time, :begin, :end and :post-blank as keywords.

Interpret code object as Org syntax. contents is nil.

Parse code object at point.

Return a list whose CAR is code and CDR is a plist with :value, :begin, :end and :post-blank keywords.

Assume point is at the first tilde marker.

Collect affiliated keywords before point.

Optional argument key-re is a regexp matching keywords, which puts matched keyword in group 1. It defaults to org-element–affiliated-re.

trans-list is an alist where key is the keyword and value the property name it should be translated to, without the colons. It defaults to org-element-keyword-translation-alist.

consed is a list of strings. Any keyword belonging to that list will have its value consed. The check is done after keyword translation. It defaults to org-element-multiple-keywords.

parsed is a list of strings. Any keyword member of this list will have its value parsed. The check is done after keyword translation. If a keyword is a member of both consed and parsed, it's value will be a list of parsed strings. It defaults to org-element-parsed-keywords.

duals is a list of strings. Any keyword member of this list can have two parts: one mandatory and one optional. Its value is a cons cell whose car is the former, and the cdr the latter. If a keyword is a member of both parsed and duals, both values will be parsed. It defaults to org-element-dual-keywords.

Return a list whose car is the position at the first of them and cdr a plist of keywords and values.

Interpret comment-block element as Org syntax. contents is nil.

Parse an export block.

Return a list whose CAR is comment-block and CDR is a plist containing :begin, :end, :hiddenp, :value and :post-blank keywords.

Assume point is at comment block beginning.

Interpret comment element as Org syntax. contents is nil.

Parse a comment.

Return a list whose CAR is comment and CDR is a plist containing :begin, :end, :value and :post-blank keywords.

Assume point is at comment beginning.

Extract contents from an element.

Parse the element starting at point.

Return value is a list like (TYPE PROPS) where TYPE is the type of the element and PROPS a plist of properties associated to the element.

Possible types are defined in org-element-all-elements.

Optional argument granularity determines the depth of the recursion. Allowed values are headline, greater-element, element, object or nil. When it is broader than object (or nil), secondary values will not be parsed, since they only contain objects.

Optional argument special, when non-nil, can be either section, quote-section, table-row and item.

If structure isn't provided but special is set to item, it will be computed.

This function assumes point is always at the beginning of the element it has to parse.

Move to inner element.

Move backward element at point.

Move forward element at point.

Interpret drawer element as Org syntax. contents is the contents of the element.

Parse a drawer.

Return a list whose CAR is drawer and CDR is a plist containing :drawer-name, :begin, :end, :hiddenp, :contents-begin, :contents-end and :post-blank keywords.

Assume point is at beginning of drawer.

Interpret dynamic-block element as Org syntax. contents is the contents of the element.

Parse a dynamic block.

Return a list whose CAR is dynamic-block and CDR is a plist containing :block-name, :begin, :end, :hiddenp, :contents-begin, :contents-end, :arguments and :post-blank keywords.

Assume point is at beginning of dynamic block.

Interpret entity object as Org syntax. contents is nil.

Parse entity at point.

Return a list whose CAR is entity and CDR a plist with :begin, :end, :latex, :latex-math-p, :html, :latin1, :utf-8, :ascii, :use-brackets-p and :post-blank as keywords.

Assume point is at the beginning of the entity.

Interpret example-block element as Org syntax. contents is nil.

Parse an example block.

Return a list whose CAR is example-block and CDR is a plist containing :begin, :end, :number-lines, :preserve-indent, :retain-labels, :use-labels, :label-fmt, :hiddenp, :switches, :value and :post-blank keywords.

Interpret export-block element as Org syntax. contents is nil.

Parse an export block.

Return a list whose CAR is export-block and CDR is a plist containing :begin, :end, :type, :hiddenp, :value and :post-blank keywords.

Assume point is at export-block beginning.

Interpret export-snippet object as Org syntax. contents is nil.

Parse export snippet at point.

Return a list whose CAR is export-snippet and CDR a plist with :begin, :end, :back-end, :value and :post-blank as keywords.

Assume point is at the beginning of the snippet.

Search for the next export-snippet object.

limit bounds the search.

Return value is a cons cell whose CAR is export-snippet CDR is its beginning position.

Fill element at point, when applicable.

This function only applies to paragraph, comment blocks, example blocks and fixed-width areas. Also, as a special case, re-align table when point is at one.

If justify is non-nil (interactively, with prefix argument), justify as well. If sentence-end-double-space is non-nil, then period followed by one space does not end a sentence, so don't break a line there. The variable fill-column controls the width for filling.

Interpret fixed-width element as Org syntax. contents is nil.

Parse a fixed-width section.

Return a list whose CAR is fixed-width and CDR is a plist containing :begin, :end, :value and :post-blank keywords.

Assume point is at the beginning of the fixed-width area.

Interpret footnote-definition element as Org syntax. contents is the contents of the footnote-definition.

Parse a footnote definition.

Return a list whose CAR is footnote-definition and CDR is a plist containing :label, :begin :end, :contents-begin, :contents-end and :post-blank keywords.

Assume point is at the beginning of the footnote definition.

Interpret footnote-reference object as Org syntax. contents is nil.

Parse footnote reference at point.

Return a list whose CAR is footnote-reference and CDR a plist with :label, :type, :inline-definition, :begin, :end and :post-blank as keywords.

Search for the next footnote-reference object.

limit bounds the search.

Return value is a cons cell whose CAR is footnote-reference and CDR is beginning position.

Move forward by one element. Move to the next element at the same level, when possible.

Return an alist of candidates for the next object.

limit bounds the search, and restriction narrows candidates to some object types.

Return value is an alist whose CAR is position and CDR the object type, as a symbol.

objects is the previous candidates alist.

Interpret headline element as Org syntax. contents is the contents of the element.

Parse an headline.

Return a list whose CAR is headline and CDR is a plist containing :raw-value, :title, :begin, :end, :pre-blank, :hiddenp, :contents-begin and :contents-end, :level, :priority, :tags, :todo-keyword,/:todo-type/, :scheduled, :deadline, :timestamp, :clock, :category, :quotedp, :archivedp, :commentedp and :footnote-section-p keywords.

The plist also contains any property set in the property drawer, with its name in lowercase, the underscores replaced with hyphens and colons at the beginning (i.e. :custom-id).

When raw-secondary-p is non-nil, headline's title will not be parsed as a secondary string, but as a plain string instead.

Assume point is at beginning of the headline.

Interpret horizontal-rule element as Org syntax. contents is nil.

Parse an horizontal rule.

Return a list whose CAR is horizontal-rule and CDR is a plist containing :begin, :end and :post-blank keywords.

Interpret inline-babel-call object as Org syntax. contents is nil.

Parse inline babel call at point.

Return a list whose CAR is inline-babel-call and CDR a plist with :begin, :end, :info and :post-blank as keywords.

Assume point is at the beginning of the babel call.

Search for the next inline-babel-call object.

limit bounds the search.

Return value is a cons cell whose CAR is inline-babel-call and CDR is beginning position.

Interpret inline-src-block object as Org syntax. contents is nil.

Parse inline source block at point.

Return a list whose CAR is inline-src-block and CDR a plist with :begin, :end, :language, :value, :parameters and :post-blank as keywords.

Assume point is at the beginning of the inline src block.

Search for the next inline-babel-call element.

limit bounds the search.

Return value is a cons cell whose CAR is inline-babel-call and CDR is beginning position.

Interpret inlinetask element as Org syntax. contents is the contents of inlinetask.

Parse an inline task.

Return a list whose CAR is inlinetask and CDR is a plist containing :title, :begin, :end, :hiddenp, :contents-begin and :contents-end, :level, :priority, :tags, :todo-keyword, :todo-type, :scheduled, :deadline, :timestamp, :clock and :post-blank keywords.

The plist also contains any property set in the property drawer, with its name in lowercase, the underscores replaced with hyphens and colons at the beginning (i.e. :custom-id).

When optional argument raw-secondary-p is non-nil, inline-task's title will not be parsed as a secondary string, but as a plain string instead.

Assume point is at beginning of the inline task.

Interpret data as Org syntax.

data is a parse tree, an element, an object or a secondary string to interpret.

Optional argument parent is used for recursive calls. It contains the element or object containing data, or nil.

Return Org syntax as a string.

Interpret italic object as Org syntax. contents is the contents of the object.

Parse italic object at point.

Return a list whose CAR is italic and CDR is a plist with :begin, :end, :contents-begin and :contents-end and :post-blank keywords.

Assume point is at the first slash marker.

Interpret item element as Org syntax. contents is the contents of the element.

Parse an item.

struct is the structure of the plain list.

Return a list whose CAR is item and CDR is a plist containing :bullet, :begin, :end, :contents-begin, :contents-end, :checkbox, :counter, :tag, :structure, :hiddenp and :post-blank keywords.

When optional argument raw-secondary-p is non-nil, item's tag, if any, will not be parsed as a secondary string, but as a plain string instead.

Assume point is at the beginning of the item.

Interpret keyword element as Org syntax. contents is nil.

Parse a keyword at point.

Return a list whose CAR is keyword and CDR is a plist containing :key, :value, :begin, :end and :post-blank keywords.

Interpret latex-environment element as Org syntax. contents is nil.

Parse a LaTeX environment.

Return a list whose CAR is latex-environment and CDR is a plist containing :begin, :end, :value and :post-blank keywords.

Assume point is at the beginning of the latex environment.

Interpret latex-fragment object as Org syntax. contents is nil.

Parse latex fragment at point.

Return a list whose CAR is latex-fragment and CDR a plist with :value, :begin, :end, and :post-blank as keywords.

Assume point is at the beginning of the latex fragment.

Search for the next latex-fragment or entity object.

limit bounds the search.

Return value is a cons cell whose CAR is entity or latex-fragment and CDR is beginning position.

Interpret line-break object as Org syntax. contents is nil.

Parse line break at point.

Return a list whose CAR is line-break, and CDR a plist with :begin, :end and :post-blank keywords.

Assume point is at the beginning of the line break.

Search for the next line-break object.

limit bounds the search.

Return value is a cons cell whose CAR is line-break and CDR is beginning position.

Interpret link object as Org syntax. contents is the contents of the object, or nil.

Parse link at point.

Return a list whose CAR is link and CDR a plist with :type, :path, :raw-link, :begin, :end, :contents-begin, :contents-end and :post-blank as keywords.

Assume point is at the beginning of the link.

Search for the next link object.

limit bounds the search.

Return value is a cons cell whose CAR is link and CDR is beginning position.

Interpret macro object as Org syntax. contents is nil.

Parse macro at point.

Return a list whose CAR is macro and CDR a plist with :key, :args, :begin, :end, :value and :post-blank as keywords.

Assume point is at the macro.

Search for the next macro object.

limit bounds the search.

Return value is cons cell whose CAR is macro and CDR is beginning position.

Map a function on selected elements or objects.

data is the parsed tree, as returned by, i.e, org-element-parse-buffer. types is a symbol or list of symbols of elements or objects types. fun is the function called on the matching element or object. It must accept one arguments: the element or object itself.

When optional argument info is non-nil, it should be a plist holding export options. In that case, parts of the parse tree not exportable according to 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.

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

Put point at beginning of this element, mark at end.

Interactively, if this command is repeated or (in Transient Mark mode) if the mark is active, it marks the next element after the ones already marked.

Non-nil when elements elem-a and elem-b are nested.

Normalize plain text in element's contents.

element must only contain plain text and objects.

If optional argument ignore-first is non-nil, ignore first line's indentation to compute maximal common indentation.

Return the normalized element that is element with global indentation removed from its contents. The function assumes that indentation is not done with TAB characters.

Ensure string s ends with a single newline character.

If s isn't a string return it unchanged. If s is the empty string, return it. Otherwise, return a new string with a single newline character at its end.

Interpret paragraph element as Org syntax. contents is the contents of the element.

Parse a paragraph.

Return a list whose CAR is paragraph and CDR is a plist containing :begin, :end, :contents-begin and :contents-end and :post-blank keywords.

Assume point is at the beginning of the paragraph.

Recursively parse the buffer and return structure. If narrowing is in effect, only parse the visible part of the buffer.

Optional argument granularity determines the depth of the recursion. It can be set to the following symbols:

headline Only parse headlines. greater-element Don't recurse into greater elements excepted headlines and sections. Thus, elements parsed are the top-level ones. element Parse everything but objects and plain text. object Parse the complete buffer (default).

When visible-only is non-nil, don't parse contents of hidden elements.

Assume buffer is in Org mode.

Parse elements between beg and end positions.

special prioritize some elements over the others. It can be set to quote-section, section item or table-row.

When value is item, structure will be used as the current list structure.

granularity determines the depth of the recursion. See org-element-parse-buffer for more information.

When visible-only is non-nil, don't parse contents of hidden elements.

Elements are accumulated into acc.

Parse objects between beg and end and return recursive structure.

Objects are accumulated in acc.

restriction is a list of object types which are allowed in the current object.

Recursively parse objects in string and return structure.

restriction, when non-nil, is a symbol limiting the object types that will be looked after.

Interpret plain-list element as Org syntax. contents is the contents of the element.

Parse a plain list.

Optional argument structure, when non-nil, is the structure of the plain list being parsed.

Return a list whose CAR is plain-list and CDR is a plist containing :type, :begin, :end, :contents-begin and :contents-end, :structure and :post-blank keywords.

Assume point is at the beginning of the list.

Interpret planning element as Org syntax. contents is nil.

Parse a planning.

Return a list whose CAR is planning and CDR is a plist containing :closed, :deadline, :scheduled, :begin, :end and :post-blank keywords.

Extract the value from the property of an element.

Interpret property-drawer element as Org syntax. contents is nil.

Parse a property drawer.

Return a list whose CAR is property-drawer and CDR is a plist containing :begin, :end, :hiddenp, :contents-begin, :contents-end, :properties and :post-blank keywords.

Assume point is at the beginning of the property drawer.

Interpret quote-block element as Org syntax. contents is the contents of the element.

Parse a quote block.

Return a list whose CAR is quote-block and CDR is a plist containing :begin, :end, :hiddenp, :contents-begin, :contents-end and :post-blank keywords.

Assume point is at the beginning of the block.

Interpret quote-section element as Org syntax. contents is nil.

Parse a quote section.

Return a list whose CAR is quote-section and CDR is a plist containing :begin, :end, :value and :post-blank keywords.

Assume point is at beginning of the section.

Interpret target object as Org syntax. contents is the contents of the object.

Parse radio target at point.

Return a list whose CAR is radio-target and CDR a plist with :begin, :end, :contents-begin, :contents-end, :value and :post-blank as keywords.

Assume point is at the radio target.

Search for the next radio-target object.

limit bounds the search.

Return value is a cons cell whose CAR is radio-target and CDR is beginning position.

Return restriction associated to element. element can be an element, an object or a symbol representing an element or object type.

Interpret section element as Org syntax. contents is the contents of the element.

Parse a section.

Return a list whose CAR is section and CDR is a plist containing :begin, :end, :contents-begin, contents-end and :post-blank keywords.

Interpret special-block element as Org syntax. contents is the contents of the element.

Parse a special block.

Return a list whose CAR is special-block and CDR is a plist containing :type, :begin, :end, :hiddenp, :contents-begin, :contents-end and :post-blank keywords.

Assume point is at the beginning of the block.

Interpret src-block element as Org syntax. contents is nil.

Parse a src block.

Return a list whose CAR is src-block and CDR is a plist containing :language, :switches, :parameters, :begin, :end, :hiddenp, :contents-begin, :contents-end, :number-lines, :retain-labels, :use-labels, :label-fmt, :preserve-indent, :value and :post-blank keywords.

Assume point is at the beginning of the block.

Interpret statistics-cookie object as Org syntax. contents is nil.

Parse statistics cookie at point.

Return a list whose CAR is statistics-cookie, and CDR a plist with :begin, :end, :value and :post-blank keywords.

Assume point is at the beginning of the statistics-cookie.

Search for the next statistics cookie object.

limit bounds the search.

Return value is a cons cell whose CAR is statistics-cookie and CDR is beginning position.

Interpret strike-through object as Org syntax. contents is the contents of the object.

Parse strike-through object at point.

Return a list whose CAR is strike-through and CDR is a plist with :begin, :end, :contents-begin and :contents-end and :post-blank keywords.

Assume point is at the first plus sign marker.

Search for the next sub/superscript object.

limit bounds the search.

Return value is a cons cell whose CAR is either subscript or superscript and CDR is beginning position.

Interpret subscript object as Org syntax. contents is the contents of the object.

Parse subscript at point.

Return a list whose CAR is subscript and CDR a plist with :begin, :end, :contents-begin, :contents-end, :use-brackets-p and :post-blank as keywords.

Assume point is at the underscore.

Interpret superscript object as Org syntax. contents is the contents of the object.

Parse superscript at point.

Return a list whose CAR is superscript and CDR a plist with :begin, :end, :contents-begin, :contents-end, :use-brackets-p and :post-blank as keywords.

Assume point is at the caret.

Swap elements elem-a and elem-b. Assume elem-b is after elem-a in the buffer. Leave point at the end of elem-a.

Interpret table-cell element as Org syntax. contents is the contents of the cell, or nil.

Parse table cell at point.

Return a list whose CAR is table-cell and CDR is a plist containing :begin, :end, :contents-begin, :contents-end and :post-blank keywords.

Search for the next table-cell object.

limit bounds the search.

Return value is a cons cell whose CAR is table-cell and CDR is beginning position.

Interpret table element as Org syntax. contents is nil.

Parse a table at point.

Return a list whose CAR is table and CDR is a plist containing :begin, :end, :tblfm, :type, :contents-begin, :contents-end, :value and :post-blank keywords.

Assume point is at the beginning of the table.

Interpret table-row element as Org syntax. contents is the contents of the table row.

Parse table row at point.

Return a list whose CAR is table-row and CDR is a plist containing :begin, :end, :contents-begin, :contents-end, :type and :post-blank keywords.

Interpret target object as Org syntax. contents is nil.

Parse target at point.

Return a list whose CAR is target and CDR a plist with :begin, :end, :value and :post-blank as keywords.

Assume point is at the target.

Search for the next target object.

limit bounds the search.

Return value is a cons cell whose CAR is target and CDR is beginning position.

Search for the next text-markup object.

limit bounds the search.

Return value is a cons cell whose CAR is a symbol among bold, italic, underline, strike-through, code and verbatim and CDR is beginning position.

Interpret timestamp object as Org syntax. contents is nil.

Parse time stamp at point.

Return a list whose CAR is timestamp, and CDR a plist with :type, :begin, :end, :value and :post-blank keywords.

Assume point is at the beginning of the timestamp.

Search for the next timestamp object.

limit bounds the search.

Return value is a cons cell whose CAR is timestamp and CDR is beginning position.

Transpose current and previous elements, keeping blank lines between. Point is moved after both elements.

Return type of element element.

The function returns the type of the element or object provided. It can also return the following special value:

/plain-text/       for a string
`org-data'         for a complete document
nil                in any other case.

Interpret underline object as Org syntax. contents is the contents of the object.

Parse underline object at point.

Return a list whose CAR is underline and CDR is a plist with :begin, :end, :contents-begin and :contents-end and :post-blank keywords.

Assume point is at the first underscore marker.

Un-indent the visible part of the buffer. Relative indentation (between items, inside blocks, etc.) isn't modified.

Move to upper element.

Interpret verbatim object as Org syntax. contents is nil.

Parse verbatim object at point.

Return a list whose CAR is verbatim and CDR is a plist with :value, :begin, :end and :post-blank keywords.

Assume point is at the first equal sign marker.

Interpret verse-block element as Org syntax. contents is verse block contents.

Parse a verse block.

Return a list whose CAR is verse-block and CDR is a plist containing :begin, :end, :contents-begin, :contents-end, :hiddenp and :post-blank keywords.

Assume point is at beginning of the block.