| blob | 32486ae9900d0b563112198591a76db92f855bb4 |
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 ;; An object can be defined anywhere on a line. It may span over more
29 ;; than a line but never contains a blank one. Objects belong to the
30 ;; following types: `emphasis', `entity', `export-snippet',
31 ;; `footnote-reference', `inline-babel-call', `inline-src-block',
32 ;; `latex-fragment', `line-break', `link', `macro', `radio-target',
33 ;; `statistics-cookie', `subscript', `superscript', `target',
34 ;; `time-stamp' and `verbatim'.
36 ;; An element always starts and ends at the beginning of a line. The
37 ;; only element's type containing objects is called a `paragraph'.
38 ;; Other types are: `comment', `comment-block', `example-block',
39 ;; `export-block', `fixed-width', `horizontal-rule', `keyword',
40 ;; `latex-environment', `babel-call', `property-drawer',
41 ;; `quote-section', `src-block', `table' and `verse-block'.
43 ;; Elements containing paragraphs are called greater elements.
44 ;; Concerned types are: `center-block', `drawer', `dynamic-block',
45 ;; `footnote-definition', `headline', `inlinetask', `item',
46 ;; `plain-list', `quote-block' and `special-block'.
48 ;; Greater elements (excepted `headline' and `item' types) and
49 ;; elements (excepted `keyword', `babel-call', and `property-drawer'
50 ;; types) can have a fixed set of keywords as attributes. Those are
51 ;; called "affiliated keywords", to distinguish them from others
52 ;; keywords, which are full-fledged elements. In particular, the
53 ;; "name" affiliated keyword allows to label almost any element in an
54 ;; Org buffer.
56 ;; Notwithstanding affiliated keywords, each greater element, element
57 ;; and object has a fixed set of properties attached to it. Among
58 ;; them, three are shared by all types: `:begin' and `:end', which
59 ;; refer to the beginning and ending buffer positions of the
60 ;; considered element or object, and `:post-blank', which holds the
61 ;; number of blank lines, or white spaces, at its end.
63 ;; Some elements also have special properties whose value can hold
64 ;; objects themselves (i.e. an item tag, an headline name, a table
65 ;; cell). Such values are called "secondary strings".
67 ;; Lisp-wise, an element or an object can be represented as a list.
68 ;; It follows the pattern (TYPE PROPERTIES CONTENTS), where:
69 ;; TYPE is a symbol describing the Org element or object.
70 ;; PROPERTIES is the property list attached to it. See docstring of
71 ;; appropriate parsing function to get an exhaustive
72 ;; list.
73 ;; CONTENTS is a list of elements, objects or raw strings contained
74 ;; in the current element or object, when applicable.
76 ;; An Org buffer is a nested list of such elements and objects, whose
77 ;; type is `org-data' and properties is nil.
79 ;; The first part of this file implements a parser and an interpreter
80 ;; for each type of Org syntax.
82 ;; The next two parts introduce two accessors and a function
83 ;; retrieving the smallest element containing point (respectively
84 ;; `org-element-get-property', `org-element-get-contents' and
85 ;; `org-element-at-point').
87 ;; The following part creates a fully recursive buffer parser. It
88 ;; also provides a tool to map a function to elements or objects
89 ;; matching some criteria in the parse tree. Functions of interest
90 ;; are `org-element-parse-buffer', `org-element-map' and, to a lesser
91 ;; extent, `org-element-parse-secondary-string'.
93 ;; The penultimate part is the cradle of an interpreter for the
94 ;; obtained parse tree: `org-element-interpret-data' (and its
95 ;; relative, `org-element-interpret-secondary').
97 ;; The library ends by furnishing a set of interactive tools for
98 ;; element's navigation and manipulation.
101 ;;; Code:
107 \f
108 ;;; Greater elements
110 ;; For each greater element type, we define a parser and an
111 ;; interpreter.
113 ;; A parser (`item''s excepted) accepts no argument and represents the
114 ;; element or object as the list described above. An interpreter
115 ;; accepts two arguments: the list representation of the element or
116 ;; object, and its contents. The latter may be nil, depending on the
117 ;; element or object considered. It returns the appropriate Org
118 ;; syntax, as a string.
120 ;; Parsing functions must follow the naming convention:
121 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
122 ;; defined in `org-element-greater-elements'.
123 ;;
124 ;; Similarly, interpreting functions must follow the naming
125 ;; convention: org-element-TYPE-interpreter.
127 ;; With the exception of `headline' and `item' types, greater elements
128 ;; cannot contain other greater elements of their own type.
130 ;; Beside implementing a parser and an interpreter, adding a new
131 ;; greater element requires to tweak `org-element-guess-type'.
132 ;; Moreover, the newly defined type must be added to both
133 ;; `org-element-all-elements' and `org-element-greater-elements'.
136 ;;;; Center Block
138 "Parse a center block.
140 Return a list whose car is `center-block' and cdr is a plist
141 containing `:begin', `:end', `:hiddenp', `:contents-begin',
142 `:contents-end' and `:post-blank' keywords.
144 Assume point is at beginning or end of the block."
171 "Interpret CENTER-BLOCK element as Org syntax.
172 CONTENTS is the contents of the element."
175 ;;;; Drawer
177 "Parse a drawer.
179 Return a list whose car is `drawer' and cdr is a plist containing
180 `:drawer-name', `:begin', `:end', `:hiddenp', `:contents-begin',
181 `:contents-end' and `:post-blank' keywords.
183 Assume point is at beginning of drawer."
208 "Interpret DRAWER element as Org syntax.
209 CONTENTS is the contents of the element."
212 contents))
214 ;;;; Dynamic Block
216 "Parse a dynamic block.
218 Return a list whose car is `dynamic-block' and cdr is a plist
219 containing `:block-name', `:begin', `:end', `:hiddenp',
220 `:contents-begin', `:contents-end', `:arguments' and
221 `:post-blank' keywords.
223 Assume point is at beginning of dynamic block."
250 "Interpret DYNAMIC-BLOCK element as Org syntax.
251 CONTENTS is the contents of the element."
256 contents))
258 ;;;; Footnote Definition
261 "Parse a footnote definition.
263 Return a list whose car is `footnote-definition' and cdr is
264 a plist containing `:label', `:begin' `:end', `:contents-begin',
265 `:contents-end' and `:post-blank' keywords."
290 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
291 CONTENTS is the contents of the footnote-definition."
293 " "
294 contents))
297 ;;;; Headline
299 "Parse an headline.
301 Return a list whose car is `headline' and cdr is a plist
302 containing `:raw-value', `:title', `:begin', `:end',
303 `:pre-blank', `:hiddenp', `:contents-begin' and `:contents-end',
304 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
305 `:scheduled', `:deadline', `:timestamp', `:clock', `:category',
306 `:quotedp', `:archivedp', `:commentedp' and `:footnote-section-p'
307 keywords.
309 The plist also contains any property set in the property drawer,
310 with its name in lowercase, the underscores replaced with hyphens
311 and colons at the beginning (i.e. `:custom-id').
313 Assume point is at beginning of the headline."
340 plist))
356 title)
357 ;; Clean RAW-VALUE from any quote or comment string.
362 ""
363 raw-value)))
364 ;; Clean TAGS from archive tag, if any.
371 ;; Then get TITLE.
373 raw-value
401 "Interpret HEADLINE element as Org syntax.
402 CONTENTS is the contents of the element."
427 ;; Align tags.
437 tags-len)
441 contents)))
443 ;;;; Inlinetask
445 "Parse an inline task.
447 Return a list whose car is `inlinetask' and cdr is a plist
448 containing `:raw-value', `:title', `:begin', `:end', `:hiddenp',
449 `:contents-begin' and `:contents-end', `:level', `:priority',
450 `:raw-value', `:tags', `:todo-keyword', `:todo-type',
451 `:scheduled', `:deadline', `:timestamp', `:clock' and
452 `:post-blank' keywords.
454 The plist also contains any property set in the property drawer,
455 with its name in lowercase, the underscores replaced with hyphens
456 and colons at the beginning (i.e. `:custom-id').
458 Assume point is at beginning of the inline task."
478 plist))
485 raw-value
490 ;; In the case of a single line task, CONTENTS-BEGIN and
491 ;; CONTENTS-END might overlap.
514 ,@standard-props
518 "Interpret INLINETASK element as Org syntax.
519 CONTENTS is the contents of inlinetask."
529 ;; Align tags.
543 ;;;; Item
545 "Parse an item.
547 STRUCT is the structure of the plain list.
549 Return a list whose car is `item' and cdr is a plist containing
550 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
551 `:checkbox', `:counter', `:tag', `:raw-tag', `:structure',
552 `:hiddenp' and `:post-blank' keywords.
554 Assume point is at the beginning of the item."
574 raw-tag
594 ;; CONTENTS-BEGIN and CONTENTS-END may be mixed
595 ;; up in the case of an empty item separated
596 ;; from the next by a blank line. Thus, ensure
597 ;; the former is always the smallest of two.
609 "Interpret ITEM element as Org syntax.
610 CONTENTS is the contents of the element."
615 ;; Compute indentation.
617 ;; Indent contents.
619 bullet
633 ;;;; Plain List
635 "Parse a plain list.
637 Return a list whose car is `plain-list' and cdr is a plist
638 containing `:type', `:begin', `:end', `:contents-begin' and
639 `:contents-end', `:level', `:structure' and `:post-blank'
640 keywords.
642 Assume point is at one of the list items."
657 ;; Get list level.
662 struct parents))
664 ;; Blank lines below list belong to the top-level list only.
669 ;; Return value.
682 "Interpret PLAIN-LIST element as Org syntax.
683 CONTENTS is the contents of the element."
684 contents)
686 ;;;; Quote Block
688 "Parse a quote block.
690 Return a list whose car is `quote-block' and cdr is a plist
691 containing `:begin', `:end', `:hiddenp', `:contents-begin',
692 `:contents-end' and `:post-blank' keywords.
694 Assume point is at beginning or end of the block."
722 "Interpret QUOTE-BLOCK element as Org syntax.
723 CONTENTS is the contents of the element."
726 ;;;; Special Block
728 "Parse a special block.
730 Return a list whose car is `special-block' and cdr is a plist
731 containing `:type', `:begin', `:end', `:hiddenp',
732 `:contents-begin', `:contents-end' and `:post-blank' keywords.
734 Assume point is at beginning or end of the block."
765 "Interpret SPECIAL-BLOCK element as Org syntax.
766 CONTENTS is the contents of the element."
771 \f
772 ;;; Elements
774 ;; For each element, a parser and an interpreter are also defined.
775 ;; Both follow the same naming convention used for greater elements.
777 ;; Also, as for greater elements, adding a new element type is done
778 ;; through the following steps: implement a parser and an interpreter,
779 ;; tweak `org-element-guess-type' so that it recognizes the new type
780 ;; and add that new type to `org-element-all-elements'.
782 ;; As a special case, when the newly defined type is a block type,
783 ;; `org-element-non-recursive-block-alist' has to be modified
784 ;; accordingly.
787 ;;;; Babel Call
789 "Parse a babel call.
791 Return a list whose car is `babel-call' and cdr is a plist
792 containing `:begin', `:end', `:info' and `:post-blank' as
793 keywords."
808 "Interpret INLINE-BABEL-CALL object as Org syntax.
809 CONTENTS is nil."
815 ;; Remove redundant square brackets.
818 main-source)
821 ;;;; Comment
823 "Parse a comment.
825 Return a list whose car is `comment' and cdr is a plist
826 containing `:begin', `:end', `:value' and `:post-blank'
827 keywords."
829 beg-coms begin end value pos-before-blank keywords)
831 ;; Move to the beginning of comments.
837 ;; Get affiliated keywords, if any.
839 ;; Store true beginning of element.
841 ;; Get ending of comments. If point is in a list, ensure to not
842 ;; get outside of it.
851 ;; Find position after blank.
854 ;; Extract value.
864 "Interpret COMMENT element as Org syntax.
865 CONTENTS is nil."
868 ;;;; Comment Block
870 "Parse an export block.
872 Return a list whose car is `comment-block' and cdr is a plist
873 containing `:begin', `:end', `:hiddenp', `:value' and
874 `:post-blank' keywords."
900 "Interpret COMMENT-BLOCK element as Org syntax.
901 CONTENTS is nil."
907 ;;;; Example Block
909 "Parse an example block.
911 Return a list whose car is `example' and cdr is a plist
912 containing `:begin', `:end', `:options', `:hiddenp', `:value' and
913 `:post-blank' keywords."
942 "Interpret EXAMPLE-BLOCK element as Org syntax.
943 CONTENTS is nil."
950 ;;;; Export Block
952 "Parse an export block.
954 Return a list whose car is `export-block' and cdr is a plist
955 containing `:begin', `:end', `:type', `:hiddenp', `:value' and
956 `:post-blank' keywords."
986 "Interpret EXPORT-BLOCK element as Org syntax.
987 CONTENTS is nil."
993 ;;;; Fixed-width
995 "Parse a fixed-width section.
997 Return a list whose car is `fixed-width' and cdr is a plist
998 containing `:begin', `:end', `:value' and `:post-blank'
999 keywords."
1001 beg-area begin end value pos-before-blank keywords)
1003 ;; Move to the beginning of the fixed-width area.
1009 ;; Get affiliated keywords, if any.
1011 ;; Store true beginning of element.
1013 ;; Get ending of fixed-width area. If point is in a list,
1014 ;; ensure to not get outside of it.
1023 ;; Find position after blank
1026 ;; Extract value.
1036 "Interpret FIXED-WIDTH element as Org syntax.
1037 CONTENTS is nil."
1040 ;;;; Horizontal Rule
1042 "Parse an horizontal rule.
1044 Return a list whose car is `horizontal-rule' and cdr is
1045 a plist containing `:begin', `:end' and `:post-blank'
1046 keywords."
1060 "Interpret HORIZONTAL-RULE element as Org syntax.
1061 CONTENTS is nil."
1064 ;;;; Keyword
1066 "Parse a keyword at point.
1068 Return a list whose car is `keyword' and cdr is a plist
1069 containing `:key', `:value', `:begin', `:end' and `:post-blank'
1070 keywords."
1089 "Interpret KEYWORD element as Org syntax.
1090 CONTENTS is nil."
1095 ;;;; Latex Environment
1097 "Parse a LaTeX environment.
1099 Return a list whose car is `latex-environment' and cdr is a plist
1100 containing `:begin', `:end', `:value' and `:post-blank' keywords."
1121 "Interpret LATEX-ENVIRONMENT element as Org syntax.
1122 CONTENTS is nil."
1125 ;;;; Paragraph
1127 "Parse a paragraph.
1129 Return a list whose car is `paragraph' and cdr is a plist
1130 containing `:begin', `:end', `:contents-begin' and
1131 `:contents-end' and `:post-blank' keywords.
1133 Assume point is at the beginning of the paragraph."
1156 "Interpret PARAGRAPH element as Org syntax.
1157 CONTENTS is the contents of the element."
1158 contents)
1160 ;;;; Property Drawer
1162 "Parse a property drawer.
1164 Return a list whose car is `property-drawer' and cdr is a plist
1165 containing `:begin', `:end', `:hiddenp', `:contents-begin',
1166 `:contents-end', `:properties' and `:post-blank' keywords."
1183 val))
1185 val))
1199 "Interpret PROPERTY-DRAWER element as Org syntax.
1200 CONTENTS is nil."
1209 ;;;; Quote Section
1211 "Parse a quote section.
1213 Return a list whose car is `quote-section' and cdr is a plist
1214 containing `:begin', `:end', `:value' and `:post-blank'
1215 keywords."
1237 "Interpret QUOTE-SECTION element as Org syntax.
1238 CONTENTS is nil."
1241 ;;;; Src Block
1243 "Parse a src block.
1245 Return a list whose car is `src-block' and cdr is a plist
1246 containing `:language', `:switches', `:parameters', `:begin',
1247 `:end', `:hiddenp', `:contents-begin', `:contents-end', `:value'
1248 and `:post-blank' keywords."
1252 ;; Get position at beginning of block.
1259 nil t))
1260 ;; Get language as a string.
1262 ;; Get switches.
1264 ;; Get parameters.
1266 ;; Get affiliated keywords.
1268 ;; Get beginning position.
1270 ;; Get position at end of block.
1274 ;; Retrieve code.
1280 ;; Get position after ending blank lines.
1283 ;; Get visibility status.
1299 "Interpret SRC-BLOCK element as Org syntax.
1300 CONTENTS is nil."
1319 value
1322 ;;;; Table
1324 "Parse a table at point.
1326 Return a list whose car is `table' and cdr is a plist containing
1327 `:begin', `:end', `:contents-begin', `:contents-end', `:tblfm',
1328 `:type', `:raw-table' and `:post-blank' keywords."
1353 "Interpret TABLE element as Org syntax.
1354 CONTENTS is nil."
1357 ;;;; Verse Block
1359 "Parse a verse block.
1361 Return a list whose car is `verse-block' and cdr is a plist
1362 containing `:begin', `:end', `:hiddenp', `:raw-value', `:value'
1363 and `:post-blank' keywords.
1365 Assume point is at beginning or end of the block."
1397 "Interpret VERSE-BLOCK element as Org syntax.
1398 CONTENTS is nil."
1404 \f
1405 ;;; Objects
1407 ;; Unlike to elements, interstices can be found between objects.
1408 ;; That's why, along with the parser, successor functions are provided
1409 ;; for each object. Some objects share the same successor
1410 ;; (i.e. `emphasis' and `verbatim' objects).
1412 ;; A successor must accept a single argument bounding the search. It
1413 ;; will return either a cons cell whose car is the object's type, as
1414 ;; a symbol, and cdr the position of its next occurrence, or nil.
1416 ;; Successors follow the naming convention:
1417 ;; org-element-NAME-successor, where NAME is the name of the
1418 ;; successor, as defined in `org-element-all-successors'.
1420 ;; Some object types (i.e `emphasis') are recursive. Restrictions on
1421 ;; object types they can contain will be specified in
1422 ;; `org-element-object-restrictions'.
1424 ;; Adding a new type of object is simple. Implement a successor,
1425 ;; a parser, and an interpreter for it, all following the naming
1426 ;; convention. Register successor in `org-element-all-successors',
1427 ;; maybe tweak restrictions about it, and that's it.
1429 ;;;; Emphasis
1431 "Parse text markup object at point.
1433 Return a list whose car is `emphasis' and cdr is a plist with
1434 `:marker', `:begin', `:end', `:contents-begin' and
1435 `:contents-end' and `:post-blank' keywords.
1437 Assume point is at the first emphasis marker."
1457 "Interpret EMPHASIS object as Org syntax.
1458 CONTENTS is the contents of the object."
1463 "Search for the next emphasis or verbatim and return position.
1465 LIMIT bounds the search.
1467 Return value is a cons cell whose car is `emphasis' or
1468 `verbatim' and cdr is beginning position."
1473 'verbatim
1477 ;;;; Entity
1479 "Parse entity at point.
1481 Return a list whose car is `entity' and cdr a plist with
1482 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
1483 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
1484 keywords.
1486 Assume point is at the beginning of the entity."
1510 "Interpret ENTITY object as Org syntax.
1511 CONTENTS is nil."
1517 "Search for the next latex-fragment or entity object.
1519 LIMIT bounds the search.
1521 Return value is a cons cell whose car is `entity' or
1522 `latex-fragment' and cdr is beginning position."
1525 ;; ENTITY-RE matches both LaTeX commands and Org entities.
1532 limit t)
1535 ;; Determine if it's a real entity or a LaTeX command.
1538 ;; No entity nor command: point is at a LaTeX fragment.
1539 ;; Determine its type to get the correct beginning position.
1547 matchers)
1550 ;;;; Export Snippet
1552 "Parse export snippet at point.
1554 Return a list whose car is `export-snippet' and cdr a plist with
1555 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
1556 keywords.
1558 Assume point is at the beginning of the snippet."
1576 "Interpret EXPORT-SNIPPET object as Org syntax.
1577 CONTENTS is nil."
1583 "Search for the next export-snippet object.
1585 LIMIT bounds the search.
1587 Return value is a cons cell whose car is `export-snippet' cdr is
1588 its beginning position."
1596 ;;;; Footnote Reference
1599 "Parse footnote reference at point.
1601 Return a list whose car is `footnote-reference' and cdr a plist
1602 with `:label', `:type', `:definition', `:begin', `:end' and
1603 `:post-blank' as keywords."
1625 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
1626 CONTENTS is nil."
1635 "Search for the next footnote-reference and return beginning
1636 position.
1638 LIMIT bounds the search.
1640 Return value is a cons cell whose car is `footnote-reference' and
1641 cdr is beginning position."
1647 ;;;; Inline Babel Call
1649 "Parse inline babel call at point.
1651 Return a list whose car is `inline-babel-call' and cdr a plist with
1652 `:begin', `:end', `:info' and `:post-blank' as keywords.
1654 Assume point is at the beginning of the babel call."
1670 "Interpret INLINE-BABEL-CALL object as Org syntax.
1671 CONTENTS is nil."
1677 ;; Remove redundant square brackets.
1680 main-source)
1684 "Search for the next inline-babel-call and return beginning
1685 position.
1687 LIMIT bounds the search.
1689 Return value is a cons cell whose car is `inline-babel-call' and
1690 cdr is beginning position."
1692 ;; Use a simplified version of
1693 ;; org-babel-inline-lob-one-liner-regexp as regexp for more speed.
1695 "\\(?:babel\\|call\\)_\\([^()\n]+?\\)\\(\\[\\(.*\\)\\]\\|\\(\\)\\)(\\([^\n]*\\))\\(\\[\\(.*?\\)\\]\\)?"
1696 limit t)
1699 ;;;; Inline Src Block
1701 "Parse inline source block at point.
1703 Return a list whose car is `inline-src-block' and cdr a plist
1704 with `:begin', `:end', `:language', `:value', `:parameters' and
1705 `:post-blank' as keywords.
1707 Assume point is at the beginning of the inline src block."
1729 "Search for the next inline-babel-call and return beginning position.
1731 LIMIT bounds the search.
1733 Return value is a cons cell whose car is `inline-babel-call' and
1734 cdr is beginning position."
1739 ;;;; Latex Fragment
1741 "Parse latex fragment at point.
1743 Return a list whose car is `latex-fragment' and cdr a plist with
1744 `:value', `:begin', `:end', and `:post-blank' as keywords.
1746 Assume point is at the beginning of the latex fragment."
1760 ;; None found: it's a macro.
1774 "Interpret LATEX-FRAGMENT object as Org syntax.
1775 CONTENTS is nil."
1778 ;;;; Line Break
1780 "Parse line break at point.
1782 Return a list whose car is `line-break', and cdr a plist with
1783 `:begin', `:end' and `:post-blank' keywords.
1785 Assume point is at the beginning of the line break."
1797 "Interpret LINE-BREAK object as Org syntax.
1798 CONTENTS is nil."
1802 "Search for the next statistics cookie and return position.
1804 LIMIT bounds the search.
1806 Return value is a cons cell whose car is `line-break' and cdr is
1807 beginning position."
1811 ;; A line break can only happen on a non-empty line.
1815 ;;;; Link
1817 "Parse link at point.
1819 Return a list whose car is `link' and cdr a plist with `:type',
1820 `:path', `:raw-link', `:begin', `:end', `:contents-begin',
1821 `:contents-end' and `:post-blank' as keywords.
1823 Assume point is at the beginning of the link."
1826 end contents-begin contents-end link-end post-blank path type
1827 raw-link link)
1829 ;; Type 1: text targeted from a radio target.
1836 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
1841 ;; RAW-LINK is the original link.
1846 ;; Determine TYPE of link and set PATH accordingly.
1848 ;; File type.
1851 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
1854 ;; Id type: PATH is the id.
1857 ;; Code-ref type: PATH is the name of the reference.
1860 ;; Custom-id type: PATH is the name of the custom id.
1863 ;; Fuzzy type: Internal link either matches a target, an
1864 ;; headline name or nothing. PATH is the target or headline's
1865 ;; name.
1867 ;; Type 3: Plain link, i.e. http://orgmode.org
1873 ;; Type 4: Angular link, i.e. <http://orgmode.org>
1880 ;; In any case, deduce end point after trailing white space from
1881 ;; LINK-END variable.
1895 "Interpret LINK object as Org syntax.
1896 CONTENTS is the contents of the object."
1902 raw-link
1906 "Search for the next link and return position.
1908 LIMIT bounds the search.
1910 Return value is a cons cell whose car is `link' and cdr is
1911 beginning position."
1916 org-any-link-re)))
1920 ;;;; Macro
1922 "Parse macro at point.
1924 Return a list whose car is `macro' and cdr a plist with `:key',
1925 `:args', `:begin', `:end', `:value' and `:post-blank' as
1926 keywords.
1928 Assume point is at the macro."
1942 ;; Repair bad splits.
1957 "Interpret MACRO object as Org syntax.
1958 CONTENTS is nil."
1962 "Search for the next macro and return position.
1964 LIMIT bounds the search.
1966 Return value is cons cell whose car is `macro' and cdr is
1967 beginning position."
1971 limit t)
1974 ;;;; Radio-target
1976 "Parse radio target at point.
1978 Return a list whose car is `radio-target' and cdr a plist with
1979 `:begin', `:end', `:contents-begin', `:contents-end', `raw-value'
1980 and `:post-blank' as keywords.
1982 Assume point is at the radio target."
2001 "Interpret TARGET object as Org syntax.
2002 CONTENTS is the contents of the object."
2006 "Search for the next radio-target and return position.
2008 LIMIT bounds the search.
2010 Return value is a cons cell whose car is `radio-target' and cdr
2011 is beginning position."
2016 ;;;; Statistics Cookie
2018 "Parse statistics cookie at point.
2020 Return a list whose car is `statistics-cookie', and cdr a plist
2021 with `:begin', `:end', `:value' and `:post-blank' keywords.
2023 Assume point is at the beginning of the statistics-cookie."
2039 "Interpret STATISTICS-COOKIE object as Org syntax.
2040 CONTENTS is nil."
2044 "Search for the next statistics cookie and return position.
2046 LIMIT bounds the search.
2048 Return value is a cons cell whose car is `statistics-cookie' and
2049 cdr is beginning position."
2054 ;;;; Subscript
2056 "Parse subscript at point.
2058 Return a list whose car is `subscript' and cdr a plist with
2059 `:begin', `:end', `:contents-begin', `:contents-end',
2060 `:use-brackets-p' and `:post-blank' as keywords.
2062 Assume point is at the underscore."
2066 t
2084 "Interpret SUBSCRIPT object as Org syntax.
2085 CONTENTS is the contents of the object."
2088 contents))
2091 "Search for the next sub/superscript and return beginning
2092 position.
2094 LIMIT bounds the search.
2096 Return value is a cons cell whose car is either `subscript' or
2097 `superscript' and cdr is beginning position."
2103 ;;;; Superscript
2105 "Parse superscript at point.
2107 Return a list whose car is `superscript' and cdr a plist with
2108 `:begin', `:end', `:contents-begin', `:contents-end',
2109 `:use-brackets-p' and `:post-blank' as keywords.
2111 Assume point is at the caret."
2115 t
2133 "Interpret SUPERSCRIPT object as Org syntax.
2134 CONTENTS is the contents of the object."
2137 contents))
2139 ;;;; Target
2141 "Parse target at point.
2143 Return a list whose car is `target' and cdr a plist with
2144 `:begin', `:end', `:contents-begin', `:contents-end', `raw-value'
2145 and `:post-blank' as keywords.
2147 Assume point is at the target."
2166 "Interpret TARGET object as Org syntax.
2167 CONTENTS is the contents of target."
2171 "Search for the next target and return position.
2173 LIMIT bounds the search.
2175 Return value is a cons cell whose car is `target' and cdr is
2176 beginning position."
2181 ;;;; Time-stamp
2183 "Parse time stamp at point.
2185 Return a list whose car is `time-stamp', and cdr a plist with
2186 `:appt-type', `:type', `:begin', `:end', `:value' and
2187 `:post-blank' keywords.
2189 Assume point is at the beginning of the time-stamp."
2227 "Interpret TIME-STAMP object as Org syntax.
2228 CONTENTS is nil."
2237 "Search for the next time-stamp and return position.
2239 LIMIT bounds the search.
2241 Return value is a cons cell whose car is `time-stamp' and cdr is
2242 beginning position."
2247 org-ts-regexp-both
2252 limit t)
2255 ;;;; Verbatim
2257 "Parse verbatim object at point.
2259 Return a list whose car is `verbatim' and cdr is a plist with
2260 `:marker', `:begin', `:end' and `:post-blank' keywords.
2262 Assume point is at the first verbatim marker."
2280 "Interpret VERBATIM object as Org syntax.
2281 CONTENTS is nil."
2287 \f
2288 ;;; Definitions And Rules
2290 ;; Define elements, greater elements and specify recursive objects,
2291 ;; along with the affiliated keywords recognized. Also set up
2292 ;; restrictions on recursive objects combinations.
2294 ;; These variables really act as a control center for the parsing
2295 ;; process.
2298 ;; Headlines and inlinetasks.
2300 ;; Comments, blocks (any type), keywords and babel calls.
2302 ;; Lists.
2304 ;; Fixed-width, drawers (any type) and tables.
2306 ;; Footnote definitions.
2308 ;; Horizontal rules.
2310 ;; LaTeX environments.
2316 export-block fixed-width footnote-definition headline
2317 horizontal-rule inlinetask item keyword latex-environment
2318 babel-call paragraph plain-list property-drawer quote-block
2319 quote-section special-block src-block table verse-block)
2324 item plain-list quote-block special-block)
2329 latex-or-entity line-break link macro radio-target
2330 statistics-cookie sub/superscript target text-markup
2331 time-stamp)
2338 "Alist of translations between object type and successor name.
2340 Sharing the same successor comes handy when, for example, the
2369 "Alist of usual translations for keywords.
2370 The key is the old name and the value the new one. The property
2375 "List of affiliated keywords that can occur more that once in an element.
2377 Their value will be consed into a list of strings, which will be
2378 returned as the value of the property.
2380 This list is checked after translations have been applied. See
2384 "List of keywords whose value can be parsed.
2386 Their value will be stored as a secondary string: a list of
2387 strings and objects.
2389 This list is checked after translations have been applied. See
2393 "List of keywords which can have a secondary value.
2395 In Org syntax, they can be written with optional square brackets
2396 before the colons. For example, results keyword can be
2397 associated to a hash value with the following:
2399 #+results[hash-string]: some-source
2401 This list is checked after translations have been applied. See
2415 "Alist of recursive objects restrictions.
2417 Car is a recursive object type and cdr is a list of successors
2418 that will be called within an object of such type.
2420 For example, in a `radio-target' object, one can only find
2421 entities, export snippets, latex-fragments, subscript and
2434 latex-fragment line-break link macro radio-target sub/superscript
2435 target text-markup time-stamp))
2436 "Alist of secondary strings restrictions.
2438 When parsed, some elements have a secondary string which could
2439 contain various objects (i.e. headline's name, or table's cells).
2440 For association, the car is the element type, and the cdr a list
2441 of successors that will be called in that secondary string.
2443 Note: `keyword' secondary string type only applies to keywords
2447 \f
2448 ;;; Accessors
2449 ;;
2450 ;; Provide two accessors: `org-element-get-property' and
2451 ;; `org-element-get-contents'.
2453 "Extract the value from the PROPERTY of an ELEMENT."
2457 "Extract contents from an ELEMENT."
2461 \f
2462 ;; Obtaining The Smallest Element Containing Point
2464 ;; `org-element-at-point' is the core function of this section. It
2465 ;; returns the Lisp representation of the element at point. It uses
2466 ;; `org-element-guess-type' and `org-element-skip-keywords' as helper
2467 ;; functions.
2469 ;; When point is at an item, there is no automatic way to determine if
2470 ;; the function should return the `plain-list' element, or the
2471 ;; corresponding `item' element. By default, `org-element-at-point'
2472 ;; works at the `plain-list' level. But, by providing an optional
2473 ;; argument, one can make it switch to the `item' level.
2483 "Regexp matching any affiliated keyword.
2485 Keyword name is put in match group 1. Moreover, if keyword
2486 belongs to `org-element-dual-keywords', put the dual value in
2487 match group 2.
2492 "Determine closest element around point.
2494 Return value is a list \(TYPE PROPS\) where TYPE is the type of
2495 the element and PROPS a plist of properties associated to the
2496 element.
2498 Possible types are defined in `org-element-all-elements'.
2500 If optional argument TOGGLE-ITEM is non-nil, parse item wise
2501 instead of plain-list wise, using STRUCTURE as the current list
2502 structure.
2504 If STRUCTURE isn't provided but TOGGLE-ITEM is non-nil, it will
2505 be computed."
2508 ;; Move before any blank line.
2513 ;; Check if point is at an affiliated keyword. In that case,
2514 ;; try moving to the beginning of the associated element. If
2515 ;; the keyword is orphaned, treat it as plain text.
2522 ;; Guessing element type on the current line is impossible:
2523 ;; try to find the beginning of the current element to get
2524 ;; more information.
2533 ;; Unable to find a paragraph delimiter above: we're at
2534 ;; bob and looking at a paragraph.
2536 ;; Trying to find element's beginning set point back to
2537 ;; its original position. There's something peculiar on
2538 ;; this line that prevents parsing, probably an
2539 ;; ill-formed keyword or an undefined drawer name. Parse
2540 ;; it as plain text anyway.
2542 ;; Original point wasn't in a list but previous paragraph
2543 ;; is. It means that either point was inside some block,
2544 ;; or current list was ended without using a blank line.
2545 ;; In the last case, paragraph really starts at list end.
2562 ;; In any other case, the paragraph started the line
2563 ;; below.
2569 ;; Straightforward case: call the appropriate parser.
2573 ;; It is obvious to tell if point is in most elements, either by
2574 ;; looking for a specific regexp in the current line, or by using
2575 ;; already implemented functions. This is the goal of
2576 ;; `org-element-guess-type'.
2579 "List of non-recursive block types, as strings.
2580 Used internally by `org-element-guess-type'. Do not modify it
2584 "Return the type of element at point, or nil if undetermined.
2585 This function may move point to an appropriate position for
2586 parsing. Used internally by `org-element-at-point'."
2587 ;; Beware: Order matters for some cases in that function.
2596 headline))))
2598 ;; Non-recursive block.
2604 ;; Property drawer. Almost `org-at-property-p', but allow drawer
2605 ;; boundaries.
2613 ;; Recursive block. If the block isn't complete, parse the
2614 ;; current part as a paragraph.
2622 ;; Regular drawers must be tested after property drawer as both
2623 ;; elements share the same ending regexp.
2628 'paragraph
2631 ;; Babel calls must be tested before general keywords as they are
2632 ;; a subset of them.
2637 'paragraph
2639 ;; Dynamic block: simplify regexp used for match. If it isn't
2640 ;; complete, parse the current part as a paragraph.
2646 'paragraph
2653 ;; A TBLFM line separated from any table is just plain text.
2655 'table
2659 ;; Most elements can have affiliated keywords. When looking for an
2660 ;; element beginning, we want to move before them, as they belong to
2661 ;; that element, and, in the meantime, collect information they give
2662 ;; into appropriate properties. Hence the following function.
2664 ;; Usage of optional arguments may not be obvious at first glance:
2666 ;; - TRANS-LIST is used to polish keywords names that have evolved
2667 ;; during Org history. In example, even though =result= and
2668 ;; =results= coexist, we want to have them under the same =result=
2669 ;; property. It's also true for "srcname" and "name", where the
2670 ;; latter seems to be preferred nowadays (thus the "name" property).
2672 ;; - CONSED allows to regroup multi-lines keywords under the same
2673 ;; property, while preserving their own identity. This is mostly
2674 ;; used for "attr_latex" and al.
2676 ;; - PARSED prepares a keyword value for export. This is useful for
2677 ;; "caption". Objects restrictions for such keywords are defined in
2678 ;; `org-element-string-restrictions'.
2680 ;; - DUALS is used to take care of keywords accepting a main and an
2681 ;; optional secondary values. For example "results" has its
2682 ;; source's name as the main value, and may have an hash string in
2683 ;; optional square brackets as the secondary one.
2685 ;; A keyword may belong to more than one category.
2687 consed parsed duals)
2688 "Collect affiliated keywords before point.
2690 Optional argument KEY-RE is a regexp matching keywords, which
2691 puts matched keyword in group 1. It defaults to
2692 `org-element--affiliated-re'.
2694 TRANS-LIST is an alist where key is the keyword and value the
2695 property name it should be translated to, without the colons. It
2696 defaults to `org-element-keyword-translation-alist'.
2698 CONSED is a list of strings. Any keyword belonging to that list
2699 will have its value consed. The check is done after keyword
2700 translation. It defaults to `org-element-multiple-keywords'.
2702 PARSED is a list of strings. Any keyword member of this list
2703 will have its value parsed. The check is done after keyword
2704 translation. If a keyword is a member of both CONSED and PARSED,
2705 it's value will be a list of parsed strings. It defaults to
2706 `org-element-parsed-keywords'.
2708 DUALS is a list of strings. Any keyword member of this list can
2709 have two parts: one mandatory and one optional. Its value is
2710 a cons cell whose car is the former, and the cdr the latter. If
2711 a keyword is a member of both PARSED and DUALS, only the primary
2712 part will be parsed. It defaults to `org-element-dual-keywords'.
2714 Return a list whose car is the position at the first of them and
2715 cdr a plist of keywords and values."
2723 output)
2728 ;; Apply translation to RAW-KWD. From there, KWD is
2729 ;; the official keyword.
2731 ;; If KWD is a dual keyword, find it secondary value.
2734 ;; Find main value for any keyword.
2737 ;; Attribute a property name to KWD.
2739 ;; Now set final shape for VALUE.
2743 value
2748 ;; Eventually store the new value in OUTPUT.
2754 \f
2755 ;;; The Org Parser
2757 ;; The two major functions here are `org-element-parse-buffer', which
2758 ;; parses Org syntax inside the current buffer, taking into account
2759 ;; region, narrowing, or even visibility if specified, and
2760 ;; `org-element-parse-secondary-string', which parses objects within
2761 ;; a given string.
2763 ;; The (almost) almighty `org-element-map' allows to apply a function
2764 ;; on elements or objects matching some type, and accumulate the
2765 ;; resulting values. In an export situation, it also skips unneeded
2766 ;; parts of the parse tree, transparently walks into included files,
2767 ;; and maintain a list of local properties (i.e. those inherited from
2768 ;; parent headlines) for function's consumption.
2770 "Recursively parse the buffer and return structure.
2771 If narrowing is in effect, only parse the visible part of the
2772 buffer.
2774 Optional argument GRANULARITY determines the depth of the
2775 recursion. It can be set to the following symbols:
2777 `headline' Only parse headlines.
2778 `greater-element' Don't recurse into greater elements. Thus,
2779 elements parsed are the top-level ones.
2780 `element' Parse everything but objects and plain text.
2781 `object' Parse the complete buffer (default).
2783 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
2784 elements.
2786 Assume buffer is in Org mode."
2793 nil nil granularity visible-only nil))))
2796 "Recursively parse objects in STRING and return structure.
2798 RESTRICTION, when non-nil, is a symbol limiting the object types
2799 that will be looked after.
2801 Optional argument BUFFER indicates the buffer from where the
2802 secondary string was extracted. It is used to determine where to
2803 get extraneous information for an object \(i.e. when resolving
2804 a link or looking for a footnote definition\). It defaults to
2805 the current buffer."
2811 "Map a function on selected elements or objects.
2813 DATA is the parsed tree, as returned by, i.e,
2814 `org-element-parse-buffer'. TYPES is a symbol or list of symbols
2815 of elements or objects types. FUN is the function called on the
2816 matching element or object. It must accept two arguments: the
2817 element or object itself and a plist holding contextual
2818 information.
2820 When optional argument INFO is non-nil, it should be a plist
2821 holding export options. In that case, parts of the parse tree
2822 not exportable according to that property list will be skipped
2823 and files included through a keyword will be visited.
2825 When optional argument FIRST-MATCH is non-nil, stop at the first
2826 match for which FUN doesn't return nil, and return that value.
2828 Nil values returned from FUN are ignored in the result."
2829 ;; Ensure TYPES is a list, even of one element.
2831 ;; Recursion depth is determined by --CATEGORY.
2841 walk-tree ; For byte-compiler
2842 --acc
2846 ;; Check if TYPE is matching among TYPES. If so, apply
2847 ;; FUN to --BLOB and accumulate return value
2848 ;; into --ACC. --LOCAL is the communication channel.
2857 ;; Recursively walk DATA. --LOCAL, if non-nil, is
2858 ;; a plist holding contextual information.
2862 ;; Determine if a recursion into --BLOB is
2863 ;; possible and allowed.
2865 ;; Element or object not exportable.
2867 ;; Archived headline: Maybe apply fun on it, but
2868 ;; skip contents.
2874 ;; At an include keyword: apply mapping to its
2875 ;; contents.
2889 walk-tree --data
2891 --local
2892 ;; Store full path of already included files
2893 ;; to avoid recursive file inclusion.
2894 `(:included-files
2897 ;; Ensure that a top-level headline in the
2898 ;; included file becomes a direct child of
2899 ;; the current headline in the buffer.
2900 :headline-offset
2906 --data --local))))))))
2907 ;; Limiting recursion to greater elements, and --BLOB
2908 ;; isn't one.
2912 ;; Limiting recursion to elements, and --BLOB only
2913 ;; contains objects.
2915 ;; No limitation on recursion, but --BLOB hasn't
2916 ;; got a recursive type.
2922 ;; Recursion is possible and allowed: Update local
2923 ;; information and move into --BLOB.
2926 walk-tree --blob
2931 ;; Return value in a proper order.
2934 ;; The following functions are internal parts of the parser. The
2935 ;; first one, `org-element-parse-elements' acts at the element's
2936 ;; level. The second one, `org-element-parse-objects' applies on all
2937 ;; objects of a paragraph or a secondary string. It uses
2938 ;; `org-element-get-candidates' to optimize the search of the next
2939 ;; object in the buffer.
2940 ;;
2941 ;; More precisely, that function looks for every allowed object type
2942 ;; first. Then, it discards failed searches, keeps further matches,
2943 ;; and searches again types matched behind point, for subsequent
2944 ;; calls. Thus, searching for a given type fails only once, and every
2945 ;; object is searched only once at top level (but sometimes more for
2946 ;; nested types).
2948 "Parse ELEMENT with point at its beginning.
2950 If ITEM is non-nil, parse item wise instead of plain-list wise,
2951 using STRUCTURE as the current list structure.
2953 GRANULARITY determines the depth of the recursion. It can be set
2954 to the following symbols:
2956 `headline' Only parse headlines.
2957 `greater-element' Don't recurse into greater elements. Thus,
2958 elements parsed are the top-level ones.
2959 `element' Parse everything but objects and plain text.
2960 `object' or nil Parse the complete buffer.
2962 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
2963 greater elements.
2965 Elements are accumulated into ACC."
2968 ;; Shortcut when parsing only headlines.
2971 ;; Main loop start.
2974 ;; 1. If ITEM is toggled, point is at an item. Knowing that,
2975 ;; there's no need to go through `org-element-at-point'.
2981 ;; Narrow region to contents, so that item bullet don't
2982 ;; interfere with paragraph parsing.
2986 cbeg cend nil structure granularity visible-only
2988 ;; 2. When ITEM is nil, find current element's type and parse
2989 ;; it accordingly to its category.
2993 ;; Case 1: ELEMENT is a footnote-definition. If
2994 ;; GRANURALITY allows parsing, use narrowing so that
2995 ;; footnote label don't interfere with paragraph
2996 ;; recognition.
3004 cbeg cend nil structure granularity visible-only
3006 ;; Case 1: ELEMENT is a paragraph. Parse objects inside,
3007 ;; if GRANULARITY allows it.
3014 nil))
3015 ;; Case 2: ELEMENT is recursive: parse it between
3016 ;; `contents-begin' and `contents-end'. If it's
3017 ;; a plain list, also switch to item mode. Make
3018 ;; sure GRANULARITY allows the recursion, or
3019 ;; ELEMENT is an headline, in which case going
3020 ;; inside is mandatory, in order to get sub-level
3021 ;; headings. If VISIBLE-ONLY is true and element
3022 ;; is hidden, do not recurse into it.
3034 granularity
3035 visible-only
3037 ;; Case 3: Else, just accumulate ELEMENT, unless
3038 ;; GRANULARITY is set to `headline'.
3040 acc)
3042 ;; Return result.
3046 "Parse objects between BEG and END and return recursive structure.
3048 Objects are accumulated in ACC.
3050 RESTRICTION, when non-nil, is a list of object types which are
3051 allowed in the current object."
3055 ;; Return the parsing function associated to the nearest
3056 ;; object among list of candidates CAND.
3063 next-object candidates)
3067 end restriction candidates))
3069 ;; 1. Text before any object.
3073 ;; 2. Object...
3077 cont-beg)
3078 ;; ... recursive. The CONT-BEG check is for
3079 ;; links, as some of them might not be recursive
3080 ;; (i.e. plain links).
3083 cont-beg
3087 ;; Restrict allowed objects. This is the
3088 ;; intersection of current restriction and next
3089 ;; object's restriction.
3092 org-element-object-restrictions))))
3094 new-restr
3098 new-restr))))))
3099 ;; ... not recursive.
3100 next-object)
3101 acc)
3103 ;; 3. Text after last object.
3106 ;; Result.
3110 "Return an alist of candidates for the next object.
3112 LIMIT bounds the search, and RESTRICTION, when non-nil, bounds
3113 the possible object types.
3115 Return value is an alist whose car is position and cdr the object
3116 type, as a string. There is an association for the closest
3117 object of each type within RESTRICTION when non-nil, or for every
3118 type otherwise.
3120 OBJECTS is the previous candidates alist."
3122 next-candidates types-to-search)
3123 ;; If no previous result, search every object type in RESTRICTION.
3124 ;; Otherwise, keep potential candidates (old objects located after
3125 ;; point) and ask to search again those which had matched before.
3131 objects)
3133 ;; Call the appropriate "get-next" function for each type to
3134 ;; search and accumulate matches.
3141 type))))
3144 types-to-search)
3145 ;; Return alist.
3146 next-candidates))
3149 \f
3150 ;;; Towards A Bijective Process
3152 ;; The parse tree obtained with `org-element-parse-buffer' is really
3153 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
3154 ;; interpreted and expanded into a string with canonical Org
3155 ;; syntax. Hence `org-element-interpret-data'.
3156 ;;
3157 ;; Data parsed from secondary strings, whose shape is slightly
3158 ;; different than the standard parse tree, is expanded with the
3159 ;; equivalent function `org-element-interpret-secondary'.
3160 ;;
3161 ;; Both functions rely internally on
3162 ;; `org-element-interpret--affiliated-keywords'.
3164 "Interpret a parse tree representing Org data.
3166 DATA is the parse tree to interpret.
3168 Optional arguments GENEALOGY and PREVIOUS are used for recursive
3169 calls:
3170 GENEALOGY is the list of its parents types.
3171 PREVIOUS is the type of the element or object at the same level
3172 interpreted before.
3174 Return Org syntax as a string."
3177 ;; BLOB can be an element, an object, a string, or nil.
3186 'identity
3190 ;; Full Org document.
3193 ;; Recursive objects.
3197 ;; Recursive elements.
3202 ;; Paragraphs.
3206 blob
3207 ;; When normalizing contents of an item,
3208 ;; ignore first line's indentation.
3215 ;; Update PREVIOUS.
3217 ;; Build white spaces.
3226 results
3232 "Interpret SECONDARY string as Org syntax.
3234 SECONDARY-STRING is a nested list as returned by
3235 `org-element-parse-secondary-string'.
3237 Return interpreted string."
3238 ;; Make SECONDARY acceptable for `org-element-interpret-data'.
3242 ;; Both functions internally use `org-element--affiliated-keywords'.
3245 "Return ELEMENT's affiliated keywords as Org syntax.
3246 If there is no affiliated keyword, return the empty string."
3256 value)
3267 ;; Remove translated keywords.
3272 org-element-affiliated-keywords))
3275 ;; Because interpretation of the parse tree must return the same
3276 ;; number of blank lines between elements and the same number of white
3277 ;; space after objects, some special care must be given to white
3278 ;; spaces.
3279 ;;
3280 ;; The first function, `org-element-normalize-string', ensures any
3281 ;; string different from the empty string will end with a single
3282 ;; newline character.
3283 ;;
3284 ;; The second function, `org-element-normalize-contents', removes
3285 ;; global indentation from the contents of the current element.
3287 "Ensure string S ends with a single newline character.
3289 If S isn't a string return it unchanged. If S is the empty
3290 string, return it. Otherwise, return a new string with a single
3291 newline character at its end."
3299 "Normalize plain text in ELEMENT's contents.
3301 ELEMENT must only contain plain text and objects.
3303 The following changes are applied to plain text:
3304 - Remove global indentation, preserving relative one.
3305 - Untabify it.
3307 If optional argument IGNORE-FIRST is non-nil, ignore first line's
3308 indentation to compute maximal common indentation.
3310 Return the normalized element."
3318 ;; 1. Remove tabs from each string in CONTENTS. Get maximal
3319 ;; common indentation (MCI) along the way.
3325 object
3331 ind-list))
3332 object)))
3333 contents))
3337 ;; 2. Remove that indentation from CONTENTS. First string
3338 ;; must be treated differently because it's the only one
3339 ;; whose indentation doesn't happen after a newline
3340 ;; character.
3349 object
3352 contents))))))))
3355 \f
3356 ;;; The Toolbox
3358 ;; Once the structure of an Org file is well understood, it's easy to
3359 ;; implement some replacements for `forward-paragraph'
3360 ;; `backward-paragraph', namely `org-element-forward' and
3361 ;; `org-element-backward'.
3363 ;; Also, `org-transpose-elements' mimics the behaviour of
3364 ;; `transpose-words', at the element's level, whereas
3365 ;; `org-element-drag-forward', `org-element-drag-backward', and
3366 ;; `org-element-up' generalize, respectively, functions
3367 ;; `org-subtree-down', `org-subtree-up' and `outline-up-heading'.
3369 ;; `org-element-unindent-buffer' will, as its name almost suggests,
3370 ;; smartly remove global indentation from buffer, making it possible
3371 ;; to use Org indent mode on a file created with hard indentation.
3373 ;; `org-element-nested-p' and `org-element-swap-A-B' are used
3374 ;; internally by some of the previously cited tools.
3376 "Non-nil when elements ELEM-A and ELEM-B are nested."
3385 "Swap elements ELEM-A and ELEM-B.
3387 Leave point at the end of ELEM-A.
3389 Assume ELEM-A is before ELEM-B and that they are not nested."
3411 "Move backward by one element."
3416 ;; At an headline. The previous element is the previous sibling,
3417 ;; or the parent if any.
3419 ;; Already at the beginning of the current element: move to the
3420 ;; beginning of the previous one.
3429 ;; When moving into a new list, go directly at the
3430 ;; beginning of the top list structure.
3438 ;; Else, move at the element beginning. One exception: if point
3439 ;; was in the blank lines after the end of a list, move directly
3440 ;; to the top item.
3447 opoint))
3454 "Drag backward element at point."
3471 ;; Compute new position of point: it's shifted by PREV-ELEM
3472 ;; body's length.
3479 "Move forward element at point."
3492 ;; Compute new position of point: it's shifted by NEXT-ELEM
3493 ;; body's length (without final blanks) and by the length of
3494 ;; blanks between ELEM and NEXT-ELEM.
3511 "Move forward by one element."
3522 ;; At an item: Either move to the next element inside, or
3523 ;; to its end if it's hidden.
3531 ;; At a recursive element: Either move inside, or if it's
3532 ;; hidden, move to its end.
3539 cbeg))))
3540 ;; Else: move to the current element's end.
3544 "Put point at beginning of this element, mark at end.
3546 Interactively, if this command is repeated or (in Transient Mark
3547 mode) if the mark is active, it marks the next element after the
3548 ones already marked."
3563 "Narrow buffer to current element."
3581 "Transpose current and previous elements, keeping blank lines between.
3582 Point is moved after both elements."
3601 "Un-indent the visible part of the buffer.
3602 Relative indentation \(between items, inside blocks, etc.\) isn't
3603 modified."
3608 unindent-tree ; For byte-compiler.
3626 "Move to upper element.
3627 Return position at the beginning of the upper element."
3638 ;; If parent is bound to be in the same list as the
3639 ;; original point, move to that parent.
3651 prev-elem)
3656 end)
3667 ;;; org-element.el ends here