| blob | 0da8515bc5d23a7c37f87ed4affc35e5725b6f7d |
1 ;;; org-element.el --- Parser And Applications for Org syntax
3 ;; Copyright (C) 2012 Free Software Foundation, Inc.
5 ;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
6 ;; Keywords: outlines, hypermedia, calendar, wp
8 ;; This program is free software; you can redistribute it and/or modify
9 ;; it under the terms of the GNU General Public License as published by
10 ;; the Free Software Foundation, either version 3 of the License, or
11 ;; (at your option) any later version.
13 ;; This program is distributed in the hope that it will be useful,
14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 ;; GNU General Public License for more details.
18 ;; This file is not part of GNU Emacs.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
23 ;;; Commentary:
25 ;; Org syntax can be divided into three categories: "Greater
26 ;; elements", "Elements" and "Objects".
28 ;; Elements are related to the structure of the document. Indeed, all
29 ;; elements are a cover for the document: each position within belongs
30 ;; to at least one element.
32 ;; An element always starts and ends at the beginning of a line. With
33 ;; a few exceptions (namely `babel-call', `clock', `headline', `item',
34 ;; `keyword', `planning', `property-drawer' and `section' types), it
35 ;; can also accept a fixed set of keywords as attributes. Those are
36 ;; called "affiliated keywords" to distinguish them from other
37 ;; keywords, which are full-fledged elements. All affiliated keywords
38 ;; are referenced in `org-element-affiliated-keywords'.
39 ;;
40 ;; Element containing other elements (and only elements) are called
41 ;; greater elements. Concerned types are: `center-block', `drawer',
42 ;; `dynamic-block', `footnote-definition', `headline', `inlinetask',
43 ;; `item', `plain-list', `quote-block', `section' and `special-block'.
44 ;;
45 ;; Other element types are: `babel-call', `clock', `comment',
46 ;; `comment-block', `example-block', `export-block', `fixed-width',
47 ;; `horizontal-rule', `keyword', `latex-environment', `paragraph',
48 ;; `planning', `property-drawer', `quote-section', `src-block',
49 ;; `table', `table-cell', `table-row' and `verse-block'. Among them,
50 ;; `paragraph', `table-cell' and `verse-block' types can contain Org
51 ;; objects and plain text.
52 ;;
53 ;; Objects are related to document's contents. Some of them are
54 ;; recursive. Associated types are of the following: `bold', `code',
55 ;; `entity', `export-snippet', `footnote-reference',
56 ;; `inline-babel-call', `inline-src-block', `italic',
57 ;; `latex-fragment', `line-break', `link', `macro', `radio-target',
58 ;; `statistics-cookie', `strike-through', `subscript', `superscript',
59 ;; `table-cell', `target', `timestamp', `underline' and `verbatim'.
60 ;;
61 ;; Some elements also have special properties whose value can hold
62 ;; objects themselves (i.e. an item tag or an headline name). Such
63 ;; values are called "secondary strings". Any object belongs to
64 ;; either an element or a secondary string.
65 ;;
66 ;; Notwithstanding affiliated keywords, each greater element, element
67 ;; and object has a fixed set of properties attached to it. Among
68 ;; them, three are shared by all types: `:begin' and `:end', which
69 ;; refer to the beginning and ending buffer positions of the
70 ;; considered element or object, and `:post-blank', which holds the
71 ;; number of blank lines, or white spaces, at its end. Greater
72 ;; elements and elements containing objects will also have
73 ;; `:contents-begin' and `:contents-end' properties to delimit
74 ;; contents.
76 ;; Lisp-wise, an element or an object can be represented as a list.
77 ;; It follows the pattern (TYPE PROPERTIES CONTENTS), where:
78 ;; TYPE is a symbol describing the Org element or object.
79 ;; PROPERTIES is the property list attached to it. See docstring of
80 ;; appropriate parsing function to get an exhaustive
81 ;; list.
82 ;; CONTENTS is a list of elements, objects or raw strings contained
83 ;; in the current element or object, when applicable.
85 ;; An Org buffer is a nested list of such elements and objects, whose
86 ;; type is `org-data' and properties is nil.
88 ;; The first part of this file implements a parser and an interpreter
89 ;; for each type of Org syntax.
91 ;; The next two parts introduce four accessors and a function
92 ;; retrieving the element starting at point (respectively
93 ;; `org-element-type', `org-element-property', `org-element-contents',
94 ;; `org-element-restriction' and `org-element-current-element').
96 ;; The following part creates a fully recursive buffer parser. It
97 ;; also provides a tool to map a function to elements or objects
98 ;; matching some criteria in the parse tree. Functions of interest
99 ;; are `org-element-parse-buffer', `org-element-map' and, to a lesser
100 ;; extent, `org-element-parse-secondary-string'.
102 ;; The penultimate part is the cradle of an interpreter for the
103 ;; obtained parse tree: `org-element-interpret-data'.
105 ;; The library ends by furnishing a set of interactive tools for
106 ;; element's navigation and manipulation, mostly based on
107 ;; `org-element-at-point' function.
110 ;;; Code:
116 \f
117 ;;; Greater elements
119 ;; For each greater element type, we define a parser and an
120 ;; interpreter.
122 ;; A parser returns the element or object as the list described above.
123 ;; Most of them accepts no argument. Though, exceptions exist. Hence
124 ;; every element containing a secondary string (see
125 ;; `org-element-secondary-value-alist') will accept an optional
126 ;; argument to toggle parsing of that secondary string. Moreover,
127 ;; `item' parser requires current list's structure as its first
128 ;; element.
130 ;; An interpreter accepts two arguments: the list representation of
131 ;; the element or object, and its contents. The latter may be nil,
132 ;; depending on the element or object considered. It returns the
133 ;; appropriate Org syntax, as a string.
135 ;; Parsing functions must follow the naming convention:
136 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
137 ;; defined in `org-element-greater-elements'.
138 ;;
139 ;; Similarly, interpreting functions must follow the naming
140 ;; convention: org-element-TYPE-interpreter.
142 ;; With the exception of `headline' and `item' types, greater elements
143 ;; cannot contain other greater elements of their own type.
145 ;; Beside implementing a parser and an interpreter, adding a new
146 ;; greater element requires to tweak `org-element-current-element'.
147 ;; Moreover, the newly defined type must be added to both
148 ;; `org-element-all-elements' and `org-element-greater-elements'.
151 ;;;; Center Block
154 "Parse a center block.
156 Return a list whose CAR is `center-block' and CDR is a plist
157 containing `:begin', `:end', `:hiddenp', `:contents-begin',
158 `:contents-end' and `:post-blank' keywords.
160 Assume point is at the beginning of the block."
183 "Interpret CENTER-BLOCK element as Org syntax.
184 CONTENTS is the contents of the element."
188 ;;;; Drawer
191 "Parse a drawer.
193 Return a list whose CAR is `drawer' and CDR is a plist containing
194 `:drawer-name', `:begin', `:end', `:hiddenp', `:contents-begin',
195 `:contents-end' and `:post-blank' keywords.
197 Assume point is at beginning of drawer."
222 "Interpret DRAWER element as Org syntax.
223 CONTENTS is the contents of the element."
226 contents))
229 ;;;; Dynamic Block
232 "Parse a dynamic block.
234 Return a list whose CAR is `dynamic-block' and CDR is a plist
235 containing `:block-name', `:begin', `:end', `:hiddenp',
236 `:contents-begin', `:contents-end', `:arguments' and
237 `:post-blank' keywords.
239 Assume point is at beginning of dynamic block."
266 "Interpret DYNAMIC-BLOCK element as Org syntax.
267 CONTENTS is the contents of the element."
272 contents))
275 ;;;; Footnote Definition
278 "Parse a footnote definition.
280 Return a list whose CAR is `footnote-definition' and CDR is
281 a plist containing `:label', `:begin' `:end', `:contents-begin',
282 `:contents-end' and `:post-blank' keywords.
284 Assume point is at the beginning of the footnote definition."
313 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
314 CONTENTS is the contents of the footnote-definition."
316 " "
317 contents))
320 ;;;; Headline
323 "Parse an headline.
325 Return a list whose CAR is `headline' and CDR is a plist
326 containing `:raw-value', `:title', `:begin', `:end',
327 `:pre-blank', `:hiddenp', `:contents-begin' and `:contents-end',
328 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
329 `:scheduled', `:deadline', `:timestamp', `:clock', `:category',
330 `:quotedp', `:archivedp', `:commentedp' and `:footnote-section-p'
331 keywords.
333 The plist also contains any property set in the property drawer,
334 with its name in lowercase, the underscores replaced with hyphens
335 and colons at the beginning (i.e. `:custom-id').
337 When RAW-SECONDARY-P is non-nil, headline's title will not be
338 parsed as a secondary string, but as a plain string instead.
340 Assume point is at beginning of the headline."
372 plist))
388 title)
389 ;; Clean RAW-VALUE from any quote or comment string.
394 ""
395 raw-value)))
396 ;; Clean TAGS from archive tag, if any.
403 ;; Then get TITLE.
434 "Interpret HEADLINE element as Org syntax.
435 CONTENTS is the contents of the element."
462 ;; Align tags.
470 ? )
471 tags))
475 tags))))
477 contents)))
480 ;;;; Inlinetask
483 "Parse an inline task.
485 Return a list whose CAR is `inlinetask' and CDR is a plist
486 containing `:title', `:begin', `:end', `:hiddenp',
487 `:contents-begin' and `:contents-end', `:level', `:priority',
488 `:tags', `:todo-keyword', `:todo-type', `:scheduled',
489 `:deadline', `:timestamp', `:clock' and `:post-blank' keywords.
491 The plist also contains any property set in the property drawer,
492 with its name in lowercase, the underscores replaced with hyphens
493 and colons at the beginning (i.e. `:custom-id').
495 When optional argument RAW-SECONDARY-P is non-nil, inline-task's
496 title will not be parsed as a secondary string, but as a plain
497 string instead.
499 Assume point is at beginning of the inline task."
522 plist))
531 ;; In the case of a single line task, CONTENTS-BEGIN and
532 ;; CONTENTS-END might overlap.
555 ,@standard-props
559 "Interpret INLINETASK element as Org syntax.
560 CONTENTS is the contents of inlinetask."
573 ;; Align tags.
581 ? )
582 tags))
586 tags))))
587 ;; Prefer degenerate inlinetasks when there are no
588 ;; contents.
591 contents
595 ;;;; Item
598 "Parse an item.
600 STRUCT is the structure of the plain list.
602 Return a list whose CAR is `item' and CDR is a plist containing
603 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
604 `:checkbox', `:counter', `:tag', `:structure', `:hiddenp' and
605 `:post-blank' keywords.
607 When optional argument RAW-SECONDARY-P is non-nil, item's tag, if
608 any, will not be parsed as a secondary string, but as a plain
609 string instead.
611 Assume point is at the beginning of the item."
638 ;; If first line isn't empty,
639 ;; contents really start at the text
640 ;; after item's meta-data.
654 ;; CONTENTS-BEGIN and CONTENTS-END may be mixed
655 ;; up in the case of an empty item separated
656 ;; from the next by a blank line. Thus, ensure
657 ;; the former is always the smallest of two.
668 "Interpret ITEM element as Org syntax.
669 CONTENTS is the contents of the element."
683 num
690 ;; Compute indentation.
692 ;; Indent contents.
694 bullet
705 ;;;; Plain List
708 "Parse a plain list.
710 Optional argument STRUCTURE, when non-nil, is the structure of
711 the plain list being parsed.
713 Return a list whose CAR is `plain-list' and CDR is a plist
714 containing `:type', `:begin', `:end', `:contents-begin' and
715 `:contents-end', `:level', `:structure' and `:post-blank'
716 keywords.
718 Assume point is at the beginning of the list."
732 ;; Get list level.
737 struct parents))
739 ;; Blank lines below list belong to the top-level list only.
744 ;; Return value.
757 "Interpret PLAIN-LIST element as Org syntax.
758 CONTENTS is the contents of the element."
759 contents)
762 ;;;; Quote Block
765 "Parse a quote block.
767 Return a list whose CAR is `quote-block' and CDR is a plist
768 containing `:begin', `:end', `:hiddenp', `:contents-begin',
769 `:contents-end' and `:post-blank' keywords.
771 Assume point is at the beginning of the block."
793 "Interpret QUOTE-BLOCK element as Org syntax.
794 CONTENTS is the contents of the element."
798 ;;;; Section
801 "Parse a section.
803 Return a list whose CAR is `section' and CDR is a plist
804 containing `:begin', `:end', `:contents-begin', `contents-end'
805 and `:post-blank' keywords."
807 ;; Beginning of section is the beginning of the first non-blank
808 ;; line after previous headline.
827 "Interpret SECTION element as Org syntax.
828 CONTENTS is the contents of the element."
829 contents)
832 ;;;; Special Block
835 "Parse a special block.
837 Return a list whose CAR is `special-block' and CDR is a plist
838 containing `:type', `:begin', `:end', `:hiddenp',
839 `:contents-begin', `:contents-end' and `:post-blank' keywords.
841 Assume point is at the beginning of the block."
867 "Interpret SPECIAL-BLOCK element as Org syntax.
868 CONTENTS is the contents of the element."
873 \f
874 ;;; Elements
876 ;; For each element, a parser and an interpreter are also defined.
877 ;; Both follow the same naming convention used for greater elements.
879 ;; Also, as for greater elements, adding a new element type is done
880 ;; through the following steps: implement a parser and an interpreter,
881 ;; tweak `org-element-current-element' so that it recognizes the new
882 ;; type and add that new type to `org-element-all-elements'.
884 ;; As a special case, when the newly defined type is a block type,
885 ;; `org-element-non-recursive-block-alist' has to be modified
886 ;; accordingly.
889 ;;;; Babel Call
892 "Parse a babel call.
894 Return a list whose CAR is `babel-call' and CDR is a plist
895 containing `:begin', `:end', `:info' and `:post-blank' as
896 keywords."
911 "Interpret BABEL-CALL element as Org syntax.
912 CONTENTS is nil."
918 ;; Remove redundant square brackets.
923 ;;;; Clock
926 "Parse a clock.
928 Return a list whose CAR is `clock' and CDR is a plist containing
929 `:status', `:value', `:time', `:begin', `:end' and `:post-blank'
930 as keywords."
955 "Interpret CLOCK element as Org syntax.
956 CONTENTS is nil."
963 "%2s:%02s"
967 ;;;; Comment
970 "Parse a comment.
972 Return a list whose CAR is `comment' and CDR is a plist
973 containing `:begin', `:end', `:value' and `:post-blank'
974 keywords.
976 Assume point is at comment beginning."
982 ;; Get comments ending. This may not be accurate if
983 ;; commented lines within an item are followed by
984 ;; commented lines outside of a list. Though, parser will
985 ;; always get it right as it already knows surrounding
986 ;; element and has narrowed buffer to its contents.
1005 "Interpret COMMENT element as Org syntax.
1006 CONTENTS is nil."
1010 ;;;; Comment Block
1013 "Parse an export block.
1015 Return a list whose CAR is `comment-block' and CDR is a plist
1016 containing `:begin', `:end', `:hiddenp', `:value' and
1017 `:post-blank' keywords.
1019 Assume point is at comment block beginning."
1042 "Interpret COMMENT-BLOCK element as Org syntax.
1043 CONTENTS is nil."
1048 ;;;; Example Block
1051 "Parse an example block.
1053 Return a list whose CAR is `example-block' and CDR is a plist
1054 containing `:begin', `:end', `:number-lines', `:preserve-indent',
1055 `:retain-labels', `:use-labels', `:label-fmt', `:hiddenp',
1056 `:switches', `:value' and `:post-blank' keywords."
1062 ;; Switches analysis
1067 ;; Should labels be retained in (or stripped from) example
1068 ;; blocks?
1073 ;; What should code-references use - labels or
1074 ;; line-numbers?
1081 ;; Standard block parsing.
1108 "Interpret EXAMPLE-BLOCK element as Org syntax.
1109 CONTENTS is nil."
1117 ;;;; Export Block
1120 "Parse an export block.
1122 Return a list whose CAR is `export-block' and CDR is a plist
1123 containing `:begin', `:end', `:type', `:hiddenp', `:value' and
1124 `:post-blank' keywords.
1126 Assume point is at export-block beginning."
1152 "Interpret EXPORT-BLOCK element as Org syntax.
1153 CONTENTS is nil."
1160 ;;;; Fixed-width
1163 "Parse a fixed-width section.
1165 Return a list whose CAR is `fixed-width' and CDR is a plist
1166 containing `:begin', `:end', `:value' and `:post-blank' keywords.
1168 Assume point is at the beginning of the fixed-width area."
1188 "Interpret FIXED-WIDTH element as Org syntax.
1189 CONTENTS is nil."
1193 ;;;; Horizontal Rule
1196 "Parse an horizontal rule.
1198 Return a list whose CAR is `horizontal-rule' and CDR is a plist
1199 containing `:begin', `:end' and `:post-blank' keywords."
1213 "Interpret HORIZONTAL-RULE element as Org syntax.
1214 CONTENTS is nil."
1218 ;;;; Keyword
1221 "Parse a keyword at point.
1223 Return a list whose CAR is `keyword' and CDR is a plist
1224 containing `:key', `:value', `:begin', `:end' and `:post-blank'
1225 keywords."
1245 "Interpret KEYWORD element as Org syntax.
1246 CONTENTS is nil."
1252 ;;;; Latex Environment
1255 "Parse a LaTeX environment.
1257 Return a list whose CAR is `latex-environment' and CDR is a plist
1258 containing `:begin', `:end', `:value' and `:post-blank'
1259 keywords.
1261 Assume point is at the beginning of the latex environment."
1281 "Interpret LATEX-ENVIRONMENT element as Org syntax.
1282 CONTENTS is nil."
1286 ;;;; Paragraph
1289 "Parse a paragraph.
1291 Return a list whose CAR is `paragraph' and CDR is a plist
1292 containing `:begin', `:end', `:contents-begin' and
1293 `:contents-end' and `:post-blank' keywords.
1295 Assume point is at the beginning of the paragraph."
1317 "Interpret PARAGRAPH element as Org syntax.
1318 CONTENTS is the contents of the element."
1319 contents)
1322 ;;;; Planning
1325 "Parse a planning.
1327 Return a list whose CAR is `planning' and CDR is a plist
1328 containing `:closed', `:deadline', `:scheduled', `:begin', `:end'
1329 and `:post-blank' keywords."
1338 closed deadline scheduled)
1358 "Interpret PLANNING element as Org syntax.
1359 CONTENTS is nil."
1361 'identity
1372 ;;;; Property Drawer
1375 "Parse a property drawer.
1377 Return a list whose CAR is `property-drawer' and CDR is a plist
1378 containing `:begin', `:end', `:hiddenp', `:contents-begin',
1379 `:contents-end', `:properties' and `:post-blank' keywords.
1381 Assume point is at the beginning of the property drawer."
1395 val))
1397 val))
1411 "Interpret PROPERTY-DRAWER element as Org syntax.
1412 CONTENTS is nil."
1422 ;;;; Quote Section
1425 "Parse a quote section.
1427 Return a list whose CAR is `quote-section' and CDR is a plist
1428 containing `:begin', `:end', `:value' and `:post-blank' keywords.
1430 Assume point is at beginning of the section."
1446 "Interpret QUOTE-SECTION element as Org syntax.
1447 CONTENTS is nil."
1451 ;;;; Src Block
1454 "Parse a src block.
1456 Return a list whose CAR is `src-block' and CDR is a plist
1457 containing `:language', `:switches', `:parameters', `:begin',
1458 `:end', `:hiddenp', `:contents-begin', `:contents-end',
1459 `:number-lines', `:retain-labels', `:use-labels', `:label-fmt',
1460 `:preserve-indent', `:value' and `:post-blank' keywords.
1462 Assume point is at the beginning of the block."
1466 ;; Get affiliated keywords.
1468 ;; Get beginning position.
1470 ;; Get language as a string.
1479 ;; Get switches.
1481 ;; Get parameters.
1483 ;; Switches analysis
1491 ;; Should labels be retained in (or stripped from) src
1492 ;; blocks?
1497 ;; What should code-references use - labels or
1498 ;; line-numbers?
1502 ;; Get position at end of block.
1506 ;; Retrieve code.
1512 ;; Get position after ending blank lines.
1515 ;; Get visibility status.
1538 "Interpret SRC-BLOCK element as Org syntax.
1539 CONTENTS is nil."
1559 value
1563 ;;;; Table
1566 "Parse a table at point.
1568 Return a list whose CAR is `table' and CDR is a plist containing
1569 `:begin', `:end', `:tblfm', `:type', `:contents-begin',
1570 `:contents-end', `:value' and `:post-blank' keywords.
1572 Assume point is at the beginning of the table."
1591 ;; Only `org' tables have contents. `table.el' tables
1592 ;; use a `:value' property to store raw table as
1593 ;; a string.
1598 table-begin table-end))
1603 "Interpret TABLE element as Org syntax.
1604 CONTENTS is nil."
1614 ;;;; Table Row
1617 "Parse table row at point.
1619 Return a list whose CAR is `table-row' and CDR is a plist
1620 containing `:begin', `:end', `:contents-begin', `:contents-end',
1621 `:type' and `:post-blank' keywords."
1625 ;; A table rule has no contents. In that case, ensure
1626 ;; CONTENTS-BEGIN matches CONTENTS-END.
1645 "Interpret TABLE-ROW element as Org syntax.
1646 CONTENTS is the contents of the table row."
1651 ;;;; Verse Block
1654 "Parse a verse block.
1656 Return a list whose CAR is `verse-block' and CDR is a plist
1657 containing `:begin', `:end', `:contents-begin', `:contents-end',
1658 `:hiddenp' and `:post-blank' keywords.
1660 Assume point is at beginning of the block."
1684 "Interpret VERSE-BLOCK element as Org syntax.
1685 CONTENTS is verse block contents."
1689 \f
1690 ;;; Objects
1691 ;;
1692 ;; Unlike to elements, interstices can be found between objects.
1693 ;; That's why, along with the parser, successor functions are provided
1694 ;; for each object. Some objects share the same successor (i.e. `code'
1695 ;; and `verbatim' objects).
1696 ;;
1697 ;; A successor must accept a single argument bounding the search. It
1698 ;; will return either a cons cell whose CAR is the object's type, as
1699 ;; a symbol, and CDR the position of its next occurrence, or nil.
1700 ;;
1701 ;; Successors follow the naming convention:
1702 ;; org-element-NAME-successor, where NAME is the name of the
1703 ;; successor, as defined in `org-element-all-successors'.
1704 ;;
1705 ;; Some object types (i.e. `emphasis') are recursive. Restrictions on
1706 ;; object types they can contain will be specified in
1707 ;; `org-element-object-restrictions'.
1708 ;;
1709 ;; Adding a new type of object is simple. Implement a successor,
1710 ;; a parser, and an interpreter for it, all following the naming
1711 ;; convention. Register type in `org-element-all-objects' and
1712 ;; successor in `org-element-all-successors'. Maybe tweak
1713 ;; restrictions about it, and that's it.
1716 ;;;; Bold
1719 "Parse bold object at point.
1721 Return a list whose CAR is `bold' and CDR is a plist with
1722 `:begin', `:end', `:contents-begin' and `:contents-end' and
1723 `:post-blank' keywords.
1725 Assume point is at the first star marker."
1743 "Interpret BOLD object as Org syntax.
1744 CONTENTS is the contents of the object."
1748 "Search for the next text-markup object.
1750 LIMIT bounds the search.
1752 Return value is a cons cell whose CAR is a symbol among `bold',
1753 `italic', `underline', `strike-through', `code' and `verbatim'
1754 and CDR is beginning position."
1770 ;;;; Code
1773 "Parse code object at point.
1775 Return a list whose CAR is `code' and CDR is a plist with
1776 `:value', `:begin', `:end' and `:post-blank' keywords.
1778 Assume point is at the first tilde marker."
1794 "Interpret CODE object as Org syntax.
1795 CONTENTS is nil."
1799 ;;;; Entity
1802 "Parse entity at point.
1804 Return a list whose CAR is `entity' and CDR a plist with
1805 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
1806 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
1807 keywords.
1809 Assume point is at the beginning of the entity."
1833 "Interpret ENTITY object as Org syntax.
1834 CONTENTS is nil."
1840 "Search for the next latex-fragment or entity object.
1842 LIMIT bounds the search.
1844 Return value is a cons cell whose CAR is `entity' or
1845 `latex-fragment' and CDR is beginning position."
1848 ;; ENTITY-RE matches both LaTeX commands and Org entities.
1855 limit t)
1858 ;; Determine if it's a real entity or a LaTeX command.
1861 ;; No entity nor command: point is at a LaTeX fragment.
1862 ;; Determine its type to get the correct beginning position.
1870 matchers)
1874 ;;;; Export Snippet
1877 "Parse export snippet at point.
1879 Return a list whose CAR is `export-snippet' and CDR a plist with
1880 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
1881 keywords.
1883 Assume point is at the beginning of the snippet."
1906 "Interpret EXPORT-SNIPPET object as Org syntax.
1907 CONTENTS is nil."
1913 "Search for the next export-snippet object.
1915 LIMIT bounds the search.
1917 Return value is a cons cell whose CAR is `export-snippet' CDR is
1918 its beginning position."
1931 ;;;; Footnote Reference
1934 "Parse footnote reference at point.
1936 Return a list whose CAR is `footnote-reference' and CDR a plist
1937 with `:label', `:type', `:inline-definition', `:begin', `:end'
1938 and `:post-blank' as keywords."
1971 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
1972 CONTENTS is nil."
1982 "Search for the next footnote-reference object.
1984 LIMIT bounds the search.
1986 Return value is a cons cell whose CAR is `footnote-reference' and
1987 CDR is beginning position."
2001 ;;;; Inline Babel Call
2004 "Parse inline babel call at point.
2006 Return a list whose CAR is `inline-babel-call' and CDR a plist
2007 with `:begin', `:end', `:info' and `:post-blank' as keywords.
2009 Assume point is at the beginning of the babel call."
2025 "Interpret INLINE-BABEL-CALL object as Org syntax.
2026 CONTENTS is nil."
2032 ;; Remove redundant square brackets.
2035 main-source)
2039 "Search for the next inline-babel-call object.
2041 LIMIT bounds the search.
2043 Return value is a cons cell whose CAR is `inline-babel-call' and
2044 CDR is beginning position."
2046 ;; Use a simplified version of
2047 ;; org-babel-inline-lob-one-liner-regexp as regexp for more speed.
2049 "\\(?:babel\\|call\\)_\\([^()\n]+?\\)\\(\\[\\(.*\\)\\]\\|\\(\\)\\)(\\([^\n]*\\))\\(\\[\\(.*?\\)\\]\\)?"
2050 limit t)
2054 ;;;; Inline Src Block
2057 "Parse inline source block at point.
2059 Return a list whose CAR is `inline-src-block' and CDR a plist
2060 with `:begin', `:end', `:language', `:value', `:parameters' and
2061 `:post-blank' as keywords.
2063 Assume point is at the beginning of the inline src block."
2083 "Interpret INLINE-SRC-BLOCK object as Org syntax.
2084 CONTENTS is nil."
2089 language
2091 body)))
2094 "Search for the next inline-babel-call element.
2096 LIMIT bounds the search.
2098 Return value is a cons cell whose CAR is `inline-babel-call' and
2099 CDR is beginning position."
2104 ;;;; Italic
2107 "Parse italic object at point.
2109 Return a list whose CAR is `italic' and CDR is a plist with
2110 `:begin', `:end', `:contents-begin' and `:contents-end' and
2111 `:post-blank' keywords.
2113 Assume point is at the first slash marker."
2131 "Interpret ITALIC object as Org syntax.
2132 CONTENTS is the contents of the object."
2136 ;;;; Latex Fragment
2139 "Parse latex fragment at point.
2141 Return a list whose CAR is `latex-fragment' and CDR a plist with
2142 `:value', `:begin', `:end', and `:post-blank' as keywords.
2144 Assume point is at the beginning of the latex fragment."
2158 ;; None found: it's a macro.
2172 "Interpret LATEX-FRAGMENT object as Org syntax.
2173 CONTENTS is nil."
2176 ;;;; Line Break
2179 "Parse line break at point.
2181 Return a list whose CAR is `line-break', and CDR a plist with
2182 `:begin', `:end' and `:post-blank' keywords.
2184 Assume point is at the beginning of the line break."
2190 "Interpret LINE-BREAK object as Org syntax.
2191 CONTENTS is nil."
2195 "Search for the next line-break object.
2197 LIMIT bounds the search.
2199 Return value is a cons cell whose CAR is `line-break' and CDR is
2200 beginning position."
2204 ;; A line break can only happen on a non-empty line.
2209 ;;;; Link
2212 "Parse link at point.
2214 Return a list whose CAR is `link' and CDR a plist with `:type',
2215 `:path', `:raw-link', `:begin', `:end', `:contents-begin',
2216 `:contents-end' and `:post-blank' as keywords.
2218 Assume point is at the beginning of the link."
2221 end contents-begin contents-end link-end post-blank path type
2222 raw-link link)
2224 ;; Type 1: Text targeted from a radio target.
2229 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
2234 ;; RAW-LINK is the original link.
2239 ;; Determine TYPE of link and set PATH accordingly.
2241 ;; File type.
2244 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
2247 ;; Id type: PATH is the id.
2250 ;; Code-ref type: PATH is the name of the reference.
2253 ;; Custom-id type: PATH is the name of the custom id.
2256 ;; Fuzzy type: Internal link either matches a target, an
2257 ;; headline name or nothing. PATH is the target or headline's
2258 ;; name.
2260 ;; Type 3: Plain link, i.e. http://orgmode.org
2266 ;; Type 4: Angular link, i.e. <http://orgmode.org>
2273 ;; In any case, deduce end point after trailing white space from
2274 ;; LINK-END variable.
2288 "Interpret LINK object as Org syntax.
2289 CONTENTS is the contents of the object, or nil."
2294 raw-link
2298 "Search for the next link object.
2300 LIMIT bounds the search.
2302 Return value is a cons cell whose CAR is `link' and CDR is
2303 beginning position."
2312 ;;;; Macro
2315 "Parse macro at point.
2317 Return a list whose CAR is `macro' and CDR a plist with `:key',
2318 `:args', `:begin', `:end', `:value' and `:post-blank' as
2319 keywords.
2321 Assume point is at the macro."
2335 ;; Repair bad splits.
2350 "Interpret MACRO object as Org syntax.
2351 CONTENTS is nil."
2355 "Search for the next macro object.
2357 LIMIT bounds the search.
2359 Return value is cons cell whose CAR is `macro' and CDR is
2360 beginning position."
2364 limit t)
2368 ;;;; Radio-target
2371 "Parse radio target at point.
2373 Return a list whose CAR is `radio-target' and CDR a plist with
2374 `:begin', `:end', `:contents-begin', `:contents-end', `:value'
2375 and `:post-blank' as keywords.
2377 Assume point is at the radio target."
2396 "Interpret TARGET object as Org syntax.
2397 CONTENTS is the contents of the object."
2401 "Search for the next radio-target object.
2403 LIMIT bounds the search.
2405 Return value is a cons cell whose CAR is `radio-target' and CDR
2406 is beginning position."
2412 ;;;; Statistics Cookie
2415 "Parse statistics cookie at point.
2417 Return a list whose CAR is `statistics-cookie', and CDR a plist
2418 with `:begin', `:end', `:value' and `:post-blank' keywords.
2420 Assume point is at the beginning of the statistics-cookie."
2436 "Interpret STATISTICS-COOKIE object as Org syntax.
2437 CONTENTS is nil."
2441 "Search for the next statistics cookie object.
2443 LIMIT bounds the search.
2445 Return value is a cons cell whose CAR is `statistics-cookie' and
2446 CDR is beginning position."
2452 ;;;; Strike-Through
2455 "Parse strike-through object at point.
2457 Return a list whose CAR is `strike-through' and CDR is a plist
2458 with `:begin', `:end', `:contents-begin' and `:contents-end' and
2459 `:post-blank' keywords.
2461 Assume point is at the first plus sign marker."
2479 "Interpret STRIKE-THROUGH object as Org syntax.
2480 CONTENTS is the contents of the object."
2484 ;;;; Subscript
2487 "Parse subscript at point.
2489 Return a list whose CAR is `subscript' and CDR a plist with
2490 `:begin', `:end', `:contents-begin', `:contents-end',
2491 `:use-brackets-p' and `:post-blank' as keywords.
2493 Assume point is at the underscore."
2497 t
2515 "Interpret SUBSCRIPT object as Org syntax.
2516 CONTENTS is the contents of the object."
2519 contents))
2522 "Search for the next sub/superscript object.
2524 LIMIT bounds the search.
2526 Return value is a cons cell whose CAR is either `subscript' or
2527 `superscript' and CDR is beginning position."
2534 ;;;; Superscript
2537 "Parse superscript at point.
2539 Return a list whose CAR is `superscript' and CDR a plist with
2540 `:begin', `:end', `:contents-begin', `:contents-end',
2541 `:use-brackets-p' and `:post-blank' as keywords.
2543 Assume point is at the caret."
2564 "Interpret SUPERSCRIPT object as Org syntax.
2565 CONTENTS is the contents of the object."
2568 contents))
2571 ;;;; Table Cell
2574 "Parse table cell at point.
2576 Return a list whose CAR is `table-cell' and CDR is a plist
2577 containing `:begin', `:end', `:contents-begin', `:contents-end'
2578 and `:post-blank' keywords."
2592 "Interpret TABLE-CELL element as Org syntax.
2593 CONTENTS is the contents of the cell, or nil."
2597 "Search for the next table-cell object.
2599 LIMIT bounds the search.
2601 Return value is a cons cell whose CAR is `table-cell' and CDR is
2602 beginning position."
2606 ;;;; Target
2609 "Parse target at point.
2611 Return a list whose CAR is `target' and CDR a plist with
2612 `:begin', `:end', `:value' and `:post-blank' as keywords.
2614 Assume point is at the target."
2629 "Interpret TARGET object as Org syntax.
2630 CONTENTS is nil."
2634 "Search for the next target object.
2636 LIMIT bounds the search.
2638 Return value is a cons cell whose CAR is `target' and CDR is
2639 beginning position."
2645 ;;;; Timestamp
2648 "Parse time stamp at point.
2650 Return a list whose CAR is `timestamp', and CDR a plist with
2651 `:type', `:begin', `:end', `:value' and `:post-blank' keywords.
2653 Assume point is at the beginning of the timestamp."
2679 "Interpret TIMESTAMP object as Org syntax.
2680 CONTENTS is nil."
2684 "Search for the next timestamp object.
2686 LIMIT bounds the search.
2688 Return value is a cons cell whose CAR is `timestamp' and CDR is
2689 beginning position."
2697 limit t)
2701 ;;;; Underline
2704 "Parse underline object at point.
2706 Return a list whose CAR is `underline' and CDR is a plist with
2707 `:begin', `:end', `:contents-begin' and `:contents-end' and
2708 `:post-blank' keywords.
2710 Assume point is at the first underscore marker."
2728 "Interpret UNDERLINE object as Org syntax.
2729 CONTENTS is the contents of the object."
2733 ;;;; Verbatim
2736 "Parse verbatim object at point.
2738 Return a list whose CAR is `verbatim' and CDR is a plist with
2739 `:value', `:begin', `:end' and `:post-blank' keywords.
2741 Assume point is at the first equal sign marker."
2757 "Interpret VERBATIM object as Org syntax.
2758 CONTENTS is nil."
2762 \f
2763 ;;; Definitions And Rules
2765 ;; Define elements, greater elements and specify recursive objects,
2766 ;; along with the affiliated keywords recognized. Also set up
2767 ;; restrictions on recursive objects combinations.
2769 ;; These variables really act as a control center for the parsing
2770 ;; process.
2773 ;; Headlines and inlinetasks.
2775 ;; Comments, blocks (any type), keywords and babel calls.
2777 ;; Lists.
2779 ;; Fixed-width, drawers (any type) and tables.
2781 ;; Footnote definitions.
2783 ;; Horizontal rules.
2785 ;; LaTeX environments.
2787 ;; Planning and Clock lines.
2797 export-block fixed-width footnote-definition headline
2798 horizontal-rule inlinetask item keyword latex-environment
2799 babel-call paragraph plain-list planning property-drawer
2800 quote-block quote-section section special-block src-block table
2801 table-row verse-block)
2806 item plain-list quote-block section special-block table)
2811 latex-or-entity line-break link macro radio-target
2812 statistics-cookie sub/superscript table-cell target
2813 text-markup timestamp)
2822 "Alist of translations between object type and successor name.
2824 Sharing the same successor comes handy when, for example, the
2829 inline-src-block italic line-break latex-fragment link macro
2830 radio-target statistics-cookie strike-through subscript superscript
2831 table-cell target timestamp underline verbatim)
2836 table-cell underline)
2861 "Alist of usual translations for keywords.
2862 The key is the old name and the value the new one. The property
2867 "List of affiliated keywords that can occur more that once in an element.
2869 Their value will be consed into a list of strings, which will be
2870 returned as the value of the property.
2872 This list is checked after translations have been applied. See
2876 "List of keywords whose value can be parsed.
2878 Their value will be stored as a secondary string: a list of
2879 strings and objects.
2881 This list is checked after translations have been applied. See
2885 "List of keywords which can have a secondary value.
2887 In Org syntax, they can be written with optional square brackets
2888 before the colons. For example, results keyword can be
2889 associated to a hash value with the following:
2891 #+RESULTS[hash-string]: some-source
2893 This list is checked after translations have been applied. See
2900 inline-babel-call inline-src-block latex-fragment
2901 line-break link macro radio-target sub/superscript
2902 target text-markup timestamp)
2904 macro radio-target statistics-cookie sub/superscript text-markup
2905 timestamp)
2919 link radio-target sub/superscript target text-markup
2920 timestamp)
2931 latex-fragment line-break link macro radio-target
2933 "Alist of objects restrictions.
2935 CAR is an element or object type containing objects and CDR is
2936 a list of successors that will be called within an element or
2937 object of such type.
2939 For example, in a `radio-target' object, one can only find
2940 entities, export snippets, latex-fragments, subscript and
2941 superscript.
2943 This alist also applies to secondary string. For example, an
2944 `headline' type element doesn't directly contain objects, but
2955 \f
2956 ;;; Accessors
2957 ;;
2958 ;; Provide four accessors: `org-element-type', `org-element-property'
2959 ;; `org-element-contents' and `org-element-restriction'.
2962 "Return type of element ELEMENT.
2964 The function returns the type of the element or object provided.
2965 It can also return the following special value:
2966 `plain-text' for a string
2967 `org-data' for a complete document
2968 nil in any other case."
2974 "Extract the value from the PROPERTY of an ELEMENT."
2978 "Extract contents from an ELEMENT."
2982 "Return restriction associated to ELEMENT.
2983 ELEMENT can be an element, an object or a symbol representing an
2984 element or object type."
2986 org-element-object-restrictions)))
2989 \f
2990 ;;; Parsing Element Starting At Point
2991 ;;
2992 ;; `org-element-current-element' is the core function of this section.
2993 ;; It returns the Lisp representation of the element starting at
2994 ;; point. It uses `org-element--element-block-re' for quick access to
2995 ;; a common regexp.
2996 ;;
2997 ;; `org-element-current-element' makes use of special modes. They are
2998 ;; activated for fixed element chaining (i.e. `plain-list' > `item')
2999 ;; or fixed conditional element chaining (i.e. `headline' >
3000 ;; `section'). Special modes are: `section', `quote-section', `item'
3001 ;; and `table-row'.
3006 'regexp-quote
3008 "Regexp matching the beginning of a non-recursive block type.
3012 "Parse the element starting at point.
3014 Return value is a list like (TYPE PROPS) where TYPE is the type
3015 of the element and PROPS a plist of properties associated to the
3016 element.
3018 Possible types are defined in `org-element-all-elements'.
3020 Optional argument GRANULARITY determines the depth of the
3021 recursion. Allowed values are `headline', `greater-element',
3022 `element', `object' or nil. When it is broader than `object' (or
3023 nil), secondary values will not be parsed, since they only
3024 contain objects.
3026 Optional argument SPECIAL, when non-nil, can be either `section',
3027 `quote-section', `table-row' and `item'.
3029 If STRUCTURE isn't provided but SPECIAL is set to `item', it will
3030 be computed.
3032 Unlike to `org-element-at-point', this function assumes point is
3033 always at the beginning of the element it has to parse. As such,
3034 it is quicker than its counterpart, albeit more restrictive."
3036 ;; If point is at an affiliated keyword, try moving to the
3037 ;; beginning of the associated element. If none is found, the
3038 ;; keyword is orphaned and will be treated as plain text.
3044 ;; Determine if parsing depth allows for secondary strings
3045 ;; parsing. It only applies to elements referenced in
3046 ;; `org-element-secondary-value-alist'.
3049 ;; Item
3052 raw-secondary-p))
3053 ;; Quote Section.
3055 ;; Table Row.
3057 ;; Headline.
3060 ;; Section (must be checked after headline).
3062 ;; Planning and Clock.
3067 ;; Non-recursive block.
3076 "org-element-%s-parser"
3079 ;; Inlinetask.
3081 ;; LaTeX Environment or Paragraph if incomplete.
3087 ;; Property Drawer.
3092 ;; Recursive Block, or Paragraph if incomplete.
3103 ;; Drawer.
3109 ;; Babel Call.
3112 ;; Dynamic Block or Paragraph if incomplete. This must be
3113 ;; checked before regular keywords since their regexp matches
3114 ;; dynamic blocks too.
3120 ;; Keyword, or Paragraph if at an orphaned affiliated keyword.
3127 ;; Footnote definition.
3130 ;; Comment.
3133 ;; Horizontal Rule.
3136 ;; Table.
3138 ;; List or Item.
3141 ;; Default element: Paragraph.
3145 ;; Most elements can have affiliated keywords. When looking for an
3146 ;; element beginning, we want to move before them, as they belong to
3147 ;; that element, and, in the meantime, collect information they give
3148 ;; into appropriate properties. Hence the following function.
3150 ;; Usage of optional arguments may not be obvious at first glance:
3152 ;; - TRANS-LIST is used to polish keywords names that have evolved
3153 ;; during Org history. In example, even though =result= and
3154 ;; =results= coexist, we want to have them under the same =result=
3155 ;; property. It's also true for "srcname" and "name", where the
3156 ;; latter seems to be preferred nowadays (thus the "name" property).
3158 ;; - CONSED allows to regroup multi-lines keywords under the same
3159 ;; property, while preserving their own identity. This is mostly
3160 ;; used for "attr_latex" and al.
3162 ;; - PARSED prepares a keyword value for export. This is useful for
3163 ;; "caption". Objects restrictions for such keywords are defined in
3164 ;; `org-element-object-restrictions'.
3166 ;; - DUALS is used to take care of keywords accepting a main and an
3167 ;; optional secondary values. For example "results" has its
3168 ;; source's name as the main value, and may have an hash string in
3169 ;; optional square brackets as the secondary one.
3171 ;; A keyword may belong to more than one category.
3182 "Regexp matching any affiliated keyword.
3184 Keyword name is put in match group 1. Moreover, if keyword
3185 belongs to `org-element-dual-keywords', put the dual value in
3186 match group 2.
3191 consed parsed duals)
3192 "Collect affiliated keywords before point.
3194 Optional argument KEY-RE is a regexp matching keywords, which
3195 puts matched keyword in group 1. It defaults to
3196 `org-element--affiliated-re'.
3198 TRANS-LIST is an alist where key is the keyword and value the
3199 property name it should be translated to, without the colons. It
3200 defaults to `org-element-keyword-translation-alist'.
3202 CONSED is a list of strings. Any keyword belonging to that list
3203 will have its value consed. The check is done after keyword
3204 translation. It defaults to `org-element-multiple-keywords'.
3206 PARSED is a list of strings. Any keyword member of this list
3207 will have its value parsed. The check is done after keyword
3208 translation. If a keyword is a member of both CONSED and PARSED,
3209 it's value will be a list of parsed strings. It defaults to
3210 `org-element-parsed-keywords'.
3212 DUALS is a list of strings. Any keyword member of this list can
3213 have two parts: one mandatory and one optional. Its value is
3214 a cons cell whose car is the former, and the cdr the latter. If
3215 a keyword is a member of both PARSED and DUALS, both values will
3216 be parsed. It defaults to `org-element-dual-keywords'.
3218 Return a list whose car is the position at the first of them and
3219 cdr a plist of keywords and values."
3227 ;; RESTRICT is the list of objects allowed in parsed
3228 ;; keywords value.
3230 output)
3235 ;; Apply translation to RAW-KWD. From there, KWD is
3236 ;; the official keyword.
3238 ;; Find main value for any keyword.
3244 ;; If KWD is a dual keyword, find its secondary
3245 ;; value. Maybe parse it.
3251 ;; Attribute a property name to KWD.
3253 ;; Now set final shape for VALUE.
3257 ;; VALUE is mandatory. Set it to nil if there is none.
3261 ;; Eventually store the new value in OUTPUT.
3267 \f
3268 ;;; The Org Parser
3270 ;; The two major functions here are `org-element-parse-buffer', which
3271 ;; parses Org syntax inside the current buffer, taking into account
3272 ;; region, narrowing, or even visibility if specified, and
3273 ;; `org-element-parse-secondary-string', which parses objects within
3274 ;; a given string.
3276 ;; The (almost) almighty `org-element-map' allows to apply a function
3277 ;; on elements or objects matching some type, and accumulate the
3278 ;; resulting values. In an export situation, it also skips unneeded
3279 ;; parts of the parse tree.
3282 "Recursively parse the buffer and return structure.
3283 If narrowing is in effect, only parse the visible part of the
3284 buffer.
3286 Optional argument GRANULARITY determines the depth of the
3287 recursion. It can be set to the following symbols:
3289 `headline' Only parse headlines.
3290 `greater-element' Don't recurse into greater elements excepted
3291 headlines and sections. Thus, elements
3292 parsed are the top-level ones.
3293 `element' Parse everything but objects and plain text.
3294 `object' Parse the complete buffer (default).
3296 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3297 elements.
3299 Assume buffer is in Org mode."
3306 ;; Start in `section' mode so text before the first
3307 ;; headline belongs to a section.
3311 "Recursively parse objects in STRING and return structure.
3313 RESTRICTION, when non-nil, is a symbol limiting the object types
3314 that will be looked after."
3320 "Map a function on selected elements or objects.
3322 DATA is the parsed tree, as returned by, i.e,
3323 `org-element-parse-buffer'. TYPES is a symbol or list of symbols
3324 of elements or objects types. FUN is the function called on the
3325 matching element or object. It must accept one arguments: the
3326 element or object itself.
3328 When optional argument INFO is non-nil, it should be a plist
3329 holding export options. In that case, parts of the parse tree
3330 not exportable according to that property list will be skipped.
3332 When optional argument FIRST-MATCH is non-nil, stop at the first
3333 match for which FUN doesn't return nil, and return that value.
3335 Optional argument NO-RECURSION is a symbol or a list of symbols
3336 representing elements or objects types. `org-element-map' won't
3337 enter any recursive element or object whose type belongs to that
3338 list. Though, FUN can still be applied on them.
3340 Nil values returned from FUN do not appear in the results."
3341 ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
3344 ;; Recursion depth is determined by --CATEGORY.
3354 ;; --RESTRICTS is a list of element types whose secondary
3355 ;; string could possibly contain an object with a type among
3356 ;; TYPES.
3360 when
3364 --acc
3368 ;; Recursively walk DATA. INFO, if non-nil, is
3369 ;; a plist holding contextual information.
3374 ;; Check if TYPE is matching among TYPES. If so,
3375 ;; apply FUN to --BLOB and accumulate return value
3376 ;; into --ACC (or exit if FIRST-MATCH is non-nil).
3382 ;; If --BLOB has a secondary string that can
3383 ;; contain objects with their type among TYPES,
3384 ;; look into that string.
3387 --walk-tree
3389 nil
3392 --blob))))
3393 ;; Now determine if a recursion into --BLOB is
3394 ;; possible. If so, do it.
3405 ;; Return value in a proper order.
3408 ;; The following functions are internal parts of the parser.
3410 ;; The first one, `org-element-parse-elements' acts at the element's
3411 ;; level.
3413 ;; The second one, `org-element-parse-objects' applies on all objects
3414 ;; of a paragraph or a secondary string. It uses
3415 ;; `org-element-get-candidates' to optimize the search of the next
3416 ;; object in the buffer.
3418 ;; More precisely, that function looks for every allowed object type
3419 ;; first. Then, it discards failed searches, keeps further matches,
3420 ;; and searches again types matched behind point, for subsequent
3421 ;; calls. Thus, searching for a given type fails only once, and every
3422 ;; object is searched only once at top level (but sometimes more for
3423 ;; nested types).
3427 "Parse elements between BEG and END positions.
3429 SPECIAL prioritize some elements over the others. It can be set
3430 to `quote-section', `section' `item' or `table-row'.
3432 When value is `item', STRUCTURE will be used as the current list
3433 structure.
3435 GRANULARITY determines the depth of the recursion. See
3436 `org-element-parse-buffer' for more information.
3438 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3439 elements.
3441 Elements are accumulated into ACC."
3446 ;; When parsing only headlines, skip any text before first one.
3449 ;; Main loop start.
3452 ;; Find current element's type and parse it accordingly to
3453 ;; its category.
3455 granularity special structure))
3460 ;; Case 1. Simply accumulate element if VISIBLE-ONLY is
3461 ;; true and element is hidden or if it has no contents
3462 ;; anyway.
3465 ;; Case 2. Greater element: parse it between
3466 ;; `contents-begin' and `contents-end'. Make sure
3467 ;; GRANULARITY allows the recursion, or ELEMENT is an
3468 ;; headline, in which case going inside is mandatory, in
3469 ;; order to get sub-level headings.
3477 ;; Possibly switch to a special mode.
3486 ;; Case 3. ELEMENT has contents. Parse objects inside,
3487 ;; if GRANULARITY allows it.
3492 ;; Case 4. Else, just accumulate ELEMENT.
3494 acc)))
3495 ;; Return result.
3499 "Parse objects between BEG and END and return recursive structure.
3501 Objects are accumulated in ACC.
3503 RESTRICTION is a list of object types which are allowed in the
3504 current object."
3508 ;; Return the parsing function associated to the nearest
3509 ;; object among list of candidates CAND.
3516 next-object candidates)
3520 end restriction candidates))
3522 ;; 1. Text before any object. Untabify it.
3528 acc)))
3529 ;; 2. Object...
3533 cont-beg)
3534 ;; ... recursive. The CONT-BEG check is for
3535 ;; links, as some of them might not be recursive
3536 ;; (i.e. plain links).
3539 cont-beg
3544 ;; Restrict allowed objects.
3546 ;; ... not recursive. Accumulate the object.
3547 next-object)
3548 acc)
3550 ;; 3. Text after last object. Untabify it.
3555 acc))
3556 ;; Result.
3560 "Return an alist of candidates for the next object.
3562 LIMIT bounds the search, and RESTRICTION narrows candidates to
3563 some object types.
3565 Return value is an alist whose CAR is position and CDR the object
3566 type, as a symbol.
3568 OBJECTS is the previous candidates alist."
3570 ;; If no previous result, search every object type in RESTRICTION.
3571 ;; Otherwise, keep potential candidates (old objects located after
3572 ;; point) and ask to search again those which had matched before.
3577 objects))
3578 ;; Call the appropriate successor function for each type to search
3579 ;; and accumulate matches.
3586 type))))
3589 types-to-search)
3590 ;; Return alist.
3591 next-candidates))
3594 \f
3595 ;;; Towards A Bijective Process
3597 ;; The parse tree obtained with `org-element-parse-buffer' is really
3598 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
3599 ;; interpreted and expanded into a string with canonical Org syntax.
3600 ;; Hence `org-element-interpret-data'.
3601 ;;
3602 ;; The function relies internally on
3603 ;; `org-element-interpret--affiliated-keywords'.
3606 "Interpret DATA as Org syntax.
3608 DATA is a parse tree, an element, an object or a secondary string
3609 to interpret.
3611 Optional argument PARENT is used for recursive calls. It contains
3612 the element or object containing data, or nil.
3614 Return Org syntax as a string."
3618 ;; Secondary string.
3623 ;; Full Org document.
3628 ;; Plain text.
3630 ;; Element/Object without contents.
3633 data nil))
3634 ;; Element/Object with contents.
3644 ;; Elements directly containing objects must
3645 ;; have their indentation normalized first.
3647 data
3648 ;; When normalizing first paragraph of an
3649 ;; item or a footnote-definition, ignore
3650 ;; first line's indentation.
3657 data
3659 contents)))))))
3661 ;; Build white spaces. If no `:post-blank' property is
3662 ;; specified, assume its value is 0.
3672 "Return ELEMENT's affiliated keywords as Org syntax.
3673 If there is no affiliated keyword, return the empty string."
3683 ": "
3686 value)
3691 element)))
3698 ;; Remove translated keywords.
3703 org-element-affiliated-keywords))
3706 ;; Because interpretation of the parse tree must return the same
3707 ;; number of blank lines between elements and the same number of white
3708 ;; space after objects, some special care must be given to white
3709 ;; spaces.
3710 ;;
3711 ;; The first function, `org-element-normalize-string', ensures any
3712 ;; string different from the empty string will end with a single
3713 ;; newline character.
3714 ;;
3715 ;; The second function, `org-element-normalize-contents', removes
3716 ;; global indentation from the contents of the current element.
3719 "Ensure string S ends with a single newline character.
3721 If S isn't a string return it unchanged. If S is the empty
3722 string, return it. Otherwise, return a new string with a single
3723 newline character at its end."
3731 "Normalize plain text in ELEMENT's contents.
3733 ELEMENT must only contain plain text and objects.
3735 If optional argument IGNORE-FIRST is non-nil, ignore first line's
3736 indentation to compute maximal common indentation.
3738 Return the normalized element that is element with global
3739 indentation removed from its contents. The function assumes that
3740 indentation is not done with TAB characters."
3744 ;; Return list of indentations within BLOB. This is done by
3745 ;; walking recursively BLOB and updating IND-LIST along the
3746 ;; way. FIRST-FLAG is non-nil when the first string hasn't
3747 ;; been seen yet. It is required as this string is the only
3748 ;; one whose indentation doesn't happen after a newline
3749 ;; character.
3757 ;; An indentation of zero means no string will be
3758 ;; modified. Quit the process.
3764 ;; Avoid matching blank or empty lines.
3772 ;; Collect indentation list in ELEMENT. Possibly remove first
3773 ;; value if IGNORE-FIRST is non-nil.
3776 ;; Build ELEMENT back, replacing each string with the same
3777 ;; string minus common indentation.
3781 ;; Return BLOB with all its strings indentation
3782 ;; shortened from MCI white spaces. FIRST-FLAG is
3783 ;; non-nil when the first string hasn't been seen
3784 ;; yet.
3799 org-element-recursive-objects)
3806 \f
3807 ;;; The Toolbox
3809 ;; The first move is to implement a way to obtain the smallest element
3810 ;; containing point. This is the job of `org-element-at-point'. It
3811 ;; basically jumps back to the beginning of section containing point
3812 ;; and moves, element after element, with
3813 ;; `org-element-current-element' until the container is found.
3814 ;;
3815 ;; Note: When using `org-element-at-point', secondary values are never
3816 ;; parsed since the function focuses on elements, not on objects.
3819 "Determine closest element around point.
3821 Return value is a list like (TYPE PROPS) where TYPE is the type
3822 of the element and PROPS a plist of properties associated to the
3823 element. Possible types are defined in
3824 `org-element-all-elements'.
3826 As a special case, if point is at the very beginning of a list or
3827 sub-list, returned element will be that list instead of the first
3828 item. In the same way, if point is at the beginning of the first
3829 row of a table, returned element will be the table instead of the
3830 first row.
3832 If optional argument KEEP-TRAIL is non-nil, the function returns
3833 a list of of elements leading to element at point. The list's
3834 CAR is always the element at point. Its last item will be the
3835 element's parent, unless element was either the first in its
3836 section (in which case the last item in the list is the first
3837 element of section) or an headline (in which case the list
3838 contains that headline as its single element). Elements
3839 in-between, if any, are siblings of the element at point."
3841 ;; If at an headline, parse it. It is the sole element that
3842 ;; doesn't require to know about context. Be sure to disallow
3843 ;; secondary string parsing, though.
3847 ;; Otherwise move at the beginning of the section containing
3848 ;; point.
3856 ;; Starting parsing successively each element with
3857 ;; `org-element-current-element'. Skip those ending before
3858 ;; original position.
3866 ;; 1. Skip any element ending before point or at point.
3871 ;; 2. An element containing point is always the element at
3872 ;; point.
3875 ;; 3. At a plain list.
3881 ;; Find the item at this level containing ORIGIN.
3883 parent)
3888 ;; Item ends before point: skip it.
3890 ;; Item contains point: store is in PARENT.
3892 ;; We went too far: return PARENT.
3894 ;; No parent: no item contained point, though the
3895 ;; plain list does. Point is in the blank lines
3896 ;; after the list: return plain list.
3900 ;; 4. At a table.
3911 ;; 4. At any other greater element type, if point is
3912 ;; within contents, move into it. Otherwise, return
3913 ;; that element.
3920 ;; Reset trail, since we found a parent.
3926 ;; Once the local structure around point is well understood, it's easy
3927 ;; to implement some replacements for `forward-paragraph'
3928 ;; `backward-paragraph', namely `org-element-forward' and
3929 ;; `org-element-backward'.
3931 ;; Also, `org-transpose-elements' mimics the behaviour of
3932 ;; `transpose-words', at the element's level, whereas
3933 ;; `org-element-drag-forward', `org-element-drag-backward', and
3934 ;; `org-element-up' generalize, respectively, functions
3935 ;; `org-subtree-down', `org-subtree-up' and `outline-up-heading'.
3937 ;; `org-element-unindent-buffer' will, as its name almost suggests,
3938 ;; smartly remove global indentation from buffer, making it possible
3939 ;; to use Org indent mode on a file created with hard indentation.
3941 ;; `org-element-nested-p' and `org-element-swap-A-B' are used
3942 ;; internally by some of the previously cited tools.
3945 "Non-nil when elements ELEM-A and ELEM-B are nested."
3954 "Swap elements ELEM-A and ELEM-B.
3956 Leave point at the end of ELEM-A."
3978 "Move backward by one element.
3979 Move to the previous element at the same level, when possible."
3986 ;; Move to beginning of current element if point isn't there.
3990 ;; At an headline: move to previous headline at the same
3991 ;; level, a parent, or BOB.
3996 ;; At an item: try to move to the previous item, if any.
4002 ;; In any other case, find the previous element in the
4003 ;; trail and move to its beginning. If no previous element
4004 ;; can be found, move to headline.
4010 "Drag backward element at point."
4027 ;; Compute new position of point: it's shifted by PREV-ELEM
4028 ;; body's length.
4035 "Move forward element at point."
4048 ;; Compute new position of point: it's shifted by NEXT-ELEM
4049 ;; body's length (without final blanks) and by the length of
4050 ;; blanks between ELEM and NEXT-ELEM.
4067 "Move forward by one element.
4068 Move to the next element at the same level, when possible."
4076 ;; At an headline, move to next headline at the same level.
4078 ;; At an item. Move to the next item, if possible.
4085 ;; In any other case, move to element's end, unless this
4086 ;; position is also the end of its parent's contents, in which
4087 ;; case, directly jump to parent's end.
4090 ;; Determine if TRAIL contains the real parent of ELEMENT.
4094 org-element-greater-elements)
4097 parent-candidate)))))
4104 "Put point at beginning of this element, mark at end.
4106 Interactively, if this command is repeated or (in Transient Mark
4107 mode) if the mark is active, it marks the next element after the
4108 ones already marked."
4123 "Narrow buffer to current element."
4141 "Transpose current and previous elements, keeping blank lines between.
4142 Point is moved after both elements."
4161 "Un-indent the visible part of the buffer.
4162 Relative indentation \(between items, inside blocks, etc.\) isn't
4163 modified."
4168 unindent-tree ; For byte-compiler.
4186 "Move to upper element."
4197 ;; At an item, with a parent in the list: move to that parent.
4204 ;; Determine parent in the trail.
4210 org-element-greater-elements)
4213 parentp)))))
4215 ;; When parent is found move to its beginning.
4217 ;; If no parent was found, move to headline above, if any
4218 ;; or return an error.
4223 "Move to inner element."
4231 ;; If contents are hidden, first disclose them.
4238 ;;; org-element.el ends here