| blob | fa112512332b5e1dc69b56e53233c0d7e7870531 |
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 (e.g. 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 cache mechanism is also provided for
113 ;; 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 inline-src-block latex-or-entity line-break macro plain-link
192 radio-target 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, superscript and text
350 markup.
352 This alist also applies to secondary string. For example, an
353 `headline' type element doesn't directly contain objects, but
364 "List of buffer-local variables used when parsing objects.
365 These variables are copied to the temporary buffer created by
369 \f
370 ;;; Accessors and Setters
371 ;;
372 ;; Provide four accessors: `org-element-type', `org-element-property'
373 ;; `org-element-contents' and `org-element-restriction'.
374 ;;
375 ;; Setter functions allow to modify elements by side effect. There is
376 ;; `org-element-put-property', `org-element-set-contents'. These
377 ;; low-level functions are useful to build a parse tree.
378 ;;
379 ;; `org-element-adopt-element', `org-element-set-element',
380 ;; `org-element-extract-element' and `org-element-insert-before' are
381 ;; high-level functions useful to modify a parse tree.
382 ;;
383 ;; `org-element-secondary-p' is a predicate used to know if a given
384 ;; object belongs to a secondary string.
387 "Return type of ELEMENT.
389 The function returns the type of the element or object provided.
390 It can also return the following special value:
391 `plain-text' for a string
392 `org-data' for a complete document
393 nil in any other case."
399 "Extract the value from the PROPERTY of an ELEMENT."
404 "Extract contents from an ELEMENT."
410 "Return restriction associated to ELEMENT.
411 ELEMENT can be an element, an object or a symbol representing an
412 element or object type."
414 org-element-object-restrictions)))
417 "In ELEMENT set PROPERTY to VALUE.
418 Return modified element."
421 element))
424 "Set ELEMENT contents to CONTENTS.
425 Return modified element."
432 "Non-nil when OBJECT belongs to a secondary string.
433 Return value is the property name, as a keyword, or nil."
436 org-element-secondary-value-alist))))
439 property)))
442 "Append elements to the contents of another element.
444 PARENT is an element or object. CHILDREN can be elements,
445 objects, or a strings.
447 The function takes care of setting `:parent' property for CHILD.
448 Return parent element."
449 ;; Link every child to PARENT. If PARENT is nil, it is a secondary
450 ;; string: parent is the list itself.
453 children)
454 ;; Add CHILDREN at the end of PARENT contents.
457 parent
459 ;; Return modified PARENT element.
463 "Extract ELEMENT from parse tree.
464 Remove element from the parse tree by side-effect, and return it
465 with its `:parent' property stripped out."
470 parent secondary
473 parent
475 ;; Return ELEMENT with its :parent removed.
479 "Insert ELEMENT before LOCATION in parse tree.
480 LOCATION is an element, object or string within the parse tree.
481 Parse tree is modified by side effect."
486 ;; Special case: LOCATION is the first element of an
487 ;; independent secondary string (e.g. :title property). Add
488 ;; ELEMENT in-place.
492 ;; Install ELEMENT at the appropriate POSITION within SIBLINGS.
502 ;; Store SIBLINGS at appropriate place in parse tree.
507 ;; Set appropriate :parent property.
511 "Replace element or object OLD with element or object NEW.
512 The function takes care of setting `:parent' property for NEW."
513 ;; Ensure OLD and NEW have the same parent.
517 ;; We cannot replace OLD with NEW since one of them is not an
518 ;; object or element. We take the long path.
521 ;; Since OLD is going to be changed into NEW by side-effect, first
522 ;; make sure that every element or object within NEW has OLD as
523 ;; parent.
526 ;; Transfer contents.
528 ;; Overwrite OLD's properties with NEW's.
530 ;; Transfer type.
534 \f
535 ;;; Greater elements
536 ;;
537 ;; For each greater element type, we define a parser and an
538 ;; interpreter.
539 ;;
540 ;; A parser returns the element or object as the list described above.
541 ;; Most of them accepts no argument. Though, exceptions exist. Hence
542 ;; every element containing a secondary string (see
543 ;; `org-element-secondary-value-alist') will accept an optional
544 ;; argument to toggle parsing of that secondary string. Moreover,
545 ;; `item' parser requires current list's structure as its first
546 ;; element.
547 ;;
548 ;; An interpreter accepts two arguments: the list representation of
549 ;; the element or object, and its contents. The latter may be nil,
550 ;; depending on the element or object considered. It returns the
551 ;; appropriate Org syntax, as a string.
552 ;;
553 ;; Parsing functions must follow the naming convention:
554 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
555 ;; defined in `org-element-greater-elements'.
556 ;;
557 ;; Similarly, interpreting functions must follow the naming
558 ;; convention: org-element-TYPE-interpreter.
559 ;;
560 ;; With the exception of `headline' and `item' types, greater elements
561 ;; cannot contain other greater elements of their own type.
562 ;;
563 ;; Beside implementing a parser and an interpreter, adding a new
564 ;; greater element requires to tweak `org-element--current-element'.
565 ;; Moreover, the newly defined type must be added to both
566 ;; `org-element-all-elements' and `org-element-greater-elements'.
569 ;;;; Center Block
572 "Parse a center block.
574 LIMIT bounds the search. AFFILIATED is a list of which CAR is
575 the buffer position at the beginning of the first affiliated
576 keyword and CDR is a plist of affiliated keywords along with
577 their value.
579 Return a list whose CAR is `center-block' and CDR is a plist
580 containing `:begin', `:end', `:contents-begin', `:contents-end',
581 `:post-blank' and `:post-affiliated' keywords.
583 Assume point is at the beginning of the block."
587 ;; Incomplete block: parse it as a paragraph.
592 ;; Empty blocks have no contents.
606 :end end
607 :contents-begin contents-begin
608 :contents-end contents-end
614 "Interpret CENTER-BLOCK element as Org syntax.
615 CONTENTS is the contents of the element."
619 ;;;; Drawer
622 "Parse a drawer.
624 LIMIT bounds the search. AFFILIATED is a list of which CAR is
625 the buffer position at the beginning of the first affiliated
626 keyword and CDR is a plist of affiliated keywords along with
627 their value.
629 Return a list whose CAR is `drawer' and CDR is a plist containing
630 `:drawer-name', `:begin', `:end', `:contents-begin',
631 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
633 Assume point is at beginning of drawer."
636 ;; Incomplete drawer: parse it as a paragraph.
644 ;; Empty drawers have no contents.
657 :end end
658 :drawer-name name
659 :contents-begin contents-begin
660 :contents-end contents-end
666 "Interpret DRAWER element as Org syntax.
667 CONTENTS is the contents of the element."
670 contents))
673 ;;;; Dynamic Block
676 "Parse a dynamic block.
678 LIMIT bounds the search. AFFILIATED is a list of which CAR is
679 the buffer position at the beginning of the first affiliated
680 keyword and CDR is a plist of affiliated keywords along with
681 their value.
683 Return a list whose CAR is `dynamic-block' and CDR is a plist
684 containing `:block-name', `:begin', `:end', `:contents-begin',
685 `:contents-end', `:arguments', `:post-blank' and
686 `:post-affiliated' keywords.
688 Assume point is at beginning of dynamic block."
692 ;; Incomplete block: parse it as a paragraph.
701 ;; Empty blocks have no contents.
714 :end end
715 :block-name name
716 :arguments arguments
717 :contents-begin contents-begin
718 :contents-end contents-end
724 "Interpret DYNAMIC-BLOCK element as Org syntax.
725 CONTENTS is the contents of the element."
730 contents))
733 ;;;; Footnote Definition
736 "Parse a footnote definition.
738 LIMIT bounds the search. AFFILIATED is a list of which CAR is
739 the buffer position at the beginning of the first affiliated
740 keyword and CDR is a plist of affiliated keywords along with
741 their value.
743 Return a list whose CAR is `footnote-definition' and CDR is
744 a plist containing `:label', `:begin' `:end', `:contents-begin',
745 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
747 Assume point is at the beginning of the footnote definition."
775 :begin begin
776 :end end
777 :contents-begin contents-begin
778 :contents-end contents-end
784 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
785 CONTENTS is the contents of the footnote-definition."
787 " "
788 contents))
791 ;;;; Headline
794 "Parse a headline.
796 Return a list whose CAR is `headline' and CDR is a plist
797 containing `:raw-value', `:title', `:alt-title', `:begin',
798 `:end', `:pre-blank', `:contents-begin' and `:contents-end',
799 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
800 `:scheduled', `:deadline', `:closed', `:archivedp', `:commentedp'
801 and `:footnote-section-p' keywords.
803 The plist also contains any property set in the property drawer,
804 with its name in upper cases and colons added at the
805 beginning (e.g., `:CUSTOM_ID').
807 When RAW-SECONDARY-P is non-nil, headline's title will not be
808 parsed as a secondary string, but as a plain string instead.
810 Assume point is at beginning of the headline."
823 raw-value)))
827 ;; Upcase property names. It avoids confusion between
828 ;; properties obtained through property drawer and default
829 ;; properties from the parser (e.g. `:end' and :END:)
839 plist))
841 ;; Read time properties on the line below the headline.
847 org-keyword-time-not-clock-regexp end t)
857 plist))))
869 ;; Clean RAW-VALUE from any comment string.
875 ""
876 raw-value))))
877 ;; Clean TAGS from archive tag, if any.
883 :begin begin
884 :end end
885 :pre-blank
888 :contents-begin contents-begin
889 :contents-end contents-end
890 :level level
892 :tags tags
893 :todo-keyword todo
894 :todo-type todo-type
900 end)
901 :footnote-section-p footnote-section-p
902 :archivedp archivedp
904 time-props
905 standard-props))))
909 headline :alt-title
914 headline :title
920 "Interpret HEADLINE element as Org syntax.
921 CONTENTS is the contents of the element."
946 ;; Align tags.
954 ? )
955 tags))
959 tags))))
961 contents)))
964 ;;;; Inlinetask
967 "Parse an inline task.
969 Return a list whose CAR is `inlinetask' and CDR is a plist
970 containing `:title', `:begin', `:end', `:contents-begin' and
971 `:contents-end', `:level', `:priority', `:raw-value', `:tags',
972 `:todo-keyword', `:todo-type', `:scheduled', `:deadline',
973 `:closed' and `:post-blank' keywords.
975 The plist also contains any property set in the property drawer,
976 with its name in upper cases and colons added at the
977 beginning (e.g., `:CUSTOM_ID').
979 When optional argument RAW-SECONDARY-P is non-nil, inline-task's
980 title will not be parsed as a secondary string, but as a plain
981 string instead.
983 Assume point is at beginning of the inline task."
993 ;; Upcase property names. It avoids confusion between
994 ;; properties obtained through property drawer and default
995 ;; properties from the parser (e.g. `:end' and :END:)
1005 plist))
1007 ;; Read time properties on the line below the inlinetask
1008 ;; opening string.
1014 org-keyword-time-not-clock-regexp end t)
1024 plist))))
1043 :begin begin
1044 :end end
1045 :contents-begin contents-begin
1046 :contents-end contents-end
1049 :tags tags
1050 :todo-keyword todo
1051 :todo-type todo-type
1053 time-props
1054 standard-props))))
1056 inlinetask :title
1059 raw-value
1061 inlinetask))))))
1064 "Interpret INLINETASK element as Org syntax.
1065 CONTENTS is the contents of inlinetask."
1080 ;; Align tags.
1088 ? )
1089 tags))
1093 tags))))
1094 ;; Prefer degenerate inlinetasks when there are no
1095 ;; contents.
1098 contents
1102 ;;;; Item
1105 "Parse an item.
1107 STRUCT is the structure of the plain list.
1109 Return a list whose CAR is `item' and CDR is a plist containing
1110 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
1111 `:checkbox', `:counter', `:tag', `:structure' and `:post-blank'
1112 keywords.
1114 When optional argument RAW-SECONDARY-P is non-nil, item's tag, if
1115 any, will not be parsed as a secondary string, but as a plain
1116 string instead.
1118 Assume point is at the beginning of the item."
1142 ;; Ignore tags in un-ordered lists: they are just
1143 ;; a part of item's body.
1149 ;; If first line isn't empty, contents really start
1150 ;; at the text after item's meta-data.
1159 :begin begin
1160 :end end
1161 ;; CONTENTS-BEGIN and CONTENTS-END may be
1162 ;; mixed up in the case of an empty item
1163 ;; separated from the next by a blank line.
1164 ;; Thus ensure the former is always the
1165 ;; smallest.
1168 :checkbox checkbox
1169 :counter counter
1170 :structure struct
1173 item :tag
1181 "Interpret ITEM element as Org syntax.
1182 CONTENTS is the contents of the element."
1192 ;; Compute indentation.
1197 ;; Indent contents.
1199 bullet
1213 ;;;; Plain List
1216 ;; Return structure of list at point. Internal function. See
1217 ;; `org-list-struct' for details.
1222 items struct)
1227 ;; At limit: end all items.
1236 ;; At list end: end all items.
1241 ;; At a new item: end previous sibling.
1253 ind
1254 bullet
1257 ;; Description tag.
1261 ;; Ending position, unknown so far.
1262 nil)))
1263 items))
1265 ;; Skip empty lines.
1267 ;; Skip inline tasks and blank lines along the way.
1274 ;; At some text line. Check if it ends any previous item.
1286 ;; Skip blocks (any type) and drawers contents.
1291 limit t)))
1297 "Parse a plain list.
1299 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1300 the buffer position at the beginning of the first affiliated
1301 keyword and CDR is a plist of affiliated keywords along with
1302 their value. STRUCTURE is the structure of the plain list being
1303 parsed.
1305 Return a list whose CAR is `plain-list' and CDR is a plist
1306 containing `:type', `:begin', `:end', `:contents-begin' and
1307 `:contents-end', `:structure', `:post-blank' and
1308 `:post-affiliated' keywords.
1310 Assume point is at the beginning of the list."
1324 pos))
1328 ;; Return value.
1332 :begin begin
1333 :end end
1334 :contents-begin contents-begin
1335 :contents-end contents-end
1336 :structure struct
1342 "Interpret PLAIN-LIST element as Org syntax.
1343 CONTENTS is the contents of the element."
1351 ;;;; Property Drawer
1354 "Parse a property drawer.
1356 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1357 the buffer position at the beginning of the first affiliated
1358 keyword and CDR is a plist of affiliated keywords along with
1359 their value.
1361 Return a list whose CAR is `property-drawer' and CDR is a plist
1362 containing `:begin', `:end', `:contents-begin', `:contents-end',
1363 `:post-blank' and `:post-affiliated' keywords.
1365 Assume point is at the beginning of the property drawer."
1370 ;; Incomplete drawer: parse it as a paragraph.
1388 :end end
1389 :contents-begin contents-begin
1390 :contents-end contents-end
1396 "Interpret PROPERTY-DRAWER element as Org syntax.
1397 CONTENTS is the properties within the drawer."
1401 ;;;; Quote Block
1404 "Parse a quote block.
1406 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1407 the buffer position at the beginning of the first affiliated
1408 keyword and CDR is a plist of affiliated keywords along with
1409 their value.
1411 Return a list whose CAR is `quote-block' and CDR is a plist
1412 containing `:begin', `:end', `:contents-begin', `:contents-end',
1413 `:post-blank' and `:post-affiliated' keywords.
1415 Assume point is at the beginning of the block."
1419 ;; Incomplete block: parse it as a paragraph.
1425 ;; Empty blocks have no contents.
1438 :end end
1439 :contents-begin contents-begin
1440 :contents-end contents-end
1446 "Interpret QUOTE-BLOCK element as Org syntax.
1447 CONTENTS is the contents of the element."
1451 ;;;; Section
1454 "Parse a section.
1456 LIMIT bounds the search.
1458 Return a list whose CAR is `section' and CDR is a plist
1459 containing `:begin', `:end', `:contents-begin', `contents-end'
1460 and `:post-blank' keywords."
1462 ;; Beginning of section is the beginning of the first non-blank
1463 ;; line after previous headline.
1472 :end end
1473 :contents-begin begin
1474 :contents-end pos-before-blank
1478 "Interpret SECTION element as Org syntax.
1479 CONTENTS is the contents of the element."
1480 contents)
1483 ;;;; Special Block
1486 "Parse a special block.
1488 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1489 the buffer position at the beginning of the first affiliated
1490 keyword and CDR is a plist of affiliated keywords along with
1491 their value.
1493 Return a list whose CAR is `special-block' and CDR is a plist
1494 containing `:type', `:begin', `:end', `:contents-begin',
1495 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
1497 Assume point is at the beginning of the block."
1504 limit t)))
1505 ;; Incomplete block: parse it as a paragraph.
1511 ;; Empty blocks have no contents.
1524 :begin begin
1525 :end end
1526 :contents-begin contents-begin
1527 :contents-end contents-end
1533 "Interpret SPECIAL-BLOCK element as Org syntax.
1534 CONTENTS is the contents of the element."
1539 \f
1540 ;;; Elements
1541 ;;
1542 ;; For each element, a parser and an interpreter are also defined.
1543 ;; Both follow the same naming convention used for greater elements.
1544 ;;
1545 ;; Also, as for greater elements, adding a new element type is done
1546 ;; through the following steps: implement a parser and an interpreter,
1547 ;; tweak `org-element--current-element' so that it recognizes the new
1548 ;; type and add that new type to `org-element-all-elements'.
1549 ;;
1550 ;; As a special case, when the newly defined type is a block type,
1551 ;; `org-element-block-name-alist' has to be modified accordingly.
1554 ;;;; Babel Call
1557 "Parse a babel call.
1559 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1560 the buffer position at the beginning of the first affiliated
1561 keyword and CDR is a plist of affiliated keywords along with
1562 their value.
1564 Return a list whose CAR is `babel-call' and CDR is a plist
1565 containing `:begin', `:end', `:value', `:post-blank' and
1566 `:post-affiliated' as keywords."
1580 :end end
1581 :value value
1587 "Interpret BABEL-CALL element as Org syntax.
1588 CONTENTS is nil."
1592 ;;;; Clock
1595 "Parse a clock.
1597 LIMIT bounds the search.
1599 Return a list whose CAR is `clock' and CDR is a plist containing
1600 `:status', `:value', `:time', `:begin', `:end' and `:post-blank'
1601 as keywords."
1621 :value value
1622 :duration duration
1623 :begin begin
1624 :end end
1628 "Interpret CLOCK element as Org syntax.
1629 CONTENTS is nil."
1637 "%2s:%02s"
1641 ;;;; Comment
1644 "Parse a comment.
1646 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1647 the buffer position at the beginning of the first affiliated
1648 keyword and CDR is a plist of affiliated keywords along with
1649 their value.
1651 Return a list whose CAR is `comment' and CDR is a plist
1652 containing `:begin', `:end', `:value', `:post-blank',
1653 `:post-affiliated' keywords.
1655 Assume point is at comment beginning."
1664 ;; Get comments ending.
1667 ;; Accumulate lines without leading hash and first
1668 ;; whitespace.
1682 :end end
1683 :value value
1689 "Interpret COMMENT element as Org syntax.
1690 CONTENTS is nil."
1694 ;;;; Comment Block
1697 "Parse an export block.
1699 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1700 the buffer position at the beginning of the first affiliated
1701 keyword and CDR is a plist of affiliated keywords along with
1702 their value.
1704 Return a list whose CAR is `comment-block' and CDR is a plist
1705 containing `:begin', `:end', `:value', `:post-blank' and
1706 `:post-affiliated' keywords.
1708 Assume point is at comment block beginning."
1712 ;; Incomplete block: parse it as a paragraph.
1725 contents-begin contents-end)))
1729 :end end
1730 :value value
1736 "Interpret COMMENT-BLOCK element as Org syntax.
1737 CONTENTS is nil."
1742 ;;;; Diary Sexp
1745 "Parse a diary sexp.
1747 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1748 the buffer position at the beginning of the first affiliated
1749 keyword and CDR is a plist of affiliated keywords along with
1750 their value.
1752 Return a list whose CAR is `diary-sexp' and CDR is a plist
1753 containing `:begin', `:end', `:value', `:post-blank' and
1754 `:post-affiliated' keywords."
1766 :begin begin
1767 :end end
1773 "Interpret DIARY-SEXP as Org syntax.
1774 CONTENTS is nil."
1778 ;;;; Example Block
1781 "Parse an example block.
1783 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1784 the buffer position at the beginning of the first affiliated
1785 keyword and CDR is a plist of affiliated keywords along with
1786 their value.
1788 Return a list whose CAR is `example-block' and CDR is a plist
1789 containing `:begin', `:end', `:number-lines', `:preserve-indent',
1790 `:retain-labels', `:use-labels', `:label-fmt', `:switches',
1791 `:value', `:post-blank' and `:post-affiliated' keywords."
1795 ;; Incomplete block: parse it as a paragraph.
1803 ;; Switches analysis
1810 ;; Should labels be retained in (or stripped from) example
1811 ;; blocks?
1816 ;; What should code-references use - labels or
1817 ;; line-numbers?
1826 ;; Standard block parsing.
1834 contents-begin contents-end))
1835 block-ind))
1844 :end end
1845 :value value
1846 :switches switches
1847 :number-lines number-lines
1848 :preserve-indent preserve-indent
1849 :retain-labels retain-labels
1850 :use-labels use-labels
1851 :label-fmt label-fmt
1857 "Interpret EXAMPLE-BLOCK element as Org syntax.
1858 CONTENTS is nil."
1865 value
1870 ;;;; Export Block
1873 "Parse an export block.
1875 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1876 the buffer position at the beginning of the first affiliated
1877 keyword and CDR is a plist of affiliated keywords along with
1878 their value.
1880 Return a list whose CAR is `export-block' and CDR is a plist
1881 containing `:begin', `:end', `:type', `:value', `:post-blank' and
1882 `:post-affiliated' keywords.
1884 Assume point is at export-block beginning."
1891 ;; Incomplete block: parse it as a paragraph.
1904 contents-end)))
1908 :end end
1909 :type type
1910 :value value
1916 "Interpret EXPORT-BLOCK element as Org syntax.
1917 CONTENTS is nil."
1924 ;;;; Fixed-width
1927 "Parse a fixed-width section.
1929 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1930 the buffer position at the beginning of the first affiliated
1931 keyword and CDR is a plist of affiliated keywords along with
1932 their value.
1934 Return a list whose CAR is `fixed-width' and CDR is a plist
1935 containing `:begin', `:end', `:value', `:post-blank' and
1936 `:post-affiliated' keywords.
1938 Assume point is at the beginning of the fixed-width area."
1942 value
1947 ;; Accumulate text without starting colons.
1960 :end end
1961 :value value
1967 "Interpret FIXED-WIDTH element as Org syntax.
1968 CONTENTS is nil."
1976 ;;;; Horizontal Rule
1979 "Parse an horizontal rule.
1981 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1982 the buffer position at the beginning of the first affiliated
1983 keyword and CDR is a plist of affiliated keywords along with
1984 their value.
1986 Return a list whose CAR is `horizontal-rule' and CDR is a plist
1987 containing `:begin', `:end', `:post-blank' and `:post-affiliated'
1988 keywords."
1998 :end end
2004 "Interpret HORIZONTAL-RULE element as Org syntax.
2005 CONTENTS is nil."
2009 ;;;; Keyword
2012 "Parse a keyword at point.
2014 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2015 the buffer position at the beginning of the first affiliated
2016 keyword and CDR is a plist of affiliated keywords along with
2017 their value.
2019 Return a list whose CAR is `keyword' and CDR is a plist
2020 containing `:key', `:value', `:begin', `:end', `:post-blank' and
2021 `:post-affiliated' keywords."
2023 ;; An orphaned affiliated keyword is considered as a regular
2024 ;; keyword. In this case AFFILIATED is nil, so we take care of
2025 ;; this corner case.
2038 :value value
2039 :begin begin
2040 :end end
2046 "Interpret KEYWORD element as Org syntax.
2047 CONTENTS is nil."
2053 ;;;; Latex Environment
2056 "Parse a LaTeX environment.
2058 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2059 the buffer position at the beginning of the first affiliated
2060 keyword and CDR is a plist of affiliated keywords along with
2061 their value.
2063 Return a list whose CAR is `latex-environment' and CDR is a plist
2064 containing `:begin', `:end', `:value', `:post-blank' and
2065 `:post-affiliated' keywords.
2067 Assume point is at the beginning of the latex environment."
2074 limit t))
2075 ;; Incomplete latex environment: parse it as a paragraph.
2085 :end end
2086 :value value
2092 "Interpret LATEX-ENVIRONMENT element as Org syntax.
2093 CONTENTS is nil."
2097 ;;;; Node Property
2100 "Parse a node-property at point.
2102 LIMIT bounds the search.
2104 Return a list whose CAR is `node-property' and CDR is a plist
2105 containing `:key', `:value', `:begin', `:end' and `:post-blank'
2106 keywords."
2118 :value value
2119 :begin begin
2120 :end end
2124 "Interpret NODE-PROPERTY element as Org syntax.
2125 CONTENTS is nil."
2131 ;;;; Paragraph
2134 "Parse a paragraph.
2136 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2137 the buffer position at the beginning of the first affiliated
2138 keyword and CDR is a plist of affiliated keywords along with
2139 their value.
2141 Return a list whose CAR is `paragraph' and CDR is a plist
2142 containing `:begin', `:end', `:contents-begin' and
2143 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
2145 Assume point is at the beginning of the paragraph."
2154 limit
2155 ;; A matching `org-element-paragraph-separate' is not
2156 ;; necessarily the end of the paragraph. In
2157 ;; particular, lines starting with # or : as a first
2158 ;; non-space character are ambiguous. We have to
2159 ;; check if they are valid Org syntax (e.g., not an
2160 ;; incomplete keyword).
2164 ;; There's no ambiguity for other symbols or
2165 ;; empty lines: stop here.
2167 ;; Stop at valid fixed-width areas.
2169 ;; Stop at drawers.
2174 ;; Stop at valid comments.
2176 ;; Stop at valid dynamic blocks.
2181 ;; Stop at valid blocks.
2188 limit t)))
2189 ;; Stop at valid latex environments.
2197 limit t)))
2198 ;; Stop at valid keywords.
2200 ;; Skip everything else.
2217 :end end
2218 :contents-begin contents-begin
2219 :contents-end contents-end
2225 "Interpret PARAGRAPH element as Org syntax.
2226 CONTENTS is the contents of the element."
2227 contents)
2230 ;;;; Planning
2233 "Parse a planning.
2235 LIMIT bounds the search.
2237 Return a list whose CAR is `planning' and CDR is a plist
2238 containing `:closed', `:deadline', `:scheduled', `:begin', `:end'
2239 and `:post-blank' keywords."
2249 closed deadline scheduled)
2261 :deadline deadline
2262 :scheduled scheduled
2263 :begin begin
2264 :end end
2268 "Interpret PLANNING element as Org syntax.
2269 CONTENTS is nil."
2271 'identity
2288 ;;;; Src Block
2291 "Parse a src block.
2293 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2294 the buffer position at the beginning of the first affiliated
2295 keyword and CDR is a plist of affiliated keywords along with
2296 their value.
2298 Return a list whose CAR is `src-block' and CDR is a plist
2299 containing `:language', `:switches', `:parameters', `:begin',
2300 `:end', `:number-lines', `:retain-labels', `:use-labels',
2301 `:label-fmt', `:preserve-indent', `:value', `:post-blank' and
2302 `:post-affiliated' keywords.
2304 Assume point is at the beginning of the block."
2307 limit t)))
2308 ;; Incomplete block: parse it as a paragraph.
2314 ;; Get language as a string.
2323 ;; Get switches.
2325 ;; Get parameters.
2327 ;; Switches analysis
2338 ;; Should labels be retained in (or stripped from)
2339 ;; src blocks?
2344 ;; What should code-references use - labels or
2345 ;; line-numbers?
2350 ;; Indentation.
2352 ;; Retrieve code.
2357 block-ind))
2361 ;; Get position after ending blank lines.
2371 :begin begin
2372 :end end
2373 :number-lines number-lines
2374 :preserve-indent preserve-indent
2375 :retain-labels retain-labels
2376 :use-labels use-labels
2377 :label-fmt label-fmt
2378 :value value
2384 "Interpret SRC-BLOCK element as Org syntax.
2385 CONTENTS is nil."
2394 val)
2408 ;;;; Table
2411 "Parse a table at point.
2413 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2414 the buffer position at the beginning of the first affiliated
2415 keyword and CDR is a plist of affiliated keywords along with
2416 their value.
2418 Return a list whose CAR is `table' and CDR is a plist containing
2419 `:begin', `:end', `:tblfm', `:type', `:contents-begin',
2420 `:contents-end', `:value', `:post-blank' and `:post-affiliated'
2421 keywords.
2423 Assume point is at the beginning of the table."
2437 acc))
2444 :end end
2445 :type type
2446 :tblfm tblfm
2447 ;; Only `org' tables have contents. `table.el' tables
2448 ;; use a `:value' property to store raw table as
2449 ;; a string.
2454 table-begin table-end))
2460 "Interpret TABLE element as Org syntax.
2461 CONTENTS is nil."
2472 ;;;; Table Row
2475 "Parse table row at point.
2477 LIMIT bounds the search.
2479 Return a list whose CAR is `table-row' and CDR is a plist
2480 containing `:begin', `:end', `:contents-begin', `:contents-end',
2481 `:type' and `:post-blank' keywords."
2485 ;; A table rule has no contents. In that case, ensure
2486 ;; CONTENTS-BEGIN matches CONTENTS-END.
2498 :begin begin
2499 :end end
2500 :contents-begin contents-begin
2501 :contents-end contents-end
2505 "Interpret TABLE-ROW element as Org syntax.
2506 CONTENTS is the contents of the table row."
2511 ;;;; Verse Block
2514 "Parse a verse block.
2516 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2517 the buffer position at the beginning of the first affiliated
2518 keyword and CDR is a plist of affiliated keywords along with
2519 their value.
2521 Return a list whose CAR is `verse-block' and CDR is a plist
2522 containing `:begin', `:end', `:contents-begin', `:contents-end',
2523 `:post-blank' and `:post-affiliated' keywords.
2525 Assume point is at beginning of the block."
2529 ;; Incomplete block: parse it as a paragraph.
2544 :end end
2545 :contents-begin contents-begin
2546 :contents-end contents-end
2552 "Interpret VERSE-BLOCK element as Org syntax.
2553 CONTENTS is verse block contents."
2557 \f
2558 ;;; Objects
2559 ;;
2560 ;; Unlike to elements, interstices can be found between objects.
2561 ;; That's why, along with the parser, successor functions are provided
2562 ;; for each object. Some objects share the same successor (e.g.,
2563 ;; `code' and `verbatim' objects).
2564 ;;
2565 ;; A successor must accept a single argument bounding the search. It
2566 ;; will return either a cons cell whose CAR is the object's type, as
2567 ;; a symbol, and CDR the position of its next occurrence, or nil.
2568 ;;
2569 ;; Successors follow the naming convention:
2570 ;; org-element-NAME-successor, where NAME is the name of the
2571 ;; successor, as defined in `org-element-all-successors'.
2572 ;;
2573 ;; Some object types (e.g., `italic') are recursive. Restrictions on
2574 ;; object types they can contain will be specified in
2575 ;; `org-element-object-restrictions'.
2576 ;;
2577 ;; Adding a new type of object is simple. Implement a successor,
2578 ;; a parser, and an interpreter for it, all following the naming
2579 ;; convention. Register type in `org-element-all-objects' and
2580 ;; successor in `org-element-all-successors'. Maybe tweak
2581 ;; restrictions about it, and that's it.
2584 ;;;; Bold
2587 "Parse bold object at point.
2589 Return a list whose CAR is `bold' and CDR is a plist with
2590 `:begin', `:end', `:contents-begin' and `:contents-end' and
2591 `:post-blank' keywords.
2593 Assume point is at the first star marker."
2605 :end end
2606 :contents-begin contents-begin
2607 :contents-end contents-end
2611 "Interpret BOLD object as Org syntax.
2612 CONTENTS is the contents of the object."
2616 "Search for the next text-markup object.
2618 Return value is a cons cell whose CAR is a symbol among `bold',
2619 `italic', `underline', `strike-through', `code' and `verbatim'
2620 and CDR is beginning position."
2636 ;;;; Code
2639 "Parse code object at point.
2641 Return a list whose CAR is `code' and CDR is a plist with
2642 `:value', `:begin', `:end' and `:post-blank' keywords.
2644 Assume point is at the first tilde marker."
2655 :begin begin
2656 :end end
2660 "Interpret CODE object as Org syntax.
2661 CONTENTS is nil."
2665 ;;;; Entity
2668 "Parse entity at point.
2670 Return a list whose CAR is `entity' and CDR a plist with
2671 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
2672 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
2673 keywords.
2675 Assume point is at the beginning of the entity."
2677 (looking-at "\\\\\\(there4\\|sup[123]\\|frac[13][24]\\|[a-zA-Z]+\\)\\($\\|{}\\|[^[:alpha:]]\\)")
2693 :begin begin
2694 :end end
2695 :use-brackets-p bracketsp
2699 "Interpret ENTITY object as Org syntax.
2700 CONTENTS is nil."
2706 "Search for the next latex-fragment or entity object.
2708 Return value is a cons cell whose CAR is `entity' or
2709 `latex-fragment' and CDR is beginning position."
2713 ;; ENTITY-RE matches both LaTeX commands and Org entities.
2720 ;; Determine if it's a real entity or a LaTeX command.
2723 ;; No entity nor command: point is at a LaTeX fragment.
2724 ;; Determine its type to get the correct beginning position.
2733 ;;;; Export Snippet
2736 "Parse export snippet at point.
2738 Return a list whose CAR is `export-snippet' and CDR a plist with
2739 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
2740 keywords.
2742 Assume point is at the beginning of the snippet."
2754 :value value
2755 :begin begin
2756 :end end
2760 "Interpret EXPORT-SNIPPET object as Org syntax.
2761 CONTENTS is nil."
2767 "Search for the next export-snippet object.
2769 Return value is a cons cell whose CAR is `export-snippet' and CDR
2770 its beginning position."
2779 ;;;; Footnote Reference
2782 "Parse footnote reference at point.
2784 Return a list whose CAR is `footnote-reference' and CDR a plist
2785 with `:label', `:type', `:inline-definition', `:begin', `:end'
2786 and `:post-blank' as keywords."
2808 :type type
2809 :begin begin
2810 :end end
2813 footnote-reference :inline-definition
2818 footnote-reference))))))
2821 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
2822 CONTENTS is nil."
2832 "Search for the next footnote-reference object.
2834 Return value is a cons cell whose CAR is `footnote-reference' and
2835 CDR is beginning position."
2849 ;;;; Inline Babel Call
2852 "Parse inline babel call at point.
2854 Return a list whose CAR is `inline-babel-call' and CDR a plist
2855 with `:begin', `:end', `:value' and `:post-blank' as keywords.
2857 Assume point is at the beginning of the babel call."
2869 :end end
2870 :value value
2874 "Interpret INLINE-BABEL-CALL object as Org syntax.
2875 CONTENTS is nil."
2879 "Search for the next inline-babel-call object.
2881 Return value is a cons cell whose CAR is `inline-babel-call' and
2882 CDR is beginning position."
2892 ;;;; Inline Src Block
2895 "Parse inline source block at point.
2897 Return a list whose CAR is `inline-src-block' and CDR a plist
2898 with `:begin', `:end', `:language', `:value', `:parameters' and
2899 `:post-blank' as keywords.
2901 Assume point is at the beginning of the inline src block."
2914 :value value
2915 :parameters parameters
2916 :begin begin
2917 :end end
2921 "Interpret INLINE-SRC-BLOCK object as Org syntax.
2922 CONTENTS is nil."
2927 language
2929 body)))
2932 "Search for the next inline-babel-call element.
2934 Return value is a cons cell whose CAR is `inline-babel-call' and
2935 CDR is beginning position."
2941 ;;;; Italic
2944 "Parse italic object at point.
2946 Return a list whose CAR is `italic' and CDR is a plist with
2947 `:begin', `:end', `:contents-begin' and `:contents-end' and
2948 `:post-blank' keywords.
2950 Assume point is at the first slash marker."
2962 :end end
2963 :contents-begin contents-begin
2964 :contents-end contents-end
2968 "Interpret ITALIC object as Org syntax.
2969 CONTENTS is the contents of the object."
2973 ;;;; Latex Fragment
2976 "Parse LaTeX fragment at point.
2978 Return a list whose CAR is `latex-fragment' and CDR a plist with
2979 `:value', `:begin', `:end', and `:post-blank' as keywords.
2981 Assume point is at the beginning of the LaTeX fragment."
2994 ;; None found: it's a macro.
3003 :begin begin
3004 :end end
3008 "Interpret LATEX-FRAGMENT object as Org syntax.
3009 CONTENTS is nil."
3012 ;;;; Line Break
3015 "Parse line break at point.
3017 Return a list whose CAR is `line-break', and CDR a plist with
3018 `:begin', `:end' and `:post-blank' keywords.
3020 Assume point is at the beginning of the line break."
3027 "Interpret LINE-BREAK object as Org syntax.
3028 CONTENTS is nil."
3032 "Search for the next line-break object.
3034 Return value is a cons cell whose CAR is `line-break' and CDR is
3035 beginning position."
3039 ;; A line break can only happen on a non-empty line.
3044 ;;;; Link
3047 "Parse link at point.
3049 Return a list whose CAR is `link' and CDR a plist with `:type',
3050 `:path', `:raw-link', `:application', `:search-option', `:begin',
3051 `:end', `:contents-begin', `:contents-end' and `:post-blank' as
3052 keywords.
3054 Assume point is at the beginning of the link."
3057 end contents-begin contents-end link-end post-blank path type
3058 raw-link link search-option application)
3060 ;; Type 1: Text targeted from a radio target.
3067 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
3072 ;; RAW-LINK is the original link. Expand any
3073 ;; abbreviation in it.
3077 ;; Determine TYPE of link and set PATH accordingly.
3079 ;; File type.
3083 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
3086 ;; Id type: PATH is the id.
3089 ;; Code-ref type: PATH is the name of the reference.
3092 ;; Custom-id type: PATH is the name of the custom id.
3095 ;; Fuzzy type: Internal link either matches a target, an
3096 ;; headline name or nothing. PATH is the target or
3097 ;; headline's name.
3099 ;; Type 3: Plain link, e.g., http://orgmode.org
3105 ;; Type 4: Angular link, e.g., <http://orgmode.org>
3112 ;; In any case, deduce end point after trailing white space from
3113 ;; LINK-END variable.
3116 ;; Extract search option and opening application out of
3117 ;; "file"-type links.
3119 ;; Application.
3124 ;; Extract search option from PATH.
3128 ;; Make sure TYPE always reports "file".
3132 :path path
3134 :application application
3135 :search-option search-option
3136 :begin begin
3137 :end end
3138 :contents-begin contents-begin
3139 :contents-end contents-end
3143 "Interpret LINK object as Org syntax.
3144 CONTENTS is the contents of the object, or nil."
3149 raw-link
3153 "Search for the next link object.
3155 Return value is a cons cell whose CAR is `link' and CDR is
3156 beginning position."
3165 "Search for the next plain link object.
3167 Return value is a cons cell whose CAR is `link' and CDR is
3168 beginning position."
3173 ;;;; Macro
3176 "Parse macro at point.
3178 Return a list whose CAR is `macro' and CDR a plist with `:key',
3179 `:args', `:begin', `:end', `:value' and `:post-blank' as
3180 keywords.
3182 Assume point is at the macro."
3193 ;; Do not use `org-split-string' since empty
3194 ;; strings are meaningful here.
3202 args nil t)
3206 :value value
3207 :args args
3208 :begin begin
3209 :end end
3213 "Interpret MACRO object as Org syntax.
3214 CONTENTS is nil."
3218 "Search for the next macro object.
3220 Return value is cons cell whose CAR is `macro' and CDR is
3221 beginning position."
3225 nil t)
3229 ;;;; Radio-target
3232 "Parse radio target at point.
3234 Return a list whose CAR is `radio-target' and CDR a plist with
3235 `:begin', `:end', `:contents-begin', `:contents-end', `:value'
3236 and `:post-blank' as keywords.
3238 Assume point is at the radio target."
3250 :end end
3251 :contents-begin contents-begin
3252 :contents-end contents-end
3253 :post-blank post-blank
3257 "Interpret TARGET object as Org syntax.
3258 CONTENTS is the contents of the object."
3262 "Search for the next radio-target object.
3264 Return value is a cons cell whose CAR is `radio-target' and CDR
3265 is beginning position."
3271 ;;;; Statistics Cookie
3274 "Parse statistics cookie at point.
3276 Return a list whose CAR is `statistics-cookie', and CDR a plist
3277 with `:begin', `:end', `:value' and `:post-blank' keywords.
3279 Assume point is at the beginning of the statistics-cookie."
3290 :end end
3291 :value value
3295 "Interpret STATISTICS-COOKIE object as Org syntax.
3296 CONTENTS is nil."
3300 "Search for the next statistics cookie object.
3302 Return value is a cons cell whose CAR is `statistics-cookie' and
3303 CDR is beginning position."
3309 ;;;; Strike-Through
3312 "Parse strike-through object at point.
3314 Return a list whose CAR is `strike-through' and CDR is a plist
3315 with `:begin', `:end', `:contents-begin' and `:contents-end' and
3316 `:post-blank' keywords.
3318 Assume point is at the first plus sign marker."
3330 :end end
3331 :contents-begin contents-begin
3332 :contents-end contents-end
3336 "Interpret STRIKE-THROUGH object as Org syntax.
3337 CONTENTS is the contents of the object."
3341 ;;;; Subscript
3344 "Parse subscript at point.
3346 Return a list whose CAR is `subscript' and CDR a plist with
3347 `:begin', `:end', `:contents-begin', `:contents-end',
3348 `:use-brackets-p' and `:post-blank' as keywords.
3350 Assume point is at the underscore."
3364 :end end
3365 :use-brackets-p bracketsp
3366 :contents-begin contents-begin
3367 :contents-end contents-end
3371 "Interpret SUBSCRIPT object as Org syntax.
3372 CONTENTS is the contents of the object."
3375 contents))
3378 "Search for the next sub/superscript object.
3380 Return value is a cons cell whose CAR is either `subscript' or
3381 `superscript' and CDR is beginning position."
3389 ;;;; Superscript
3392 "Parse superscript at point.
3394 Return a list whose CAR is `superscript' and CDR a plist with
3395 `:begin', `:end', `:contents-begin', `:contents-end',
3396 `:use-brackets-p' and `:post-blank' as keywords.
3398 Assume point is at the caret."
3412 :end end
3413 :use-brackets-p bracketsp
3414 :contents-begin contents-begin
3415 :contents-end contents-end
3419 "Interpret SUPERSCRIPT object as Org syntax.
3420 CONTENTS is the contents of the object."
3423 contents))
3426 ;;;; Table Cell
3429 "Parse table cell at point.
3431 Return a list whose CAR is `table-cell' and CDR is a plist
3432 containing `:begin', `:end', `:contents-begin', `:contents-end'
3433 and `:post-blank' keywords."
3441 :end end
3442 :contents-begin contents-begin
3443 :contents-end contents-end
3447 "Interpret TABLE-CELL element as Org syntax.
3448 CONTENTS is the contents of the cell, or nil."
3452 "Search for the next table-cell object.
3454 Return value is a cons cell whose CAR is `table-cell' and CDR is
3455 beginning position."
3459 ;;;; Target
3462 "Parse target at point.
3464 Return a list whose CAR is `target' and CDR a plist with
3465 `:begin', `:end', `:value' and `:post-blank' as keywords.
3467 Assume point is at the target."
3477 :end end
3478 :value value
3482 "Interpret TARGET object as Org syntax.
3483 CONTENTS is nil."
3487 "Search for the next target object.
3489 Return value is a cons cell whose CAR is `target' and CDR is
3490 beginning position."
3496 ;;;; Timestamp
3499 "Parse time stamp at point.
3501 Return a list whose CAR is `timestamp', and CDR a plist with
3502 `:type', `:raw-value', `:year-start', `:month-start',
3503 `:day-start', `:hour-start', `:minute-start', `:year-end',
3504 `:month-end', `:day-end', `:hour-end', `:minute-end',
3505 `:repeater-type', `:repeater-value', `:repeater-unit',
3506 `:warning-type', `:warning-value', `:warning-unit', `:begin',
3507 `:end', `:value' and `:post-blank' keywords.
3509 Assume point is at the beginning of the timestamp."
3527 date-start)
3538 raw-value)
3540 :repeater-type
3546 :repeater-unit
3555 :warning-unit
3558 year-start month-start day-start hour-start minute-start year-end
3559 month-end day-end hour-end minute-end)
3560 ;; Parse date-start.
3568 ;; Compute date-end. It can be provided directly in time-stamp,
3569 ;; or extracted from time range. Otherwise, it defaults to the
3570 ;; same values as date-start.
3580 :raw-value raw-value
3581 :year-start year-start
3582 :month-start month-start
3583 :day-start day-start
3584 :hour-start hour-start
3585 :minute-start minute-start
3586 :year-end year-end
3587 :month-end month-end
3588 :day-end day-end
3589 :hour-end hour-end
3590 :minute-end minute-end
3591 :begin begin
3592 :end end
3594 repeater-props
3595 warning-props)))))
3598 "Interpret TIMESTAMP object as Org syntax.
3599 CONTENTS is nil."
3618 ;; Build an Org timestamp string from TIME. ACTIVEP is
3619 ;; non-nil when time stamp is active. If WITH-TIME-P is
3620 ;; non-nil, add a time part. HOUR-END and MINUTE-END
3621 ;; specify a time range in the timestamp. REPEAT-STRING is
3622 ;; the repeater string, if any.
3626 org-time-stamp-formats)
3627 time)))
3633 nil nil ts)))
3638 " "
3639 s
3641 ;; Return value.
3642 ts)))
3654 build-ts-string
3673 0
3681 "--"
3693 "Search for the next timestamp object.
3695 Return value is a cons cell whose CAR is `timestamp' and CDR is
3696 beginning position."
3704 nil t)
3708 ;;;; Underline
3711 "Parse underline object at point.
3713 Return a list whose CAR is `underline' and CDR is a plist with
3714 `:begin', `:end', `:contents-begin' and `:contents-end' and
3715 `:post-blank' keywords.
3717 Assume point is at the first underscore marker."
3729 :end end
3730 :contents-begin contents-begin
3731 :contents-end contents-end
3735 "Interpret UNDERLINE object as Org syntax.
3736 CONTENTS is the contents of the object."
3740 ;;;; Verbatim
3743 "Parse verbatim object at point.
3745 Return a list whose CAR is `verbatim' and CDR is a plist with
3746 `:value', `:begin', `:end' and `:post-blank' keywords.
3748 Assume point is at the first equal sign marker."
3759 :begin begin
3760 :end end
3764 "Interpret VERBATIM object as Org syntax.
3765 CONTENTS is nil."
3769 \f
3770 ;;; Parsing Element Starting At Point
3771 ;;
3772 ;; `org-element--current-element' is the core function of this section.
3773 ;; It returns the Lisp representation of the element starting at
3774 ;; point.
3775 ;;
3776 ;; `org-element--current-element' makes use of special modes. They
3777 ;; are activated for fixed element chaining (e.g., `plain-list' >
3778 ;; `item') or fixed conditional element chaining (e.g., `headline' >
3779 ;; `section'). Special modes are: `first-section', `item',
3780 ;; `node-property', `section' and `table-row'.
3784 "Parse the element starting at point.
3786 Return value is a list like (TYPE PROPS) where TYPE is the type
3787 of the element and PROPS a plist of properties associated to the
3788 element.
3790 Possible types are defined in `org-element-all-elements'.
3792 LIMIT bounds the search.
3794 Optional argument GRANULARITY determines the depth of the
3795 recursion. Allowed values are `headline', `greater-element',
3796 `element', `object' or nil. When it is broader than `object' (or
3797 nil), secondary values will not be parsed, since they only
3798 contain objects.
3800 Optional argument SPECIAL, when non-nil, can be either
3801 `first-section', `item', `node-property', `section', and
3802 `table-row'.
3804 If STRUCTURE isn't provided but SPECIAL is set to `item', it will
3805 be computed.
3807 This function assumes point is always at the beginning of the
3808 element it has to parse."
3811 ;; Determine if parsing depth allows for secondary strings
3812 ;; parsing. It only applies to elements referenced in
3813 ;; `org-element-secondary-value-alist'.
3816 ;; Item.
3819 ;; Table Row.
3821 ;; Node Property.
3823 ;; Headline.
3826 ;; Sections (must be checked after headline).
3831 limit)))
3832 ;; When not at bol, point is at the beginning of an item or
3833 ;; a footnote definition: next item is always a paragraph.
3835 ;; Planning and Clock.
3840 ;; Inlinetask.
3843 ;; From there, elements can have affiliated keywords.
3846 ;; Jumping over affiliated keywords put point off-limits.
3847 ;; Parse them as regular keywords.
3851 ;; LaTeX Environment.
3855 ;; Drawer and Property Drawer.
3860 ;; Fixed Width
3863 ;; Inline Comments, Blocks, Babel Calls, Dynamic Blocks and
3864 ;; Keywords.
3873 org-element-block-name-alist)))
3888 ;; Footnote Definition.
3891 ;; Horizontal Rule.
3894 ;; Diary Sexp.
3897 ;; Table.
3899 ;; List.
3902 limit affiliated
3904 ;; Default element: Paragraph.
3908 ;; Most elements can have affiliated keywords. When looking for an
3909 ;; element beginning, we want to move before them, as they belong to
3910 ;; that element, and, in the meantime, collect information they give
3911 ;; into appropriate properties. Hence the following function.
3914 "Collect affiliated keywords from point down to LIMIT.
3916 Return a list whose CAR is the position at the first of them and
3917 CDR a plist of keywords and values and move point to the
3918 beginning of the first line after them.
3920 As a special case, if element doesn't start at the beginning of
3921 the line (e.g., a paragraph starting an item), CAR is current
3922 position of point and CDR is nil."
3926 ;; RESTRICT is the list of objects allowed in parsed
3927 ;; keywords value.
3929 output)
3932 ;; Apply translation to RAW-KWD. From there, KWD is
3933 ;; the official keyword.
3935 org-element-keyword-translation-alist))
3936 raw-kwd))
3937 ;; Find main value for any keyword.
3943 ;; PARSEDP is non-nil when keyword should have its
3944 ;; value parsed.
3946 ;; If KWD is a dual keyword, find its secondary
3947 ;; value. Maybe parse it.
3954 ;; Attribute a property name to KWD.
3956 ;; Now set final shape for VALUE.
3962 ;; Attributes can always appear on multiple lines.
3965 ;; Eventually store the new value in OUTPUT.
3967 ;; Move to next keyword.
3969 ;; If affiliated keywords are orphaned: move back to first one.
3970 ;; They will be parsed as a paragraph.
3972 ;; Return value.
3976 \f
3977 ;;; The Org Parser
3978 ;;
3979 ;; The two major functions here are `org-element-parse-buffer', which
3980 ;; parses Org syntax inside the current buffer, taking into account
3981 ;; region, narrowing, or even visibility if specified, and
3982 ;; `org-element-parse-secondary-string', which parses objects within
3983 ;; a given string.
3984 ;;
3985 ;; The (almost) almighty `org-element-map' allows to apply a function
3986 ;; on elements or objects matching some type, and accumulate the
3987 ;; resulting values. In an export situation, it also skips unneeded
3988 ;; parts of the parse tree.
3991 "Recursively parse the buffer and return structure.
3992 If narrowing is in effect, only parse the visible part of the
3993 buffer.
3995 Optional argument GRANULARITY determines the depth of the
3996 recursion. It can be set to the following symbols:
3998 `headline' Only parse headlines.
3999 `greater-element' Don't recurse into greater elements excepted
4000 headlines and sections. Thus, elements
4001 parsed are the top-level ones.
4002 `element' Parse everything but objects and plain text.
4003 `object' Parse the complete buffer (default).
4005 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
4006 elements.
4008 An element or an objects is represented as a list with the
4009 pattern (TYPE PROPERTIES CONTENTS), where :
4011 TYPE is a symbol describing the element or object. See
4012 `org-element-all-elements' and `org-element-all-objects' for an
4013 exhaustive list of such symbols. One can retrieve it with
4014 `org-element-type' function.
4016 PROPERTIES is the list of attributes attached to the element or
4017 object, as a plist. Although most of them are specific to the
4018 element or object type, all types share `:begin', `:end',
4019 `:post-blank' and `:parent' properties, which respectively
4020 refer to buffer position where the element or object starts,
4021 ends, the number of white spaces or blank lines after it, and
4022 the element or object containing it. Properties values can be
4023 obtained by using `org-element-property' function.
4025 CONTENTS is a list of elements, objects or raw strings
4026 contained in the current element or object, when applicable.
4027 One can access them with `org-element-contents' function.
4029 The Org buffer has `org-data' as type and nil as properties.
4030 `org-element-map' function can be used to find specific elements
4031 or objects within the parse tree.
4033 This function assumes that current major mode is `org-mode'."
4039 ;; Start in `first-section' mode so text before the first
4040 ;; headline belongs to a section.
4044 "Recursively parse objects in STRING and return structure.
4046 RESTRICTION is a symbol limiting the object types that will be
4047 looked after.
4049 Optional argument PARENT, when non-nil, is the element or object
4050 containing the secondary string. It is used to set correctly
4051 `:parent' property within the string."
4052 ;; Copy buffer-local variables listed in
4053 ;; `org-element-object-variables' into temporary buffer. This is
4054 ;; required since object parsing is dependent on these variables.
4058 org-element-object-variables))))
4066 secondary))
4067 secondary))))
4071 "Map a function on selected elements or objects.
4073 DATA is a parse tree, an element, an object, a string, or a list
4074 of such constructs. TYPES is a symbol or list of symbols of
4075 elements or objects types (see `org-element-all-elements' and
4076 `org-element-all-objects' for a complete list of types). FUN is
4077 the function called on the matching element or object. It has to
4078 accept one argument: the element or object itself.
4080 When optional argument INFO is non-nil, it should be a plist
4081 holding export options. In that case, parts of the parse tree
4082 not exportable according to that property list will be skipped.
4084 When optional argument FIRST-MATCH is non-nil, stop at the first
4085 match for which FUN doesn't return nil, and return that value.
4087 Optional argument NO-RECURSION is a symbol or a list of symbols
4088 representing elements or objects types. `org-element-map' won't
4089 enter any recursive element or object whose type belongs to that
4090 list. Though, FUN can still be applied on them.
4092 When optional argument WITH-AFFILIATED is non-nil, FUN will also
4093 apply to matching objects within parsed affiliated keywords (see
4094 `org-element-parsed-keywords').
4096 Nil values returned from FUN do not appear in the results.
4099 Examples:
4100 ---------
4102 Assuming TREE is a variable containing an Org buffer parse tree,
4103 the following example will return a flat list of all `src-block'
4104 and `example-block' elements in it:
4106 \(org-element-map tree '(example-block src-block) 'identity)
4108 The following snippet will find the first headline with a level
4111 \(org-element-map tree 'headline
4112 \(lambda (hl)
4113 \(and (= (org-element-property :level hl) 1)
4115 \(org-element-property :begin hl)))
4116 nil t)
4118 The next example will return a flat list of all `plain-list' type
4119 elements in TREE that are not a sub-list themselves:
4121 \(org-element-map tree 'plain-list 'identity nil nil 'plain-list)
4123 Eventually, this example will return a flat list of all `bold'
4124 type objects containing a `latex-snippet' type object, even
4125 looking into captions:
4127 \(org-element-map tree 'bold
4128 \(lambda (b)
4129 \(and (org-element-map b 'latex-snippet 'identity nil t) b))
4130 nil nil nil t)"
4131 ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
4134 ;; Recursion depth is determined by --CATEGORY.
4141 ;; If one object is found, the function
4142 ;; has to recurse into every object.
4145 ;; If one regular element is found, the
4146 ;; function has to recurse, at least,
4147 ;; into every element it encounters.
4150 types)
4151 category)))
4152 ;; Compute properties for affiliated keywords if necessary.
4157 org-element-affiliated-keywords)))
4158 --acc
4159 --walk-tree
4163 ;; Recursively walk DATA. INFO, if non-nil, is a plist
4164 ;; holding contextual information.
4168 ;; Ignored element in an export context.
4170 ;; List of elements or objects.
4172 ;; Unconditionally enter parse trees.
4176 ;; Check if TYPE is matching among TYPES. If so,
4177 ;; apply FUN to --DATA and accumulate return value
4178 ;; into --ACC (or exit if FIRST-MATCH is non-nil).
4184 ;; If --DATA has a secondary string that can contain
4185 ;; objects with their type among TYPES, look into it.
4192 ;; If --DATA has any affiliated keywords and
4193 ;; WITH-AFFILIATED is non-nil, look for objects in
4194 ;; them.
4202 ;; Pay attention to the type of value.
4203 ;; Preserve order for multiple keywords.
4219 --affiliated-alist))
4220 ;; Determine if a recursion into --DATA is possible.
4222 ;; --TYPE is explicitly removed from recursion.
4224 ;; --DATA has no contents.
4226 ;; Looking for greater elements but --DATA is simply
4227 ;; an element or an object.
4230 ;; Looking for elements but --DATA is an object.
4233 ;; In any other case, map contents.
4237 ;; Return value in a proper order.
4241 ;; The following functions are internal parts of the parser.
4242 ;;
4243 ;; The first one, `org-element--parse-elements' acts at the element's
4244 ;; level.
4245 ;;
4246 ;; The second one, `org-element--parse-objects' applies on all objects
4247 ;; of a paragraph or a secondary string. It uses
4248 ;; `org-element--get-next-object-candidates' to optimize the search of
4249 ;; the next object in the buffer.
4250 ;;
4251 ;; More precisely, that function looks for every allowed object type
4252 ;; first. Then, it discards failed searches, keeps further matches,
4253 ;; and searches again types matched behind point, for subsequent
4254 ;; calls. Thus, searching for a given type fails only once, and every
4255 ;; object is searched only once at top level (but sometimes more for
4256 ;; nested types).
4260 "Parse elements between BEG and END positions.
4262 SPECIAL prioritize some elements over the others. It can be set
4263 to `first-section', `section' `item' or `table-row'.
4265 When value is `item', STRUCTURE will be used as the current list
4266 structure.
4268 GRANULARITY determines the depth of the recursion. See
4269 `org-element-parse-buffer' for more information.
4271 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
4272 elements.
4274 Elements are accumulated into ACC."
4277 ;; Visible only: skip invisible parts at the beginning of the
4278 ;; element.
4281 ;; When parsing only headlines, skip any text before first one.
4284 ;; Main loop start.
4286 ;; Find current element's type and parse it accordingly to
4287 ;; its category.
4289 end granularity special structure))
4293 ;; Visible only: skip invisible parts between siblings.
4296 ;; Fill ELEMENT contents by side-effect.
4298 ;; If element has no contents, don't modify it.
4300 ;; Greater element: parse it between `contents-begin' and
4301 ;; `contents-end'. Make sure GRANULARITY allows the
4302 ;; recursion, or ELEMENT is a headline, in which case going
4303 ;; inside is mandatory, in order to get sub-level headings.
4311 ;; Possibly switch to a special mode.
4319 granularity visible-only element))
4320 ;; ELEMENT has contents. Parse objects inside, if
4321 ;; GRANULARITY allows it.
4327 ;; Return result.
4328 acc))
4331 "Parse objects between BEG and END and return recursive structure.
4333 Objects are accumulated in ACC.
4335 RESTRICTION is a list of object successors which are allowed in
4336 the current object."
4345 restriction candidates)))
4352 ;; 1. Text before any object. Untabify it.
4357 acc
4361 ;; 2. Object...
4364 ;; Fill contents of NEXT-OBJECT by side-effect, if it has
4365 ;; a recursive type.
4373 ;; 3. Text after last object. Untabify it.
4377 acc
4381 ;; Result.
4382 acc))))
4385 "Return an alist of candidates for the next object.
4387 RESTRICTION is a list of object types, as symbols. Only
4388 candidates with such types are looked after.
4390 OBJECTS is the previous candidates alist. If it is set to
4391 `initial', no search has been done before, and all symbols in
4392 RESTRICTION should be looked after.
4394 Return value is an alist whose CAR is the object type and CDR its
4395 beginning position."
4397 nil
4399 ;; When searching for the first time, look for every successor
4400 ;; allowed in RESTRICTION.
4404 restriction)
4405 ;; Focus on objects returned during last search. Keep those
4406 ;; still after point. Search again objects before it.
4412 type)))
4415 objects))))
4418 \f
4419 ;;; Towards A Bijective Process
4420 ;;
4421 ;; The parse tree obtained with `org-element-parse-buffer' is really
4422 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
4423 ;; interpreted and expanded into a string with canonical Org syntax.
4424 ;; Hence `org-element-interpret-data'.
4425 ;;
4426 ;; The function relies internally on
4427 ;; `org-element--interpret-affiliated-keywords'.
4429 ;;;###autoload
4431 "Interpret DATA as Org syntax.
4433 DATA is a parse tree, an element, an object or a secondary string
4434 to interpret.
4436 Optional argument PSEUDO-OBJECTS is a list of symbols defining
4437 new types that should be treated as objects. An unknown type not
4438 belonging to this list is seen as a pseudo-element instead. Both
4439 pseudo-objects and pseudo-elements are transparent entities, i.e.
4440 only their contents are interpreted.
4442 Return Org syntax as a string."
4446 "Interpret DATA as Org syntax.
4448 DATA is a parse tree, an element, an object or a secondary string
4449 to interpret. PARENT is used for recursive calls. It contains
4450 the element or object containing data, or nil. PSEUDO-OBJECTS
4451 are list of symbols defining new element or object types.
4452 Unknown types that don't belong to this list are treated as
4453 pseudo-elements instead.
4455 Return Org syntax as a string."
4457 ;; Find interpreter for current object or element. If it
4458 ;; doesn't exist (e.g. this is a pseudo object or element),
4459 ;; return contents, if any.
4465 ;; Secondary string.
4471 ;; Full Org document.
4477 ;; Plain text: return it.
4479 ;; Element or object without contents.
4481 ;; Element or object with contents.
4484 ;; Recursively interpret contents.
4490 data
4491 ;; Fix indentation of elements containing
4492 ;; objects. We ignore `table-row' elements
4493 ;; as they are one line long anyway.
4495 data
4496 ;; When normalizing first paragraph of an
4497 ;; item or a footnote-definition, ignore
4498 ;; first line's indentation.
4505 ;; Build white spaces. If no `:post-blank' property is
4506 ;; specified, assume its value is 0.
4517 "Return ELEMENT's affiliated keywords as Org syntax.
4518 If there is no affiliated keyword, return the empty string."
4528 ": "
4531 value)
4539 ;; All attribute keywords can have multiple lines.
4545 ;; List all ELEMENT's properties matching an attribute line or an
4546 ;; affiliated keyword, but ignore translated keywords since they
4547 ;; cannot belong to the property list.
4554 org-element-keyword-translation-alist)))))
4555 collect prop)
4558 ;; Because interpretation of the parse tree must return the same
4559 ;; number of blank lines between elements and the same number of white
4560 ;; space after objects, some special care must be given to white
4561 ;; spaces.
4562 ;;
4563 ;; The first function, `org-element-normalize-string', ensures any
4564 ;; string different from the empty string will end with a single
4565 ;; newline character.
4566 ;;
4567 ;; The second function, `org-element-normalize-contents', removes
4568 ;; global indentation from the contents of the current element.
4571 "Ensure string S ends with a single newline character.
4573 If S isn't a string return it unchanged. If S is the empty
4574 string, return it. Otherwise, return a new string with a single
4575 newline character at its end."
4583 "Normalize plain text in ELEMENT's contents.
4585 ELEMENT must only contain plain text and objects.
4587 If optional argument IGNORE-FIRST is non-nil, ignore first line's
4588 indentation to compute maximal common indentation.
4590 Return the normalized element that is element with global
4591 indentation removed from its contents. The function assumes that
4592 indentation is not done with TAB characters."
4594 find-min-ind ; For byte-compiler.
4597 ;; Return minimal common indentation within BLOB. This is
4598 ;; done by walking recursively BLOB and updating MIN-IND
4599 ;; along the way. FIRST-FLAG is non-nil when the first
4600 ;; string hasn't been seen yet. It is required as this
4601 ;; string is the only one whose indentation doesn't happen
4602 ;; after a newline character.
4609 ;; An indentation of zero means no string will be
4610 ;; modified. Quit the process.
4619 ;; Find minimal indentation in ELEMENT.
4622 ;; Build ELEMENT back, replacing each string with the same
4623 ;; string minus common indentation.
4628 ;; Return BLOB with all its strings indentation
4629 ;; shortened from MIN-IND white spaces. FIRST-FLAG
4630 ;; is non-nil when the first string hasn't been seen
4631 ;; yet.
4646 org-element-recursive-objects)
4650 blob))))
4654 \f
4655 ;;; Cache
4656 ;;
4657 ;; Implement a caching mechanism for `org-element-at-point' and
4658 ;; `org-element-context', which see.
4659 ;;
4660 ;; A single public function is provided: `org-element-cache-reset'.
4661 ;;
4662 ;; Cache is enabled by default, but can be disabled globally with
4663 ;; `org-element-use-cache'. `org-element-cache-sync-idle-time',
4664 ;; org-element-cache-sync-duration' and `org-element-cache-sync-break'
4665 ;; can be tweaked to control caching behaviour.
4666 ;;
4667 ;; Internally, parsed elements are stored in an AVL tree,
4668 ;; `org-element--cache'. This tree is updated lazily: whenever
4669 ;; a change happens to the buffer, a synchronization request is
4670 ;; registered in `org-element--cache-sync-requests' (see
4671 ;; `org-element--cache-submit-request'). During idle time, requests
4672 ;; are processed by `org-element--cache-sync'. Synchronization also
4673 ;; happens when an element is required from the cache. In this case,
4674 ;; the process stops as soon as the needed element is up-to-date.
4675 ;;
4676 ;; A synchronization request can only apply on a synchronized part of
4677 ;; the cache. Therefore, the cache is updated at least to the
4678 ;; location where the new request applies. Thus, requests are ordered
4679 ;; from left to right and all elements starting before the first
4680 ;; request are correct. This property is used by functions like
4681 ;; `org-element--cache-find' to retrieve elements in the part of the
4682 ;; cache that can be trusted.
4683 ;;
4684 ;; A request applies to every element, starting from its original
4685 ;; location (or key, see below). When a request is processed, it
4686 ;; moves forward and may collide the next one. In this case, both
4687 ;; requests are merged into a new one that starts from that element.
4688 ;; As a consequence, the whole synchronization complexity does not
4689 ;; depend on the number of pending requests, but on the number of
4690 ;; elements the very first request will be applied on.
4691 ;;
4692 ;; Elements cannot be accessed through their beginning position, which
4693 ;; may or may not be up-to-date. Instead, each element in the tree is
4694 ;; associated to a key, obtained with `org-element--cache-key'. This
4695 ;; mechanism is robust enough to preserve total order among elements
4696 ;; even when the tree is only partially synchronized.
4697 ;;
4698 ;; Objects contained in an element are stored in a hash table,
4699 ;; `org-element--cache-objects'.
4703 "Non nil when Org parser should cache its results.
4710 "Maximum duration, as a time value, for a cache synchronization.
4711 If the synchronization is not over after this delay, the process
4712 pauses and resumes after `org-element-cache-sync-break'
4716 "Duration, as a time value, of the pause between synchronizations.
4720 ;;;; Data Structure
4723 "AVL tree used to cache elements.
4724 Each node of the tree contains an element. Comparison is done
4725 with `org-element--cache-compare'. This cache is used in
4729 "Hash table used as to cache objects.
4730 Key is an element, as returned by `org-element-at-point', and
4731 value is an alist where each association is:
4733 \(POS CANDIDATES . OBJECTS)
4735 where POS is a buffer position, CANDIDATES is the last know list
4736 of successors (see `org-element--get-next-object-candidates') in
4737 container starting at POS and OBJECTS is a list of objects known
4738 to live within that container, from farthest to closest.
4741 at, respectively, positions 1, 7 and 8,
4745 If the paragraph is completely parsed, OBJECTS-DATA will be
4747 \((1 nil BOLD-OBJECT ENTITY-OBJECT)
4748 \(8 nil ENTITY-OBJECT))
4750 whereas in a partially parsed paragraph, it could be
4752 \((1 ((entity . 1) (bold . 7)) ENTITY-OBJECT))
4757 "List of pending synchronization requests.
4759 A request is a vector with the following pattern:
4761 \[NEXT END OFFSET PARENT PHASE]
4763 Processing a synchronization request consists in three phases:
4765 0. Delete modified elements,
4766 1. Fill missing area in cache,
4767 2. Shift positions and re-parent elements after the changes.
4769 During phase 0, NEXT is the key of the first element to be
4770 removed and END is buffer position delimiting the modifications.
4771 Every element starting between these are removed. PARENT is an
4772 element to be removed. Every element contained in it will also
4773 be removed.
4775 During phase 1, NEXT is the key of the next known element in
4776 cache. Parse buffer between that element and the one before it
4777 in order to determine the parent of the next element. Set PARENT
4778 to the element containing NEXT.
4780 During phase 2, NEXT is the key of the next element to shift in
4781 the parse tree. All elements starting from this one have their
4782 properties relatives to buffer positions shifted by integer
4783 OFFSET and, if they belong to element PARENT, are adopted by it.
4791 "Hash table used to store keys during synchronization.
4795 "Return a unique key for ELEMENT in cache tree.
4797 Keys are used to keep a total order among elements in the cache.
4798 Comparison is done with `org-element--cache-key-less-p'.
4800 When no synchronization is taking place, a key is simply the
4801 beginning position of the element, or that position plus one in
4802 the case of an first item (respectively row) in
4803 a list (respectively a table).
4805 During a synchronization, the key is the one the element had when
4806 the cache was synchronized for the last time. Elements added to
4807 cache during the synchronization get a new key generated with
4808 `org-element--cache-generate-key'.
4810 Such keys are stored in `org-element--cache-sync-keys'. The hash
4811 table is cleared once the synchronization is complete."
4814 ;; Increase beginning position of items (respectively
4815 ;; table rows) by one, so the first item can get
4816 ;; a different key from its parent list (respectively
4817 ;; table).
4820 begin)))
4823 key))))
4826 "Default value for a new key level.
4830 "Generate a key between LOWER and UPPER.
4832 LOWER and UPPER are integers or lists, possibly empty.
4834 If LOWER and UPPER are equals, return LOWER. Otherwise, return
4835 a unique key, as an integer or a list of integers, according to
4836 the following rules:
4838 - LOWER and UPPER are compared level-wise until values differ.
4840 - If, at a given level, LOWER and UPPER differ from more than
4841 2, the new key shares all the levels above with LOWER and
4842 gets a new level. Its value is the mean between LOWER and
4843 UPPER.
4845 \(1 2) + (1 4) --> (1 3)
4847 - If LOWER has no value to compare with, it is assumed that its
4848 value is 0:
4850 \(1 1) + (1 1 2) --> (1 1 1)
4852 Likewise, if UPPER is short of levels, the current value is
4853 `most-positive-fixnum'.
4855 - If they differ from only one, the new key inherits from
4856 current LOWER lever and has a new level at the value
4857 `org-element--cache-default-key'.
4859 \(1 2) + (1 3) --> (1 2 org-element--cache-default-key)
4861 - If the key is only one level long, it is returned as an
4862 integer.
4864 \(1 2) + (3 2) --> 2"
4868 key)
4886 org-element--cache-default-key))
4887 org-element--cache-default-key)
4888 key)
4894 key)
4901 ;; (n) is equivalent to (n 0 0 0 0 ...) so we want to avoid
4902 ;; ending on a sequence of 0.
4907 key)))
4915 org-element--cache-default-key))
4916 org-element--cache-default-key)
4917 key))))
4918 ;; Ensure we don't return a list with a single element.
4922 "Non-nil if key A is less than key B.
4923 A and B are either integers or lists of integers, as returned by
4924 `org-element--cache-key'."
4932 ;; If A is empty, either keys are equal (B is also empty) or
4933 ;; B is less than A (B is longer). Therefore return nil.
4934 ;;
4935 ;; If A is not empty, B is necessarily empty and A is less
4936 ;; than B (A is longer). Therefore, return a non-nil value.
4937 a))))
4940 "Non-nil when element A is located before element B."
4945 "Return root value in cache.
4946 This function assumes `org-element--cache' is a valid AVL tree."
4950 ;;;; Tools
4953 "Non-nil when cache is active in current buffer."
4958 "Find element in cache starting at POS or before.
4960 POS refers to a buffer position.
4962 When optional argument SIDE is non-nil, the function checks for
4963 elements starting at or past POS instead. If SIDE is `both', the
4964 function returns a cons cell where car is the first element
4965 starting at or before POS and cdr the first element starting
4966 after POS.
4968 The function can only find elements in the synchronized part of
4969 the cache."
4973 lower upper)
4988 ;; We found an element in cache starting at POS. If `side'
4989 ;; is `both' we also want the next one in order to generate
4990 ;; a key in-between.
4991 ;;
4992 ;; If the element is the first row or item in a table or
4993 ;; a plain list, we always return the table or the plain
4994 ;; list.
4995 ;;
4996 ;; In any other case, we return the element found.
5005 lower parent
5006 upper parent)))))
5009 lower element
5010 upper element)))))
5017 "Store ELEMENT in current buffer's cache, if allowed.
5018 When optional argument DATA is non-nil, assume is it object data
5019 relative to ELEMENT and store it in the objects cache."
5023 ;; During synchronization, first build an appropriate key
5024 ;; for the new element so `avl-tree-enter' can insert it at
5025 ;; the right spot in the cache.
5034 org-element--cache-sync-keys)))
5036 ;; Headlines are not stored in cache, so objects in titles are
5037 ;; not stored either.
5042 ;;;; Synchronization
5045 "Set idle timer for cache synchronization in BUFFER."
5052 org-element-cache-sync-idle-time))
5053 nil
5054 #'org-element--cache-sync
5055 buffer)))
5058 "Non-nil when synchronization process should be interrupted.
5059 TIME-LIMIT is a time value or nil."
5065 "Shift ELEMENT properties relative to buffer positions by OFFSET.
5067 Properties containing buffer positions are `:begin', `:end',
5068 `:contents-begin', `:contents-end' and `:structure'. When
5069 optional argument PROPS is a list of keywords, only shift
5070 properties provided in that list.
5072 Properties are modified by side-effect."
5074 ;; Shift `:structure' property for the first plain list only: it
5075 ;; is the only one that really matters and it prevents from
5076 ;; shifting it more than once.
5090 "Synchronize cache with recent modification in BUFFER.
5091 When optional argument THRESHOLD is non-nil, do the
5092 synchronization for all elements starting before or at threshold,
5093 then exit. Otherwise, synchronize cache for as long as
5094 `org-element-cache-sync-duration' or until Emacs leaves idle
5095 state."
5106 request
5108 threshold
5111 org-element-cache-sync-duration)))
5113 ;; Request processed. Merge current and next offsets and
5114 ;; transfer phase number and ending position.
5121 ;; If more requests are awaiting, set idle timer accordingly.
5122 ;; Otherwise, reset keys.
5128 "Process synchronization REQUEST for all entries before NEXT.
5130 REQUEST is a vector, built by `org-element--cache-submit-request'.
5132 NEXT is a cache key, as returned by `org-element--cache-key'.
5134 When non-nil, THRESHOLD is a buffer position. Synchronization
5135 stops as soon as a shifted element begins after it.
5137 When non-nil, TIME-LIMIT is a time value. Synchronization stops
5138 after this time or when Emacs exits idle state.
5140 Return nil if the process stops before completing the request,
5141 t otherwise."
5144 ;; Phase 1.
5145 ;;
5146 ;; Delete all elements starting after BEG, but not after buffer
5147 ;; position END or past element with key NEXT.
5148 ;;
5149 ;; As an exception, also delete elements starting after
5150 ;; modifications but included in an element altered by
5151 ;; modifications (orphans).
5152 ;;
5153 ;; At each iteration, we start again at tree root since
5154 ;; a deletion modifies structure of the balanced tree.
5163 ;; Find first element in cache with key BEG or after it.
5164 ;; We don't use `org-element--cache-find' because it
5165 ;; couldn't reach orphaned elements past NEXT. Moreover,
5166 ;; BEG is a key, not a buffer position.
5176 data-key key
5179 data-key key
5180 node nil)))))
5184 ;; Remove orphaned elements.
5190 up))
5194 next)))
5204 ;; Phase 2.
5205 ;;
5206 ;; Phase 1 left a hole in the parse tree. Some elements after
5207 ;; it could have parents within. For example, in the following
5208 ;; buffer:
5209 ;;
5210 ;;
5211 ;; - item
5212 ;;
5213 ;;
5214 ;; Paragraph1
5215 ;;
5216 ;; Paragraph2
5217 ;;
5218 ;;
5219 ;; if we remove a blank line between "item" and "Paragraph1",
5220 ;; everything down to "Paragraph2" is removed from cache. But
5221 ;; the paragraph now belongs to the list, and its `:parent'
5222 ;; property no longer is accurate.
5223 ;;
5224 ;; Therefore we need to parse again elements in the hole, or at
5225 ;; least in its last section, so that we can re-parent
5226 ;; subsequent elements, during phase 3.
5227 ;;
5228 ;; Note that we only need to get the parent from the first
5229 ;; element in cache after the hole.
5230 ;;
5231 ;; Also, this part can be delayed if we don't need to retrieve
5232 ;; an element after the hole.
5234 ;; Next element will start at its beginning position plus
5235 ;; offset, since it hasn't been shifted yet. Therefore, LIMIT
5236 ;; contains the real beginning position of the first element
5237 ;; to shift and re-parent.
5246 ;; Phase 3.
5247 ;;
5248 ;; Shift all elements starting from key START, but before NEXT, by
5249 ;; OFFSET, and re-parent them when appropriate.
5250 ;;
5251 ;; Elements are modified by side-effect so the tree structure
5252 ;; remains intact.
5253 ;;
5254 ;; Once THRESHOLD, if any, is reached, or once there is an input
5255 ;; pending, exit. Before leaving, the current synchronization
5256 ;; request is updated.
5263 exit-flag)
5264 ;; No re-parenting nor shifting planned: request is over.
5274 ;; We reached NEXT. Request is complete.
5276 ;; Handle interruption request. Update current request.
5281 ;; Shift element.
5284 ;; Shift associated objects data, if any.
5292 ;; Re-parent it.
5298 ;; Cache is up-to-date past THRESHOLD. Request
5299 ;; interruption.
5304 ;; We reached end of tree: synchronization complete.
5305 t)))
5308 "Parse elements in current section, down to POS.
5310 Start parsing from the closest between the last known element in
5311 cache or headline above. Return the smallest element containing
5312 POS.
5314 When optional argument SYNCP is non-nil, return the parent of the
5315 element containing POS instead. In that case, it is also
5316 possible to provide TIME-LIMIT, which is a time value specifying
5317 when the parsing should stop. The function returns `interrupted'
5318 if the process stopped before finding the expected result."
5325 element next)
5327 ;; Nothing in cache before point: start parsing from first
5328 ;; element following headline above, or first element in
5329 ;; buffer.
5335 ;; Cache returned exact match: return it.
5338 ;; There's a headline between cached value and POS: cached
5339 ;; value is invalid. Start parsing from first element
5340 ;; following the headline.
5346 ;; Check if CACHED or any of its ancestors contain point.
5347 ;;
5348 ;; If there is such an element, we inspect it in order to know
5349 ;; if we return it or if we need to parse its contents.
5350 ;; Otherwise, we just start parsing from current location,
5351 ;; which is right after the top-most element containing
5352 ;; CACHED.
5353 ;;
5354 ;; As a special case, if POS is at the end of the buffer, we
5355 ;; want to return the innermost element ending there.
5356 ;;
5357 ;; Also, if we find an ancestor and discover that we need to
5358 ;; parse its contents, make sure we don't start from
5359 ;; `:contents-begin', as we would otherwise go past CACHED
5360 ;; again. Instead, in that situation, we will resume parsing
5361 ;; from NEXT, which is located after CACHED or its higher
5362 ;; ancestor not containing point.
5374 ;; Parse successively each element until we reach POS.
5380 special-flag)
5388 end 'element special-flag
5395 ;; Skip any element ending before point. Also skip
5396 ;; element ending at point (unless it is also the end of
5397 ;; buffer) since we're sure that another element begins
5398 ;; after it.
5401 ;; A non-greater element contains point: return it.
5404 ;; Otherwise, we have to decide if ELEMENT really
5405 ;; contains POS. In that case we start parsing from
5406 ;; contents' beginning.
5407 ;;
5408 ;; If POS is at contents' beginning but it is also at
5409 ;; the beginning of the first item in a list or a table.
5410 ;; In that case, we need to create an anchor for that
5411 ;; list or table, so return it.
5412 ;;
5413 ;; Also, if POS is at the end of the buffer, no element
5414 ;; can start after it, but more than one may end there.
5415 ;; Arbitrarily, we choose to return the innermost of
5416 ;; such elements.
5432 parent element
5433 end cend))))
5434 ;; Otherwise, return ELEMENT as it is the smallest
5435 ;; element containing POS.
5440 ;;;; Staging Buffer Changes
5448 "Regexp matching an element opening line.
5449 When such a line is modified, modifications may propagate after
5450 modified area. In that situation, every element between that
5459 "Regexp matching an element closing line.
5460 When such a line is modified, modifications may propagate before
5461 modified area. In that situation, every element between that
5465 "Non-nil when a sensitive line is about to be changed.
5469 "Request extension of area going to be modified if needed.
5470 BEG and END are the beginning and end of the range of changed
5471 text. See `before-change-functions' for more information."
5473 ;; Make sure buffer positions in cache are correct until END.
5482 ;; A sensitive line is a headline or a block (or drawer,
5483 ;; or latex-environment) boundary. Inserting one can
5484 ;; modify buffer drastically both above and below that
5485 ;; line, possibly making cache invalid. Therefore, we
5486 ;; need to pay attention to changes happening to them.
5490 org-element--cache-opening-line)))
5502 "Update buffer modifications for current buffer.
5503 BEG and END are the beginning and end of the range of changed
5504 text, and the length in bytes of the pre-change text replaced by
5505 that range. See `after-change-functions' for more information."
5515 ;; Determine if modified area needs to be extended,
5516 ;; according to both previous and current state. We make
5517 ;; a special case for headline editing: if a headline is
5518 ;; modified but not removed, do not extend.
5523 org-element--cache-opening-line))
5535 ;; Effectively extend modified area.
5542 ;; Store synchronization request.
5545 ;; Activate a timer to process the request during idle time.
5549 "Submit a new cache synchronization request for current buffer.
5550 BEG and END are buffer positions delimiting the minimal area
5551 where cache data should be removed. OFFSET is the size of the
5552 change, as an integer."
5554 ;; Find the position of the first element in cache to remove.
5555 ;;
5556 ;; Partially modified elements will be removed during request
5557 ;; processing. As an exception, greater elements around the
5558 ;; changes that are robust to contents modifications are
5559 ;; preserved.
5560 ;;
5561 ;; We look just before BEG because an element ending at BEG
5562 ;; needs to be removed too.
5571 drawer dynamic-block inlinetask
5572 property-drawer quote-block special-block))
5575 ;; UP is a greater element that is wrapped around
5576 ;; the changes. We only need to extend its
5577 ;; ending boundaries and those of all its
5578 ;; parents.
5584 ;; We're at top level element containing ELEMENT: if
5585 ;; it's altered by buffer modifications, it is first
5586 ;; element in cache to be removed. Otherwise, that
5587 ;; first element is the following one.
5590 ;; Changes happened before the first known element. Shift the
5591 ;; rest of the cache.
5594 org-element--cache-sync-requests))
5595 ;; There is at least an element to remove. Find position past
5596 ;; every element containing END.
5607 org-element--cache-sync-requests))
5608 ;; No element to remove. No need to re-parent either. Simply
5609 ;; shift additional elements, if any, by OFFSET.
5614 ;;;; Public Functions
5616 ;;;###autoload
5618 "Reset cache in current buffer.
5619 When optional argument ALL is non-nil, reset cache in all Org
5620 buffers. This function will do nothing if
5621 `org-element-use-cache' is nil."
5641 \f
5642 ;;; The Toolbox
5643 ;;
5644 ;; The first move is to implement a way to obtain the smallest element
5645 ;; containing point. This is the job of `org-element-at-point'. It
5646 ;; basically jumps back to the beginning of section containing point
5647 ;; and proceed, one element after the other, with
5648 ;; `org-element--current-element' until the container is found. Note:
5649 ;; When using `org-element-at-point', secondary values are never
5650 ;; parsed since the function focuses on elements, not on objects.
5651 ;;
5652 ;; At a deeper level, `org-element-context' lists all elements and
5653 ;; objects containing point.
5654 ;;
5655 ;; `org-element-nested-p' and `org-element-swap-A-B' may be used
5656 ;; internally by navigation and manipulation tools.
5659 ;;;###autoload
5661 "Determine closest element around point.
5663 Return value is a list like (TYPE PROPS) where TYPE is the type
5664 of the element and PROPS a plist of properties associated to the
5665 element.
5667 Possible types are defined in `org-element-all-elements'.
5668 Properties depend on element or object type, but always include
5669 `:begin', `:end', `:parent' and `:post-blank' properties.
5671 As a special case, if point is at the very beginning of the first
5672 item in a list or sub-list, returned element will be that list
5673 instead of the item. Likewise, if point is at the beginning of
5674 the first row of a table, returned element will be the table
5675 instead of the first row.
5677 When point is at the end of the buffer, return the innermost
5678 element ending there."
5684 ;; Within blank lines at the beginning of buffer, return nil.
5686 ;; Within blank lines right after a headline, return that
5687 ;; headline.
5691 ;; Otherwise parse until we find element containing ORIGIN.
5698 ;;;###autoload
5700 "Return closest element or object around point.
5702 Return value is a list like (TYPE PROPS) where TYPE is the type
5703 of the element or object and PROPS a plist of properties
5704 associated to it.
5706 Possible types are defined in `org-element-all-elements' and
5707 `org-element-all-objects'. Properties depend on element or
5708 object type, but always include `:begin', `:end', `:parent' and
5709 `:post-blank'.
5711 Optional argument ELEMENT, when non-nil, is the closest element
5712 containing point, as returned by `org-element-at-point'.
5713 Providing it allows for quicker computation."
5719 ;; If point is inside an element containing objects or
5720 ;; a secondary string, narrow buffer to the container and
5721 ;; proceed with parsing. Otherwise, return ELEMENT.
5723 ;; At a parsed affiliated keyword, check if we're inside main
5724 ;; or dual value.
5731 org-element-parsed-keywords))
5740 ;; Also change type to retrieve correct restrictions.
5742 ;; At an item, objects can only be located within tag, if any.
5752 ;; At an headline or inlinetask, objects are in title.
5759 ;; At a paragraph, a table-row or a verse block, objects are
5760 ;; located within their contents.
5764 ;; CBEG is nil for table rules.
5769 ;; At a parsed keyword, objects are located within value.
5772 org-element-document-properties))
5779 ;; At a planning line, if point is at a timestamp, return it,
5780 ;; otherwise, return element.
5788 ;; All other locations cannot contain objects: bail out.
5799 objects-data next)
5803 ;; Get list of next object candidates in CANDIDATES.
5804 ;; When entering for the first time PARENT, grab it
5805 ;; from cache, if available, or compute it. Then,
5806 ;; for each subsequent iteration in PARENT, always
5807 ;; compute it since we're beyond cache anyway.
5810 ;; Increase key of objects contained in
5811 ;; table cells by one so they cannot get
5812 ;; the same key as the cell itself.
5819 cache))))
5823 restriction candidates))
5825 ;; Compare ORIGIN with next object starting position,
5826 ;; if any.
5827 ;;
5828 ;; If ORIGIN is lesser or if there is no object
5829 ;; following, look for a previous object that might
5830 ;; contain it in cache. If there is no cache, we
5831 ;; didn't miss any object so simply return PARENT.
5832 ;;
5833 ;; If ORIGIN is greater or equal, parse next
5834 ;; candidate for further processing.
5838 candidates))))
5855 ;; Process NEXT to know if we need to skip it, return
5856 ;; it or move into it.
5861 ;; ORIGIN is after NEXT, so skip it.
5863 ;; ORIGIN is within a non-recursive next or
5864 ;; at an object boundaries: Return that object.
5868 ;; Otherwise, move into NEXT and reset flags as we
5869 ;; shift parent.
5875 next nil
5876 objects-data nil
5878 ;; Store results in cache, if applicable.
5882 "Non-nil when elements ELEM-A and ELEM-B are nested."
5891 "Swap elements ELEM-A and ELEM-B.
5892 Assume ELEM-B is after ELEM-A in the buffer. Leave point at the
5893 end of ELEM-A."
5895 ;; There are two special cases when an element doesn't start at bol:
5896 ;; the first paragraph in an item or in a footnote definition.
5898 ;; Only a paragraph without any affiliated keyword can be moved at
5899 ;; ELEM-A position in such a situation. Note that the case of
5900 ;; a footnote definition is impossible: it cannot contain two
5901 ;; paragraphs in a row because it cannot contain a blank line.
5907 ;; In a special situation, ELEM-A will have no indentation. We'll
5908 ;; give it ELEM-B's (which will in, in turn, have no indentation).
5922 ;; Store overlays responsible for visibility status. We
5923 ;; also need to store their boundaries as they will be
5924 ;; removed from buffer.
5931 ;; Get contents.
5939 ;; Restore ex ELEM-A overlays.
5948 ;; Restore ex ELEM-B overlays.
5956 "Remove maximum common indentation in string S and return it.
5957 When optional argument N is a positive integer, remove exactly
5958 that much characters from indentation, if possible, or return
5959 S as-is otherwise. Unlike to `org-remove-indentation', this
5960 function doesn't call `untabify' on S."
5965 ;; Find maximum common indentation, if not specified.
5973 min-ind)))
5975 ;; Remove exactly N indentation, but give up if not possible.
5988 ;; Local variables:
5989 ;; generated-autoload-file: "org-loaddefs.el"
5990 ;; End:
5992 ;;; org-element.el ends here