| blob | 73942084cf3373bc09de40a4c555414ec33b1fc6 |
1 ;;; org-element.el --- Parser And Applications for Org syntax
3 ;; Copyright (C) 2011 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 ;; You should have received a copy of the GNU General Public License
19 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
21 ;;; Commentary:
23 ;; Org syntax can be divided into three categories: "Greater
24 ;; elements", "Elements" and "Objects".
26 ;; An object can be defined anywhere on a line. It may span over more
27 ;; than a line but never contains a blank one. Objects belong to the
28 ;; following types: `emphasis', `entity', `export-snippet',
29 ;; `footnote-reference', `inline-babel-call', `inline-src-block',
30 ;; `latex-fragment', `line-break', `link', `macro', `radio-target',
31 ;; `statistics-cookie', `subscript', `superscript', `target',
32 ;; `time-stamp' and `verbatim'.
34 ;; An element always starts and ends at the beginning of a line. The
35 ;; only element's type containing objects is called a `paragraph'.
36 ;; Other types are: `comment', `comment-block', `example-block',
37 ;; `export-block', `fixed-width', `horizontal-rule', `keyword',
38 ;; `latex-environment', `babel-call', `property-drawer',
39 ;; `quote-section', `src-block', `table' and `verse-block'.
41 ;; Elements containing paragraphs are called greater elements.
42 ;; Concerned types are: `center-block', `drawer', `dynamic-block',
43 ;; `footnote-definition', `headline', `inlinetask', `item',
44 ;; `plain-list', `quote-block' and `special-block'.
46 ;; Greater elements (excepted `headline' and `item' types) and
47 ;; elements (excepted `keyword', `babel-call', and `property-drawer'
48 ;; types) can have a fixed set of keywords as attributes. Those are
49 ;; called "affiliated keywords", to distinguish them from others
50 ;; keywords, which are full-fledged elements. In particular, the
51 ;; "name" affiliated keyword allows to label almost any element in an
52 ;; Org buffer.
54 ;; Notwithstanding affiliated keywords, each greater element, element
55 ;; and object has a fixed set of properties attached to it. Among
56 ;; them, three are shared by all types: `:begin' and `:end', which
57 ;; refer to the beginning and ending buffer positions of the
58 ;; considered element or object, and `:post-blank', which holds the
59 ;; number of blank lines, or white spaces, at its end.
61 ;; Some elements also have special properties whose value can hold
62 ;; objects themselves (i.e. an item tag, an headline name, a table
63 ;; cell). Such values are called "secondary strings".
65 ;; Lisp-wise, an element or an object can be represented as a list.
66 ;; It follows the pattern (TYPE PROPERTIES CONTENTS), where:
67 ;; TYPE is a symbol describing the Org element or object.
68 ;; PROPERTIES is the property list attached to it. See docstring of
69 ;; appropriate parsing function to get an exhaustive
70 ;; list.
71 ;; CONTENTS is a list of elements, objects or raw strings contained
72 ;; in the current element or object, when applicable.
74 ;; An Org buffer is a nested list of such elements and objects, whose
75 ;; type is `org-data' and properties is nil.
77 ;; The first part of this file implements a parser and an interpreter
78 ;; for each type of Org syntax.
80 ;; The next two parts introduce two accessors and a function
81 ;; retrieving the smallest element containing point (respectively
82 ;; `org-element-get-property', `org-element-get-contents' and
83 ;; `org-element-at-point').
85 ;; The following part creates a fully recursive buffer parser. It
86 ;; also provides a tool to map a function to elements or objects
87 ;; matching some criteria in the parse tree. Functions of interest
88 ;; are `org-element-parse-buffer', `org-element-map' and, to a lesser
89 ;; extent, `org-element-parse-secondary-string'.
91 ;; The penultimate part is the cradle of an interpreter for the
92 ;; obtained parse tree: `org-element-interpret-data' (and its
93 ;; relative, `org-element-interpret-secondary').
95 ;; The library ends by furnishing a set of interactive tools for
96 ;; element's navigation and manipulation.
99 ;;; Code:
105 \f
106 ;;; Greater elements
108 ;; For each greater element type, we define a parser and an
109 ;; interpreter.
111 ;; A parser (`item''s excepted) accepts no argument and represents the
112 ;; element or object as the list described above. An interpreter
113 ;; accepts two arguments: the list representation of the element or
114 ;; object, and its contents. The latter may be nil, depending on the
115 ;; element or object considered. It returns the appropriate Org
116 ;; syntax, as a string.
118 ;; Parsing functions must follow the naming convention:
119 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
120 ;; defined in `org-element-greater-elements'.
121 ;;
122 ;; Similarly, interpreting functions must follow the naming
123 ;; convention: org-element-TYPE-interpreter.
125 ;; With the exception of `headline' and `item' types, greater elements
126 ;; cannot contain other greater elements of their own type.
128 ;; Beside implementing a parser and an interpreter, adding a new
129 ;; greater element requires to tweak `org-element-guess-type'.
130 ;; Moreover, the newly defined type must be added to both
131 ;; `org-element-all-elements' and `org-element-greater-elements'.
134 ;;;; Center Block
136 "Parse a center block.
138 Return a list whose car is `center-block' and cdr is a plist
139 containing `:begin', `:end', `:hiddenp', `:contents-begin',
140 `:contents-end' and `:post-blank' keywords.
142 Assume point is at beginning or end of the block."
169 "Interpret CENTER-BLOCK element as Org syntax.
170 CONTENTS is the contents of the element."
173 ;;;; Drawer
175 "Parse a drawer.
177 Return a list whose car is `drawer' and cdr is a plist containing
178 `:drawer-name', `:begin', `:end', `:hiddenp', `:contents-begin',
179 `:contents-end' and `:post-blank' keywords.
181 Assume point is at beginning of drawer."
206 "Interpret DRAWER element as Org syntax.
207 CONTENTS is the contents of the element."
210 contents))
212 ;;;; Dynamic Block
214 "Parse a dynamic block.
216 Return a list whose car is `dynamic-block' and cdr is a plist
217 containing `:block-name', `:begin', `:end', `:hiddenp',
218 `:contents-begin', `:contents-end', `:arguments' and
219 `:post-blank' keywords.
221 Assume point is at beginning of dynamic block."
248 "Interpret DYNAMIC-BLOCK element as Org syntax.
249 CONTENTS is the contents of the element."
254 contents))
256 ;;;; Footnote Definition
259 "Parse a footnote definition.
261 Return a list whose car is `footnote-definition' and cdr is
262 a plist containing `:label', `:begin' `:end', `:contents-begin',
263 `contents-end' and `:post-blank' keywords."
288 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
289 CONTENTS is the contents of the footnote-definition."
291 " "
292 contents))
295 ;;;; Headline
297 "Parse an headline.
299 Return a list whose car is `headline' and cdr is a plist
300 containing `:raw-value', `:title', `:begin', `:end',
301 `:pre-blank', `:hiddenp', `:contents-begin' and `:contents-end',
302 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
303 `:scheduled', `:deadline', `:timestamp', `:clock', `:category',
304 `:custom-id', `:id', `:quotedp', `:archivedp', `:commentedp',
305 `:last-sibling-p' and `:footnote-section-p' keywords.
307 The plist also contains any property set in the property drawer,
308 with its name in lowercase, the underscores replaced with hyphens
309 and colons at the beginning (i.e. `:custom-id').
311 Assume point is at beginning of the headline."
338 plist))
354 title)
355 ;; Clean RAW-VALUE from any quote or comment string.
360 ""
361 raw-value)))
362 ;; Clean TAGS from archive tag, if any.
369 ;; Then get TITLE.
371 raw-value
399 "Interpret HEADLINE element as Org syntax.
400 CONTENTS is the contents of the element."
425 ;; Align tags.
435 tags-len)
439 contents)))
441 ;;;; Inlinetask
443 "Parse an inline task.
445 Return a list whose car is `inlinetask' and cdr is a plist
446 containing `:raw-value', `:title', `:begin', `:end', `:hiddenp',
447 `:contents-begin' and `:contents-end', `:level', `:with-priority',
448 `tags:', `todo-keyword', `todo-type', and `:post-blank' keywords.
450 Assume point is at beginning of the inline task."
460 raw-value
465 ;; In the case of a single line task, CONTENTS-BEGIN and
466 ;; CONTENTS-END might overlap.
488 "Interpret INLINETASK element as Org syntax.
489 CONTENTS is the contents of inlinetask."
499 ;; Align tags.
513 ;;;; Item
515 "Parse an item.
517 STRUCT is the structure of the plain list.
519 Return a list whose car is `item' and cdr is a plist containing
520 `:begin', `:end', `:contents-begin', `:contents-end',
521 `:checkbox', `:counter', `:tag' and `:hiddenp'.
523 Assume point is at the beginning of the item."
543 raw-tag
559 ;; Note: CONTENTS-BEGIN and CONTENTS-END can be mixed up in the
560 ;; case of an empty item separated from the next by a blank
561 ;; line.
577 "Interpret ITEM element as Org syntax.
578 CONTENTS is the contents of the element."
583 ;; Compute indentation.
585 ;; Indent contents.
587 bullet
601 ;;;; Plain List
603 "Parse a plain list.
605 Return a list whose car is `plain-list' and cdr is a plist
606 containing `:type', `:begin', `:end', `:contents-begin' and
607 `:contents-end', `:level', `:structure' and `:post-blank'
608 keywords.
610 Assume point is at one of the list items."
625 ;; Get list level.
630 struct parents))
632 ;; Blank lines below list belong to the top-level list only.
637 ;; Return value.
650 "Interpret PLAIN-LIST element as Org syntax.
651 CONTENTS is the contents of the element."
652 contents)
654 ;;;; Quote Block
656 "Parse a quote block.
658 Return a list whose car is `quote-block' and cdr is a plist
659 containing `:begin', `:end', `:hiddenp', `:contents-begin',
660 `:contents-end' and `:post-blank' keywords.
662 Assume point is at beginning or end of the block."
690 "Interpret QUOTE-BLOCK element as Org syntax.
691 CONTENTS is the contents of the element."
694 ;;;; Special Block
696 "Parse a special block.
698 Return a list whose car is `special-block' and cdr is a plist
699 containing `:type', `:begin', `:end', `:hiddenp',
700 `:contents-begin', `:contents-end' and `:post-blank' keywords.
702 Assume point is at beginning or end of the block."
733 "Interpret SPECIAL-BLOCK element as Org syntax.
734 CONTENTS is the contents of the element."
739 \f
740 ;;; Elements
742 ;; For each element, a parser and an interpreter are also defined.
743 ;; Both follow the same naming convention used for greater elements.
745 ;; Also, as for greater elements, adding a new element type is done
746 ;; through the following steps: implement a parser and an interpreter,
747 ;; tweak `org-element-guess-type' so that it recognizes the new type
748 ;; and add that new type to `org-element-all-elements'.
750 ;; As a special case, when the newly defined type is a block type,
751 ;; `org-element-non-recursive-block-alist' has to be modified
752 ;; accordingly.
755 ;;;; Babel Call
757 "Parse a babel call.
759 Return a list whose car is `babel-call' and cdr is a plist
760 containing `:begin', `:end', `:info' and `:post-blank' as
761 keywords."
776 "Interpret INLINE-BABEL-CALL object as Org syntax.
777 CONTENTS is nil."
783 ;; Remove redundant square brackets.
786 main-source)
789 ;;;; Comment
791 "Parse a comment.
793 Return a list whose car is `comment' and cdr is a plist
794 containing `:begin', `:end', `:value' and `:post-blank'
795 keywords."
797 beg-coms begin end value pos-before-blank keywords)
799 ;; Move to the beginning of comments.
805 ;; Get affiliated keywords, if any.
807 ;; Store true beginning of element.
809 ;; Get ending of comments. If point is in a list, ensure to not
810 ;; get outside of it.
819 ;; Find position after blank.
822 ;; Extract value.
832 "Interpret COMMENT element as Org syntax.
833 CONTENTS is nil."
836 ;;;; Comment Block
838 "Parse an export block.
840 Return a list whose car is `comment-block' and cdr is a plist
841 containing `:begin', `:end', `:hiddenp', `:value' and
842 `:post-blank' keywords."
868 "Interpret COMMENT-BLOCK element as Org syntax.
869 CONTENTS is nil."
875 ;;;; Example Block
877 "Parse an example block.
879 Return a list whose car is `example' and cdr is a plist
880 containing `:begin', `:end', `:options', `:hiddenp', `:value' and
881 `:post-blank' keywords."
910 "Interpret EXAMPLE-BLOCK element as Org syntax.
911 CONTENTS is nil."
918 ;;;; Export Block
920 "Parse an export block.
922 Return a list whose car is `export-block' and cdr is a plist
923 containing `:begin', `:end', `:type', `:hiddenp', `:value' and
924 `:post-blank' keywords."
954 "Interpret EXPORT-BLOCK element as Org syntax.
955 CONTENTS is nil."
961 ;;;; Fixed-width
963 "Parse a fixed-width section.
965 Return a list whose car is `fixed-width' and cdr is a plist
966 containing `:begin', `:end', `:value' and `:post-blank'
967 keywords."
969 beg-area begin end value pos-before-blank keywords)
971 ;; Move to the beginning of the fixed-width area.
977 ;; Get affiliated keywords, if any.
979 ;; Store true beginning of element.
981 ;; Get ending of fixed-width area. If point is in a list,
982 ;; ensure to not get outside of it.
991 ;; Find position after blank
994 ;; Extract value.
1004 "Interpret FIXED-WIDTH element as Org syntax.
1005 CONTENTS is nil."
1008 ;;;; Horizontal Rule
1010 "Parse an horizontal rule.
1012 Return a list whose car is `horizontal-rule' and cdr is
1013 a plist containing `:begin', `:end' and `:post-blank'
1014 keywords."
1028 "Interpret HORIZONTAL-RULE element as Org syntax.
1029 CONTENTS is nil."
1032 ;;;; Keyword
1034 "Parse a keyword at point.
1036 Return a list whose car is `keyword' and cdr is a plist
1037 containing `:key', `:value', `:begin', `:end' and `:post-blank'
1038 keywords."
1057 "Interpret KEYWORD element as Org syntax.
1058 CONTENTS is nil."
1063 ;;;; Latex Environment
1065 "Parse a LaTeX environment.
1067 Return a list whose car is `latex-environment' and cdr is a plist
1068 containing `:begin', `:end', `:value' and `:post-blank' keywords."
1089 "Interpret LATEX-ENVIRONMENT element as Org syntax.
1090 CONTENTS is nil."
1093 ;;;; Paragraph
1095 "Parse a paragraph.
1097 Return a list whose car is `paragraph' and cdr is a plist
1098 containing `:begin', `:end', `:contents-begin' and
1099 `:contents-end' and `:post-blank' keywords.
1101 Assume point is at the beginning of the paragraph."
1124 "Interpret PARAGRAPH element as Org syntax.
1125 CONTENTS is the contents of the element."
1126 contents)
1128 ;;;; Property Drawer
1130 "Parse a property drawer.
1132 Return a list whose car is `property-drawer' and cdr is a plist
1133 containing `:begin', `:end', `:hiddenp', `:contents-begin',
1134 `:contents-end', `:properties' and `:post-blank' keywords."
1151 val))
1153 val))
1167 "Interpret PROPERTY-DRAWER element as Org syntax.
1168 CONTENTS is nil."
1177 ;;;; Quote Section
1179 "Parse a quote section.
1181 Return a list whose car is `quote-section' and cdr is a plist
1182 containing `:begin', `:end', `:value' and `:post-blank'
1183 keywords."
1205 "Interpret QUOTE-SECTION element as Org syntax.
1206 CONTENTS is nil."
1209 ;;;; Src Block
1211 "Parse a src block.
1213 Return a list whose car is `src-block' and cdr is a plist
1214 containing `:language', `:switches', `:parameters', `:begin',
1215 `:end', `:hiddenp', `:contents-begin', `:contents-end', `:value'
1216 and `:post-blank' keywords."
1220 ;; Get position at beginning of block.
1227 nil t))
1228 ;; Get language as a string.
1230 ;; Get switches.
1232 ;; Get parameters.
1234 ;; Get affiliated keywords.
1236 ;; Get beginning position.
1238 ;; Get position at end of block.
1242 ;; Retrieve code.
1248 ;; Get position after ending blank lines.
1251 ;; Get visibility status.
1267 "Interpret SRC-BLOCK element as Org syntax.
1268 CONTENTS is nil."
1287 value
1290 ;;;; Table
1292 "Parse a table at point.
1294 Return a list whose car is `table' and cdr is a plist containing
1295 `:begin', `:end', `:contents-begin', `:contents-end', `:tblfm',
1296 `:type', `:raw-table' and `:post-blank' keywords."
1321 "Interpret TABLE element as Org syntax.
1322 CONTENTS is nil."
1325 ;;;; Verse Block
1327 "Parse a verse block.
1329 Return a list whose car is `verse-block' and cdr is a plist
1330 containing `:begin', `:end', `:hiddenp', `:raw-value', `:value'
1331 and `:post-blank' keywords.
1333 Assume point is at beginning or end of the block."
1365 "Interpret VERSE-BLOCK element as Org syntax.
1366 CONTENTS is nil."
1372 \f
1373 ;;; Objects
1375 ;; Unlike to elements, interstices can be found between objects.
1376 ;; That's why, along with the parser, successor functions are provided
1377 ;; for each object. Some objects share the same successor
1378 ;; (i.e. `emphasis' and `verbatim' objects).
1380 ;; A successor must accept a single argument bounding the search. It
1381 ;; will return either a cons cell whose car is the object's type, as
1382 ;; a symbol, and cdr the position of its next occurrence, or nil.
1384 ;; Successors follow the naming convention:
1385 ;; org-element-NAME-successor, where NAME is the name of the
1386 ;; successor, as defined in `org-element-all-successors'.
1388 ;; Some object types (i.e `emphasis') are recursive. Restrictions on
1389 ;; object types they can contain will be specified in
1390 ;; `org-element-object-restrictions'.
1392 ;; Adding a new type of object is simple. Implement a successor,
1393 ;; a parser, and an interpreter for it, all following the naming
1394 ;; convention. Register successor in `org-element-all-successors',
1395 ;; maybe tweak restrictions about it, and that's it.
1397 ;;;; Emphasis
1399 "Parse text markup object at point.
1401 Return a list whose car is `emphasis' and cdr is a plist with
1402 `:marker', `:begin', `:end', `:contents-begin' and
1403 `:contents-end' and `:post-blank' keywords.
1405 Assume point is at the first emphasis marker."
1425 "Interpret EMPHASIS object as Org syntax.
1426 CONTENTS is the contents of the object."
1431 "Search for the next emphasis or verbatim and return position.
1433 LIMIT bounds the search.
1435 Return value is a cons cell whose car is `emphasis' or
1436 `verbatim' and cdr is beginning position."
1441 'verbatim
1445 ;;;; Entity
1447 "Parse entity at point.
1449 Return a list whose car is `entity' and cdr a plist with
1450 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
1451 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
1452 keywords.
1454 Assume point is at the beginning of the entity."
1478 "Interpret ENTITY object as Org syntax.
1479 CONTENTS is nil."
1485 "Search for the next latex-fragment or entity object.
1487 LIMIT bounds the search.
1489 Return value is a cons cell whose car is `entity' or
1490 `latex-fragment' and cdr is beginning position."
1493 ;; ENTITY-RE matches both LaTeX commands and Org entities.
1500 limit t)
1503 ;; Determine if it's a real entity or a LaTeX command.
1506 ;; No entity nor command: point is at a LaTeX fragment.
1507 ;; Determine its type to get the correct beginning position.
1515 matchers)
1518 ;;;; Export Snippet
1520 "Parse export snippet at point.
1522 Return a list whose car is `export-snippet' and cdr a plist with
1523 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
1524 keywords.
1526 Assume point is at the beginning of the snippet."
1544 "Interpret EXPORT-SNIPPET object as Org syntax.
1545 CONTENTS is nil."
1551 "Search for the next export-snippet object.
1553 LIMIT bounds the search.
1555 Return value is a cons cell whose car is `export-snippet' cdr is
1556 its beginning position."
1564 ;;;; Footnote Reference
1567 "Parse footnote reference at point.
1569 Return a list whose car is `footnote-reference' and cdr a plist
1570 with `:label', `:type', `:definition', `:begin', `:end' and
1571 `:post-blank' as keywords."
1593 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
1594 CONTENTS is nil."
1603 "Search for the next footnote-reference and return beginning
1604 position.
1606 LIMIT bounds the search.
1608 Return value is a cons cell whose car is `footnote-reference' and
1609 cdr is beginning position."
1615 ;;;; Inline Babel Call
1617 "Parse inline babel call at point.
1619 Return a list whose car is `inline-babel-call' and cdr a plist with
1620 `:begin', `:end', `:info' and `:post-blank' as keywords.
1622 Assume point is at the beginning of the babel call."
1638 "Interpret INLINE-BABEL-CALL object as Org syntax.
1639 CONTENTS is nil."
1645 ;; Remove redundant square brackets.
1648 main-source)
1652 "Search for the next inline-babel-call and return beginning
1653 position.
1655 LIMIT bounds the search.
1657 Return value is a cons cell whose car is `inline-babel-call' and
1658 cdr is beginning position."
1660 ;; Use a simplified version of
1661 ;; org-babel-inline-lob-one-liner-regexp as regexp for more speed.
1663 "\\(?:babel\\|call\\)_\\([^()\n]+?\\)\\(\\[\\(.*\\)\\]\\|\\(\\)\\)(\\([^\n]*\\))\\(\\[\\(.*?\\)\\]\\)?"
1664 limit t)
1667 ;;;; Inline Src Block
1669 "Parse inline source block at point.
1671 Return a list whose car is `inline-src-block' and cdr a plist
1672 with `:begin', `:end', `:language', `:value', `:parameters' and
1673 `:post-blank' as keywords.
1675 Assume point is at the beginning of the inline src block."
1697 "Search for the next inline-babel-call and return beginning position.
1699 LIMIT bounds the search.
1701 Return value is a cons cell whose car is `inline-babel-call' and
1702 cdr is beginning position."
1707 ;;;; Latex Fragment
1709 "Parse latex fragment at point.
1711 Return a list whose car is `latex-fragment' and cdr a plist with
1712 `:value', `:begin', `:end', and `:post-blank' as keywords.
1714 Assume point is at the beginning of the latex fragment."
1728 ;; None found: it's a macro.
1742 "Interpret LATEX-FRAGMENT object as Org syntax.
1743 CONTENTS is nil."
1746 ;;;; Line Break
1748 "Parse line break at point.
1750 Return a list whose car is `line-break', and cdr a plist with
1751 `:begin', `:end' and `:post-blank' keywords.
1753 Assume point is at the beginning of the line break."
1765 "Interpret LINE-BREAK object as Org syntax.
1766 CONTENTS is nil."
1770 "Search for the next statistics cookie and return position.
1772 LIMIT bounds the search.
1774 Return value is a cons cell whose car is `line-break' and cdr is
1775 beginning position."
1779 ;; A line break can only happen on a non-empty line.
1783 ;;;; Link
1785 "Parse link at point.
1787 Return a list whose car is `link' and cdr a plist with `:type',
1788 `:path', `:raw-link', `:begin', `:end', `:contents-begin',
1789 `:contents-end' and `:post-blank' as keywords.
1791 Assume point is at the beginning of the link."
1794 end contents-begin contents-end link-end post-blank path type
1795 raw-link link)
1797 ;; Type 1: text targeted from a radio target.
1804 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
1809 ;; RAW-LINK is the original link.
1814 ;; Determine TYPE of link and set PATH accordingly.
1816 ;; File type.
1819 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
1822 ;; Id type: PATH is the id.
1825 ;; Code-ref type: PATH is the name of the reference.
1828 ;; Custom-id type: PATH is the name of the custom id.
1831 ;; Fuzzy type: Internal link either matches a target, an
1832 ;; headline name or nothing. PATH is the target or headline's
1833 ;; name.
1835 ;; Type 3: Plain link, i.e. http://orgmode.org
1841 ;; Type 4: Angular link, i.e. <http://orgmode.org>
1848 ;; In any case, deduce end point after trailing white space from
1849 ;; LINK-END variable.
1863 "Interpret LINK object as Org syntax.
1864 CONTENTS is the contents of the object."
1870 raw-link
1874 "Search for the next link and return position.
1876 LIMIT bounds the search.
1878 Return value is a cons cell whose car is `link' and cdr is
1879 beginning position."
1884 org-any-link-re)))
1888 ;;;; Macro
1890 "Parse macro at point.
1892 Return a list whose car is `macro' and cdr a plist with `:key',
1893 `:args', `:begin', `:end', `:value' and `:post-blank' as
1894 keywords.
1896 Assume point is at the macro."
1910 ;; Repair bad splits.
1925 "Interpret MACRO object as Org syntax.
1926 CONTENTS is nil."
1930 "Search for the next macro and return position.
1932 LIMIT bounds the search.
1934 Return value is cons cell whose car is `macro' and cdr is
1935 beginning position."
1939 limit t)
1942 ;;;; Radio-target
1944 "Parse radio target at point.
1946 Return a list whose car is `radio-target' and cdr a plist with
1947 `:begin', `:end', `:contents-begin', `:contents-end', `raw-value'
1948 and `:post-blank' as keywords.
1950 Assume point is at the radio target."
1969 "Interpret TARGET object as Org syntax.
1970 CONTENTS is the contents of the object."
1974 "Search for the next radio-target and return position.
1976 LIMIT bounds the search.
1978 Return value is a cons cell whose car is `radio-target' and cdr
1979 is beginning position."
1984 ;;;; Statistics Cookie
1986 "Parse statistics cookie at point.
1988 Return a list whose car is `statistics-cookie', and cdr a plist
1989 with `:begin', `:end', `:value' and `:post-blank' keywords.
1991 Assume point is at the beginning of the statistics-cookie."
2007 "Interpret STATISTICS-COOKIE object as Org syntax.
2008 CONTENTS is nil."
2012 "Search for the next statistics cookie and return position.
2014 LIMIT bounds the search.
2016 Return value is a cons cell whose car is `statistics-cookie' and
2017 cdr is beginning position."
2022 ;;;; Subscript
2024 "Parse subscript at point.
2026 Return a list whose car is `subscript' and cdr a plist with
2027 `:begin', `:end', `:contents-begin', `:contents-end',
2028 `:use-brackets-p' and `:post-blank' as keywords.
2030 Assume point is at the underscore."
2034 t
2052 "Interpret SUBSCRIPT object as Org syntax.
2053 CONTENTS is the contents of the object."
2056 contents))
2059 "Search for the next sub/superscript and return beginning
2060 position.
2062 LIMIT bounds the search.
2064 Return value is a cons cell whose car is either `subscript' or
2065 `superscript' and cdr is beginning position."
2071 ;;;; Superscript
2073 "Parse superscript at point.
2075 Return a list whose car is `superscript' and cdr a plist with
2076 `:begin', `:end', `:contents-begin', `:contents-end',
2077 `:use-brackets-p' and `:post-blank' as keywords.
2079 Assume point is at the caret."
2083 t
2101 "Interpret SUPERSCRIPT object as Org syntax.
2102 CONTENTS is the contents of the object."
2105 contents))
2107 ;;;; Target
2109 "Parse target at point.
2111 Return a list whose car is `target' and cdr a plist with
2112 `:begin', `:end', `:contents-begin', `:contents-end', `raw-value'
2113 and `:post-blank' as keywords.
2115 Assume point is at the target."
2134 "Interpret TARGET object as Org syntax.
2135 CONTENTS is the contents of target."
2139 "Search for the next target and return position.
2141 LIMIT bounds the search.
2143 Return value is a cons cell whose car is `target' and cdr is
2144 beginning position."
2149 ;;;; Time-stamp
2151 "Parse time stamp at point.
2153 Return a list whose car is `time-stamp', and cdr a plist with
2154 `:appt-type', `:type', `:begin', `:end', `:value' and
2155 `:post-blank' keywords.
2157 Assume point is at the beginning of the time-stamp."
2195 "Interpret TIME-STAMP object as Org syntax.
2196 CONTENTS is nil."
2205 "Search for the next time-stamp and return position.
2207 LIMIT bounds the search.
2209 Return value is a cons cell whose car is `time-stamp' and cdr is
2210 beginning position."
2215 org-ts-regexp-both
2220 limit t)
2223 ;;;; Verbatim
2225 "Parse verbatim object at point.
2227 Return a list whose car is `verbatim' and cdr is a plist with
2228 `:marker', `:begin', `:end' and `:post-blank' keywords.
2230 Assume point is at the first verbatim marker."
2248 "Interpret VERBATIM object as Org syntax.
2249 CONTENTS is nil."
2255 \f
2256 ;;; Definitions And Rules
2258 ;; Define elements, greater elements and specify recursive objects,
2259 ;; along with the affiliated keywords recognized. Also set up
2260 ;; restrictions on recursive objects combinations.
2262 ;; These variables really act as a control center for the parsing
2263 ;; process.
2266 ;; Headlines and inlinetasks.
2268 ;; Comments, blocks (any type), keywords and babel calls.
2270 ;; Lists.
2272 ;; Fixed-width, drawers (any type) and tables.
2274 ;; Footnote definitions.
2276 ;; Horizontal rules.
2278 ;; LaTeX environments.
2284 export-block fixed-width footnote-definition headline
2285 horizontal-rule inlinetask item keyword latex-environment
2286 babel-call paragraph plain-list property-drawer quote-block
2287 quote-section special-block src-block table verse-block)
2292 item plain-list quote-block special-block)
2297 latex-or-entity line-break link macro radio-target
2298 statistics-cookie sub/superscript target text-markup
2299 time-stamp)
2306 "Alist of translations between object type and successor name.
2308 Sharing the same successor comes handy when, for example, the
2337 "Alist of usual translations for keywords.
2338 The key is the old name and the value the new one. The property
2343 "List of affiliated keywords that can occur more that once in an element.
2345 Their value will be consed into a list of strings, which will be
2346 returned as the value of the property.
2348 This list is checked after translations have been applied. See
2352 "List of keywords whose value can be parsed.
2354 Their value will be stored as a secondary string: a list of
2355 strings and objects.
2357 This list is checked after translations have been applied. See
2361 "List of keywords which can have a secondary value.
2363 In Org syntax, they can be written with optional square brackets
2364 before the colons. For example, results keyword can be
2365 associated to a hash value with the following:
2367 #+results[hash-string]: some-source
2369 This list is checked after translations have been applied. See
2383 "Alist of recursive objects restrictions.
2385 Car is a recursive object type and cdr is a list of successors
2386 that will be called within an object of such type.
2388 For example, in a `radio-target' object, one can only find
2389 entities, export snippets, latex-fragments, subscript and
2402 latex-fragment line-break link macro radio-target sub/superscript
2403 target text-markup time-stamp))
2404 "Alist of secondary strings restrictions.
2406 When parsed, some elements have a secondary string which could
2407 contain various objects (i.e. headline's name, or table's cells).
2408 For association, the car is the element type, and the cdr a list
2409 of successors that will be called in that secondary string.
2411 Note: `keyword' secondary string type only applies to keywords
2415 \f
2416 ;;; Accessors
2417 ;;
2418 ;; Provide two accessors: `org-element-get-property' and
2419 ;; `org-element-get-contents'.
2421 "Extract the value from the PROPERTY of an ELEMENT."
2425 "Extract contents from an ELEMENT."
2429 \f
2430 ;; Obtaining The Smallest Element Containing Point
2432 ;; `org-element-at-point' is the core function of this section. It
2433 ;; returns the Lisp representation of the element at point. It uses
2434 ;; `org-element-guess-type' and `org-element-skip-keywords' as helper
2435 ;; functions.
2437 ;; When point is at an item, there is no automatic way to determine if
2438 ;; the function should return the `plain-list' element, or the
2439 ;; corresponding `item' element. By default, `org-element-at-point'
2440 ;; works at the `plain-list' level. But, by providing an optional
2441 ;; argument, one can make it switch to the `item' level.
2451 "Regexp matching any affiliated keyword.
2453 Keyword name is put in match group 1. Moreover, if keyword
2454 belongs to `org-element-dual-keywords', put the dual value in
2455 match group 2.
2460 "Determine closest element around point.
2462 Return value is a list \(TYPE PROPS\) where TYPE is the type of
2463 the element and PROPS a plist of properties associated to the
2464 element.
2466 Possible types are defined in `org-element-all-elements'.
2468 If optional argument TOGGLE-ITEM is non-nil, parse item wise
2469 instead of plain-list wise, using STRUCTURE as the current list
2470 structure.
2472 If STRUCTURE isn't provided but TOGGLE-ITEM is non-nil, it will
2473 be computed."
2476 ;; Move before any blank line.
2481 ;; Check if point is at an affiliated keyword. In that case,
2482 ;; try moving to the beginning of the associated element. If
2483 ;; the keyword is orphaned, treat it as plain text.
2490 ;; Guessing element type on the current line is impossible:
2491 ;; try to find the beginning of the current element to get
2492 ;; more information.
2501 ;; Unable to find a paragraph delimiter above: we're at
2502 ;; bob and looking at a paragraph.
2504 ;; Trying to find element's beginning set point back to
2505 ;; its original position. There's something peculiar on
2506 ;; this line that prevents parsing, probably an
2507 ;; ill-formed keyword or an undefined drawer name. Parse
2508 ;; it as plain text anyway.
2510 ;; Original point wasn't in a list but previous paragraph
2511 ;; is. It means that either point was inside some block,
2512 ;; or current list was ended without using a blank line.
2513 ;; In the last case, paragraph really starts at list end.
2530 ;; In any other case, the paragraph started the line
2531 ;; below.
2537 ;; Straightforward case: call the appropriate parser.
2541 ;; It is obvious to tell if point is in most elements, either by
2542 ;; looking for a specific regexp in the current line, or by using
2543 ;; already implemented functions. This is the goal of
2544 ;; `org-element-guess-type'.
2547 "List of non-recursive block types, as strings.
2548 Used internally by `org-element-guess-type'. Do not modify it
2552 "Return the type of element at point, or nil if undetermined.
2553 This function may move point to an appropriate position for
2554 parsing. Used internally by `org-element-at-point'."
2555 ;; Beware: Order matters for some cases in that function.
2564 headline))))
2566 ;; Non-recursive block.
2572 ;; Property drawer. Almost `org-at-property-p', but allow drawer
2573 ;; boundaries.
2581 ;; Recursive block. If the block isn't complete, parse the
2582 ;; current part as a paragraph.
2590 ;; Regular drawers must be tested after property drawer as both
2591 ;; elements share the same ending regexp.
2596 'paragraph
2599 ;; Babel calls must be tested before general keywords as they are
2600 ;; a subset of them.
2605 'paragraph
2607 ;; Dynamic block: simplify regexp used for match. If it isn't
2608 ;; complete, parse the current part as a paragraph.
2614 'paragraph
2621 ;; A TBLFM line separated from any table is just plain text.
2623 'table
2627 ;; Most elements can have affiliated keywords. When looking for an
2628 ;; element beginning, we want to move before them, as they belong to
2629 ;; that element, and, in the meantime, collect information they give
2630 ;; into appropriate properties. Hence the following function.
2632 ;; Usage of optional arguments may not be obvious at first glance:
2634 ;; - TRANS-LIST is used to polish keywords names that have evolved
2635 ;; during Org history. In example, even though =result= and
2636 ;; =results= coexist, we want to have them under the same =result=
2637 ;; property. It's also true for "srcname" and "name", where the
2638 ;; latter seems to be preferred nowadays (thus the "name" property).
2640 ;; - CONSED allows to regroup multi-lines keywords under the same
2641 ;; property, while preserving their own identity. This is mostly
2642 ;; used for "attr_latex" and al.
2644 ;; - PARSED prepares a keyword value for export. This is useful for
2645 ;; "caption". Objects restrictions for such keywords are defined in
2646 ;; `org-element-string-restrictions'.
2648 ;; - DUALS is used to take care of keywords accepting a main and an
2649 ;; optional secondary values. For example "results" has its
2650 ;; source's name as the main value, and may have an hash string in
2651 ;; optional square brackets as the secondary one.
2653 ;; A keyword may belong to more than one category.
2655 consed parsed duals)
2656 "Collect affiliated keywords before point.
2658 Optional argument KEY-RE is a regexp matching keywords, which
2659 puts matched keyword in group 1. It defaults to
2660 `org-element--affiliated-re'.
2662 TRANS-LIST is an alist where key is the keyword and value the
2663 property name it should be translated to, without the colons. It
2664 defaults to `org-element-keyword-translation-alist'.
2666 CONSED is a list of strings. Any keyword belonging to that list
2667 will have its value consed. The check is done after keyword
2668 translation. It defaults to `org-element-multiple-keywords'.
2670 PARSED is a list of strings. Any keyword member of this list
2671 will have its value parsed. The check is done after keyword
2672 translation. If a keyword is a member of both CONSED and PARSED,
2673 it's value will be a list of parsed strings. It defaults to
2674 `org-element-parsed-keywords'.
2676 DUALS is a list of strings. Any keyword member of this list can
2677 have two parts: one mandatory and one optional. Its value is
2678 a cons cell whose car is the former, and the cdr the latter. If
2679 a keyword is a member of both PARSED and DUALS, only the primary
2680 part will be parsed. It defaults to `org-element-dual-keywords'.
2682 Return a list whose car is the position at the first of them and
2683 cdr a plist of keywords and values."
2691 output)
2696 ;; Apply translation to RAW-KWD. From there, KWD is
2697 ;; the official keyword.
2699 ;; If KWD is a dual keyword, find it secondary value.
2702 ;; Find main value for any keyword.
2705 ;; Attribute a property name to KWD.
2707 ;; Now set final shape for VALUE.
2711 value
2716 ;; Eventually store the new value in OUTPUT.
2722 \f
2723 ;;; The Org Parser
2725 ;; The two major functions here are `org-element-parse-buffer', which
2726 ;; parses Org syntax inside the current buffer, taking into account
2727 ;; region, narrowing, or even visibility if specified, and
2728 ;; `org-element-parse-secondary-string', which parses objects within
2729 ;; a given string.
2731 ;; The (almost) almighty `org-element-map' allows to apply a function
2732 ;; on elements or objects matching some type, and accumulate the
2733 ;; resulting values. In an export situation, it also skips unneeded
2734 ;; parts of the parse tree, transparently walks into included files,
2735 ;; and maintain a list of local properties (i.e. those inherited from
2736 ;; parent headlines) for function's consumption.
2738 "Recursively parse the buffer and return structure.
2739 If narrowing is in effect, only parse the visible part of the
2740 buffer.
2742 Optional argument GRANULARITY determines the depth of the
2743 recursion. It can be set to the following symbols:
2745 `headline' Only parse headlines.
2746 `greater-element' Don't recurse into greater elements. Thus,
2747 elements parsed are the top-level ones.
2748 `element' Parse everything but objects and plain text.
2749 `object' Parse the complete buffer (default).
2751 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
2752 elements.
2754 Assume buffer is in Org mode."
2761 nil nil granularity visible-only nil))))
2764 "Recursively parse objects in STRING and return structure.
2766 RESTRICTION, when non-nil, is a symbol limiting the object types
2767 that will be looked after.
2769 Optional argument BUFFER indicates the buffer from where the
2770 secondary string was extracted. It is used to determine where to
2771 get extraneous information for an object \(i.e. when resolving
2772 a link or looking for a footnote definition\). It defaults to
2773 the current buffer."
2779 "Map a function on selected elements or objects.
2781 DATA is the parsed tree, as returned by, i.e,
2782 `org-element-parse-buffer'. TYPES is a symbol or list of symbols
2783 of elements or objects types. FUN is the function called on the
2784 matching element or object. It must accept two arguments: the
2785 element or object itself and a plist holding contextual
2786 information.
2788 When optional argument OPTIONS is non-nil, it should be a plist
2789 holding export options. In that case, parts of the parse tree
2790 not exportable according to that property list will be skipped
2791 and files included through a keyword will be visited.
2793 When optional argument FIRST-MATCH is non-nil, stop at the first
2794 match for which FUN doesn't return nil, and return that value.
2796 Nil values returned from FUN are ignored in the result."
2797 ;; Ensure TYPES is a list, even of one element.
2799 ;; Recursion depth is determined by TYPE-CATEGORY, to avoid
2800 ;; unnecessary steps.
2810 walk-tree ; For byte-compiler
2811 acc ; Accumulate results into ACC.
2814 ;; Check if TYPE is matching among TYPES. If so, apply FUN
2815 ;; to BLOB and accumulate return value into ACC. INFO is
2816 ;; the communication channel.
2826 ;; Recursively walk DATA. INFO, if non-nil, is a plist
2827 ;; holding contextual information.
2832 ;; Determine if a recursion into BLOB is possible
2833 ;; and allowed.
2835 ;; Element or object not exportable.
2837 ;; Archived headline: skip it.
2844 ;; At an include keyword: apply mapping to its
2845 ;; contents.
2857 walk-tree
2858 data
2860 info
2861 ;; Store full path of already included files
2862 ;; to avoid recursive file inclusion.
2863 `(:included-files
2866 ;; Ensure that a top-level headline in the
2867 ;; included file becomes a direct child of
2868 ;; the current headline in the buffer.
2869 :headline-offset
2874 ;; Limiting recursion to greater elements, and BLOB
2875 ;; isn't one.
2879 ;; Limiting recursion to elements, and BLOB only
2880 ;; contains objects.
2882 ;; No limitation on recursion, but BLOB hasn't got
2883 ;; a recursive type.
2889 ;; Recursion is possible and allowed: Update local
2890 ;; informations and move into BLOB.
2893 walk-tree
2894 blob
2899 ;; Return value in a proper order.
2902 ;; The following functions are internal parts of the parser. The
2903 ;; first one, `org-element-parse-elements' acts at the element's
2904 ;; level. The second one, `org-element-parse-objects' applies on all
2905 ;; objects of a paragraph or a secondary string. It uses
2906 ;; `org-element-get-candidates' to optimize the search of the next
2907 ;; object in the buffer.
2908 ;;
2909 ;; More precisely, that function looks for every allowed object type
2910 ;; first. Then, it discards failed searches, keeps further matches,
2911 ;; and searches again types matched behind point, for subsequent
2912 ;; calls. Thus, searching for a given type fails only once, and every
2913 ;; object is searched only once at top level (but sometimes more for
2914 ;; nested types).
2916 "Parse ELEMENT with point at its beginning.
2918 If ITEM is non-nil, parse item wise instead of plain-list wise,
2919 using STRUCTURE as the current list structure.
2921 GRANULARITY determines the depth of the recursion. It can be set
2922 to the following symbols:
2924 `headline' Only parse headlines.
2925 `greater-element' Don't recurse into greater elements. Thus,
2926 elements parsed are the top-level ones.
2927 `element' Parse everything but objects and plain text.
2928 `object' or nil Parse the complete buffer.
2930 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
2931 greater elements.
2933 Elements are accumulated into ACC."
2936 ;; Shortcut when parsing only headlines.
2939 ;; Main loop start.
2942 ;; 1. If ITEM is toggled, point is at an item. Knowing that,
2943 ;; there's no need to go through `org-element-at-point'.
2949 ;; Narrow region to contents, so that item bullet don't
2950 ;; interfere with paragraph parsing.
2954 cbeg cend nil structure granularity visible-only
2956 ;; 2. When ITEM is nil, find current element's type and parse
2957 ;; it accordingly to its category.
2961 ;; Case 1: ELEMENT is a footnote-definition. If
2962 ;; GRANURALITY allows parsing, use narrowing so that
2963 ;; footnote label don't interfere with paragraph
2964 ;; recognition.
2972 cbeg cend nil structure granularity visible-only
2974 ;; Case 1: ELEMENT is a paragraph. Parse objects inside,
2975 ;; if GRANULARITY allows it.
2982 nil))
2983 ;; Case 2: ELEMENT is recursive: parse it between
2984 ;; `contents-begin' and `contents-end'. If it's
2985 ;; a plain list, also switch to item mode. Make
2986 ;; sure GRANULARITY allows the recursion, or
2987 ;; ELEMENT is an headline, in which case going
2988 ;; inside is mandatory, in order to get sub-level
2989 ;; headings. If VISIBLE-ONLY is true and element
2990 ;; is hidden, do not recurse into it.
3002 granularity
3003 visible-only
3005 ;; Case 3: Else, just accumulate ELEMENT, unless
3006 ;; GRANULARITY is set to `headline'.
3008 acc)
3010 ;; Return result.
3014 "Parse objects between BEG and END and return recursive structure.
3016 Objects are accumulated in ACC.
3018 RESTRICTION, when non-nil, is a list of object types which are
3019 allowed in the current object."
3023 ;; Return the parsing function associated to the nearest
3024 ;; object among list of candidates CAND.
3031 next-object candidates)
3035 end restriction candidates))
3037 ;; 1. Text before any object.
3041 ;; 2. Object...
3045 cont-beg)
3046 ;; ... recursive. The CONT-BEG check is for
3047 ;; links, as some of them might not be recursive
3048 ;; (i.e. plain links).
3051 cont-beg
3055 ;; Restrict allowed objects. This is the
3056 ;; intersection of current restriction and next
3057 ;; object's restriction.
3060 org-element-object-restrictions))))
3062 new-restr
3066 new-restr))))))
3067 ;; ... not recursive.
3068 next-object)
3069 acc)
3071 ;; 3. Text after last object.
3074 ;; Result.
3078 "Return an alist of candidates for the next object.
3080 LIMIT bounds the search, and RESTRICTION, when non-nil, bounds
3081 the possible object types.
3083 Return value is an alist whose car is position and cdr the object
3084 type, as a string. There is an association for the closest
3085 object of each type within RESTRICTION when non-nil, or for every
3086 type otherwise.
3088 OBJECTS is the previous candidates alist."
3090 next-candidates types-to-search)
3091 ;; If no previous result, search every object type in RESTRICTION.
3092 ;; Otherwise, keep potential candidates (old objects located after
3093 ;; point) and ask to search again those which had matched before.
3099 objects)
3101 ;; Call the appropriate "get-next" function for each type to
3102 ;; search and accumulate matches.
3109 type))))
3112 types-to-search)
3113 ;; Return alist.
3114 next-candidates))
3117 \f
3118 ;;; Towards A Bijective Process
3120 ;; The parse tree obtained with `org-element-parse-buffer' is really
3121 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
3122 ;; interpreted and expanded into a string with canonical Org
3123 ;; syntax. Hence `org-element-interpret-data'.
3124 ;;
3125 ;; Data parsed from secondary strings, whose shape is slightly
3126 ;; different than the standard parse tree, is expanded with the
3127 ;; equivalent function `org-element-interpret-secondary'.
3128 ;;
3129 ;; Both functions rely internally on
3130 ;; `org-element-interpret--affiliated-keywords'.
3132 "Interpret a parse tree representing Org data.
3134 DATA is the parse tree to interpret.
3136 Optional arguments GENEALOGY and PREVIOUS are used for recursive
3137 calls:
3138 GENEALOGY is the list of its parents types.
3139 PREVIOUS is the type of the element or object at the same level
3140 interpreted before.
3142 Return Org syntax as a string."
3145 ;; BLOB can be an element, an object, a string, or nil.
3154 'identity
3158 ;; Full Org document.
3161 ;; Recursive objects.
3165 ;; Recursive elements.
3170 ;; Paragraphs.
3174 blob
3175 ;; When normalizing contents of an item,
3176 ;; ignore first line's indentation.
3183 ;; Update PREVIOUS.
3185 ;; Build white spaces.
3194 results
3200 "Interpret SECONDARY string as Org syntax.
3202 SECONDARY-STRING is a nested list as returned by
3203 `org-element-parse-secondary-string'.
3205 Return interpreted string."
3206 ;; Make SECONDARY acceptable for `org-element-interpret-data'.
3210 ;; Both functions internally use `org-element--affiliated-keywords'.
3213 "Return ELEMENT's affiliated keywords as Org syntax.
3214 If there is no affiliated keyword, return the empty string."
3224 value)
3235 ;; Remove translated keywords.
3240 org-element-affiliated-keywords))
3243 ;; Because interpretation of the parse tree must return the same
3244 ;; number of blank lines between elements and the same number of white
3245 ;; space after objects, some special care must be given to white
3246 ;; spaces.
3247 ;;
3248 ;; The first function, `org-element-normalize-string', ensures any
3249 ;; string different from the empty string will end with a single
3250 ;; newline character.
3251 ;;
3252 ;; The second function, `org-element-normalize-contents', removes
3253 ;; global indentation from the contents of the current element.
3255 "Ensure string S ends with a single newline character.
3257 If S isn't a string return it unchanged. If S is the empty
3258 string, return it. Otherwise, return a new string with a single
3259 newline character at its end."
3267 "Normalize plain text in ELEMENT's contents.
3269 ELEMENT must only contain plain text and objects.
3271 The following changes are applied to plain text:
3272 - Remove global indentation, preserving relative one.
3273 - Untabify it.
3275 If optional argument IGNORE-FIRST is non-nil, ignore first line's
3276 indentation to compute maximal common indentation.
3278 Return the normalized element."
3286 ;; 1. Remove tabs from each string in CONTENTS. Get maximal
3287 ;; common indentation (MCI) along the way.
3293 object
3299 ind-list))
3300 object)))
3301 contents))
3305 ;; 2. Remove that indentation from CONTENTS. First string
3306 ;; must be treated differently because it's the only one
3307 ;; whose indentation doesn't happen after a newline
3308 ;; character.
3317 object
3320 contents))))))))
3323 \f
3324 ;;; The Toolbox
3326 ;; Once the structure of an Org file is well understood, it's easy to
3327 ;; implement some replacements for `forward-paragraph'
3328 ;; `backward-paragraph', namely `org-element-forward' and
3329 ;; `org-element-backward'.
3331 ;; Also, `org-transpose-elements' mimics the behaviour of
3332 ;; `transpose-words', at the element's level, whereas
3333 ;; `org-element-drag-forward', `org-element-drag-backward', and
3334 ;; `org-element-up' generalize, respectively, functions
3335 ;; `org-subtree-down', `org-subtree-up' and `outline-up-heading'.
3337 ;; `org-element-unindent-buffer' will, as its name almost suggests,
3338 ;; smartly remove global indentation from buffer, making it possible
3339 ;; to use Org indent mode on a file created with hard indentation.
3341 ;; `org-element-nested-p' and `org-element-swap-A-B' are used
3342 ;; internally by some of the previously cited tools.
3344 "Non-nil when elements ELEM-A and ELEM-B are nested."
3353 "Swap elements ELEM-A and ELEM-B.
3355 Leave point at the end of ELEM-A.
3357 Assume ELEM-A is before ELEM-B and that they are not nested."
3379 "Move backward by one element."
3384 ;; At an headline. The previous element is the previous sibling,
3385 ;; or the parent if any.
3387 ;; Already at the beginning of the current element: move to the
3388 ;; beginning of the previous one.
3397 ;; When moving into a new list, go directly at the
3398 ;; beginning of the top list structure.
3406 ;; Else, move at the element beginning. One exception: if point
3407 ;; was in the blank lines after the end of a list, move directly
3408 ;; to the top item.
3415 opoint))
3422 "Drag backward element at point."
3439 ;; Compute new position of point: it's shifted by PREV-ELEM
3440 ;; body's length.
3447 "Move forward element at point."
3460 ;; Compute new position of point: it's shifted by NEXT-ELEM
3461 ;; body's length (without final blanks) and by the length of
3462 ;; blanks between ELEM and NEXT-ELEM.
3479 "Move forward by one element."
3490 ;; At an item: Either move to the next element inside, or
3491 ;; to its end if it's hidden.
3499 ;; At a recursive element: Either move inside, or if it's
3500 ;; hidden, move to its end.
3507 cbeg))))
3508 ;; Else: move to the current element's end.
3512 "Put point at beginning of this element, mark at end.
3514 Interactively, if this command is repeated or (in Transient Mark
3515 mode) if the mark is active, it marks the next element after the
3516 ones already marked."
3531 "Narrow buffer to current element."
3549 "Transpose current and previous elements, keeping blank lines between.
3550 Point is moved after both elements."
3569 "Un-indent the visible part of the buffer.
3570 Relative indentation \(between items, inside blocks, etc.\) isn't
3571 modified."
3576 unindent-tree ; For byte-compiler.
3594 "Move to upper element.
3595 Return position at the beginning of the upper element."
3606 ;; If parent is bound to be in the same list as the
3607 ;; original point, move to that parent.
3619 prev-elem)
3624 end)
3635 ;;; org-element.el ends here