| blob | 9f8df456b211b720d2d423a62300f49127296e84 |
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' (and its
104 ;; relative, `org-element-interpret-secondary').
106 ;; The library ends by furnishing a set of interactive tools for
107 ;; element's navigation and manipulation, mostly based on
108 ;; `org-element-at-point' function.
111 ;;; Code:
117 \f
118 ;;; Greater elements
120 ;; For each greater element type, we define a parser and an
121 ;; interpreter.
123 ;; A parser returns the element or object as the list described above.
124 ;; Most of them accepts no argument. Though, exceptions exist. Hence
125 ;; every element containing a secondary string (see
126 ;; `org-element-secondary-value-alist') will accept an optional
127 ;; argument to toggle parsing of that secondary string. Moreover,
128 ;; `item' parser requires current list's structure as its first
129 ;; element.
131 ;; An interpreter accepts two arguments: the list representation of
132 ;; the element or object, and its contents. The latter may be nil,
133 ;; depending on the element or object considered. It returns the
134 ;; appropriate Org syntax, as a string.
136 ;; Parsing functions must follow the naming convention:
137 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
138 ;; defined in `org-element-greater-elements'.
139 ;;
140 ;; Similarly, interpreting functions must follow the naming
141 ;; convention: org-element-TYPE-interpreter.
143 ;; With the exception of `headline' and `item' types, greater elements
144 ;; cannot contain other greater elements of their own type.
146 ;; Beside implementing a parser and an interpreter, adding a new
147 ;; greater element requires to tweak `org-element-current-element'.
148 ;; Moreover, the newly defined type must be added to both
149 ;; `org-element-all-elements' and `org-element-greater-elements'.
152 ;;;; Center Block
155 "Parse a center block.
157 Return a list whose CAR is `center-block' and CDR is a plist
158 containing `:begin', `:end', `:hiddenp', `:contents-begin',
159 `:contents-end' and `:post-blank' keywords.
161 Assume point is at beginning or end of the block."
188 "Interpret CENTER-BLOCK element as Org syntax.
189 CONTENTS is the contents of the element."
193 ;;;; Drawer
196 "Parse a drawer.
198 Return a list whose CAR is `drawer' and CDR is a plist containing
199 `:drawer-name', `:begin', `:end', `:hiddenp', `:contents-begin',
200 `:contents-end' and `:post-blank' keywords.
202 Assume point is at beginning of drawer."
227 "Interpret DRAWER element as Org syntax.
228 CONTENTS is the contents of the element."
231 contents))
234 ;;;; Dynamic Block
237 "Parse a dynamic block.
239 Return a list whose CAR is `dynamic-block' and CDR is a plist
240 containing `:block-name', `:begin', `:end', `:hiddenp',
241 `:contents-begin', `:contents-end', `:arguments' and
242 `:post-blank' keywords.
244 Assume point is at beginning of dynamic block."
271 "Interpret DYNAMIC-BLOCK element as Org syntax.
272 CONTENTS is the contents of the element."
277 contents))
280 ;;;; Footnote Definition
283 "Parse a footnote definition.
285 Return a list whose CAR is `footnote-definition' and CDR is
286 a plist containing `:label', `:begin' `:end', `:contents-begin',
287 `:contents-end' and `:post-blank' keywords.
289 Assume point is at the beginning of the footnote definition."
318 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
319 CONTENTS is the contents of the footnote-definition."
321 " "
322 contents))
325 ;;;; Headline
328 "Parse an headline.
330 Return a list whose CAR is `headline' and CDR is a plist
331 containing `:raw-value', `:title', `:begin', `:end',
332 `:pre-blank', `:hiddenp', `:contents-begin' and `:contents-end',
333 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
334 `:scheduled', `:deadline', `:timestamp', `:clock', `:category',
335 `:quotedp', `:archivedp', `:commentedp' and `:footnote-section-p'
336 keywords.
338 The plist also contains any property set in the property drawer,
339 with its name in lowercase, the underscores replaced with hyphens
340 and colons at the beginning (i.e. `:custom-id').
342 When RAW-SECONDARY-P is non-nil, headline's title will not be
343 parsed as a secondary string, but as a plain string instead.
345 Assume point is at beginning of the headline."
377 plist))
393 title)
394 ;; Clean RAW-VALUE from any quote or comment string.
399 ""
400 raw-value)))
401 ;; Clean TAGS from archive tag, if any.
408 ;; Then get TITLE.
439 "Interpret HEADLINE element as Org syntax.
440 CONTENTS is the contents of the element."
468 ;; Align tags.
476 ? )
477 tags))
481 tags))))
483 contents)))
486 ;;;; Inlinetask
489 "Parse an inline task.
491 Return a list whose CAR is `inlinetask' and CDR is a plist
492 containing `:title', `:begin', `:end', `:hiddenp',
493 `:contents-begin' and `:contents-end', `:level', `:priority',
494 `:tags', `:todo-keyword', `:todo-type', `:scheduled',
495 `:deadline', `:timestamp', `:clock' and `:post-blank' keywords.
497 The plist also contains any property set in the property drawer,
498 with its name in lowercase, the underscores replaced with hyphens
499 and colons at the beginning (i.e. `:custom-id').
501 When optional argument RAW-SECONDARY-P is non-nil, inline-task's
502 title will not be parsed as a secondary string, but as a plain
503 string instead.
505 Assume point is at beginning of the inline task."
528 plist))
537 ;; In the case of a single line task, CONTENTS-BEGIN and
538 ;; CONTENTS-END might overlap.
561 ,@standard-props
565 "Interpret INLINETASK element as Org syntax.
566 CONTENTS is the contents of inlinetask."
579 ;; Align tags.
587 ? )
588 tags))
592 tags))))
593 ;; Prefer degenerate inlinetasks when there are no
594 ;; contents.
597 contents
601 ;;;; Item
604 "Parse an item.
606 STRUCT is the structure of the plain list.
608 Return a list whose CAR is `item' and CDR is a plist containing
609 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
610 `:checkbox', `:counter', `:tag', `:structure', `:hiddenp' and
611 `:post-blank' keywords.
613 When optional argument RAW-SECONDARY-P is non-nil, item's tag, if
614 any, will not be parsed as a secondary string, but as a plain
615 string instead.
617 Assume point is at the beginning of the item."
644 ;; If first line isn't empty,
645 ;; contents really start at the text
646 ;; after item's meta-data.
660 ;; CONTENTS-BEGIN and CONTENTS-END may be mixed
661 ;; up in the case of an empty item separated
662 ;; from the next by a blank line. Thus, ensure
663 ;; the former is always the smallest of two.
674 "Interpret ITEM element as Org syntax.
675 CONTENTS is the contents of the element."
689 num
696 ;; Compute indentation.
698 ;; Indent contents.
700 bullet
711 ;;;; Plain List
714 "Parse a plain list.
716 Optional argument STRUCTURE, when non-nil, is the structure of
717 the plain list being parsed.
719 Return a list whose CAR is `plain-list' and CDR is a plist
720 containing `:type', `:begin', `:end', `:contents-begin' and
721 `:contents-end', `:level', `:structure' and `:post-blank'
722 keywords.
724 Assume point is at one of the list items."
739 ;; Get list level.
744 struct parents))
746 ;; Blank lines below list belong to the top-level list only.
751 ;; Return value.
764 "Interpret PLAIN-LIST element as Org syntax.
765 CONTENTS is the contents of the element."
766 contents)
769 ;;;; Quote Block
772 "Parse a quote block.
774 Return a list whose CAR is `quote-block' and CDR is a plist
775 containing `:begin', `:end', `:hiddenp', `:contents-begin',
776 `:contents-end' and `:post-blank' keywords.
778 Assume point is at beginning or end of the block."
805 "Interpret QUOTE-BLOCK element as Org syntax.
806 CONTENTS is the contents of the element."
810 ;;;; Section
813 "Parse a section.
815 Return a list whose CAR is `section' and CDR is a plist
816 containing `:begin', `:end', `:contents-begin', `contents-end'
817 and `:post-blank' keywords."
819 ;; Beginning of section is the beginning of the first non-blank
820 ;; line after previous headline.
839 "Interpret SECTION element as Org syntax.
840 CONTENTS is the contents of the element."
841 contents)
844 ;;;; Special Block
847 "Parse a special block.
849 Return a list whose CAR is `special-block' and CDR is a plist
850 containing `:type', `:begin', `:end', `:hiddenp',
851 `:contents-begin', `:contents-end' and `:post-blank' keywords.
853 Assume point is at beginning or end of the block."
884 "Interpret SPECIAL-BLOCK element as Org syntax.
885 CONTENTS is the contents of the element."
890 \f
891 ;;; Elements
893 ;; For each element, a parser and an interpreter are also defined.
894 ;; Both follow the same naming convention used for greater elements.
896 ;; Also, as for greater elements, adding a new element type is done
897 ;; through the following steps: implement a parser and an interpreter,
898 ;; tweak `org-element-current-element' so that it recognizes the new
899 ;; type and add that new type to `org-element-all-elements'.
901 ;; As a special case, when the newly defined type is a block type,
902 ;; `org-element-non-recursive-block-alist' has to be modified
903 ;; accordingly.
906 ;;;; Babel Call
909 "Parse a babel call.
911 Return a list whose CAR is `babel-call' and CDR is a plist
912 containing `:begin', `:end', `:info' and `:post-blank' as
913 keywords."
928 "Interpret BABEL-CALL element as Org syntax.
929 CONTENTS is nil."
935 ;; Remove redundant square brackets.
940 ;;;; Clock
943 "Parse a clock.
945 Return a list whose CAR is `clock' and CDR is a plist containing
946 `:status', `:value', `:time', `:begin', `:end' and `:post-blank'
947 as keywords."
972 "Interpret CLOCK element as Org syntax.
973 CONTENTS is nil."
980 "%2s:%02s"
984 ;;;; Comment
987 "Parse a comment.
989 Return a list whose CAR is `comment' and CDR is a plist
990 containing `:begin', `:end', `:value' and `:post-blank'
991 keywords."
995 ;; First type of comment: comments at column 0.
1005 ;; Second type of comment: indented comments.
1013 ;; Get comments ending. This may not be accurate if
1014 ;; commented lines within an item are followed by commented
1015 ;; lines outside of the list. Though, parser will always
1016 ;; get it right as it already knows surrounding element and
1017 ;; has narrowed buffer to its contents.
1020 ;; Find position after blank.
1032 "Interpret COMMENT element as Org syntax.
1033 CONTENTS is nil."
1037 ;;;; Comment Block
1040 "Parse an export block.
1042 Return a list whose CAR is `comment-block' and CDR is a plist
1043 containing `:begin', `:end', `:hiddenp', `:value' and
1044 `:post-blank' keywords."
1070 "Interpret COMMENT-BLOCK element as Org syntax.
1071 CONTENTS is nil."
1076 ;;;; Example Block
1079 "Parse an example block.
1081 Return a list whose CAR is `example-block' and CDR is a plist
1082 containing `:begin', `:end', `:number-lines', `:preserve-indent',
1083 `:retain-labels', `:use-labels', `:label-fmt', `:hiddenp',
1084 `:switches', `:value' and `:post-blank' keywords."
1092 ;; Switches analysis
1097 ;; Should labels be retained in (or stripped from) example
1098 ;; blocks?
1103 ;; What should code-references use - labels or
1104 ;; line-numbers?
1111 ;; Standard block parsing.
1138 "Interpret EXAMPLE-BLOCK element as Org syntax.
1139 CONTENTS is nil."
1147 ;;;; Export Block
1150 "Parse an export block.
1152 Return a list whose CAR is `export-block' and CDR is a plist
1153 containing `:begin', `:end', `:type', `:hiddenp', `:value' and
1154 `:post-blank' keywords."
1184 "Interpret EXPORT-BLOCK element as Org syntax.
1185 CONTENTS is nil."
1192 ;;;; Fixed-width
1195 "Parse a fixed-width section.
1197 Return a list whose CAR is `fixed-width' and CDR is a plist
1198 containing `:begin', `:end', `:value' and `:post-blank'
1199 keywords."
1201 beg-area begin end value pos-before-blank keywords)
1203 ;; Move to the beginning of the fixed-width area.
1209 ;; Get affiliated keywords, if any.
1211 ;; Store true beginning of element.
1213 ;; Get ending of fixed-width area. If point is in a list,
1214 ;; ensure to not get outside of it.
1223 ;; Find position after blank
1226 ;; Extract value.
1236 "Interpret FIXED-WIDTH element as Org syntax.
1237 CONTENTS is nil."
1241 ;;;; Horizontal Rule
1244 "Parse an horizontal rule.
1246 Return a list whose CAR is `horizontal-rule' and CDR is
1247 a plist containing `:begin', `:end' and `:post-blank'
1248 keywords."
1262 "Interpret HORIZONTAL-RULE element as Org syntax.
1263 CONTENTS is nil."
1267 ;;;; Keyword
1270 "Parse a keyword at point.
1272 Return a list whose CAR is `keyword' and CDR is a plist
1273 containing `:key', `:value', `:begin', `:end' and `:post-blank'
1274 keywords."
1293 "Interpret KEYWORD element as Org syntax.
1294 CONTENTS is nil."
1300 ;;;; Latex Environment
1303 "Parse a LaTeX environment.
1305 Return a list whose CAR is `latex-environment' and CDR is a plist
1306 containing `:begin', `:end', `:value' and `:post-blank'
1307 keywords."
1328 "Interpret LATEX-ENVIRONMENT element as Org syntax.
1329 CONTENTS is nil."
1333 ;;;; Paragraph
1336 "Parse a paragraph.
1338 Return a list whose CAR is `paragraph' and CDR is a plist
1339 containing `:begin', `:end', `:contents-begin' and
1340 `:contents-end' and `:post-blank' keywords.
1342 Assume point is at the beginning of the paragraph."
1365 "Interpret PARAGRAPH element as Org syntax.
1366 CONTENTS is the contents of the element."
1367 contents)
1370 ;;;; Planning
1373 "Parse a planning.
1375 Return a list whose CAR is `planning' and CDR is a plist
1376 containing `:closed', `:deadline', `:scheduled', `:begin', `:end'
1377 and `:post-blank' keywords."
1386 closed deadline scheduled)
1406 "Interpret PLANNING element as Org syntax.
1407 CONTENTS is nil."
1409 'identity
1420 ;;;; Property Drawer
1423 "Parse a property drawer.
1425 Return a list whose CAR is `property-drawer' and CDR is a plist
1426 containing `:begin', `:end', `:hiddenp', `:contents-begin',
1427 `:contents-end', `:properties' and `:post-blank' keywords."
1444 val))
1446 val))
1460 "Interpret PROPERTY-DRAWER element as Org syntax.
1461 CONTENTS is nil."
1471 ;;;; Quote Section
1474 "Parse a quote section.
1476 Return a list whose CAR is `quote-section' and CDR is a plist
1477 containing `:begin', `:end', `:value' and `:post-blank' keywords.
1479 Assume point is at beginning of the section."
1495 "Interpret QUOTE-SECTION element as Org syntax.
1496 CONTENTS is nil."
1500 ;;;; Src Block
1503 "Parse a src block.
1505 Return a list whose CAR is `src-block' and CDR is a plist
1506 containing `:language', `:switches', `:parameters', `:begin',
1507 `:end', `:hiddenp', `:contents-begin', `:contents-end',
1508 `:number-lines', `:retain-labels', `:use-labels', `:label-fmt',
1509 `:preserve-indent', `:value' and `:post-blank' keywords."
1513 ;; Get position at beginning of block.
1521 nil t))
1522 ;; Get language as a string.
1524 ;; Get parameters.
1526 ;; Get switches.
1528 ;; Switches analysis
1536 ;; Should labels be retained in (or stripped from) src
1537 ;; blocks?
1542 ;; What should code-references use - labels or
1543 ;; line-numbers?
1547 ;; Get affiliated keywords.
1549 ;; Get beginning position.
1551 ;; Get position at end of block.
1555 ;; Retrieve code.
1561 ;; Get position after ending blank lines.
1564 ;; Get visibility status.
1585 "Interpret SRC-BLOCK element as Org syntax.
1586 CONTENTS is nil."
1606 value
1610 ;;;; Table
1613 "Parse a table at point.
1615 Return a list whose CAR is `table' and CDR is a plist containing
1616 `:begin', `:end', `:tblfm', `:type', `:contents-begin',
1617 `:contents-end', `:value' and `:post-blank' keywords."
1636 ;; Only `org' tables have contents. `table.el'
1637 ;; tables use a `:value' property to store raw
1638 ;; table as a string.
1643 table-begin table-end))
1648 "Interpret TABLE element as Org syntax.
1649 CONTENTS is nil."
1659 ;;;; Table Row
1662 "Parse table row at point.
1664 Return a list whose CAR is `table-row' and CDR is a plist
1665 containing `:begin', `:end', `:contents-begin', `:contents-end',
1666 `:type' and `:post-blank' keywords."
1670 ;; A table rule has no contents. In that case, ensure
1671 ;; CONTENTS-BEGIN matches CONTENTS-END.
1690 "Interpret TABLE-ROW element as Org syntax.
1691 CONTENTS is the contents of the table row."
1696 ;;;; Verse Block
1699 "Parse a verse block.
1701 Return a list whose CAR is `verse-block' and CDR is a plist
1702 containing `:begin', `:end', `:contents-begin', `:contents-end',
1703 `:hiddenp' and `:post-blank' keywords.
1705 Assume point is at beginning of the block."
1729 "Interpret VERSE-BLOCK element as Org syntax.
1730 CONTENTS is verse block contents."
1734 \f
1735 ;;; Objects
1736 ;;
1737 ;; Unlike to elements, interstices can be found between objects.
1738 ;; That's why, along with the parser, successor functions are provided
1739 ;; for each object. Some objects share the same successor (i.e. `code'
1740 ;; and `verbatim' objects).
1741 ;;
1742 ;; A successor must accept a single argument bounding the search. It
1743 ;; will return either a cons cell whose CAR is the object's type, as
1744 ;; a symbol, and CDR the position of its next occurrence, or nil.
1745 ;;
1746 ;; Successors follow the naming convention:
1747 ;; org-element-NAME-successor, where NAME is the name of the
1748 ;; successor, as defined in `org-element-all-successors'.
1749 ;;
1750 ;; Some object types (i.e. `emphasis') are recursive. Restrictions on
1751 ;; object types they can contain will be specified in
1752 ;; `org-element-object-restrictions'.
1753 ;;
1754 ;; Adding a new type of object is simple. Implement a successor,
1755 ;; a parser, and an interpreter for it, all following the naming
1756 ;; convention. Register type in `org-element-all-objects' and
1757 ;; successor in `org-element-all-successors'. Maybe tweak
1758 ;; restrictions about it, and that's it.
1761 ;;;; Bold
1764 "Parse bold object at point.
1766 Return a list whose CAR is `bold' and CDR is a plist with
1767 `:begin', `:end', `:contents-begin' and `:contents-end' and
1768 `:post-blank' keywords.
1770 Assume point is at the first star marker."
1788 "Interpret BOLD object as Org syntax.
1789 CONTENTS is the contents of the object."
1793 "Search for the next text-markup object.
1795 LIMIT bounds the search.
1797 Return value is a cons cell whose CAR is a symbol among `bold',
1798 `italic', `underline', `strike-through', `code' and `verbatim'
1799 and CDR is beginning position."
1815 ;;;; Code
1818 "Parse code object at point.
1820 Return a list whose CAR is `code' and CDR is a plist with
1821 `:value', `:begin', `:end' and `:post-blank' keywords.
1823 Assume point is at the first tilde marker."
1839 "Interpret CODE object as Org syntax.
1840 CONTENTS is nil."
1844 ;;;; Entity
1847 "Parse entity at point.
1849 Return a list whose CAR is `entity' and CDR a plist with
1850 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
1851 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
1852 keywords.
1854 Assume point is at the beginning of the entity."
1878 "Interpret ENTITY object as Org syntax.
1879 CONTENTS is nil."
1885 "Search for the next latex-fragment or entity object.
1887 LIMIT bounds the search.
1889 Return value is a cons cell whose CAR is `entity' or
1890 `latex-fragment' and CDR is beginning position."
1893 ;; ENTITY-RE matches both LaTeX commands and Org entities.
1900 limit t)
1903 ;; Determine if it's a real entity or a LaTeX command.
1906 ;; No entity nor command: point is at a LaTeX fragment.
1907 ;; Determine its type to get the correct beginning position.
1915 matchers)
1919 ;;;; Export Snippet
1922 "Parse export snippet at point.
1924 Return a list whose CAR is `export-snippet' and CDR a plist with
1925 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
1926 keywords.
1928 Assume point is at the beginning of the snippet."
1950 "Interpret EXPORT-SNIPPET object as Org syntax.
1951 CONTENTS is nil."
1957 "Search for the next export-snippet object.
1959 LIMIT bounds the search.
1961 Return value is a cons cell whose CAR is `export-snippet' CDR is
1962 its beginning position."
1975 ;;;; Footnote Reference
1978 "Parse footnote reference at point.
1980 Return a list whose CAR is `footnote-reference' and CDR a plist
1981 with `:label', `:type', `:inline-definition', `:begin', `:end'
1982 and `:post-blank' as keywords."
2015 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
2016 CONTENTS is nil."
2026 "Search for the next footnote-reference object.
2028 LIMIT bounds the search.
2030 Return value is a cons cell whose CAR is `footnote-reference' and
2031 CDR is beginning position."
2045 ;;;; Inline Babel Call
2048 "Parse inline babel call at point.
2050 Return a list whose CAR is `inline-babel-call' and CDR a plist
2051 with `:begin', `:end', `:info' and `:post-blank' as keywords.
2053 Assume point is at the beginning of the babel call."
2069 "Interpret INLINE-BABEL-CALL object as Org syntax.
2070 CONTENTS is nil."
2076 ;; Remove redundant square brackets.
2079 main-source)
2083 "Search for the next inline-babel-call object.
2085 LIMIT bounds the search.
2087 Return value is a cons cell whose CAR is `inline-babel-call' and
2088 CDR is beginning position."
2090 ;; Use a simplified version of
2091 ;; org-babel-inline-lob-one-liner-regexp as regexp for more speed.
2093 "\\(?:babel\\|call\\)_\\([^()\n]+?\\)\\(\\[\\(.*\\)\\]\\|\\(\\)\\)(\\([^\n]*\\))\\(\\[\\(.*?\\)\\]\\)?"
2094 limit t)
2098 ;;;; Inline Src Block
2101 "Parse inline source block at point.
2103 Return a list whose CAR is `inline-src-block' and CDR a plist
2104 with `:begin', `:end', `:language', `:value', `:parameters' and
2105 `:post-blank' as keywords.
2107 Assume point is at the beginning of the inline src block."
2127 "Interpret INLINE-SRC-BLOCK object as Org syntax.
2128 CONTENTS is nil."
2133 language
2135 body)))
2138 "Search for the next inline-babel-call element.
2140 LIMIT bounds the search.
2142 Return value is a cons cell whose CAR is `inline-babel-call' and
2143 CDR is beginning position."
2148 ;;;; Italic
2151 "Parse italic object at point.
2153 Return a list whose CAR is `italic' and CDR is a plist with
2154 `:begin', `:end', `:contents-begin' and `:contents-end' and
2155 `:post-blank' keywords.
2157 Assume point is at the first slash marker."
2175 "Interpret ITALIC object as Org syntax.
2176 CONTENTS is the contents of the object."
2180 ;;;; Latex Fragment
2183 "Parse latex fragment at point.
2185 Return a list whose CAR is `latex-fragment' and CDR a plist with
2186 `:value', `:begin', `:end', and `:post-blank' as keywords.
2188 Assume point is at the beginning of the latex fragment."
2202 ;; None found: it's a macro.
2216 "Interpret LATEX-FRAGMENT object as Org syntax.
2217 CONTENTS is nil."
2220 ;;;; Line Break
2223 "Parse line break at point.
2225 Return a list whose CAR is `line-break', and CDR a plist with
2226 `:begin', `:end' and `:post-blank' keywords.
2228 Assume point is at the beginning of the line break."
2234 "Interpret LINE-BREAK object as Org syntax.
2235 CONTENTS is nil."
2239 "Search for the next line-break object.
2241 LIMIT bounds the search.
2243 Return value is a cons cell whose CAR is `line-break' and CDR is
2244 beginning position."
2248 ;; A line break can only happen on a non-empty line.
2253 ;;;; Link
2256 "Parse link at point.
2258 Return a list whose CAR is `link' and CDR a plist with `:type',
2259 `:path', `:raw-link', `:begin', `:end', `:contents-begin',
2260 `:contents-end' and `:post-blank' as keywords.
2262 Assume point is at the beginning of the link."
2265 end contents-begin contents-end link-end post-blank path type
2266 raw-link link)
2268 ;; Type 1: Text targeted from a radio target.
2273 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
2278 ;; RAW-LINK is the original link.
2283 ;; Determine TYPE of link and set PATH accordingly.
2285 ;; File type.
2288 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
2291 ;; Id type: PATH is the id.
2294 ;; Code-ref type: PATH is the name of the reference.
2297 ;; Custom-id type: PATH is the name of the custom id.
2300 ;; Fuzzy type: Internal link either matches a target, an
2301 ;; headline name or nothing. PATH is the target or headline's
2302 ;; name.
2304 ;; Type 3: Plain link, i.e. http://orgmode.org
2310 ;; Type 4: Angular link, i.e. <http://orgmode.org>
2317 ;; In any case, deduce end point after trailing white space from
2318 ;; LINK-END variable.
2332 "Interpret LINK object as Org syntax.
2333 CONTENTS is the contents of the object, or nil."
2338 raw-link
2342 "Search for the next link object.
2344 LIMIT bounds the search.
2346 Return value is a cons cell whose CAR is `link' and CDR is
2347 beginning position."
2356 ;;;; Macro
2359 "Parse macro at point.
2361 Return a list whose CAR is `macro' and CDR a plist with `:key',
2362 `:args', `:begin', `:end', `:value' and `:post-blank' as
2363 keywords.
2365 Assume point is at the macro."
2379 ;; Repair bad splits.
2394 "Interpret MACRO object as Org syntax.
2395 CONTENTS is nil."
2399 "Search for the next macro object.
2401 LIMIT bounds the search.
2403 Return value is cons cell whose CAR is `macro' and CDR is
2404 beginning position."
2408 limit t)
2412 ;;;; Radio-target
2415 "Parse radio target at point.
2417 Return a list whose CAR is `radio-target' and CDR a plist with
2418 `:begin', `:end', `:contents-begin', `:contents-end', `:value'
2419 and `:post-blank' as keywords.
2421 Assume point is at the radio target."
2440 "Interpret TARGET object as Org syntax.
2441 CONTENTS is the contents of the object."
2445 "Search for the next radio-target object.
2447 LIMIT bounds the search.
2449 Return value is a cons cell whose CAR is `radio-target' and CDR
2450 is beginning position."
2456 ;;;; Statistics Cookie
2459 "Parse statistics cookie at point.
2461 Return a list whose CAR is `statistics-cookie', and CDR a plist
2462 with `:begin', `:end', `:value' and `:post-blank' keywords.
2464 Assume point is at the beginning of the statistics-cookie."
2480 "Interpret STATISTICS-COOKIE object as Org syntax.
2481 CONTENTS is nil."
2485 "Search for the next statistics cookie object.
2487 LIMIT bounds the search.
2489 Return value is a cons cell whose CAR is `statistics-cookie' and
2490 CDR is beginning position."
2496 ;;;; Strike-Through
2499 "Parse strike-through object at point.
2501 Return a list whose CAR is `strike-through' and CDR is a plist
2502 with `:begin', `:end', `:contents-begin' and `:contents-end' and
2503 `:post-blank' keywords.
2505 Assume point is at the first plus sign marker."
2523 "Interpret STRIKE-THROUGH object as Org syntax.
2524 CONTENTS is the contents of the object."
2528 ;;;; Subscript
2531 "Parse subscript at point.
2533 Return a list whose CAR is `subscript' and CDR a plist with
2534 `:begin', `:end', `:contents-begin', `:contents-end',
2535 `:use-brackets-p' and `:post-blank' as keywords.
2537 Assume point is at the underscore."
2541 t
2559 "Interpret SUBSCRIPT object as Org syntax.
2560 CONTENTS is the contents of the object."
2563 contents))
2566 "Search for the next sub/superscript object.
2568 LIMIT bounds the search.
2570 Return value is a cons cell whose CAR is either `subscript' or
2571 `superscript' and CDR is beginning position."
2578 ;;;; Superscript
2581 "Parse superscript at point.
2583 Return a list whose CAR is `superscript' and CDR a plist with
2584 `:begin', `:end', `:contents-begin', `:contents-end',
2585 `:use-brackets-p' and `:post-blank' as keywords.
2587 Assume point is at the caret."
2608 "Interpret SUPERSCRIPT object as Org syntax.
2609 CONTENTS is the contents of the object."
2612 contents))
2615 ;;;; Table Cell
2618 "Parse table cell at point.
2620 Return a list whose CAR is `table-cell' and CDR is a plist
2621 containing `:begin', `:end', `:contents-begin', `:contents-end'
2622 and `:post-blank' keywords."
2636 "Interpret TABLE-CELL element as Org syntax.
2637 CONTENTS is the contents of the cell, or nil."
2641 "Search for the next table-cell object.
2643 LIMIT bounds the search.
2645 Return value is a cons cell whose CAR is `table-cell' and CDR is
2646 beginning position."
2650 ;;;; Target
2653 "Parse target at point.
2655 Return a list whose CAR is `target' and CDR a plist with
2656 `:begin', `:end', `:value' and `:post-blank' as keywords.
2658 Assume point is at the target."
2673 "Interpret TARGET object as Org syntax.
2674 CONTENTS is nil."
2678 "Search for the next target object.
2680 LIMIT bounds the search.
2682 Return value is a cons cell whose CAR is `target' and CDR is
2683 beginning position."
2689 ;;;; Timestamp
2692 "Parse time stamp at point.
2694 Return a list whose CAR is `timestamp', and CDR a plist with
2695 `:type', `:begin', `:end', `:value' and `:post-blank' keywords.
2697 Assume point is at the beginning of the timestamp."
2723 "Interpret TIMESTAMP object as Org syntax.
2724 CONTENTS is nil."
2728 "Search for the next timestamp object.
2730 LIMIT bounds the search.
2732 Return value is a cons cell whose CAR is `timestamp' and CDR is
2733 beginning position."
2741 limit t)
2745 ;;;; Underline
2748 "Parse underline object at point.
2750 Return a list whose CAR is `underline' and CDR is a plist with
2751 `:begin', `:end', `:contents-begin' and `:contents-end' and
2752 `:post-blank' keywords.
2754 Assume point is at the first underscore marker."
2772 "Interpret UNDERLINE object as Org syntax.
2773 CONTENTS is the contents of the object."
2777 ;;;; Verbatim
2780 "Parse verbatim object at point.
2782 Return a list whose CAR is `verbatim' and CDR is a plist with
2783 `:value', `:begin', `:end' and `:post-blank' keywords.
2785 Assume point is at the first equal sign marker."
2801 "Interpret VERBATIM object as Org syntax.
2802 CONTENTS is nil."
2806 \f
2807 ;;; Definitions And Rules
2809 ;; Define elements, greater elements and specify recursive objects,
2810 ;; along with the affiliated keywords recognized. Also set up
2811 ;; restrictions on recursive objects combinations.
2813 ;; These variables really act as a control center for the parsing
2814 ;; process.
2817 ;; Headlines and inlinetasks.
2819 ;; Comments, blocks (any type), keywords and babel calls.
2821 ;; Lists.
2823 ;; Fixed-width, drawers (any type) and tables.
2825 ;; Footnote definitions.
2827 ;; Horizontal rules.
2829 ;; LaTeX environments.
2831 ;; Planning and Clock lines.
2841 export-block fixed-width footnote-definition headline
2842 horizontal-rule inlinetask item keyword latex-environment
2843 babel-call paragraph plain-list planning property-drawer
2844 quote-block quote-section section special-block src-block table
2845 table-row verse-block)
2850 item plain-list quote-block section special-block table)
2855 latex-or-entity line-break link macro radio-target
2856 statistics-cookie sub/superscript table-cell target
2857 text-markup timestamp)
2866 "Alist of translations between object type and successor name.
2868 Sharing the same successor comes handy when, for example, the
2873 inline-src-block italic line-break latex-fragment link macro
2874 radio-target statistics-cookie strike-through subscript superscript
2875 table-cell target timestamp underline verbatim)
2880 table-cell underline)
2905 "Alist of usual translations for keywords.
2906 The key is the old name and the value the new one. The property
2911 "List of affiliated keywords that can occur more that once in an element.
2913 Their value will be consed into a list of strings, which will be
2914 returned as the value of the property.
2916 This list is checked after translations have been applied. See
2920 "List of keywords whose value can be parsed.
2922 Their value will be stored as a secondary string: a list of
2923 strings and objects.
2925 This list is checked after translations have been applied. See
2929 "List of keywords which can have a secondary value.
2931 In Org syntax, they can be written with optional square brackets
2932 before the colons. For example, results keyword can be
2933 associated to a hash value with the following:
2935 #+RESULTS[hash-string]: some-source
2937 This list is checked after translations have been applied. See
2944 inline-babel-call inline-src-block latex-fragment
2945 line-break link macro radio-target sub/superscript
2946 target text-markup timestamp)
2948 macro radio-target statistics-cookie sub/superscript text-markup
2949 timestamp)
2963 link radio-target sub/superscript target text-markup
2964 timestamp)
2975 latex-fragment line-break link macro radio-target
2977 "Alist of objects restrictions.
2979 CAR is an element or object type containing objects and CDR is
2980 a list of successors that will be called within an element or
2981 object of such type.
2983 For example, in a `radio-target' object, one can only find
2984 entities, export snippets, latex-fragments, subscript and
2985 superscript.
2987 This alist also applies to secondary string. For example, an
2988 `headline' type element doesn't directly contain objects, but
2999 \f
3000 ;;; Accessors
3001 ;;
3002 ;; Provide four accessors: `org-element-type', `org-element-property'
3003 ;; `org-element-contents' and `org-element-restriction'.
3006 "Return type of element ELEMENT.
3008 The function returns the type of the element or object provided.
3009 It can also return the following special value:
3010 `plain-text' for a string
3011 `org-data' for a complete document
3012 nil in any other case."
3018 "Extract the value from the PROPERTY of an ELEMENT."
3022 "Extract contents from an ELEMENT."
3026 "Return restriction associated to ELEMENT.
3027 ELEMENT can be an element, an object or a symbol representing an
3028 element or object type."
3030 org-element-object-restrictions)))
3033 \f
3034 ;;; Parsing Element Starting At Point
3035 ;;
3036 ;; `org-element-current-element' is the core function of this section.
3037 ;; It returns the Lisp representation of the element starting at
3038 ;; point. It uses `org-element--element-block-re' for quick access to
3039 ;; a common regexp.
3040 ;;
3041 ;; `org-element-current-element' makes use of special modes. They are
3042 ;; activated for fixed element chaining (i.e. `plain-list' > `item')
3043 ;; or fixed conditional element chaining (i.e. `headline' >
3044 ;; `section'). Special modes are: `section', `quote-section', `item'
3045 ;; and `table-row'.
3050 'regexp-quote
3052 "Regexp matching the beginning of a non-recursive block type.
3056 "Parse the element starting at point.
3058 Return value is a list like (TYPE PROPS) where TYPE is the type
3059 of the element and PROPS a plist of properties associated to the
3060 element.
3062 Possible types are defined in `org-element-all-elements'.
3064 Optional argument GRANULARITY determines the depth of the
3065 recursion. Allowed values are `headline', `greater-element',
3066 `element', `object' or nil. When it is broader than `object' (or
3067 nil), secondary values will not be parsed, since they only
3068 contain objects.
3070 Optional argument SPECIAL, when non-nil, can be either `section',
3071 `quote-section', `table-row' and `item'.
3073 If STRUCTURE isn't provided but SPECIAL is set to `item', it will
3074 be computed.
3076 Unlike to `org-element-at-point', this function assumes point is
3077 always at the beginning of the element it has to parse. As such,
3078 it is quicker than its counterpart, albeit more restrictive."
3080 ;; If point is at an affiliated keyword, try moving to the
3081 ;; beginning of the associated element. If none is found, the
3082 ;; keyword is orphaned and will be treated as plain text.
3088 ;; Determine if parsing depth allows for secondary strings
3089 ;; parsing. It only applies to elements referenced in
3090 ;; `org-element-secondary-value-alist'.
3093 ;; Item
3096 raw-secondary-p))
3097 ;; Quote Section.
3099 ;; Table Row.
3101 ;; Headline.
3104 ;; Section (must be checked after headline).
3106 ;; Planning and Clock.
3111 ;; Non-recursive block.
3120 "org-element-%s-parser"
3123 ;; Inlinetask.
3125 ;; LaTeX Environment or Paragraph if incomplete.
3131 ;; Property Drawer.
3136 ;; Recursive Block, or Paragraph if incomplete.
3147 ;; Drawer.
3153 ;; Babel Call.
3156 ;; Dynamic Block or Paragraph if incomplete. This must be
3157 ;; checked before regular keywords since their regexp matches
3158 ;; dynamic blocks too.
3164 ;; Keyword, or Paragraph if at an orphaned affiliated keyword.
3171 ;; Footnote definition.
3174 ;; Comment.
3177 ;; Horizontal Rule.
3180 ;; Table.
3182 ;; List or Item.
3185 ;; Default element: Paragraph.
3189 ;; Most elements can have affiliated keywords. When looking for an
3190 ;; element beginning, we want to move before them, as they belong to
3191 ;; that element, and, in the meantime, collect information they give
3192 ;; into appropriate properties. Hence the following function.
3194 ;; Usage of optional arguments may not be obvious at first glance:
3196 ;; - TRANS-LIST is used to polish keywords names that have evolved
3197 ;; during Org history. In example, even though =result= and
3198 ;; =results= coexist, we want to have them under the same =result=
3199 ;; property. It's also true for "srcname" and "name", where the
3200 ;; latter seems to be preferred nowadays (thus the "name" property).
3202 ;; - CONSED allows to regroup multi-lines keywords under the same
3203 ;; property, while preserving their own identity. This is mostly
3204 ;; used for "attr_latex" and al.
3206 ;; - PARSED prepares a keyword value for export. This is useful for
3207 ;; "caption". Objects restrictions for such keywords are defined in
3208 ;; `org-element-object-restrictions'.
3210 ;; - DUALS is used to take care of keywords accepting a main and an
3211 ;; optional secondary values. For example "results" has its
3212 ;; source's name as the main value, and may have an hash string in
3213 ;; optional square brackets as the secondary one.
3215 ;; A keyword may belong to more than one category.
3226 "Regexp matching any affiliated keyword.
3228 Keyword name is put in match group 1. Moreover, if keyword
3229 belongs to `org-element-dual-keywords', put the dual value in
3230 match group 2.
3235 consed parsed duals)
3236 "Collect affiliated keywords before point.
3238 Optional argument KEY-RE is a regexp matching keywords, which
3239 puts matched keyword in group 1. It defaults to
3240 `org-element--affiliated-re'.
3242 TRANS-LIST is an alist where key is the keyword and value the
3243 property name it should be translated to, without the colons. It
3244 defaults to `org-element-keyword-translation-alist'.
3246 CONSED is a list of strings. Any keyword belonging to that list
3247 will have its value consed. The check is done after keyword
3248 translation. It defaults to `org-element-multiple-keywords'.
3250 PARSED is a list of strings. Any keyword member of this list
3251 will have its value parsed. The check is done after keyword
3252 translation. If a keyword is a member of both CONSED and PARSED,
3253 it's value will be a list of parsed strings. It defaults to
3254 `org-element-parsed-keywords'.
3256 DUALS is a list of strings. Any keyword member of this list can
3257 have two parts: one mandatory and one optional. Its value is
3258 a cons cell whose car is the former, and the cdr the latter. If
3259 a keyword is a member of both PARSED and DUALS, both values will
3260 be parsed. It defaults to `org-element-dual-keywords'.
3262 Return a list whose car is the position at the first of them and
3263 cdr a plist of keywords and values."
3271 ;; RESTRICT is the list of objects allowed in parsed
3272 ;; keywords value.
3274 output)
3279 ;; Apply translation to RAW-KWD. From there, KWD is
3280 ;; the official keyword.
3282 ;; Find main value for any keyword.
3288 ;; If KWD is a dual keyword, find its secondary
3289 ;; value. Maybe parse it.
3295 ;; Attribute a property name to KWD.
3297 ;; Now set final shape for VALUE.
3301 ;; VALUE is mandatory. Set it to nil if there is none.
3305 ;; Eventually store the new value in OUTPUT.
3311 \f
3312 ;;; The Org Parser
3314 ;; The two major functions here are `org-element-parse-buffer', which
3315 ;; parses Org syntax inside the current buffer, taking into account
3316 ;; region, narrowing, or even visibility if specified, and
3317 ;; `org-element-parse-secondary-string', which parses objects within
3318 ;; a given string.
3320 ;; The (almost) almighty `org-element-map' allows to apply a function
3321 ;; on elements or objects matching some type, and accumulate the
3322 ;; resulting values. In an export situation, it also skips unneeded
3323 ;; parts of the parse tree.
3326 "Recursively parse the buffer and return structure.
3327 If narrowing is in effect, only parse the visible part of the
3328 buffer.
3330 Optional argument GRANULARITY determines the depth of the
3331 recursion. It can be set to the following symbols:
3333 `headline' Only parse headlines.
3334 `greater-element' Don't recurse into greater elements excepted
3335 headlines and sections. Thus, elements
3336 parsed are the top-level ones.
3337 `element' Parse everything but objects and plain text.
3338 `object' Parse the complete buffer (default).
3340 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3341 elements.
3343 Assume buffer is in Org mode."
3350 ;; Start in `section' mode so text before the first
3351 ;; headline belongs to a section.
3355 "Recursively parse objects in STRING and return structure.
3357 RESTRICTION, when non-nil, is a symbol limiting the object types
3358 that will be looked after."
3364 "Map a function on selected elements or objects.
3366 DATA is the parsed tree, as returned by, i.e,
3367 `org-element-parse-buffer'. TYPES is a symbol or list of symbols
3368 of elements or objects types. FUN is the function called on the
3369 matching element or object. It must accept one arguments: the
3370 element or object itself.
3372 When optional argument INFO is non-nil, it should be a plist
3373 holding export options. In that case, parts of the parse tree
3374 not exportable according to that property list will be skipped.
3376 When optional argument FIRST-MATCH is non-nil, stop at the first
3377 match for which FUN doesn't return nil, and return that value.
3379 Optional argument NO-RECURSION is a symbol or a list of symbols
3380 representing elements or objects types. `org-element-map' won't
3381 enter any recursive element or object whose type belongs to that
3382 list. Though, FUN can still be applied on them.
3384 Nil values returned from FUN do not appear in the results."
3385 ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
3388 ;; Recursion depth is determined by --CATEGORY.
3398 ;; --RESTRICTS is a list of element types whose secondary
3399 ;; string could possibly contain an object with a type among
3400 ;; TYPES.
3404 when
3408 --acc
3412 ;; Recursively walk DATA. INFO, if non-nil, is
3413 ;; a plist holding contextual information.
3418 ;; Check if TYPE is matching among TYPES. If so,
3419 ;; apply FUN to --BLOB and accumulate return value
3420 ;; into --ACC (or exit if FIRST-MATCH is non-nil).
3426 ;; If --BLOB has a secondary string that can
3427 ;; contain objects with their type among TYPES,
3428 ;; look into that string.
3431 --walk-tree
3433 nil
3436 --blob))))
3437 ;; Now determine if a recursion into --BLOB is
3438 ;; possible. If so, do it.
3449 ;; Return value in a proper order.
3452 ;; The following functions are internal parts of the parser.
3454 ;; The first one, `org-element-parse-elements' acts at the element's
3455 ;; level.
3457 ;; The second one, `org-element-parse-objects' applies on all objects
3458 ;; of a paragraph or a secondary string. It uses
3459 ;; `org-element-get-candidates' to optimize the search of the next
3460 ;; object in the buffer.
3462 ;; More precisely, that function looks for every allowed object type
3463 ;; first. Then, it discards failed searches, keeps further matches,
3464 ;; and searches again types matched behind point, for subsequent
3465 ;; calls. Thus, searching for a given type fails only once, and every
3466 ;; object is searched only once at top level (but sometimes more for
3467 ;; nested types).
3471 "Parse elements between BEG and END positions.
3473 SPECIAL prioritize some elements over the others. It can be set
3474 to `quote-section', `section' `item' or `table-row'.
3476 When value is `item', STRUCTURE will be used as the current list
3477 structure.
3479 GRANULARITY determines the depth of the recursion. See
3480 `org-element-parse-buffer' for more information.
3482 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3483 elements.
3485 Elements are accumulated into ACC."
3490 ;; When parsing only headlines, skip any text before first one.
3493 ;; Main loop start.
3496 ;; Find current element's type and parse it accordingly to
3497 ;; its category.
3499 granularity special structure))
3504 ;; Case 1. Simply accumulate element if VISIBLE-ONLY is
3505 ;; true and element is hidden or if it has no contents
3506 ;; anyway.
3509 ;; Case 2. Greater element: parse it between
3510 ;; `contents-begin' and `contents-end'. Make sure
3511 ;; GRANULARITY allows the recursion, or ELEMENT is an
3512 ;; headline, in which case going inside is mandatory, in
3513 ;; order to get sub-level headings.
3521 ;; Possibly switch to a special mode.
3530 ;; Case 3. ELEMENT has contents. Parse objects inside,
3531 ;; if GRANULARITY allows it.
3536 ;; Case 4. Else, just accumulate ELEMENT.
3538 acc)))
3539 ;; Return result.
3543 "Parse objects between BEG and END and return recursive structure.
3545 Objects are accumulated in ACC.
3547 RESTRICTION is a list of object types which are allowed in the
3548 current object."
3552 ;; Return the parsing function associated to the nearest
3553 ;; object among list of candidates CAND.
3560 next-object candidates)
3564 end restriction candidates))
3566 ;; 1. Text before any object. Untabify it.
3572 acc)))
3573 ;; 2. Object...
3577 cont-beg)
3578 ;; ... recursive. The CONT-BEG check is for
3579 ;; links, as some of them might not be recursive
3580 ;; (i.e. plain links).
3583 cont-beg
3588 ;; Restrict allowed objects.
3590 ;; ... not recursive. Accumulate the object.
3591 next-object)
3592 acc)
3594 ;; 3. Text after last object. Untabify it.
3599 acc))
3600 ;; Result.
3604 "Return an alist of candidates for the next object.
3606 LIMIT bounds the search, and RESTRICTION narrows candidates to
3607 some object types.
3609 Return value is an alist whose CAR is position and CDR the object
3610 type, as a symbol.
3612 OBJECTS is the previous candidates alist."
3614 ;; If no previous result, search every object type in RESTRICTION.
3615 ;; Otherwise, keep potential candidates (old objects located after
3616 ;; point) and ask to search again those which had matched before.
3621 objects))
3622 ;; Call the appropriate successor function for each type to search
3623 ;; and accumulate matches.
3630 type))))
3633 types-to-search)
3634 ;; Return alist.
3635 next-candidates))
3638 \f
3639 ;;; Towards A Bijective Process
3641 ;; The parse tree obtained with `org-element-parse-buffer' is really
3642 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
3643 ;; interpreted and expanded into a string with canonical Org
3644 ;; syntax. Hence `org-element-interpret-data'.
3645 ;;
3646 ;; Data parsed from secondary strings, whose shape is slightly
3647 ;; different than the standard parse tree, is expanded with the
3648 ;; equivalent function `org-element-interpret-secondary'.
3649 ;;
3650 ;; Both functions rely internally on
3651 ;; `org-element-interpret--affiliated-keywords'.
3654 "Interpret a parse tree representing Org data.
3656 DATA is the parse tree to interpret.
3658 Optional arguments GENEALOGY and PREVIOUS are used for recursive
3659 calls:
3660 GENEALOGY is the list of its parents types.
3661 PREVIOUS is the type of the element or object at the same level
3662 interpreted before.
3664 Return Org syntax as a string."
3667 ;; BLOB can be an element, an object, a string, or nil.
3679 ;; Elements or objects without contents.
3681 ;; Full Org document.
3684 ;; Greater elements.
3690 blob
3691 ;; When normalizing first paragraph of an item or
3692 ;; a footnote-definition, ignore first line's
3693 ;; indentation.
3699 ;; Update PREVIOUS.
3701 ;; Build white spaces. If no `:post-blank' property is
3702 ;; specified, assume its value is 0.
3715 "Interpret SECONDARY string as Org syntax.
3717 SECONDARY-STRING is a nested list as returned by
3718 `org-element-parse-secondary-string'.
3720 Return interpreted string."
3721 ;; Make SECONDARY acceptable for `org-element-interpret-data'.
3725 ;; Both functions internally use `org-element--affiliated-keywords'.
3728 "Return ELEMENT's affiliated keywords as Org syntax.
3729 If there is no affiliated keyword, return the empty string."
3740 ": "
3743 value)
3748 element)))
3755 ;; Remove translated keywords.
3760 org-element-affiliated-keywords))
3763 ;; Because interpretation of the parse tree must return the same
3764 ;; number of blank lines between elements and the same number of white
3765 ;; space after objects, some special care must be given to white
3766 ;; spaces.
3767 ;;
3768 ;; The first function, `org-element-normalize-string', ensures any
3769 ;; string different from the empty string will end with a single
3770 ;; newline character.
3771 ;;
3772 ;; The second function, `org-element-normalize-contents', removes
3773 ;; global indentation from the contents of the current element.
3776 "Ensure string S ends with a single newline character.
3778 If S isn't a string return it unchanged. If S is the empty
3779 string, return it. Otherwise, return a new string with a single
3780 newline character at its end."
3788 "Normalize plain text in ELEMENT's contents.
3790 ELEMENT must only contain plain text and objects.
3792 If optional argument IGNORE-FIRST is non-nil, ignore first line's
3793 indentation to compute maximal common indentation.
3795 Return the normalized element that is element with global
3796 indentation removed from its contents. The function assumes that
3797 indentation is not done with TAB characters."
3801 ;; Return list of indentations within BLOB. This is done by
3802 ;; walking recursively BLOB and updating IND-LIST along the
3803 ;; way. FIRST-FLAG is non-nil when the first string hasn't
3804 ;; been seen yet. It is required as this string is the only
3805 ;; one whose indentation doesn't happen after a newline
3806 ;; character.
3814 ;; An indentation of zero means no string will be
3815 ;; modified. Quit the process.
3821 ;; Avoid matching blank or empty lines.
3829 ;; Collect indentation list in ELEMENT. Possibly remove first
3830 ;; value if IGNORE-FIRST is non-nil.
3833 ;; Build ELEMENT back, replacing each string with the same
3834 ;; string minus common indentation.
3838 ;; Return BLOB with all its strings indentation
3839 ;; shortened from MCI white spaces. FIRST-FLAG is
3840 ;; non-nil when the first string hasn't been seen
3841 ;; yet.
3856 org-element-recursive-objects)
3863 \f
3864 ;;; The Toolbox
3866 ;; The first move is to implement a way to obtain the smallest element
3867 ;; containing point. This is the job of `org-element-at-point'. It
3868 ;; basically jumps back to the beginning of section containing point
3869 ;; and moves, element after element, with
3870 ;; `org-element-current-element' until the container is found.
3871 ;;
3872 ;; Note: When using `org-element-at-point', secondary values are never
3873 ;; parsed since the function focuses on elements, not on objects.
3876 "Determine closest element around point.
3878 Return value is a list like (TYPE PROPS) where TYPE is the type
3879 of the element and PROPS a plist of properties associated to the
3880 element. Possible types are defined in
3881 `org-element-all-elements'.
3883 As a special case, if point is at the very beginning of a list or
3884 sub-list, returned element will be that list instead of the first
3885 item. In the same way, if point is at the beginning of the first
3886 row of a table, returned element will be the table instead of the
3887 first row.
3889 If optional argument KEEP-TRAIL is non-nil, the function returns
3890 a list of of elements leading to element at point. The list's
3891 CAR is always the element at point. Its last item will be the
3892 element's parent, unless element was either the first in its
3893 section (in which case the last item in the list is the first
3894 element of section) or an headline (in which case the list
3895 contains that headline as its single element). Elements
3896 in-between, if any, are siblings of the element at point."
3898 ;; If at an headline, parse it. It is the sole element that
3899 ;; doesn't require to know about context. Be sure to disallow
3900 ;; secondary string parsing, though.
3904 ;; Otherwise move at the beginning of the section containing
3905 ;; point.
3913 ;; Starting parsing successively each element with
3914 ;; `org-element-current-element'. Skip those ending before
3915 ;; original position.
3923 ;; 1. Skip any element ending before point or at point.
3928 ;; 2. An element containing point is always the element at
3929 ;; point.
3932 ;; 3. At a plain list.
3938 ;; Find the item at this level containing ORIGIN.
3940 parent)
3945 ;; Item ends before point: skip it.
3947 ;; Item contains point: store is in PARENT.
3949 ;; We went too far: return PARENT.
3951 ;; No parent: no item contained point, though the
3952 ;; plain list does. Point is in the blank lines
3953 ;; after the list: return plain list.
3957 ;; 4. At a table.
3968 ;; 4. At any other greater element type, if point is
3969 ;; within contents, move into it. Otherwise, return
3970 ;; that element.
3977 ;; Reset trail, since we found a parent.
3983 ;; Once the local structure around point is well understood, it's easy
3984 ;; to implement some replacements for `forward-paragraph'
3985 ;; `backward-paragraph', namely `org-element-forward' and
3986 ;; `org-element-backward'.
3988 ;; Also, `org-transpose-elements' mimics the behaviour of
3989 ;; `transpose-words', at the element's level, whereas
3990 ;; `org-element-drag-forward', `org-element-drag-backward', and
3991 ;; `org-element-up' generalize, respectively, functions
3992 ;; `org-subtree-down', `org-subtree-up' and `outline-up-heading'.
3994 ;; `org-element-unindent-buffer' will, as its name almost suggests,
3995 ;; smartly remove global indentation from buffer, making it possible
3996 ;; to use Org indent mode on a file created with hard indentation.
3998 ;; `org-element-nested-p' and `org-element-swap-A-B' are used
3999 ;; internally by some of the previously cited tools.
4002 "Non-nil when elements ELEM-A and ELEM-B are nested."
4011 "Swap elements ELEM-A and ELEM-B.
4013 Leave point at the end of ELEM-A."
4035 "Move backward by one element.
4036 Move to the previous element at the same level, when possible."
4043 ;; Move to beginning of current element if point isn't there.
4047 ;; At an headline: move to previous headline at the same
4048 ;; level, a parent, or BOB.
4053 ;; At an item: try to move to the previous item, if any.
4059 ;; In any other case, find the previous element in the
4060 ;; trail and move to its beginning. If no previous element
4061 ;; can be found, move to headline.
4067 "Drag backward element at point."
4084 ;; Compute new position of point: it's shifted by PREV-ELEM
4085 ;; body's length.
4092 "Move forward element at point."
4105 ;; Compute new position of point: it's shifted by NEXT-ELEM
4106 ;; body's length (without final blanks) and by the length of
4107 ;; blanks between ELEM and NEXT-ELEM.
4124 "Move forward by one element.
4125 Move to the next element at the same level, when possible."
4133 ;; At an headline, move to next headline at the same level.
4135 ;; At an item. Move to the next item, if possible.
4142 ;; In any other case, move to element's end, unless this
4143 ;; position is also the end of its parent's contents, in which
4144 ;; case, directly jump to parent's end.
4147 ;; Determine if TRAIL contains the real parent of ELEMENT.
4151 org-element-greater-elements)
4154 parent-candidate)))))
4161 "Put point at beginning of this element, mark at end.
4163 Interactively, if this command is repeated or (in Transient Mark
4164 mode) if the mark is active, it marks the next element after the
4165 ones already marked."
4180 "Narrow buffer to current element."
4198 "Transpose current and previous elements, keeping blank lines between.
4199 Point is moved after both elements."
4218 "Un-indent the visible part of the buffer.
4219 Relative indentation \(between items, inside blocks, etc.\) isn't
4220 modified."
4225 unindent-tree ; For byte-compiler.
4243 "Move to upper element."
4254 ;; At an item, with a parent in the list: move to that parent.
4261 ;; Determine parent in the trail.
4267 org-element-greater-elements)
4270 parentp)))))
4272 ;; When parent is found move to its beginning.
4274 ;; If no parent was found, move to headline above, if any
4275 ;; or return an error.
4280 "Move to inner element."
4288 ;; If contents are hidden, first disclose them.
4295 ;;; org-element.el ends here