| blob | 7fa0bbd429b9a04383636e70067c2d5894bc737a |
1 ;;; org-element.el --- Parser And Applications for Org syntax
3 ;; Copyright (C) 2012-2014 Free Software Foundation, Inc.
5 ;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
6 ;; Keywords: outlines, hypermedia, calendar, wp
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
23 ;;; Commentary:
24 ;;
25 ;; Org syntax can be divided into three categories: "Greater
26 ;; elements", "Elements" and "Objects".
27 ;;
28 ;; Elements are related to the structure of the document. Indeed, all
29 ;; elements are a cover for the document: each position within belongs
30 ;; to at least one element.
31 ;;
32 ;; An element always starts and ends at the beginning of a line. With
33 ;; a few exceptions (`clock', `headline', `inlinetask', `item',
34 ;; `planning', `node-property', `section' and `table-row' types), it
35 ;; can also accept a fixed set of keywords as attributes. Those are
36 ;; called "affiliated keywords" to distinguish them from other
37 ;; keywords, which are full-fledged elements. Almost all affiliated
38 ;; keywords are referenced in `org-element-affiliated-keywords'; the
39 ;; others are export attributes and start with "ATTR_" prefix.
40 ;;
41 ;; Element containing other elements (and only elements) are called
42 ;; greater elements. Concerned types are: `center-block', `drawer',
43 ;; `dynamic-block', `footnote-definition', `headline', `inlinetask',
44 ;; `item', `plain-list', `property-drawer', `quote-block', `section'
45 ;; and `special-block'.
46 ;;
47 ;; Other element types are: `babel-call', `clock', `comment',
48 ;; `comment-block', `diary-sexp', `example-block', `export-block',
49 ;; `fixed-width', `horizontal-rule', `keyword', `latex-environment',
50 ;; `node-property', `paragraph', `planning', `src-block', `table',
51 ;; `table-row' and `verse-block'. Among them, `paragraph' and
52 ;; `verse-block' types can contain Org objects and plain text.
53 ;;
54 ;; Objects are related to document's contents. Some of them are
55 ;; recursive. Associated types are of the following: `bold', `code',
56 ;; `entity', `export-snippet', `footnote-reference',
57 ;; `inline-babel-call', `inline-src-block', `italic',
58 ;; `latex-fragment', `line-break', `link', `macro', `radio-target',
59 ;; `statistics-cookie', `strike-through', `subscript', `superscript',
60 ;; `table-cell', `target', `timestamp', `underline' and `verbatim'.
61 ;;
62 ;; Some elements also have special properties whose value can hold
63 ;; objects themselves (i.e. an item tag or a headline name). Such
64 ;; values are called "secondary strings". Any object belongs to
65 ;; either an element or a secondary string.
66 ;;
67 ;; Notwithstanding affiliated keywords, each greater element, element
68 ;; and object has a fixed set of properties attached to it. Among
69 ;; them, four are shared by all types: `:begin' and `:end', which
70 ;; refer to the beginning and ending buffer positions of the
71 ;; considered element or object, `:post-blank', which holds the number
72 ;; of blank lines, or white spaces, at its end and `:parent' which
73 ;; refers to the element or object containing it. Greater elements,
74 ;; elements and objects containing objects will also have
75 ;; `:contents-begin' and `:contents-end' properties to delimit
76 ;; contents. Eventually, greater elements and elements accepting
77 ;; affiliated keywords will have a `:post-affiliated' property,
78 ;; referring to the buffer position after all such keywords.
79 ;;
80 ;; At the lowest level, a `:parent' property is also attached to any
81 ;; string, as a text property.
82 ;;
83 ;; Lisp-wise, an element or an object can be represented as a list.
84 ;; It follows the pattern (TYPE PROPERTIES CONTENTS), where:
85 ;; TYPE is a symbol describing the Org element or object.
86 ;; PROPERTIES is the property list attached to it. See docstring of
87 ;; appropriate parsing function to get an exhaustive
88 ;; list.
89 ;; CONTENTS is a list of elements, objects or raw strings contained
90 ;; in the current element or object, when applicable.
91 ;;
92 ;; An Org buffer is a nested list of such elements and objects, whose
93 ;; type is `org-data' and properties is nil.
94 ;;
95 ;; The first part of this file defines Org syntax, while the second
96 ;; one provide accessors and setters functions.
97 ;;
98 ;; The next part implements a parser and an interpreter for each
99 ;; element and object type in Org syntax.
100 ;;
101 ;; The following part creates a fully recursive buffer parser. It
102 ;; also provides a tool to map a function to elements or objects
103 ;; matching some criteria in the parse tree. Functions of interest
104 ;; are `org-element-parse-buffer', `org-element-map' and, to a lesser
105 ;; extent, `org-element-parse-secondary-string'.
106 ;;
107 ;; The penultimate part is the cradle of an interpreter for the
108 ;; obtained parse tree: `org-element-interpret-data'.
109 ;;
110 ;; The library ends by furnishing `org-element-at-point' function, and
111 ;; a way to give information about document structure around point
112 ;; with `org-element-context'. A simple cache mechanism is also
113 ;; provided for these functions.
116 ;;; Code:
123 \f
124 ;;; Definitions And Rules
125 ;;
126 ;; Define elements, greater elements and specify recursive objects,
127 ;; along with the affiliated keywords recognized. Also set up
128 ;; restrictions on recursive objects combinations.
129 ;;
130 ;; These variables really act as a control center for the parsing
131 ;; process.
135 ;; Headlines, inlinetasks.
137 ;; Footnote definitions.
139 ;; Diary sexps.
142 ;; Empty lines.
144 ;; Tables (any type).
146 ;; Blocks (any type), Babel calls and keywords. Note: this
147 ;; is only an indication and need some thorough check.
149 ;; Drawers (any type) and fixed-width areas. This is also
150 ;; only an indication.
152 ;; Horizontal rules.
154 ;; LaTeX environments.
156 ;; Planning and Clock lines.
158 org-deadline-string
159 org-closed-string
160 org-clock-string))
162 ;; Lists.
169 "Regexp to separate paragraphs in an Org buffer.
171 is not sufficient to know if point is at a paragraph ending. See
176 dynamic-block example-block export-block fixed-width
177 footnote-definition headline horizontal-rule inlinetask item
178 keyword latex-environment node-property paragraph plain-list
179 planning property-drawer quote-block section
180 special-block src-block table table-row verse-block)
185 item plain-list property-drawer quote-block section
186 special-block table)
191 latex-or-entity line-break link macro plain-link radio-target
192 statistics-cookie sub/superscript table-cell target
193 text-markup timestamp)
202 "Alist of translations between object type and successor name.
203 Sharing the same successor comes handy when, for example, the
208 inline-src-block italic line-break latex-fragment link macro
209 radio-target statistics-cookie strike-through subscript superscript
210 table-cell target timestamp underline verbatim)
215 table-cell underline)
225 "Alist between block names and the associated parsing function.
226 Names must be uppercase. Any block whose name has no association
232 Only these types can accept search options and an explicit
238 "List of affiliated keywords as strings.
246 "Alist of usual translations for keywords.
247 The key is the old name and the value the new one. The property
251 "List of affiliated keywords that can occur more than once in an element.
253 Their value will be consed into a list of strings, which will be
254 returned as the value of the property.
256 This list is checked after translations have been applied. See
257 `org-element-keyword-translation-alist'.
263 "List of affiliated keywords whose value can be parsed.
265 Their value will be stored as a secondary string: a list of
266 strings and objects.
268 This list is checked after translations have been applied. See
272 "List of affiliated keywords which can have a secondary value.
274 In Org syntax, they can be written with optional square brackets
275 before the colons. For example, RESULTS keyword can be
276 associated to a hash value with the following:
278 #+RESULTS[hash-string]: some-source
280 This list is checked after translations have been applied. See
284 "List of properties associated to the whole document.
285 Any keyword in this list will have its value parsed and stored as
291 ;; Dual affiliated keywords.
295 ;; Regular affiliated keywords.
301 org-element-affiliated-keywords)))
303 ;; Export attributes.
305 "Regexp matching any affiliated keyword.
307 Keyword name is put in match group 1. Moreover, if keyword
308 belongs to `org-element-dual-keywords', put the dual value in
309 match group 2.
324 ;; Ignore all links excepted plain links in a link description.
325 ;; Also ignore radio-targets and line breaks.
329 ;; Remove any variable object from radio target as it would
330 ;; prevent it from being properly recognized.
335 ;; Ignore inline babel call and inline src block as formulas are
336 ;; possible. Also ignore line breaks and statistics cookies.
342 "Alist of objects restrictions.
344 CAR is an element or object type containing objects and CDR is
345 a list of successors that will be called within an element or
346 object of such type.
348 For example, in a `radio-target' object, one can only find
349 entities, latex-fragments, subscript and superscript.
351 This alist also applies to secondary string. For example, an
352 `headline' type element doesn't directly contain objects, but
363 "List of buffer-local variables used when parsing objects.
364 These variables are copied to the temporary buffer created by
368 \f
369 ;;; Accessors and Setters
370 ;;
371 ;; Provide four accessors: `org-element-type', `org-element-property'
372 ;; `org-element-contents' and `org-element-restriction'.
373 ;;
374 ;; Setter functions allow to modify elements by side effect. There is
375 ;; `org-element-put-property', `org-element-set-contents'. These
376 ;; low-level functions are useful to build a parse tree.
377 ;;
378 ;; `org-element-adopt-element', `org-element-set-element',
379 ;; `org-element-extract-element' and `org-element-insert-before' are
380 ;; high-level functions useful to modify a parse tree.
381 ;;
382 ;; `org-element-secondary-p' is a predicate used to know if a given
383 ;; object belongs to a secondary string.
386 "Return type of ELEMENT.
388 The function returns the type of the element or object provided.
389 It can also return the following special value:
390 `plain-text' for a string
391 `org-data' for a complete document
392 nil in any other case."
398 "Extract the value from the PROPERTY of an ELEMENT."
403 "Extract contents from an ELEMENT."
409 "Return restriction associated to ELEMENT.
410 ELEMENT can be an element, an object or a symbol representing an
411 element or object type."
413 org-element-object-restrictions)))
416 "In ELEMENT set PROPERTY to VALUE.
417 Return modified element."
420 element))
423 "Set ELEMENT contents to CONTENTS.
424 Return modified element."
431 "Non-nil when OBJECT belongs to a secondary string.
432 Return value is the property name, as a keyword, or nil."
435 org-element-secondary-value-alist))))
438 property)))
441 "Append elements to the contents of another element.
443 PARENT is an element or object. CHILDREN can be elements,
444 objects, or a strings.
446 The function takes care of setting `:parent' property for CHILD.
447 Return parent element."
448 ;; Link every child to PARENT. If PARENT is nil, it is a secondary
449 ;; string: parent is the list itself.
452 children)
453 ;; Add CHILDREN at the end of PARENT contents.
456 parent
458 ;; Return modified PARENT element.
462 "Extract ELEMENT from parse tree.
463 Remove element from the parse tree by side-effect, and return it
464 with its `:parent' property stripped out."
469 parent secondary
472 parent
474 ;; Return ELEMENT with its :parent removed.
478 "Insert ELEMENT before LOCATION in parse tree.
479 LOCATION is an element, object or string within the parse tree.
480 Parse tree is modified by side effect."
485 ;; Special case: LOCATION is the first element of an
486 ;; independent secondary string (e.g. :title property). Add
487 ;; ELEMENT in-place.
491 ;; Install ELEMENT at the appropriate POSITION within SIBLINGS.
501 ;; Store SIBLINGS at appropriate place in parse tree.
506 ;; Set appropriate :parent property.
510 "Replace element or object OLD with element or object NEW.
511 The function takes care of setting `:parent' property for NEW."
512 ;; Ensure OLD and NEW have the same parent.
516 ;; We cannot replace OLD with NEW since one of them is not an
517 ;; object or element. We take the long path.
520 ;; Since OLD is going to be changed into NEW by side-effect, first
521 ;; make sure that every element or object within NEW has OLD as
522 ;; parent.
525 ;; Transfer contents.
527 ;; Overwrite OLD's properties with NEW's.
529 ;; Transfer type.
533 \f
534 ;;; Greater elements
535 ;;
536 ;; For each greater element type, we define a parser and an
537 ;; interpreter.
538 ;;
539 ;; A parser returns the element or object as the list described above.
540 ;; Most of them accepts no argument. Though, exceptions exist. Hence
541 ;; every element containing a secondary string (see
542 ;; `org-element-secondary-value-alist') will accept an optional
543 ;; argument to toggle parsing of that secondary string. Moreover,
544 ;; `item' parser requires current list's structure as its first
545 ;; element.
546 ;;
547 ;; An interpreter accepts two arguments: the list representation of
548 ;; the element or object, and its contents. The latter may be nil,
549 ;; depending on the element or object considered. It returns the
550 ;; appropriate Org syntax, as a string.
551 ;;
552 ;; Parsing functions must follow the naming convention:
553 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
554 ;; defined in `org-element-greater-elements'.
555 ;;
556 ;; Similarly, interpreting functions must follow the naming
557 ;; convention: org-element-TYPE-interpreter.
558 ;;
559 ;; With the exception of `headline' and `item' types, greater elements
560 ;; cannot contain other greater elements of their own type.
561 ;;
562 ;; Beside implementing a parser and an interpreter, adding a new
563 ;; greater element requires to tweak `org-element--current-element'.
564 ;; Moreover, the newly defined type must be added to both
565 ;; `org-element-all-elements' and `org-element-greater-elements'.
568 ;;;; Center Block
571 "Parse a center block.
573 LIMIT bounds the search. AFFILIATED is a list of which CAR is
574 the buffer position at the beginning of the first affiliated
575 keyword and CDR is a plist of affiliated keywords along with
576 their value.
578 Return a list whose CAR is `center-block' and CDR is a plist
579 containing `:begin', `:end', `:contents-begin', `:contents-end',
580 `:post-blank' and `:post-affiliated' keywords.
582 Assume point is at the beginning of the block."
586 ;; Incomplete block: parse it as a paragraph.
591 ;; Empty blocks have no contents.
605 :end end
606 :contents-begin contents-begin
607 :contents-end contents-end
613 "Interpret CENTER-BLOCK element as Org syntax.
614 CONTENTS is the contents of the element."
618 ;;;; Drawer
621 "Parse a drawer.
623 LIMIT bounds the search. AFFILIATED is a list of which CAR is
624 the buffer position at the beginning of the first affiliated
625 keyword and CDR is a plist of affiliated keywords along with
626 their value.
628 Return a list whose CAR is `drawer' and CDR is a plist containing
629 `:drawer-name', `:begin', `:end', `:contents-begin',
630 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
632 Assume point is at beginning of drawer."
635 ;; Incomplete drawer: parse it as a paragraph.
643 ;; Empty drawers have no contents.
656 :end end
657 :drawer-name name
658 :contents-begin contents-begin
659 :contents-end contents-end
665 "Interpret DRAWER element as Org syntax.
666 CONTENTS is the contents of the element."
669 contents))
672 ;;;; Dynamic Block
675 "Parse a dynamic block.
677 LIMIT bounds the search. AFFILIATED is a list of which CAR is
678 the buffer position at the beginning of the first affiliated
679 keyword and CDR is a plist of affiliated keywords along with
680 their value.
682 Return a list whose CAR is `dynamic-block' and CDR is a plist
683 containing `:block-name', `:begin', `:end', `:contents-begin',
684 `:contents-end', `:arguments', `:post-blank' and
685 `:post-affiliated' keywords.
687 Assume point is at beginning of dynamic block."
691 ;; Incomplete block: parse it as a paragraph.
700 ;; Empty blocks have no contents.
713 :end end
714 :block-name name
715 :arguments arguments
716 :contents-begin contents-begin
717 :contents-end contents-end
723 "Interpret DYNAMIC-BLOCK element as Org syntax.
724 CONTENTS is the contents of the element."
729 contents))
732 ;;;; Footnote Definition
735 "Parse a footnote definition.
737 LIMIT bounds the search. AFFILIATED is a list of which CAR is
738 the buffer position at the beginning of the first affiliated
739 keyword and CDR is a plist of affiliated keywords along with
740 their value.
742 Return a list whose CAR is `footnote-definition' and CDR is
743 a plist containing `:label', `:begin' `:end', `:contents-begin',
744 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
746 Assume point is at the beginning of the footnote definition."
774 :begin begin
775 :end end
776 :contents-begin contents-begin
777 :contents-end contents-end
783 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
784 CONTENTS is the contents of the footnote-definition."
786 " "
787 contents))
790 ;;;; Headline
793 "Parse a headline.
795 Return a list whose CAR is `headline' and CDR is a plist
796 containing `:raw-value', `:title', `:alt-title', `:begin',
797 `:end', `:pre-blank', `:contents-begin' and `:contents-end',
798 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
799 `:scheduled', `:deadline', `:closed', `:archivedp', `:commentedp'
800 and `:footnote-section-p' keywords.
802 The plist also contains any property set in the property drawer,
803 with its name in upper cases and colons added at the
804 beginning (i.e. `:CUSTOM_ID').
806 When RAW-SECONDARY-P is non-nil, headline's title will not be
807 parsed as a secondary string, but as a plain string instead.
809 Assume point is at beginning of the headline."
822 raw-value)))
826 ;; Upcase property names. It avoids confusion between
827 ;; properties obtained through property drawer and default
828 ;; properties from the parser (e.g. `:end' and :END:)
838 plist))
840 ;; Read time properties on the line below the headline.
846 org-keyword-time-not-clock-regexp end t)
856 plist))))
868 ;; Clean RAW-VALUE from any comment string.
874 ""
875 raw-value))))
876 ;; Clean TAGS from archive tag, if any.
882 :begin begin
883 :end end
884 :pre-blank
887 :contents-begin contents-begin
888 :contents-end contents-end
889 :level level
891 :tags tags
892 :todo-keyword todo
893 :todo-type todo-type
899 end)
900 :footnote-section-p footnote-section-p
901 :archivedp archivedp
903 time-props
904 standard-props))))
908 headline :alt-title
913 headline :title
919 "Interpret HEADLINE element as Org syntax.
920 CONTENTS is the contents of the element."
945 ;; Align tags.
953 ? )
954 tags))
958 tags))))
960 contents)))
963 ;;;; Inlinetask
966 "Parse an inline task.
968 Return a list whose CAR is `inlinetask' and CDR is a plist
969 containing `:title', `:begin', `:end', `:contents-begin' and
970 `:contents-end', `:level', `:priority', `:raw-value', `:tags',
971 `:todo-keyword', `:todo-type', `:scheduled', `:deadline',
972 `:closed' and `:post-blank' keywords.
974 The plist also contains any property set in the property drawer,
975 with its name in upper cases and colons added at the
976 beginning (i.e. `:CUSTOM_ID').
978 When optional argument RAW-SECONDARY-P is non-nil, inline-task's
979 title will not be parsed as a secondary string, but as a plain
980 string instead.
982 Assume point is at beginning of the inline task."
992 ;; Upcase property names. It avoids confusion between
993 ;; properties obtained through property drawer and default
994 ;; properties from the parser (e.g. `:end' and :END:)
1004 plist))
1006 ;; Read time properties on the line below the inlinetask
1007 ;; opening string.
1013 org-keyword-time-not-clock-regexp end t)
1023 plist))))
1041 :begin begin
1042 :end end
1043 :contents-begin contents-begin
1044 :contents-end contents-end
1047 :tags tags
1048 :todo-keyword todo
1049 :todo-type todo-type
1051 time-props
1052 standard-props))))
1054 inlinetask :title
1057 raw-value
1059 inlinetask))))))
1062 "Interpret INLINETASK element as Org syntax.
1063 CONTENTS is the contents of inlinetask."
1078 ;; Align tags.
1086 ? )
1087 tags))
1091 tags))))
1092 ;; Prefer degenerate inlinetasks when there are no
1093 ;; contents.
1096 contents
1100 ;;;; Item
1103 "Parse an item.
1105 STRUCT is the structure of the plain list.
1107 Return a list whose CAR is `item' and CDR is a plist containing
1108 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
1109 `:checkbox', `:counter', `:tag', `:structure' and `:post-blank'
1110 keywords.
1112 When optional argument RAW-SECONDARY-P is non-nil, item's tag, if
1113 any, will not be parsed as a secondary string, but as a plain
1114 string instead.
1116 Assume point is at the beginning of the item."
1140 ;; Ignore tags in un-ordered lists: they are just
1141 ;; a part of item's body.
1147 ;; If first line isn't empty, contents really start
1148 ;; at the text after item's meta-data.
1157 :begin begin
1158 :end end
1159 ;; CONTENTS-BEGIN and CONTENTS-END may be
1160 ;; mixed up in the case of an empty item
1161 ;; separated from the next by a blank line.
1162 ;; Thus ensure the former is always the
1163 ;; smallest.
1166 :checkbox checkbox
1167 :counter counter
1168 :structure struct
1171 item :tag
1179 "Interpret ITEM element as Org syntax.
1180 CONTENTS is the contents of the element."
1190 ;; Compute indentation.
1195 ;; Indent contents.
1197 bullet
1211 ;;;; Plain List
1214 ;; Return structure of list at point. Internal function. See
1215 ;; `org-list-struct' for details.
1220 items struct)
1225 ;; At limit: end all items.
1234 ;; At list end: end all items.
1239 ;; At a new item: end previous sibling.
1251 ind
1252 bullet
1255 ;; Description tag.
1259 ;; Ending position, unknown so far.
1260 nil)))
1261 items))
1263 ;; Skip empty lines.
1265 ;; Skip inline tasks and blank lines along the way.
1272 ;; At some text line. Check if it ends any previous item.
1284 ;; Skip blocks (any type) and drawers contents.
1290 limit t)))
1296 "Parse a plain list.
1298 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1299 the buffer position at the beginning of the first affiliated
1300 keyword and CDR is a plist of affiliated keywords along with
1301 their value. STRUCTURE is the structure of the plain list being
1302 parsed.
1304 Return a list whose CAR is `plain-list' and CDR is a plist
1305 containing `:type', `:begin', `:end', `:contents-begin' and
1306 `:contents-end', `:structure', `:post-blank' and
1307 `:post-affiliated' keywords.
1309 Assume point is at the beginning of the list."
1323 pos))
1327 ;; Return value.
1331 :begin begin
1332 :end end
1333 :contents-begin contents-begin
1334 :contents-end contents-end
1335 :structure struct
1341 "Interpret PLAIN-LIST element as Org syntax.
1342 CONTENTS is the contents of the element."
1350 ;;;; Property Drawer
1353 "Parse a property drawer.
1355 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1356 the buffer position at the beginning of the first affiliated
1357 keyword and CDR is a plist of affiliated keywords along with
1358 their value.
1360 Return a list whose CAR is `property-drawer' and CDR is a plist
1361 containing `:begin', `:end', `:contents-begin', `:contents-end',
1362 `:post-blank' and `:post-affiliated' keywords.
1364 Assume point is at the beginning of the property drawer."
1369 ;; Incomplete drawer: parse it as a paragraph.
1387 :end end
1388 :contents-begin contents-begin
1389 :contents-end contents-end
1395 "Interpret PROPERTY-DRAWER element as Org syntax.
1396 CONTENTS is the properties within the drawer."
1400 ;;;; Quote Block
1403 "Parse a quote block.
1405 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1406 the buffer position at the beginning of the first affiliated
1407 keyword and CDR is a plist of affiliated keywords along with
1408 their value.
1410 Return a list whose CAR is `quote-block' and CDR is a plist
1411 containing `:begin', `:end', `:contents-begin', `:contents-end',
1412 `:post-blank' and `:post-affiliated' keywords.
1414 Assume point is at the beginning of the block."
1418 ;; Incomplete block: parse it as a paragraph.
1424 ;; Empty blocks have no contents.
1437 :end end
1438 :contents-begin contents-begin
1439 :contents-end contents-end
1445 "Interpret QUOTE-BLOCK element as Org syntax.
1446 CONTENTS is the contents of the element."
1450 ;;;; Section
1453 "Parse a section.
1455 LIMIT bounds the search.
1457 Return a list whose CAR is `section' and CDR is a plist
1458 containing `:begin', `:end', `:contents-begin', `contents-end'
1459 and `:post-blank' keywords."
1461 ;; Beginning of section is the beginning of the first non-blank
1462 ;; line after previous headline.
1471 :end end
1472 :contents-begin begin
1473 :contents-end pos-before-blank
1477 "Interpret SECTION element as Org syntax.
1478 CONTENTS is the contents of the element."
1479 contents)
1482 ;;;; Special Block
1485 "Parse a special block.
1487 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1488 the buffer position at the beginning of the first affiliated
1489 keyword and CDR is a plist of affiliated keywords along with
1490 their value.
1492 Return a list whose CAR is `special-block' and CDR is a plist
1493 containing `:type', `:begin', `:end', `:contents-begin',
1494 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
1496 Assume point is at the beginning of the block."
1503 limit t)))
1504 ;; Incomplete block: parse it as a paragraph.
1510 ;; Empty blocks have no contents.
1523 :begin begin
1524 :end end
1525 :contents-begin contents-begin
1526 :contents-end contents-end
1532 "Interpret SPECIAL-BLOCK element as Org syntax.
1533 CONTENTS is the contents of the element."
1538 \f
1539 ;;; Elements
1540 ;;
1541 ;; For each element, a parser and an interpreter are also defined.
1542 ;; Both follow the same naming convention used for greater elements.
1543 ;;
1544 ;; Also, as for greater elements, adding a new element type is done
1545 ;; through the following steps: implement a parser and an interpreter,
1546 ;; tweak `org-element--current-element' so that it recognizes the new
1547 ;; type and add that new type to `org-element-all-elements'.
1548 ;;
1549 ;; As a special case, when the newly defined type is a block type,
1550 ;; `org-element-block-name-alist' has to be modified accordingly.
1553 ;;;; Babel Call
1556 "Parse a babel call.
1558 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1559 the buffer position at the beginning of the first affiliated
1560 keyword and CDR is a plist of affiliated keywords along with
1561 their value.
1563 Return a list whose CAR is `babel-call' and CDR is a plist
1564 containing `:begin', `:end', `:value', `:post-blank' and
1565 `:post-affiliated' as keywords."
1579 :end end
1580 :value value
1586 "Interpret BABEL-CALL element as Org syntax.
1587 CONTENTS is nil."
1591 ;;;; Clock
1594 "Parse a clock.
1596 LIMIT bounds the search.
1598 Return a list whose CAR is `clock' and CDR is a plist containing
1599 `:status', `:value', `:time', `:begin', `:end' and `:post-blank'
1600 as keywords."
1620 :value value
1621 :duration duration
1622 :begin begin
1623 :end end
1627 "Interpret CLOCK element as Org syntax.
1628 CONTENTS is nil."
1636 "%2s:%02s"
1640 ;;;; Comment
1643 "Parse a comment.
1645 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1646 the buffer position at the beginning of the first affiliated
1647 keyword and CDR is a plist of affiliated keywords along with
1648 their value.
1650 Return a list whose CAR is `comment' and CDR is a plist
1651 containing `:begin', `:end', `:value', `:post-blank',
1652 `:post-affiliated' keywords.
1654 Assume point is at comment beginning."
1663 ;; Get comments ending.
1666 ;; Accumulate lines without leading hash and first
1667 ;; whitespace.
1681 :end end
1682 :value value
1688 "Interpret COMMENT element as Org syntax.
1689 CONTENTS is nil."
1693 ;;;; Comment Block
1696 "Parse an export block.
1698 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1699 the buffer position at the beginning of the first affiliated
1700 keyword and CDR is a plist of affiliated keywords along with
1701 their value.
1703 Return a list whose CAR is `comment-block' and CDR is a plist
1704 containing `:begin', `:end', `:value', `:post-blank' and
1705 `:post-affiliated' keywords.
1707 Assume point is at comment block beginning."
1711 ;; Incomplete block: parse it as a paragraph.
1724 contents-begin contents-end)))
1728 :end end
1729 :value value
1735 "Interpret COMMENT-BLOCK element as Org syntax.
1736 CONTENTS is nil."
1741 ;;;; Diary Sexp
1744 "Parse a diary sexp.
1746 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1747 the buffer position at the beginning of the first affiliated
1748 keyword and CDR is a plist of affiliated keywords along with
1749 their value.
1751 Return a list whose CAR is `diary-sexp' and CDR is a plist
1752 containing `:begin', `:end', `:value', `:post-blank' and
1753 `:post-affiliated' keywords."
1765 :begin begin
1766 :end end
1772 "Interpret DIARY-SEXP as Org syntax.
1773 CONTENTS is nil."
1777 ;;;; Example Block
1780 "Parse an example block.
1782 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1783 the buffer position at the beginning of the first affiliated
1784 keyword and CDR is a plist of affiliated keywords along with
1785 their value.
1787 Return a list whose CAR is `example-block' and CDR is a plist
1788 containing `:begin', `:end', `:number-lines', `:preserve-indent',
1789 `:retain-labels', `:use-labels', `:label-fmt', `:switches',
1790 `:value', `:post-blank' and `:post-affiliated' keywords."
1794 ;; Incomplete block: parse it as a paragraph.
1802 ;; Switches analysis
1809 ;; Should labels be retained in (or stripped from) example
1810 ;; blocks?
1815 ;; What should code-references use - labels or
1816 ;; line-numbers?
1825 ;; Standard block parsing.
1833 contents-begin contents-end))
1834 block-ind))
1843 :end end
1844 :value value
1845 :switches switches
1846 :number-lines number-lines
1847 :preserve-indent preserve-indent
1848 :retain-labels retain-labels
1849 :use-labels use-labels
1850 :label-fmt label-fmt
1856 "Interpret EXAMPLE-BLOCK element as Org syntax.
1857 CONTENTS is nil."
1864 value
1869 ;;;; Export Block
1872 "Parse an export block.
1874 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1875 the buffer position at the beginning of the first affiliated
1876 keyword and CDR is a plist of affiliated keywords along with
1877 their value.
1879 Return a list whose CAR is `export-block' and CDR is a plist
1880 containing `:begin', `:end', `:type', `:value', `:post-blank' and
1881 `:post-affiliated' keywords.
1883 Assume point is at export-block beginning."
1890 ;; Incomplete block: parse it as a paragraph.
1903 contents-end)))
1907 :end end
1908 :type type
1909 :value value
1915 "Interpret EXPORT-BLOCK element as Org syntax.
1916 CONTENTS is nil."
1923 ;;;; Fixed-width
1926 "Parse a fixed-width section.
1928 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1929 the buffer position at the beginning of the first affiliated
1930 keyword and CDR is a plist of affiliated keywords along with
1931 their value.
1933 Return a list whose CAR is `fixed-width' and CDR is a plist
1934 containing `:begin', `:end', `:value', `:post-blank' and
1935 `:post-affiliated' keywords.
1937 Assume point is at the beginning of the fixed-width area."
1941 value
1946 ;; Accumulate text without starting colons.
1959 :end end
1960 :value value
1966 "Interpret FIXED-WIDTH element as Org syntax.
1967 CONTENTS is nil."
1975 ;;;; Horizontal Rule
1978 "Parse an horizontal rule.
1980 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1981 the buffer position at the beginning of the first affiliated
1982 keyword and CDR is a plist of affiliated keywords along with
1983 their value.
1985 Return a list whose CAR is `horizontal-rule' and CDR is a plist
1986 containing `:begin', `:end', `:post-blank' and `:post-affiliated'
1987 keywords."
1997 :end end
2003 "Interpret HORIZONTAL-RULE element as Org syntax.
2004 CONTENTS is nil."
2008 ;;;; Keyword
2011 "Parse a keyword at point.
2013 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2014 the buffer position at the beginning of the first affiliated
2015 keyword and CDR is a plist of affiliated keywords along with
2016 their value.
2018 Return a list whose CAR is `keyword' and CDR is a plist
2019 containing `:key', `:value', `:begin', `:end', `:post-blank' and
2020 `:post-affiliated' keywords."
2022 ;; An orphaned affiliated keyword is considered as a regular
2023 ;; keyword. In this case AFFILIATED is nil, so we take care of
2024 ;; this corner case.
2037 :value value
2038 :begin begin
2039 :end end
2045 "Interpret KEYWORD element as Org syntax.
2046 CONTENTS is nil."
2052 ;;;; Latex Environment
2055 "Parse a LaTeX environment.
2057 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2058 the buffer position at the beginning of the first affiliated
2059 keyword and CDR is a plist of affiliated keywords along with
2060 their value.
2062 Return a list whose CAR is `latex-environment' and CDR is a plist
2063 containing `:begin', `:end', `:value', `:post-blank' and
2064 `:post-affiliated' keywords.
2066 Assume point is at the beginning of the latex environment."
2073 limit t))
2074 ;; Incomplete latex environment: parse it as a paragraph.
2084 :end end
2085 :value value
2091 "Interpret LATEX-ENVIRONMENT element as Org syntax.
2092 CONTENTS is nil."
2096 ;;;; Node Property
2099 "Parse a node-property at point.
2101 LIMIT bounds the search.
2103 Return a list whose CAR is `node-property' and CDR is a plist
2104 containing `:key', `:value', `:begin', `:end' and `:post-blank'
2105 keywords."
2117 :value value
2118 :begin begin
2119 :end end
2123 "Interpret NODE-PROPERTY element as Org syntax.
2124 CONTENTS is nil."
2130 ;;;; Paragraph
2133 "Parse a paragraph.
2135 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2136 the buffer position at the beginning of the first affiliated
2137 keyword and CDR is a plist of affiliated keywords along with
2138 their value.
2140 Return a list whose CAR is `paragraph' and CDR is a plist
2141 containing `:begin', `:end', `:contents-begin' and
2142 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
2144 Assume point is at the beginning of the paragraph."
2153 limit
2154 ;; A matching `org-element-paragraph-separate' is not
2155 ;; necessarily the end of the paragraph. In
2156 ;; particular, lines starting with # or : as a first
2157 ;; non-space character are ambiguous. We have check
2158 ;; if they are valid Org syntax (i.e. not an
2159 ;; incomplete keyword).
2163 ;; There's no ambiguity for other symbols or
2164 ;; empty lines: stop here.
2166 ;; Stop at valid fixed-width areas.
2168 ;; Stop at drawers.
2173 ;; Stop at valid comments.
2175 ;; Stop at valid dynamic blocks.
2180 ;; Stop at valid blocks.
2187 limit t)))
2188 ;; Stop at valid latex environments.
2196 limit t)))
2197 ;; Stop at valid keywords.
2199 ;; Skip everything else.
2216 :end end
2217 :contents-begin contents-begin
2218 :contents-end contents-end
2224 "Interpret PARAGRAPH element as Org syntax.
2225 CONTENTS is the contents of the element."
2226 contents)
2229 ;;;; Planning
2232 "Parse a planning.
2234 LIMIT bounds the search.
2236 Return a list whose CAR is `planning' and CDR is a plist
2237 containing `:closed', `:deadline', `:scheduled', `:begin', `:end'
2238 and `:post-blank' keywords."
2248 closed deadline scheduled)
2260 :deadline deadline
2261 :scheduled scheduled
2262 :begin begin
2263 :end end
2267 "Interpret PLANNING element as Org syntax.
2268 CONTENTS is nil."
2270 'identity
2287 ;;;; Src Block
2290 "Parse a src block.
2292 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2293 the buffer position at the beginning of the first affiliated
2294 keyword and CDR is a plist of affiliated keywords along with
2295 their value.
2297 Return a list whose CAR is `src-block' and CDR is a plist
2298 containing `:language', `:switches', `:parameters', `:begin',
2299 `:end', `:number-lines', `:retain-labels', `:use-labels',
2300 `:label-fmt', `:preserve-indent', `:value', `:post-blank' and
2301 `:post-affiliated' keywords.
2303 Assume point is at the beginning of the block."
2306 limit t)))
2307 ;; Incomplete block: parse it as a paragraph.
2313 ;; Get language as a string.
2322 ;; Get switches.
2324 ;; Get parameters.
2326 ;; Switches analysis
2337 ;; Should labels be retained in (or stripped from)
2338 ;; src blocks?
2343 ;; What should code-references use - labels or
2344 ;; line-numbers?
2349 ;; Indentation.
2351 ;; Retrieve code.
2356 block-ind))
2360 ;; Get position after ending blank lines.
2370 :begin begin
2371 :end end
2372 :number-lines number-lines
2373 :preserve-indent preserve-indent
2374 :retain-labels retain-labels
2375 :use-labels use-labels
2376 :label-fmt label-fmt
2377 :value value
2383 "Interpret SRC-BLOCK element as Org syntax.
2384 CONTENTS is nil."
2393 val)
2407 ;;;; Table
2410 "Parse a table at point.
2412 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2413 the buffer position at the beginning of the first affiliated
2414 keyword and CDR is a plist of affiliated keywords along with
2415 their value.
2417 Return a list whose CAR is `table' and CDR is a plist containing
2418 `:begin', `:end', `:tblfm', `:type', `:contents-begin',
2419 `:contents-end', `:value', `:post-blank' and `:post-affiliated'
2420 keywords.
2422 Assume point is at the beginning of the table."
2436 acc))
2443 :end end
2444 :type type
2445 :tblfm tblfm
2446 ;; Only `org' tables have contents. `table.el' tables
2447 ;; use a `:value' property to store raw table as
2448 ;; a string.
2453 table-begin table-end))
2459 "Interpret TABLE element as Org syntax.
2460 CONTENTS is nil."
2471 ;;;; Table Row
2474 "Parse table row at point.
2476 LIMIT bounds the search.
2478 Return a list whose CAR is `table-row' and CDR is a plist
2479 containing `:begin', `:end', `:contents-begin', `:contents-end',
2480 `:type' and `:post-blank' keywords."
2484 ;; A table rule has no contents. In that case, ensure
2485 ;; CONTENTS-BEGIN matches CONTENTS-END.
2497 :begin begin
2498 :end end
2499 :contents-begin contents-begin
2500 :contents-end contents-end
2504 "Interpret TABLE-ROW element as Org syntax.
2505 CONTENTS is the contents of the table row."
2510 ;;;; Verse Block
2513 "Parse a verse block.
2515 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2516 the buffer position at the beginning of the first affiliated
2517 keyword and CDR is a plist of affiliated keywords along with
2518 their value.
2520 Return a list whose CAR is `verse-block' and CDR is a plist
2521 containing `:begin', `:end', `:contents-begin', `:contents-end',
2522 `:post-blank' and `:post-affiliated' keywords.
2524 Assume point is at beginning of the block."
2528 ;; Incomplete block: parse it as a paragraph.
2543 :end end
2544 :contents-begin contents-begin
2545 :contents-end contents-end
2551 "Interpret VERSE-BLOCK element as Org syntax.
2552 CONTENTS is verse block contents."
2556 \f
2557 ;;; Objects
2558 ;;
2559 ;; Unlike to elements, interstices can be found between objects.
2560 ;; That's why, along with the parser, successor functions are provided
2561 ;; for each object. Some objects share the same successor (i.e. `code'
2562 ;; and `verbatim' objects).
2563 ;;
2564 ;; A successor must accept a single argument bounding the search. It
2565 ;; will return either a cons cell whose CAR is the object's type, as
2566 ;; a symbol, and CDR the position of its next occurrence, or nil.
2567 ;;
2568 ;; Successors follow the naming convention:
2569 ;; org-element-NAME-successor, where NAME is the name of the
2570 ;; successor, as defined in `org-element-all-successors'.
2571 ;;
2572 ;; Some object types (i.e. `italic') are recursive. Restrictions on
2573 ;; object types they can contain will be specified in
2574 ;; `org-element-object-restrictions'.
2575 ;;
2576 ;; Adding a new type of object is simple. Implement a successor,
2577 ;; a parser, and an interpreter for it, all following the naming
2578 ;; convention. Register type in `org-element-all-objects' and
2579 ;; successor in `org-element-all-successors'. Maybe tweak
2580 ;; restrictions about it, and that's it.
2583 ;;;; Bold
2586 "Parse bold object at point.
2588 Return a list whose CAR is `bold' and CDR is a plist with
2589 `:begin', `:end', `:contents-begin' and `:contents-end' and
2590 `:post-blank' keywords.
2592 Assume point is at the first star marker."
2604 :end end
2605 :contents-begin contents-begin
2606 :contents-end contents-end
2610 "Interpret BOLD object as Org syntax.
2611 CONTENTS is the contents of the object."
2615 "Search for the next text-markup object.
2617 Return value is a cons cell whose CAR is a symbol among `bold',
2618 `italic', `underline', `strike-through', `code' and `verbatim'
2619 and CDR is beginning position."
2635 ;;;; Code
2638 "Parse code object at point.
2640 Return a list whose CAR is `code' and CDR is a plist with
2641 `:value', `:begin', `:end' and `:post-blank' keywords.
2643 Assume point is at the first tilde marker."
2654 :begin begin
2655 :end end
2659 "Interpret CODE object as Org syntax.
2660 CONTENTS is nil."
2664 ;;;; Entity
2667 "Parse entity at point.
2669 Return a list whose CAR is `entity' and CDR a plist with
2670 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
2671 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
2672 keywords.
2674 Assume point is at the beginning of the entity."
2676 (looking-at "\\\\\\(there4\\|sup[123]\\|frac[13][24]\\|[a-zA-Z]+\\)\\($\\|{}\\|[^[:alpha:]]\\)")
2692 :begin begin
2693 :end end
2694 :use-brackets-p bracketsp
2698 "Interpret ENTITY object as Org syntax.
2699 CONTENTS is nil."
2705 "Search for the next latex-fragment or entity object.
2707 Return value is a cons cell whose CAR is `entity' or
2708 `latex-fragment' and CDR is beginning position."
2712 ;; ENTITY-RE matches both LaTeX commands and Org entities.
2719 ;; Determine if it's a real entity or a LaTeX command.
2722 ;; No entity nor command: point is at a LaTeX fragment.
2723 ;; Determine its type to get the correct beginning position.
2732 ;;;; Export Snippet
2735 "Parse export snippet at point.
2737 Return a list whose CAR is `export-snippet' and CDR a plist with
2738 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
2739 keywords.
2741 Assume point is at the beginning of the snippet."
2753 :value value
2754 :begin begin
2755 :end end
2759 "Interpret EXPORT-SNIPPET object as Org syntax.
2760 CONTENTS is nil."
2766 "Search for the next export-snippet object.
2768 Return value is a cons cell whose CAR is `export-snippet' and CDR
2769 its beginning position."
2778 ;;;; Footnote Reference
2781 "Parse footnote reference at point.
2783 Return a list whose CAR is `footnote-reference' and CDR a plist
2784 with `:label', `:type', `:inline-definition', `:begin', `:end'
2785 and `:post-blank' as keywords."
2807 :type type
2808 :begin begin
2809 :end end
2812 footnote-reference :inline-definition
2817 footnote-reference))))))
2820 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
2821 CONTENTS is nil."
2831 "Search for the next footnote-reference object.
2833 Return value is a cons cell whose CAR is `footnote-reference' and
2834 CDR is beginning position."
2848 ;;;; Inline Babel Call
2851 "Parse inline babel call at point.
2853 Return a list whose CAR is `inline-babel-call' and CDR a plist
2854 with `:begin', `:end', `:value' and `:post-blank' as keywords.
2856 Assume point is at the beginning of the babel call."
2868 :end end
2869 :value value
2873 "Interpret INLINE-BABEL-CALL object as Org syntax.
2874 CONTENTS is nil."
2878 "Search for the next inline-babel-call object.
2880 Return value is a cons cell whose CAR is `inline-babel-call' and
2881 CDR is beginning position."
2887 ;;;; Inline Src Block
2890 "Parse inline source block at point.
2892 Return a list whose CAR is `inline-src-block' and CDR a plist
2893 with `:begin', `:end', `:language', `:value', `:parameters' and
2894 `:post-blank' as keywords.
2896 Assume point is at the beginning of the inline src block."
2909 :value value
2910 :parameters parameters
2911 :begin begin
2912 :end end
2916 "Interpret INLINE-SRC-BLOCK object as Org syntax.
2917 CONTENTS is nil."
2922 language
2924 body)))
2927 "Search for the next inline-babel-call element.
2929 Return value is a cons cell whose CAR is `inline-babel-call' and
2930 CDR is beginning position."
2936 ;;;; Italic
2939 "Parse italic object at point.
2941 Return a list whose CAR is `italic' and CDR is a plist with
2942 `:begin', `:end', `:contents-begin' and `:contents-end' and
2943 `:post-blank' keywords.
2945 Assume point is at the first slash marker."
2957 :end end
2958 :contents-begin contents-begin
2959 :contents-end contents-end
2963 "Interpret ITALIC object as Org syntax.
2964 CONTENTS is the contents of the object."
2968 ;;;; Latex Fragment
2971 "Parse LaTeX fragment at point.
2973 Return a list whose CAR is `latex-fragment' and CDR a plist with
2974 `:value', `:begin', `:end', and `:post-blank' as keywords.
2976 Assume point is at the beginning of the LaTeX fragment."
2989 ;; None found: it's a macro.
2998 :begin begin
2999 :end end
3003 "Interpret LATEX-FRAGMENT object as Org syntax.
3004 CONTENTS is nil."
3007 ;;;; Line Break
3010 "Parse line break at point.
3012 Return a list whose CAR is `line-break', and CDR a plist with
3013 `:begin', `:end' and `:post-blank' keywords.
3015 Assume point is at the beginning of the line break."
3022 "Interpret LINE-BREAK object as Org syntax.
3023 CONTENTS is nil."
3027 "Search for the next line-break object.
3029 Return value is a cons cell whose CAR is `line-break' and CDR is
3030 beginning position."
3034 ;; A line break can only happen on a non-empty line.
3039 ;;;; Link
3042 "Parse link at point.
3044 Return a list whose CAR is `link' and CDR a plist with `:type',
3045 `:path', `:raw-link', `:application', `:search-option', `:begin',
3046 `:end', `:contents-begin', `:contents-end' and `:post-blank' as
3047 keywords.
3049 Assume point is at the beginning of the link."
3052 end contents-begin contents-end link-end post-blank path type
3053 raw-link link search-option application)
3055 ;; Type 1: Text targeted from a radio target.
3060 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
3065 ;; RAW-LINK is the original link. Expand any
3066 ;; abbreviation in it.
3070 ;; Determine TYPE of link and set PATH accordingly.
3072 ;; File type.
3076 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
3079 ;; Id type: PATH is the id.
3082 ;; Code-ref type: PATH is the name of the reference.
3085 ;; Custom-id type: PATH is the name of the custom id.
3088 ;; Fuzzy type: Internal link either matches a target, an
3089 ;; headline name or nothing. PATH is the target or
3090 ;; headline's name.
3092 ;; Type 3: Plain link, i.e. http://orgmode.org
3098 ;; Type 4: Angular link, i.e. <http://orgmode.org>
3105 ;; In any case, deduce end point after trailing white space from
3106 ;; LINK-END variable.
3109 ;; Extract search option and opening application out of
3110 ;; "file"-type links.
3112 ;; Application.
3117 ;; Extract search option from PATH.
3121 ;; Make sure TYPE always reports "file".
3125 :path path
3127 :application application
3128 :search-option search-option
3129 :begin begin
3130 :end end
3131 :contents-begin contents-begin
3132 :contents-end contents-end
3136 "Interpret LINK object as Org syntax.
3137 CONTENTS is the contents of the object, or nil."
3142 raw-link
3146 "Search for the next link object.
3148 Return value is a cons cell whose CAR is `link' and CDR is
3149 beginning position."
3158 "Search for the next plain link object.
3160 Return value is a cons cell whose CAR is `link' and CDR is
3161 beginning position."
3166 ;;;; Macro
3169 "Parse macro at point.
3171 Return a list whose CAR is `macro' and CDR a plist with `:key',
3172 `:args', `:begin', `:end', `:value' and `:post-blank' as
3173 keywords.
3175 Assume point is at the macro."
3186 ;; Do not use `org-split-string' since empty
3187 ;; strings are meaningful here.
3195 args nil t)
3199 :value value
3200 :args args
3201 :begin begin
3202 :end end
3206 "Interpret MACRO object as Org syntax.
3207 CONTENTS is nil."
3211 "Search for the next macro object.
3213 Return value is cons cell whose CAR is `macro' and CDR is
3214 beginning position."
3218 nil t)
3222 ;;;; Radio-target
3225 "Parse radio target at point.
3227 Return a list whose CAR is `radio-target' and CDR a plist with
3228 `:begin', `:end', `:contents-begin', `:contents-end', `:value'
3229 and `:post-blank' as keywords.
3231 Assume point is at the radio target."
3243 :end end
3244 :contents-begin contents-begin
3245 :contents-end contents-end
3246 :post-blank post-blank
3250 "Interpret TARGET object as Org syntax.
3251 CONTENTS is the contents of the object."
3255 "Search for the next radio-target object.
3257 Return value is a cons cell whose CAR is `radio-target' and CDR
3258 is beginning position."
3264 ;;;; Statistics Cookie
3267 "Parse statistics cookie at point.
3269 Return a list whose CAR is `statistics-cookie', and CDR a plist
3270 with `:begin', `:end', `:value' and `:post-blank' keywords.
3272 Assume point is at the beginning of the statistics-cookie."
3283 :end end
3284 :value value
3288 "Interpret STATISTICS-COOKIE object as Org syntax.
3289 CONTENTS is nil."
3293 "Search for the next statistics cookie object.
3295 Return value is a cons cell whose CAR is `statistics-cookie' and
3296 CDR is beginning position."
3302 ;;;; Strike-Through
3305 "Parse strike-through object at point.
3307 Return a list whose CAR is `strike-through' and CDR is a plist
3308 with `:begin', `:end', `:contents-begin' and `:contents-end' and
3309 `:post-blank' keywords.
3311 Assume point is at the first plus sign marker."
3323 :end end
3324 :contents-begin contents-begin
3325 :contents-end contents-end
3329 "Interpret STRIKE-THROUGH object as Org syntax.
3330 CONTENTS is the contents of the object."
3334 ;;;; Subscript
3337 "Parse subscript at point.
3339 Return a list whose CAR is `subscript' and CDR a plist with
3340 `:begin', `:end', `:contents-begin', `:contents-end',
3341 `:use-brackets-p' and `:post-blank' as keywords.
3343 Assume point is at the underscore."
3357 :end end
3358 :use-brackets-p bracketsp
3359 :contents-begin contents-begin
3360 :contents-end contents-end
3364 "Interpret SUBSCRIPT object as Org syntax.
3365 CONTENTS is the contents of the object."
3368 contents))
3371 "Search for the next sub/superscript object.
3373 Return value is a cons cell whose CAR is either `subscript' or
3374 `superscript' and CDR is beginning position."
3382 ;;;; Superscript
3385 "Parse superscript at point.
3387 Return a list whose CAR is `superscript' and CDR a plist with
3388 `:begin', `:end', `:contents-begin', `:contents-end',
3389 `:use-brackets-p' and `:post-blank' as keywords.
3391 Assume point is at the caret."
3405 :end end
3406 :use-brackets-p bracketsp
3407 :contents-begin contents-begin
3408 :contents-end contents-end
3412 "Interpret SUPERSCRIPT object as Org syntax.
3413 CONTENTS is the contents of the object."
3416 contents))
3419 ;;;; Table Cell
3422 "Parse table cell at point.
3424 Return a list whose CAR is `table-cell' and CDR is a plist
3425 containing `:begin', `:end', `:contents-begin', `:contents-end'
3426 and `:post-blank' keywords."
3434 :end end
3435 :contents-begin contents-begin
3436 :contents-end contents-end
3440 "Interpret TABLE-CELL element as Org syntax.
3441 CONTENTS is the contents of the cell, or nil."
3445 "Search for the next table-cell object.
3447 Return value is a cons cell whose CAR is `table-cell' and CDR is
3448 beginning position."
3452 ;;;; Target
3455 "Parse target at point.
3457 Return a list whose CAR is `target' and CDR a plist with
3458 `:begin', `:end', `:value' and `:post-blank' as keywords.
3460 Assume point is at the target."
3470 :end end
3471 :value value
3475 "Interpret TARGET object as Org syntax.
3476 CONTENTS is nil."
3480 "Search for the next target object.
3482 Return value is a cons cell whose CAR is `target' and CDR is
3483 beginning position."
3489 ;;;; Timestamp
3492 "Parse time stamp at point.
3494 Return a list whose CAR is `timestamp', and CDR a plist with
3495 `:type', `:raw-value', `:year-start', `:month-start',
3496 `:day-start', `:hour-start', `:minute-start', `:year-end',
3497 `:month-end', `:day-end', `:hour-end', `:minute-end',
3498 `:repeater-type', `:repeater-value', `:repeater-unit',
3499 `:warning-type', `:warning-value', `:warning-unit', `:begin',
3500 `:end', `:value' and `:post-blank' keywords.
3502 Assume point is at the beginning of the timestamp."
3520 date-start)
3531 raw-value)
3533 :repeater-type
3539 :repeater-unit
3548 :warning-unit
3551 year-start month-start day-start hour-start minute-start year-end
3552 month-end day-end hour-end minute-end)
3553 ;; Parse date-start.
3561 ;; Compute date-end. It can be provided directly in time-stamp,
3562 ;; or extracted from time range. Otherwise, it defaults to the
3563 ;; same values as date-start.
3573 :raw-value raw-value
3574 :year-start year-start
3575 :month-start month-start
3576 :day-start day-start
3577 :hour-start hour-start
3578 :minute-start minute-start
3579 :year-end year-end
3580 :month-end month-end
3581 :day-end day-end
3582 :hour-end hour-end
3583 :minute-end minute-end
3584 :begin begin
3585 :end end
3587 repeater-props
3588 warning-props)))))
3591 "Interpret TIMESTAMP object as Org syntax.
3592 CONTENTS is nil."
3611 ;; Build an Org timestamp string from TIME. ACTIVEP is
3612 ;; non-nil when time stamp is active. If WITH-TIME-P is
3613 ;; non-nil, add a time part. HOUR-END and MINUTE-END
3614 ;; specify a time range in the timestamp. REPEAT-STRING is
3615 ;; the repeater string, if any.
3619 org-time-stamp-formats)
3620 time)))
3626 nil nil ts)))
3631 " "
3632 s
3634 ;; Return value.
3635 ts)))
3647 build-ts-string
3666 0
3674 "--"
3686 "Search for the next timestamp object.
3688 Return value is a cons cell whose CAR is `timestamp' and CDR is
3689 beginning position."
3697 nil t)
3701 ;;;; Underline
3704 "Parse underline object at point.
3706 Return a list whose CAR is `underline' and CDR is a plist with
3707 `:begin', `:end', `:contents-begin' and `:contents-end' and
3708 `:post-blank' keywords.
3710 Assume point is at the first underscore marker."
3722 :end end
3723 :contents-begin contents-begin
3724 :contents-end contents-end
3728 "Interpret UNDERLINE object as Org syntax.
3729 CONTENTS is the contents of the object."
3733 ;;;; Verbatim
3736 "Parse verbatim object at point.
3738 Return a list whose CAR is `verbatim' and CDR is a plist with
3739 `:value', `:begin', `:end' and `:post-blank' keywords.
3741 Assume point is at the first equal sign marker."
3752 :begin begin
3753 :end end
3757 "Interpret VERBATIM object as Org syntax.
3758 CONTENTS is nil."
3762 \f
3763 ;;; Parsing Element Starting At Point
3764 ;;
3765 ;; `org-element--current-element' is the core function of this section.
3766 ;; It returns the Lisp representation of the element starting at
3767 ;; point.
3768 ;;
3769 ;; `org-element--current-element' makes use of special modes. They
3770 ;; are activated for fixed element chaining (i.e. `plain-list' >
3771 ;; `item') or fixed conditional element chaining (i.e. `headline' >
3772 ;; `section'). Special modes are: `first-section', `item',
3773 ;; `node-property', `section' and `table-row'.
3777 "Parse the element starting at point.
3779 Return value is a list like (TYPE PROPS) where TYPE is the type
3780 of the element and PROPS a plist of properties associated to the
3781 element.
3783 Possible types are defined in `org-element-all-elements'.
3785 LIMIT bounds the search.
3787 Optional argument GRANULARITY determines the depth of the
3788 recursion. Allowed values are `headline', `greater-element',
3789 `element', `object' or nil. When it is broader than `object' (or
3790 nil), secondary values will not be parsed, since they only
3791 contain objects.
3793 Optional argument SPECIAL, when non-nil, can be either
3794 `first-section', `item', `node-property', `section', and
3795 `table-row'.
3797 If STRUCTURE isn't provided but SPECIAL is set to `item', it will
3798 be computed.
3800 This function assumes point is always at the beginning of the
3801 element it has to parse."
3804 ;; Determine if parsing depth allows for secondary strings
3805 ;; parsing. It only applies to elements referenced in
3806 ;; `org-element-secondary-value-alist'.
3809 ;; Item.
3812 ;; Table Row.
3814 ;; Node Property.
3816 ;; Headline.
3819 ;; Sections (must be checked after headline).
3824 limit)))
3825 ;; When not at bol, point is at the beginning of an item or
3826 ;; a footnote definition: next item is always a paragraph.
3828 ;; Planning and Clock.
3833 ;; Inlinetask.
3836 ;; From there, elements can have affiliated keywords.
3839 ;; Jumping over affiliated keywords put point off-limits.
3840 ;; Parse them as regular keywords.
3844 ;; LaTeX Environment.
3848 ;; Drawer and Property Drawer.
3853 ;; Fixed Width
3856 ;; Inline Comments, Blocks, Babel Calls, Dynamic Blocks and
3857 ;; Keywords.
3866 org-element-block-name-alist)))
3881 ;; Footnote Definition.
3884 ;; Horizontal Rule.
3887 ;; Diary Sexp.
3890 ;; Table.
3892 ;; List.
3895 limit affiliated
3897 ;; Default element: Paragraph.
3901 ;; Most elements can have affiliated keywords. When looking for an
3902 ;; element beginning, we want to move before them, as they belong to
3903 ;; that element, and, in the meantime, collect information they give
3904 ;; into appropriate properties. Hence the following function.
3907 "Collect affiliated keywords from point down to LIMIT.
3909 Return a list whose CAR is the position at the first of them and
3910 CDR a plist of keywords and values and move point to the
3911 beginning of the first line after them.
3913 As a special case, if element doesn't start at the beginning of
3914 the line (i.e. a paragraph starting an item), CAR is current
3915 position of point and CDR is nil."
3919 ;; RESTRICT is the list of objects allowed in parsed
3920 ;; keywords value.
3922 output)
3925 ;; Apply translation to RAW-KWD. From there, KWD is
3926 ;; the official keyword.
3928 org-element-keyword-translation-alist))
3929 raw-kwd))
3930 ;; Find main value for any keyword.
3936 ;; PARSEDP is non-nil when keyword should have its
3937 ;; value parsed.
3939 ;; If KWD is a dual keyword, find its secondary
3940 ;; value. Maybe parse it.
3947 ;; Attribute a property name to KWD.
3949 ;; Now set final shape for VALUE.
3955 ;; Attributes can always appear on multiple lines.
3958 ;; Eventually store the new value in OUTPUT.
3960 ;; Move to next keyword.
3962 ;; If affiliated keywords are orphaned: move back to first one.
3963 ;; They will be parsed as a paragraph.
3965 ;; Return value.
3969 \f
3970 ;;; The Org Parser
3971 ;;
3972 ;; The two major functions here are `org-element-parse-buffer', which
3973 ;; parses Org syntax inside the current buffer, taking into account
3974 ;; region, narrowing, or even visibility if specified, and
3975 ;; `org-element-parse-secondary-string', which parses objects within
3976 ;; a given string.
3977 ;;
3978 ;; The (almost) almighty `org-element-map' allows to apply a function
3979 ;; on elements or objects matching some type, and accumulate the
3980 ;; resulting values. In an export situation, it also skips unneeded
3981 ;; parts of the parse tree.
3984 "Recursively parse the buffer and return structure.
3985 If narrowing is in effect, only parse the visible part of the
3986 buffer.
3988 Optional argument GRANULARITY determines the depth of the
3989 recursion. It can be set to the following symbols:
3991 `headline' Only parse headlines.
3992 `greater-element' Don't recurse into greater elements excepted
3993 headlines and sections. Thus, elements
3994 parsed are the top-level ones.
3995 `element' Parse everything but objects and plain text.
3996 `object' Parse the complete buffer (default).
3998 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3999 elements.
4001 An element or an objects is represented as a list with the
4002 pattern (TYPE PROPERTIES CONTENTS), where :
4004 TYPE is a symbol describing the element or object. See
4005 `org-element-all-elements' and `org-element-all-objects' for an
4006 exhaustive list of such symbols. One can retrieve it with
4007 `org-element-type' function.
4009 PROPERTIES is the list of attributes attached to the element or
4010 object, as a plist. Although most of them are specific to the
4011 element or object type, all types share `:begin', `:end',
4012 `:post-blank' and `:parent' properties, which respectively
4013 refer to buffer position where the element or object starts,
4014 ends, the number of white spaces or blank lines after it, and
4015 the element or object containing it. Properties values can be
4016 obtained by using `org-element-property' function.
4018 CONTENTS is a list of elements, objects or raw strings
4019 contained in the current element or object, when applicable.
4020 One can access them with `org-element-contents' function.
4022 The Org buffer has `org-data' as type and nil as properties.
4023 `org-element-map' function can be used to find specific elements
4024 or objects within the parse tree.
4026 This function assumes that current major mode is `org-mode'."
4032 ;; Start in `first-section' mode so text before the first
4033 ;; headline belongs to a section.
4037 "Recursively parse objects in STRING and return structure.
4039 RESTRICTION is a symbol limiting the object types that will be
4040 looked after.
4042 Optional argument PARENT, when non-nil, is the element or object
4043 containing the secondary string. It is used to set correctly
4044 `:parent' property within the string."
4045 ;; Copy buffer-local variables listed in
4046 ;; `org-element-object-variables' into temporary buffer. This is
4047 ;; required since object parsing is dependent on these variables.
4051 org-element-object-variables))))
4059 secondary))
4060 secondary))))
4064 "Map a function on selected elements or objects.
4066 DATA is a parse tree, an element, an object, a string, or a list
4067 of such constructs. TYPES is a symbol or list of symbols of
4068 elements or objects types (see `org-element-all-elements' and
4069 `org-element-all-objects' for a complete list of types). FUN is
4070 the function called on the matching element or object. It has to
4071 accept one argument: the element or object itself.
4073 When optional argument INFO is non-nil, it should be a plist
4074 holding export options. In that case, parts of the parse tree
4075 not exportable according to that property list will be skipped.
4077 When optional argument FIRST-MATCH is non-nil, stop at the first
4078 match for which FUN doesn't return nil, and return that value.
4080 Optional argument NO-RECURSION is a symbol or a list of symbols
4081 representing elements or objects types. `org-element-map' won't
4082 enter any recursive element or object whose type belongs to that
4083 list. Though, FUN can still be applied on them.
4085 When optional argument WITH-AFFILIATED is non-nil, FUN will also
4086 apply to matching objects within parsed affiliated keywords (see
4087 `org-element-parsed-keywords').
4089 Nil values returned from FUN do not appear in the results.
4092 Examples:
4093 ---------
4095 Assuming TREE is a variable containing an Org buffer parse tree,
4096 the following example will return a flat list of all `src-block'
4097 and `example-block' elements in it:
4099 \(org-element-map tree '(example-block src-block) 'identity)
4101 The following snippet will find the first headline with a level
4104 \(org-element-map tree 'headline
4105 \(lambda (hl)
4106 \(and (= (org-element-property :level hl) 1)
4108 \(org-element-property :begin hl)))
4109 nil t)
4111 The next example will return a flat list of all `plain-list' type
4112 elements in TREE that are not a sub-list themselves:
4114 \(org-element-map tree 'plain-list 'identity nil nil 'plain-list)
4116 Eventually, this example will return a flat list of all `bold'
4117 type objects containing a `latex-snippet' type object, even
4118 looking into captions:
4120 \(org-element-map tree 'bold
4121 \(lambda (b)
4122 \(and (org-element-map b 'latex-snippet 'identity nil t) b))
4123 nil nil nil t)"
4124 ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
4127 ;; Recursion depth is determined by --CATEGORY.
4134 ;; If one object is found, the function
4135 ;; has to recurse into every object.
4138 ;; If one regular element is found, the
4139 ;; function has to recurse, at least,
4140 ;; into every element it encounters.
4143 types)
4144 category)))
4145 ;; Compute properties for affiliated keywords if necessary.
4150 org-element-affiliated-keywords)))
4151 --acc
4152 --walk-tree
4156 ;; Recursively walk DATA. INFO, if non-nil, is a plist
4157 ;; holding contextual information.
4161 ;; Ignored element in an export context.
4163 ;; List of elements or objects.
4165 ;; Unconditionally enter parse trees.
4169 ;; Check if TYPE is matching among TYPES. If so,
4170 ;; apply FUN to --DATA and accumulate return value
4171 ;; into --ACC (or exit if FIRST-MATCH is non-nil).
4177 ;; If --DATA has a secondary string that can contain
4178 ;; objects with their type among TYPES, look into it.
4185 ;; If --DATA has any affiliated keywords and
4186 ;; WITH-AFFILIATED is non-nil, look for objects in
4187 ;; them.
4195 ;; Pay attention to the type of value.
4196 ;; Preserve order for multiple keywords.
4212 --affiliated-alist))
4213 ;; Determine if a recursion into --DATA is possible.
4215 ;; --TYPE is explicitly removed from recursion.
4217 ;; --DATA has no contents.
4219 ;; Looking for greater elements but --DATA is simply
4220 ;; an element or an object.
4223 ;; Looking for elements but --DATA is an object.
4226 ;; In any other case, map contents.
4230 ;; Return value in a proper order.
4234 ;; The following functions are internal parts of the parser.
4235 ;;
4236 ;; The first one, `org-element--parse-elements' acts at the element's
4237 ;; level.
4238 ;;
4239 ;; The second one, `org-element--parse-objects' applies on all objects
4240 ;; of a paragraph or a secondary string. It uses
4241 ;; `org-element--get-next-object-candidates' to optimize the search of
4242 ;; the next object in the buffer.
4243 ;;
4244 ;; More precisely, that function looks for every allowed object type
4245 ;; first. Then, it discards failed searches, keeps further matches,
4246 ;; and searches again types matched behind point, for subsequent
4247 ;; calls. Thus, searching for a given type fails only once, and every
4248 ;; object is searched only once at top level (but sometimes more for
4249 ;; nested types).
4253 "Parse elements between BEG and END positions.
4255 SPECIAL prioritize some elements over the others. It can be set
4256 to `first-section', `section' `item' or `table-row'.
4258 When value is `item', STRUCTURE will be used as the current list
4259 structure.
4261 GRANULARITY determines the depth of the recursion. See
4262 `org-element-parse-buffer' for more information.
4264 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
4265 elements.
4267 Elements are accumulated into ACC."
4270 ;; Visible only: skip invisible parts at the beginning of the
4271 ;; element.
4274 ;; When parsing only headlines, skip any text before first one.
4277 ;; Main loop start.
4279 ;; Find current element's type and parse it accordingly to
4280 ;; its category.
4282 end granularity special structure))
4286 ;; Visible only: skip invisible parts between siblings.
4289 ;; Fill ELEMENT contents by side-effect.
4291 ;; If element has no contents, don't modify it.
4293 ;; Greater element: parse it between `contents-begin' and
4294 ;; `contents-end'. Make sure GRANULARITY allows the
4295 ;; recursion, or ELEMENT is a headline, in which case going
4296 ;; inside is mandatory, in order to get sub-level headings.
4304 ;; Possibly switch to a special mode.
4312 granularity visible-only element))
4313 ;; ELEMENT has contents. Parse objects inside, if
4314 ;; GRANULARITY allows it.
4320 ;; Return result.
4321 acc))
4324 "Parse objects between BEG and END and return recursive structure.
4326 Objects are accumulated in ACC.
4328 RESTRICTION is a list of object successors which are allowed in
4329 the current object."
4338 restriction candidates)))
4345 ;; 1. Text before any object. Untabify it.
4350 acc
4354 ;; 2. Object...
4357 ;; Fill contents of NEXT-OBJECT by side-effect, if it has
4358 ;; a recursive type.
4366 ;; 3. Text after last object. Untabify it.
4370 acc
4374 ;; Result.
4375 acc))))
4378 "Return an alist of candidates for the next object.
4380 RESTRICTION is a list of object types, as symbols. Only
4381 candidates with such types are looked after.
4383 OBJECTS is the previous candidates alist. If it is set to
4384 `initial', no search has been done before, and all symbols in
4385 RESTRICTION should be looked after.
4387 Return value is an alist whose CAR is the object type and CDR its
4388 beginning position."
4390 nil
4392 ;; When searching for the first time, look for every successor
4393 ;; allowed in RESTRICTION.
4397 restriction)
4398 ;; Focus on objects returned during last search. Keep those
4399 ;; still after point. Search again objects before it.
4405 type)))
4408 objects))))
4411 \f
4412 ;;; Towards A Bijective Process
4413 ;;
4414 ;; The parse tree obtained with `org-element-parse-buffer' is really
4415 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
4416 ;; interpreted and expanded into a string with canonical Org syntax.
4417 ;; Hence `org-element-interpret-data'.
4418 ;;
4419 ;; The function relies internally on
4420 ;; `org-element--interpret-affiliated-keywords'.
4422 ;;;###autoload
4424 "Interpret DATA as Org syntax.
4426 DATA is a parse tree, an element, an object or a secondary string
4427 to interpret.
4429 Optional argument PSEUDO-OBJECTS is a list of symbols defining
4430 new types that should be treated as objects. An unknown type not
4431 belonging to this list is seen as a pseudo-element instead. Both
4432 pseudo-objects and pseudo-elements are transparent entities, i.e.
4433 only their contents are interpreted.
4435 Return Org syntax as a string."
4439 "Interpret DATA as Org syntax.
4441 DATA is a parse tree, an element, an object or a secondary string
4442 to interpret. PARENT is used for recursive calls. It contains
4443 the element or object containing data, or nil. PSEUDO-OBJECTS
4444 are list of symbols defining new element or object types.
4445 Unknown types that don't belong to this list are treated as
4446 pseudo-elements instead.
4448 Return Org syntax as a string."
4450 ;; Find interpreter for current object or element. If it
4451 ;; doesn't exist (e.g. this is a pseudo object or element),
4452 ;; return contents, if any.
4458 ;; Secondary string.
4464 ;; Full Org document.
4470 ;; Plain text: return it.
4472 ;; Element or object without contents.
4474 ;; Element or object with contents.
4477 ;; Recursively interpret contents.
4483 data
4484 ;; Fix indentation of elements containing
4485 ;; objects. We ignore `table-row' elements
4486 ;; as they are one line long anyway.
4488 data
4489 ;; When normalizing first paragraph of an
4490 ;; item or a footnote-definition, ignore
4491 ;; first line's indentation.
4498 ;; Build white spaces. If no `:post-blank' property is
4499 ;; specified, assume its value is 0.
4510 "Return ELEMENT's affiliated keywords as Org syntax.
4511 If there is no affiliated keyword, return the empty string."
4521 ": "
4524 value)
4532 ;; All attribute keywords can have multiple lines.
4538 ;; List all ELEMENT's properties matching an attribute line or an
4539 ;; affiliated keyword, but ignore translated keywords since they
4540 ;; cannot belong to the property list.
4547 org-element-keyword-translation-alist)))))
4548 collect prop)
4551 ;; Because interpretation of the parse tree must return the same
4552 ;; number of blank lines between elements and the same number of white
4553 ;; space after objects, some special care must be given to white
4554 ;; spaces.
4555 ;;
4556 ;; The first function, `org-element-normalize-string', ensures any
4557 ;; string different from the empty string will end with a single
4558 ;; newline character.
4559 ;;
4560 ;; The second function, `org-element-normalize-contents', removes
4561 ;; global indentation from the contents of the current element.
4564 "Ensure string S ends with a single newline character.
4566 If S isn't a string return it unchanged. If S is the empty
4567 string, return it. Otherwise, return a new string with a single
4568 newline character at its end."
4576 "Normalize plain text in ELEMENT's contents.
4578 ELEMENT must only contain plain text and objects.
4580 If optional argument IGNORE-FIRST is non-nil, ignore first line's
4581 indentation to compute maximal common indentation.
4583 Return the normalized element that is element with global
4584 indentation removed from its contents. The function assumes that
4585 indentation is not done with TAB characters."
4587 find-min-ind ; For byte-compiler.
4590 ;; Return minimal common indentation within BLOB. This is
4591 ;; done by walking recursively BLOB and updating MIN-IND
4592 ;; along the way. FIRST-FLAG is non-nil when the first
4593 ;; string hasn't been seen yet. It is required as this
4594 ;; string is the only one whose indentation doesn't happen
4595 ;; after a newline character.
4602 ;; An indentation of zero means no string will be
4603 ;; modified. Quit the process.
4612 ;; Find minimal indentation in ELEMENT.
4615 ;; Build ELEMENT back, replacing each string with the same
4616 ;; string minus common indentation.
4621 ;; Return BLOB with all its strings indentation
4622 ;; shortened from MIN-IND white spaces. FIRST-FLAG
4623 ;; is non-nil when the first string hasn't been seen
4624 ;; yet.
4639 org-element-recursive-objects)
4643 blob))))
4647 \f
4648 ;;; The Toolbox
4649 ;;
4650 ;; The first move is to implement a way to obtain the smallest element
4651 ;; containing point. This is the job of `org-element-at-point'. It
4652 ;; basically jumps back to the beginning of section containing point
4653 ;; and proceed, one element after the other, with
4654 ;; `org-element--current-element' until the container is found. Note:
4655 ;; When using `org-element-at-point', secondary values are never
4656 ;; parsed since the function focuses on elements, not on objects.
4657 ;;
4658 ;; At a deeper level, `org-element-context' lists all elements and
4659 ;; objects containing point.
4660 ;;
4661 ;; `org-element-nested-p' and `org-element-swap-A-B' may be used
4662 ;; internally by navigation and manipulation tools.
4665 ;;;###autoload
4667 "Determine closest element around point.
4669 Return value is a list like (TYPE PROPS) where TYPE is the type
4670 of the element and PROPS a plist of properties associated to the
4671 element.
4673 Possible types are defined in `org-element-all-elements'.
4674 Properties depend on element or object type, but always include
4675 `:begin', `:end', `:parent' and `:post-blank' properties.
4677 As a special case, if point is at the very beginning of the first
4678 item in a list or sub-list, returned element will be that list
4679 instead of the item. Likewise, if point is at the beginning of
4680 the first row of a table, returned element will be the table
4681 instead of the first row.
4683 When point is at the end of the buffer, return the innermost
4684 element ending there."
4691 ;; Within blank lines at the beginning of buffer, return nil.
4693 ;; Within blank lines right after a headline, return that
4694 ;; headline.
4698 ;; Otherwise use cache in order to approximate current element.
4703 ;; Nothing in cache before point: start parsing from first
4704 ;; element following headline above, or first element in
4705 ;; buffer.
4711 ;; Cache returned exact match: return it.
4713 ;; There's a headline between cached value and ORIGIN:
4714 ;; cached value is invalid. Start parsing from first
4715 ;; element following the headline.
4721 ;; Check if CACHED or any of its ancestors contain point.
4722 ;;
4723 ;; If there is such an element, we inspect it in order to
4724 ;; know if we return it or if we need to parse its contents.
4725 ;; Otherwise, we just start parsing from current location,
4726 ;; which is right after the top-most element containing
4727 ;; CACHED.
4728 ;;
4729 ;; As a special case, if ORIGIN is at the end of the buffer,
4730 ;; we want to return the innermost element ending there.
4731 ;;
4732 ;; Also, if we find an ancestor and discover that we need to
4733 ;; parse its contents, make sure we don't start from
4734 ;; `:contents-begin', as we would otherwise go past CACHED
4735 ;; again. Instead, in that situation, we will resume
4736 ;; parsing from NEXT, which is located after CACHED or its
4737 ;; higher ancestor not containing point.
4742 begin))
4750 ;; Parse successively each element until we reach ORIGIN.
4755 parent special-flag)
4759 end 'element special-flag
4766 ;; Special case: ORIGIN is at the end of the buffer and
4767 ;; CACHED ends here. No element can start after it, but
4768 ;; more than one may end there. Arbitrarily, we choose
4769 ;; to return the innermost of such elements.
4782 parent element
4783 end cend))))
4784 ;; Skip any element ending before point. Also skip
4785 ;; element ending at point since we're sure that another
4786 ;; element begins after it.
4788 ;; A non-greater element contains point: return it.
4791 ;; Otherwise, we have to decide if ELEMENT really
4792 ;; contains ORIGIN. In that case we start parsing from
4793 ;; contents' beginning. Otherwise we return UP as it is
4794 ;; the smallest element containing ORIGIN.
4795 ;;
4796 ;; There is a special cases to consider, though. If
4797 ;; ORIGIN is at contents' beginning but it is also at
4798 ;; the beginning of the first item in a list or a table.
4799 ;; In that case, we need to create an anchor for that
4800 ;; list or table, so return it.
4812 parent element
4813 end cend))))))
4814 ;; Continue parsing buffer contents from new position.
4817 ;;;###autoload
4819 "Return closest element or object around point.
4821 Return value is a list like (TYPE PROPS) where TYPE is the type
4822 of the element or object and PROPS a plist of properties
4823 associated to it.
4825 Possible types are defined in `org-element-all-elements' and
4826 `org-element-all-objects'. Properties depend on element or
4827 object type, but always include `:begin', `:end', `:parent' and
4828 `:post-blank'.
4830 Optional argument ELEMENT, when non-nil, is the closest element
4831 containing point, as returned by `org-element-at-point'.
4832 Providing it allows for quicker computation."
4838 ;; If point is inside an element containing objects or
4839 ;; a secondary string, narrow buffer to the container and
4840 ;; proceed with parsing. Otherwise, return ELEMENT.
4842 ;; At a parsed affiliated keyword, check if we're inside main
4843 ;; or dual value.
4850 org-element-parsed-keywords))
4859 ;; Also change type to retrieve correct restrictions.
4861 ;; At an item, objects can only be located within tag, if any.
4871 ;; At an headline or inlinetask, objects are in title.
4878 ;; At a paragraph, a table-row or a verse block, objects are
4879 ;; located within their contents.
4883 ;; CBEG is nil for table rules.
4887 ;; At a parsed keyword, objects are located within value.
4890 org-element-document-properties))
4897 ;; All other locations cannot contain objects: bail out.
4904 objects-data next update-cache-flag)
4908 ;; Get list of next object candidates in CANDIDATES.
4909 ;; When entering for the first time PARENT, grab it
4910 ;; from cache, if available, or compute it. Then,
4911 ;; for each subsequent iteration in PARENT, always
4912 ;; compute it since we're beyond cache anyway.
4917 cache))))
4921 restriction candidates))
4923 ;; Compare ORIGIN with next object starting position,
4924 ;; if any.
4925 ;;
4926 ;; If ORIGIN is lesser or if there is no object
4927 ;; following, look for a previous object that might
4928 ;; contain it in cache. If there is no cache, we
4929 ;; didn't miss any object so simply return PARENT.
4930 ;;
4931 ;; If ORIGIN is greater or equal, parse next
4932 ;; candidate for further processing.
4936 candidates))))
4942 ;; Object ends before ORIGIN and we
4943 ;; know next one in cache starts
4944 ;; after it: bail out.
4952 ;; Process NEXT to know if we need to skip it, return
4953 ;; it or move into it.
4958 ;; ORIGIN is after NEXT, so skip it.
4960 ;; ORIGIN is within a non-recursive next or
4961 ;; at an object boundaries: Return that object.
4965 ;; Otherwise, move into NEXT and reset flags as we
4966 ;; shift parent.
4972 next nil
4973 objects-data nil
4975 ;; Store results in cache, if applicable.
4979 "Non-nil when elements ELEM-A and ELEM-B are nested."
4988 "Swap elements ELEM-A and ELEM-B.
4989 Assume ELEM-B is after ELEM-A in the buffer. Leave point at the
4990 end of ELEM-A."
4992 ;; There are two special cases when an element doesn't start at bol:
4993 ;; the first paragraph in an item or in a footnote definition.
4995 ;; Only a paragraph without any affiliated keyword can be moved at
4996 ;; ELEM-A position in such a situation. Note that the case of
4997 ;; a footnote definition is impossible: it cannot contain two
4998 ;; paragraphs in a row because it cannot contain a blank line.
5004 ;; In a special situation, ELEM-A will have no indentation. We'll
5005 ;; give it ELEM-B's (which will in, in turn, have no indentation).
5019 ;; Store overlays responsible for visibility status. We
5020 ;; also need to store their boundaries as they will be
5021 ;; removed from buffer.
5028 ;; Get contents.
5036 ;; Restore ex ELEM-A overlays.
5045 ;; Restore ex ELEM-B overlays.
5053 "Remove maximum common indentation in string S and return it.
5054 When optional argument N is a positive integer, remove exactly
5055 that much characters from indentation, if possible, or return
5056 S as-is otherwise. Unlike to `org-remove-indentation', this
5057 function doesn't call `untabify' on S."
5062 ;; Find maximum common indentation, if not specified.
5070 min-ind)))
5072 ;; Remove exactly N indentation, but give up if not possible.
5082 \f
5083 ;;; Cache
5084 ;;
5085 ;; Both functions `org-element-at-point' and `org-element-context'
5086 ;; benefit from a simple caching mechanism.
5087 ;;
5088 ;; Three public functions are provided: `org-element-cache-put',
5089 ;; `org-element-cache-get' and `org-element-cache-reset'.
5090 ;;
5091 ;; Cache is enabled by default, but can be disabled globally with
5092 ;; `org-element-use-cache'. `org-element-cache-sync-idle-time' and
5093 ;; `org-element-cache-merge-changes-threshold' can be tweaked to
5094 ;; control caching behaviour.
5098 "Non nil when Org parser should cache its results.
5102 "Number of characters triggering cache syncing.
5104 The cache mechanism only stores one buffer modification at any
5105 given time. When another change happens, it replaces it with
5106 a change containing both the stored modification and the current
5107 one. This is a trade-off, as merging them prevents another
5108 syncing, but every element between them is then lost.
5110 This variable determines the maximum size, in characters, we
5114 "Number of seconds of idle time wait before syncing buffer cache.
5115 Syncing also happens when current modification is too distant
5116 from the stored one (for more information, see
5120 ;;;; Data Structure
5123 "AVL tree used to cache elements.
5124 Each node of the tree contains an element. Comparison is done
5125 with `org-element--cache-compare'. This cache is used in
5129 "Hash table used as to cache objects.
5130 Key is an element, as returned by `org-element-at-point', and
5131 value is an alist where each association is:
5133 \(POS CANDIDATES . OBJECTS)
5135 where POS is a buffer position, CANDIDATES is the last know list
5136 of successors (see `org-element--get-next-object-candidates') in
5137 container starting at POS and OBJECTS is a list of objects known
5138 to live within that container, from farthest to closest.
5141 at, respectively, positions 1, 7 and 8,
5145 If the paragraph is completely parsed, OBJECTS-DATA will be
5147 \((1 nil BOLD-OBJECT ENTITY-OBJECT)
5148 \(8 nil ENTITY-OBJECT))
5150 whereas in a partially parsed paragraph, it could be
5152 \((1 ((entity . 1) (bold . 7)) ENTITY-OBJECT))
5157 "Non-nil when element A is located before element B."
5161 ;; Items and plain lists on the one hand, table rows and
5162 ;; tables on the other hand can start at the same position.
5163 ;; In this case, the parent element is always before its child
5164 ;; in the buffer.
5170 "Return root value in cache.
5171 This function assumes `org-element--cache' is a valid AVL tree."
5175 ;;;; Staging Buffer Changes
5178 "Contains data about cache validity for current buffer.
5180 Value is a vector of seven elements,
5182 [ACTIVEP BEGIN END OFFSET TIMER PREVIOUS-STATE]
5184 ACTIVEP is a boolean non-nil when changes described in the other
5185 slots are valid for current buffer.
5187 BEGIN and END are the beginning and ending position of the area
5188 for which cache cannot be trusted.
5190 OFFSET it an integer specifying the number to add to position of
5191 elements after that area.
5193 TIMER is a timer used to apply these changes to cache when Emacs
5194 is idle.
5196 PREVIOUS-STATE is a symbol referring to the state of the buffer
5197 before a change happens. It is used to know if sensitive
5198 areas (block boundaries, headlines) were modified. It can be set
5207 "Regexp matching an element opening line.
5208 When such a line is modified, modifications may propagate after
5209 modified area. In that situation, every element between that
5218 "Regexp matching an element closing line.
5219 When such a line is modified, modifications may propagate before
5220 modified area. In that situation, every element between that
5224 "Non-nil when changes are not integrated in cache yet."
5229 "Push change to current buffer staging area.
5230 BEG and END and the beginning and ending position of the
5231 modification area. OFFSET is the size of the change, as an
5232 integer."
5240 nil
5241 #'org-element--cache-sync
5246 "Remove any cache change set for current buffer."
5252 "Request extension of area going to be modified if needed.
5253 BEG and END are the beginning and end of the range of changed
5254 text. See `before-change-functions' for more information."
5262 ;; A sensitive line is a headline or a block (or drawer,
5263 ;; or latex-environment) boundary. Inserting one can
5264 ;; modify buffer drastically both above and below that
5265 ;; line, possibly making cache invalid. Therefore, we
5266 ;; need to pay special attention to changes happening to
5267 ;; them.
5271 org-element--cache-opening-line)))
5284 "Update buffer modifications for current buffer.
5286 BEG and END are the beginning and end of the range of changed
5287 text, and the length in bytes of the pre-change text replaced by
5288 that range. See `after-change-functions' for more information.
5290 If there are already pending changes, try to merge them into
5291 a bigger change record. If that's not possible, the function
5292 will first synchronize cache with previous change and store the
5293 new one."
5303 ;; Determine if modified area needs to be extended,
5304 ;; according to both previous and current state. We make
5305 ;; a special case for headline editing: if a headline is
5306 ;; modified but not removed, do not extend.
5311 org-element--cache-opening-line)))
5322 ;; Effectively extend modified area.
5325 ;; Headline above is inclusive.
5329 ;; Headline below is exclusive.
5331 ;; Store changes.
5334 ;; No pending changes. Store the new ones.
5341 ;; If we cannot merge two change sets (i.e. they
5342 ;; modify distinct buffer parts) first apply current
5343 ;; change set and store new one. This way, there is
5344 ;; never more than one pending change set, which
5345 ;; avoids handling costly merges.
5349 ;; Change sets can be merged. We can expand the area
5350 ;; that requires an update, and postpone the sync.
5359 ;;;; Synchronization
5362 "Shift ELEMENT properties relative to buffer positions by OFFSET.
5364 Properties containing buffer positions are `:begin', `:end',
5365 `:contents-begin', `:contents-end' and `:structure'. When
5366 optional argument PROPS is a list of keywords, only shift
5367 properties provided in that list.
5369 Properties are modified by side-effect. Return ELEMENT."
5371 ;; Shift :structure property for the first plain list only: it is
5372 ;; the only one that really matters and it prevents from shifting
5373 ;; it more than once.
5385 element)
5388 "Apply FUNCTION to all elements in cache.
5389 FUNCTION is applied to the elements in ascending order, or
5390 descending order if REVERSE is non-nil."
5398 "Synchronize cache with recent modification in BUFFER.
5399 Elements ending before modification area are kept in cache.
5400 Elements starting after modification area have their position
5401 shifted by the size of the modification. Every other element is
5402 removed from the cache."
5409 ;; END is the beginning position of the first element
5410 ;; in cache that isn't removed but needs to be
5411 ;; shifted. It will be updated during phase 1.
5413 ;; Phase 1.
5414 ;;
5415 ;; Delete, in ascending order, all elements starting after
5416 ;; BEG, but before END.
5417 ;;
5418 ;; BEG is the position of the first element in cache to
5419 ;; remove. It takes into consideration partially modified
5420 ;; elements (starting before changes but ending after
5421 ;; them). Though, it preserves greater elements that are
5422 ;; not affected when changes alter only their contents.
5423 ;;
5424 ;; END is updated when necessary to include elements
5425 ;; starting after modifications but included in an element
5426 ;; altered by modifications.
5427 ;;
5428 ;; At each iteration, we start again at tree root since
5429 ;; a deletion modifies structure of the balanced tree.
5440 drawer dynamic-block inlinetask
5441 property-drawer quote-block
5442 special-block))
5444 beg)
5446 end))
5447 ;; UP is a greater element that is
5448 ;; wrapped around the changes. We
5449 ;; only need to extend its ending
5450 ;; boundaries and those of all its
5451 ;; parents.
5462 ;; We're at top level element containing
5463 ;; ELEMENT: if it's altered by buffer
5464 ;; modifications, it is first element in
5465 ;; cache to be removed. Otherwise, that
5466 ;; first element is the following one.
5471 ;; DATA will contain the closest element from
5472 ;; BEG, always after it.
5484 node nil)))))
5486 ;; No DATA is found so there's no element left
5487 ;; after BEG. Bail out.
5489 ;; Element starts after END, it is the first
5490 ;; one that needn't be removed from cache.
5491 ;; Move to second phase.
5493 ;; Remove element. Extend END so that all
5494 ;; elements it may contain are also removed.
5499 t)))))
5500 ;; Phase 2.
5501 ;;
5502 ;; Shift all elements starting after END by OFFSET (for an
5503 ;; offset different from 0).
5504 ;;
5505 ;; Increasing all beginning positions by OFFSET doesn't
5506 ;; alter tree structure, so elements are modified by
5507 ;; side-effect.
5508 ;;
5509 ;; We change all elements in decreasing order and make
5510 ;; sure to quit at the first element in cache starting
5511 ;; before END.
5518 ;; Shift element.
5520 ;; Shift associated objects data, if any.
5528 object offset)))))
5530 ;; Eventually signal cache as up-to-date.
5534 ;;;; Public Functions
5537 "Return cached data relative to KEY.
5539 KEY is either a number or an Org element, as returned by
5540 `org-element-at-point'. If KEY is a number, return closest
5541 cached data before or at position KEY. Otherwise, return cached
5542 objects contained in element KEY.
5544 In any case, return nil if no data is found, or if caching is not
5545 allowed.
5547 If changes are pending in current buffer, first synchronize the
5548 cache, unless optional argument IGNORE-CHANGES is non-nil."
5550 ;; If there are pending changes, first sync them.
5565 ;; When KEY is at the beginning of a table or list,
5566 ;; make sure to return it instead of the first row or
5567 ;; item.
5571 beg))
5575 last)))))
5578 "Store DATA in current buffer's cache, if allowed.
5579 If optional argument ELEMENT is non-nil, store DATA as objects
5580 relative to it. Otherwise, store DATA as an element. Nothing
5581 will be stored if `org-element-use-cache' is nil. Return DATA."
5588 ;;;###autoload
5590 "Reset cache in current buffer.
5591 When optional argument ALL is non-nil, reset cache in all Org
5592 buffers. This function will do nothing if
5593 `org-element-use-cache' is nil."
5605 'org-element--cache-objects
5617 ;; Local variables:
5618 ;; generated-autoload-file: "org-loaddefs.el"
5619 ;; End:
5621 ;;; org-element.el ends here