| blob | b669de7335731afe512b298f044e2ee7f8d5d023 |
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', `property-drawer', `node-property', `section' and
35 ;; `table-row' types), it can also accept a fixed set of keywords as
36 ;; attributes. Those are called "affiliated keywords" to distinguish
37 ;; them from other keywords, which are full-fledged elements. Almost
38 ;; all affiliated keywords are referenced in
39 ;; `org-element-affiliated-keywords'; the others are export attributes
40 ;; and start with "ATTR_" prefix.
41 ;;
42 ;; Element containing other elements (and only elements) are called
43 ;; greater elements. Concerned types are: `center-block', `drawer',
44 ;; `dynamic-block', `footnote-definition', `headline', `inlinetask',
45 ;; `item', `plain-list', `property-drawer', `quote-block', `section'
46 ;; and `special-block'.
47 ;;
48 ;; Other element types are: `babel-call', `clock', `comment',
49 ;; `comment-block', `diary-sexp', `example-block', `export-block',
50 ;; `fixed-width', `horizontal-rule', `keyword', `latex-environment',
51 ;; `node-property', `paragraph', `planning', `src-block', `table',
52 ;; `table-row' and `verse-block'. Among them, `paragraph' and
53 ;; `verse-block' types can contain Org objects and plain text.
54 ;;
55 ;; Objects are related to document's contents. Some of them are
56 ;; recursive. Associated types are of the following: `bold', `code',
57 ;; `entity', `export-snippet', `footnote-reference',
58 ;; `inline-babel-call', `inline-src-block', `italic',
59 ;; `latex-fragment', `line-break', `link', `macro', `radio-target',
60 ;; `statistics-cookie', `strike-through', `subscript', `superscript',
61 ;; `table-cell', `target', `timestamp', `underline' and `verbatim'.
62 ;;
63 ;; Some elements also have special properties whose value can hold
64 ;; objects themselves (e.g. an item tag or a headline name). Such
65 ;; values are called "secondary strings". Any object belongs to
66 ;; either an element or a secondary string.
67 ;;
68 ;; Notwithstanding affiliated keywords, each greater element, element
69 ;; and object has a fixed set of properties attached to it. Among
70 ;; them, four are shared by all types: `:begin' and `:end', which
71 ;; refer to the beginning and ending buffer positions of the
72 ;; considered element or object, `:post-blank', which holds the number
73 ;; of blank lines, or white spaces, at its end and `:parent' which
74 ;; refers to the element or object containing it. Greater elements,
75 ;; elements and objects containing objects will also have
76 ;; `:contents-begin' and `:contents-end' properties to delimit
77 ;; contents. Eventually, All elements have a `:post-affiliated'
78 ;; property referring to the buffer position after all affiliated
79 ;; keywords, if any, or to their beginning position otherwise.
80 ;;
81 ;; At the lowest level, a `:parent' property is also attached to any
82 ;; string, as a text property.
83 ;;
84 ;; Lisp-wise, an element or an object can be represented as a list.
85 ;; It follows the pattern (TYPE PROPERTIES CONTENTS), where:
86 ;; TYPE is a symbol describing the Org element or object.
87 ;; PROPERTIES is the property list attached to it. See docstring of
88 ;; appropriate parsing function to get an exhaustive
89 ;; list.
90 ;; CONTENTS is a list of elements, objects or raw strings contained
91 ;; in the current element or object, when applicable.
92 ;;
93 ;; An Org buffer is a nested list of such elements and objects, whose
94 ;; type is `org-data' and properties is nil.
95 ;;
96 ;; The first part of this file defines Org syntax, while the second
97 ;; one provide accessors and setters functions.
98 ;;
99 ;; The next part implements a parser and an interpreter for each
100 ;; element and object type in Org syntax.
101 ;;
102 ;; The following part creates a fully recursive buffer parser. It
103 ;; also provides a tool to map a function to elements or objects
104 ;; matching some criteria in the parse tree. Functions of interest
105 ;; are `org-element-parse-buffer', `org-element-map' and, to a lesser
106 ;; extent, `org-element-parse-secondary-string'.
107 ;;
108 ;; The penultimate part is the cradle of an interpreter for the
109 ;; obtained parse tree: `org-element-interpret-data'.
110 ;;
111 ;; The library ends by furnishing `org-element-at-point' function, and
112 ;; a way to give information about document structure around point
113 ;; with `org-element-context'. A cache mechanism is also provided for
114 ;; these functions.
117 ;;; Code:
124 \f
125 ;;; Definitions And Rules
126 ;;
127 ;; Define elements, greater elements and specify recursive objects,
128 ;; along with the affiliated keywords recognized. Also set up
129 ;; restrictions on recursive objects combinations.
130 ;;
131 ;; These variables really act as a control center for the parsing
132 ;; process.
136 ;; Headlines, inlinetasks.
138 ;; Footnote definitions.
140 ;; Diary sexps.
143 ;; Empty lines.
145 ;; Tables (any type).
147 ;; Blocks (any type), Babel calls and keywords. Note: this
148 ;; is only an indication and need some thorough check.
150 ;; Drawers (any type) and fixed-width areas. This is also
151 ;; only an indication.
153 ;; Horizontal rules.
155 ;; LaTeX environments.
157 ;; Clock lines.
159 ;; Lists.
166 "Regexp to separate paragraphs in an Org buffer.
168 is not sufficient to know if point is at a paragraph ending. See
173 dynamic-block example-block export-block fixed-width
174 footnote-definition headline horizontal-rule inlinetask item
175 keyword latex-environment node-property paragraph plain-list
176 planning property-drawer quote-block section
177 special-block src-block table table-row verse-block)
182 item plain-list property-drawer quote-block section
183 special-block table)
188 inline-src-block italic line-break latex-fragment link macro
189 radio-target statistics-cookie strike-through subscript superscript
190 table-cell target timestamp underline verbatim)
195 superscript table-cell underline)
205 "Alist between block names and the associated parsing function.
206 Names must be uppercase. Any block whose name has no association
212 Only these types can accept search options and an explicit
218 "List of affiliated keywords as strings.
226 "Alist of usual translations for keywords.
227 The key is the old name and the value the new one. The property
231 "List of affiliated keywords that can occur more than once in an element.
233 Their value will be consed into a list of strings, which will be
234 returned as the value of the property.
236 This list is checked after translations have been applied. See
237 `org-element-keyword-translation-alist'.
243 "List of affiliated keywords whose value can be parsed.
245 Their value will be stored as a secondary string: a list of
246 strings and objects.
248 This list is checked after translations have been applied. See
252 "List of affiliated keywords which can have a secondary value.
254 In Org syntax, they can be written with optional square brackets
255 before the colons. For example, RESULTS keyword can be
256 associated to a hash value with the following:
258 #+RESULTS[hash-string]: some-source
260 This list is checked after translations have been applied. See
264 "List of properties associated to the whole document.
265 Any keyword in this list will have its value parsed and stored as
271 ;; Dual affiliated keywords.
275 ;; Regular affiliated keywords.
281 org-element-affiliated-keywords)))
283 ;; Export attributes.
285 "Regexp matching any affiliated keyword.
287 Keyword name is put in match group 1. Moreover, if keyword
288 belongs to `org-element-dual-keywords', put the dual value in
289 match group 2.
303 ;; Ignore all links excepted plain links in a link description.
304 ;; Also ignore radio-targets and line breaks.
306 italic latex-fragment macro plain-link statistics-cookie
307 strike-through subscript superscript underline verbatim)
309 ;; Remove any variable object from radio target as it would
310 ;; prevent it from being properly recognized.
312 subscript superscript underline superscript)
316 ;; Ignore inline babel call and inline src block as formulas are
317 ;; possible. Also ignore line breaks and statistics cookies.
319 latex-fragment link macro radio-target strike-through
320 subscript superscript target timestamp underline verbatim)
324 "Alist of objects restrictions.
326 key is an element or object type containing objects and value is
327 a list of types that can be contained within an element or object
328 of such type.
330 For example, in a `radio-target' object, one can only find
331 entities, latex-fragments, subscript, superscript and text
332 markup.
334 This alist also applies to secondary string. For example, an
335 `headline' type element doesn't directly contain objects, but
345 \f
346 ;;; Accessors and Setters
347 ;;
348 ;; Provide four accessors: `org-element-type', `org-element-property'
349 ;; `org-element-contents' and `org-element-restriction'.
350 ;;
351 ;; Setter functions allow to modify elements by side effect. There is
352 ;; `org-element-put-property', `org-element-set-contents'. These
353 ;; low-level functions are useful to build a parse tree.
354 ;;
355 ;; `org-element-adopt-element', `org-element-set-element',
356 ;; `org-element-extract-element' and `org-element-insert-before' are
357 ;; high-level functions useful to modify a parse tree.
358 ;;
359 ;; `org-element-secondary-p' is a predicate used to know if a given
360 ;; object belongs to a secondary string.
363 "Return type of ELEMENT.
365 The function returns the type of the element or object provided.
366 It can also return the following special value:
367 `plain-text' for a string
368 `org-data' for a complete document
369 nil in any other case."
375 "Extract the value from the PROPERTY of an ELEMENT."
380 "Extract contents from an ELEMENT."
386 "Return restriction associated to ELEMENT.
387 ELEMENT can be an element, an object or a symbol representing an
388 element or object type."
390 org-element-object-restrictions)))
393 "In ELEMENT set PROPERTY to VALUE.
394 Return modified element."
397 element))
400 "Set ELEMENT contents to CONTENTS.
401 Return modified element."
408 "Non-nil when OBJECT belongs to a secondary string.
409 Return value is the property name, as a keyword, or nil."
412 org-element-secondary-value-alist))))
415 property)))
418 "Append elements to the contents of another element.
420 PARENT is an element or object. CHILDREN can be elements,
421 objects, or a strings.
423 The function takes care of setting `:parent' property for CHILD.
424 Return parent element."
425 ;; Link every child to PARENT. If PARENT is nil, it is a secondary
426 ;; string: parent is the list itself.
429 children)
430 ;; Add CHILDREN at the end of PARENT contents.
433 parent
435 ;; Return modified PARENT element.
439 "Extract ELEMENT from parse tree.
440 Remove element from the parse tree by side-effect, and return it
441 with its `:parent' property stripped out."
446 parent secondary
449 parent
451 ;; Return ELEMENT with its :parent removed.
455 "Insert ELEMENT before LOCATION in parse tree.
456 LOCATION is an element, object or string within the parse tree.
457 Parse tree is modified by side effect."
462 ;; Special case: LOCATION is the first element of an
463 ;; independent secondary string (e.g. :title property). Add
464 ;; ELEMENT in-place.
468 ;; Install ELEMENT at the appropriate POSITION within SIBLINGS.
478 ;; Store SIBLINGS at appropriate place in parse tree.
483 ;; Set appropriate :parent property.
487 "Replace element or object OLD with element or object NEW.
488 The function takes care of setting `:parent' property for NEW."
489 ;; Ensure OLD and NEW have the same parent.
493 ;; We cannot replace OLD with NEW since one of them is not an
494 ;; object or element. We take the long path.
497 ;; Since OLD is going to be changed into NEW by side-effect, first
498 ;; make sure that every element or object within NEW has OLD as
499 ;; parent.
502 ;; Transfer contents.
504 ;; Overwrite OLD's properties with NEW's.
506 ;; Transfer type.
510 \f
511 ;;; Greater elements
512 ;;
513 ;; For each greater element type, we define a parser and an
514 ;; interpreter.
515 ;;
516 ;; A parser returns the element or object as the list described above.
517 ;; Most of them accepts no argument. Though, exceptions exist. Hence
518 ;; every element containing a secondary string (see
519 ;; `org-element-secondary-value-alist') will accept an optional
520 ;; argument to toggle parsing of that secondary string. Moreover,
521 ;; `item' parser requires current list's structure as its first
522 ;; element.
523 ;;
524 ;; An interpreter accepts two arguments: the list representation of
525 ;; the element or object, and its contents. The latter may be nil,
526 ;; depending on the element or object considered. It returns the
527 ;; appropriate Org syntax, as a string.
528 ;;
529 ;; Parsing functions must follow the naming convention:
530 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
531 ;; defined in `org-element-greater-elements'.
532 ;;
533 ;; Similarly, interpreting functions must follow the naming
534 ;; convention: org-element-TYPE-interpreter.
535 ;;
536 ;; With the exception of `headline' and `item' types, greater elements
537 ;; cannot contain other greater elements of their own type.
538 ;;
539 ;; Beside implementing a parser and an interpreter, adding a new
540 ;; greater element requires to tweak `org-element--current-element'.
541 ;; Moreover, the newly defined type must be added to both
542 ;; `org-element-all-elements' and `org-element-greater-elements'.
545 ;;;; Center Block
548 "Parse a center block.
550 LIMIT bounds the search. AFFILIATED is a list of which CAR is
551 the buffer position at the beginning of the first affiliated
552 keyword and CDR is a plist of affiliated keywords along with
553 their value.
555 Return a list whose CAR is `center-block' and CDR is a plist
556 containing `:begin', `:end', `:contents-begin', `:contents-end',
557 `:post-blank' and `:post-affiliated' keywords.
559 Assume point is at the beginning of the block."
563 ;; Incomplete block: parse it as a paragraph.
568 ;; Empty blocks have no contents.
582 :end end
583 :contents-begin contents-begin
584 :contents-end contents-end
590 "Interpret CENTER-BLOCK element as Org syntax.
591 CONTENTS is the contents of the element."
595 ;;;; Drawer
598 "Parse a drawer.
600 LIMIT bounds the search. AFFILIATED is a list of which CAR is
601 the buffer position at the beginning of the first affiliated
602 keyword and CDR is a plist of affiliated keywords along with
603 their value.
605 Return a list whose CAR is `drawer' and CDR is a plist containing
606 `:drawer-name', `:begin', `:end', `:contents-begin',
607 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
609 Assume point is at beginning of drawer."
612 ;; Incomplete drawer: parse it as a paragraph.
620 ;; Empty drawers have no contents.
633 :end end
634 :drawer-name name
635 :contents-begin contents-begin
636 :contents-end contents-end
642 "Interpret DRAWER element as Org syntax.
643 CONTENTS is the contents of the element."
646 contents))
649 ;;;; Dynamic Block
652 "Parse a dynamic block.
654 LIMIT bounds the search. AFFILIATED is a list of which CAR is
655 the buffer position at the beginning of the first affiliated
656 keyword and CDR is a plist of affiliated keywords along with
657 their value.
659 Return a list whose CAR is `dynamic-block' and CDR is a plist
660 containing `:block-name', `:begin', `:end', `:contents-begin',
661 `:contents-end', `:arguments', `:post-blank' and
662 `:post-affiliated' keywords.
664 Assume point is at beginning of dynamic block."
668 ;; Incomplete block: parse it as a paragraph.
677 ;; Empty blocks have no contents.
690 :end end
691 :block-name name
692 :arguments arguments
693 :contents-begin contents-begin
694 :contents-end contents-end
700 "Interpret DYNAMIC-BLOCK element as Org syntax.
701 CONTENTS is the contents of the element."
706 contents))
709 ;;;; Footnote Definition
712 "Parse a footnote definition.
714 LIMIT bounds the search. AFFILIATED is a list of which CAR is
715 the buffer position at the beginning of the first affiliated
716 keyword and CDR is a plist of affiliated keywords along with
717 their value.
719 Return a list whose CAR is `footnote-definition' and CDR is
720 a plist containing `:label', `:begin' `:end', `:contents-begin',
721 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
723 Assume point is at the beginning of the footnote definition."
751 :begin begin
752 :end end
753 :contents-begin contents-begin
754 :contents-end contents-end
760 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
761 CONTENTS is the contents of the footnote-definition."
763 " "
764 contents))
767 ;;;; Headline
770 "Return node properties associated to headline at point.
771 Upcase property names. It avoids confusion between properties
772 obtained through property drawer and default properties from the
773 parser (e.g. `:end' and :END:). Return value is a plist."
785 properties))))
788 "Return time properties associated to headline at point.
789 Return value is a plist."
803 plist))))
806 "Parse a headline.
808 Return a list whose CAR is `headline' and CDR is a plist
809 containing `:raw-value', `:title', `:alt-title', `:begin',
810 `:end', `:pre-blank', `:contents-begin' and `:contents-end',
811 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
812 `:scheduled', `:deadline', `:closed', `:archivedp', `:commentedp'
813 `:footnote-section-p', `:post-blank' and `:post-affiliated'
814 keywords.
816 The plist also contains any property set in the property drawer,
817 with its name in upper cases and colons added at the
818 beginning (e.g., `:CUSTOM_ID').
820 LIMIT is a buffer position bounding the search.
822 When RAW-SECONDARY-P is non-nil, headline's title will not be
823 parsed as a secondary string, but as a plain string instead.
825 Assume point is at beginning of the headline."
838 raw-value)))
855 ;; Clean RAW-VALUE from any comment string.
861 ""
862 raw-value))))
863 ;; Clean TAGS from archive tag, if any.
869 :begin begin
870 :end end
871 :pre-blank
874 :contents-begin contents-begin
875 :contents-end contents-end
876 :level level
878 :tags tags
879 :todo-keyword todo
880 :todo-type todo-type
883 end)
884 :footnote-section-p footnote-section-p
885 :archivedp archivedp
886 :commentedp commentedp
888 time-props
889 standard-props))))
893 headline :alt-title
898 headline :title
904 "Interpret HEADLINE element as Org syntax.
905 CONTENTS is the contents of the element."
921 ?*)
925 " "
928 org-footnote-section
929 title))))
931 heading
932 ;; Align tags.
940 ?\s)
941 tags))
945 tags))))
947 contents)))
950 ;;;; Inlinetask
953 "Parse an inline task.
955 Return a list whose CAR is `inlinetask' and CDR is a plist
956 containing `:title', `:begin', `:end', `:contents-begin' and
957 `:contents-end', `:level', `:priority', `:raw-value', `:tags',
958 `:todo-keyword', `:todo-type', `:scheduled', `:deadline',
959 `:closed', `:post-blank' and `:post-affiliated' keywords.
961 The plist also contains any property set in the property drawer,
962 with its name in upper cases and colons added at the
963 beginning (e.g., `:CUSTOM_ID').
965 When optional argument RAW-SECONDARY-P is non-nil, inline-task's
966 title will not be parsed as a secondary string, but as a plain
967 string instead.
969 Assume point is at beginning of the inline task."
999 :begin begin
1000 :end end
1001 :contents-begin contents-begin
1002 :contents-end contents-end
1005 :tags tags
1006 :todo-keyword todo
1007 :todo-type todo-type
1010 time-props
1011 standard-props))))
1013 inlinetask :title
1016 raw-value
1018 inlinetask))))))
1021 "Interpret INLINETASK element as Org syntax.
1022 CONTENTS is the contents of inlinetask."
1037 ;; Align tags.
1045 ? )
1046 tags))
1050 tags))))
1051 ;; Prefer degenerate inlinetasks when there are no
1052 ;; contents.
1055 contents
1059 ;;;; Item
1062 "Parse an item.
1064 STRUCT is the structure of the plain list.
1066 Return a list whose CAR is `item' and CDR is a plist containing
1067 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
1068 `:checkbox', `:counter', `:tag', `:structure', `:post-blank' and
1069 `:post-affiliated' keywords.
1071 When optional argument RAW-SECONDARY-P is non-nil, item's tag, if
1072 any, will not be parsed as a secondary string, but as a plain
1073 string instead.
1075 Assume point is at the beginning of the item."
1099 ;; Ignore tags in un-ordered lists: they are just
1100 ;; a part of item's body.
1106 ;; If first line isn't empty, contents really start
1107 ;; at the text after item's meta-data.
1116 :begin begin
1117 :end end
1118 ;; CONTENTS-BEGIN and CONTENTS-END may be
1119 ;; mixed up in the case of an empty item
1120 ;; separated from the next by a blank line.
1121 ;; Thus ensure the former is always the
1122 ;; smallest.
1125 :checkbox checkbox
1126 :counter counter
1127 :structure struct
1131 item :tag
1139 "Interpret ITEM element as Org syntax.
1140 CONTENTS is the contents of the element."
1150 ;; Compute indentation.
1155 ;; Indent contents.
1157 bullet
1171 ;;;; Plain List
1174 ;; Return structure of list at point. Internal function. See
1175 ;; `org-list-struct' for details.
1180 items struct)
1185 ;; At limit: end all items.
1194 ;; At list end: end all items.
1199 ;; At a new item: end previous sibling.
1211 ind
1212 bullet
1215 ;; Description tag.
1219 ;; Ending position, unknown so far.
1220 nil)))
1221 items))
1223 ;; Skip empty lines.
1225 ;; Skip inline tasks and blank lines along the way.
1232 ;; At some text line. Check if it ends any previous item.
1244 ;; Skip blocks (any type) and drawers contents.
1249 limit t)))
1255 "Parse a plain list.
1257 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1258 the buffer position at the beginning of the first affiliated
1259 keyword and CDR is a plist of affiliated keywords along with
1260 their value. STRUCTURE is the structure of the plain list being
1261 parsed.
1263 Return a list whose CAR is `plain-list' and CDR is a plist
1264 containing `:type', `:begin', `:end', `:contents-begin' and
1265 `:contents-end', `:structure', `:post-blank' and
1266 `:post-affiliated' keywords.
1268 Assume point is at the beginning of the list."
1282 pos))
1286 ;; Return value.
1290 :begin begin
1291 :end end
1292 :contents-begin contents-begin
1293 :contents-end contents-end
1294 :structure struct
1300 "Interpret PLAIN-LIST element as Org syntax.
1301 CONTENTS is the contents of the element."
1309 ;;;; Property Drawer
1312 "Parse a property drawer.
1314 LIMIT bounds the search.
1316 Return a list whose car is `property-drawer' and cdr is a plist
1317 containing `:begin', `:end', `:contents-begin', `:contents-end',
1318 `:post-blank' and `:post-affiliated' keywords.
1320 Assume point is at the beginning of the property drawer."
1333 :end end
1335 :contents-end contents-end
1340 "Interpret PROPERTY-DRAWER element as Org syntax.
1341 CONTENTS is the properties within the drawer."
1345 ;;;; Quote Block
1348 "Parse a quote block.
1350 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1351 the buffer position at the beginning of the first affiliated
1352 keyword and CDR is a plist of affiliated keywords along with
1353 their value.
1355 Return a list whose CAR is `quote-block' and CDR is a plist
1356 containing `:begin', `:end', `:contents-begin', `:contents-end',
1357 `:post-blank' and `:post-affiliated' keywords.
1359 Assume point is at the beginning of the block."
1363 ;; Incomplete block: parse it as a paragraph.
1369 ;; Empty blocks have no contents.
1382 :end end
1383 :contents-begin contents-begin
1384 :contents-end contents-end
1390 "Interpret QUOTE-BLOCK element as Org syntax.
1391 CONTENTS is the contents of the element."
1395 ;;;; Section
1398 "Parse a section.
1400 LIMIT bounds the search.
1402 Return a list whose CAR is `section' and CDR is a plist
1403 containing `:begin', `:end', `:contents-begin', `contents-end',
1404 `:post-blank' and `:post-affiliated' keywords."
1406 ;; Beginning of section is the beginning of the first non-blank
1407 ;; line after previous headline.
1416 :end end
1417 :contents-begin begin
1418 :contents-end pos-before-blank
1423 "Interpret SECTION element as Org syntax.
1424 CONTENTS is the contents of the element."
1425 contents)
1428 ;;;; Special Block
1431 "Parse a special block.
1433 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1434 the buffer position at the beginning of the first affiliated
1435 keyword and CDR is a plist of affiliated keywords along with
1436 their value.
1438 Return a list whose CAR is `special-block' and CDR is a plist
1439 containing `:type', `:begin', `:end', `:contents-begin',
1440 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
1442 Assume point is at the beginning of the block."
1449 limit t)))
1450 ;; Incomplete block: parse it as a paragraph.
1456 ;; Empty blocks have no contents.
1469 :begin begin
1470 :end end
1471 :contents-begin contents-begin
1472 :contents-end contents-end
1478 "Interpret SPECIAL-BLOCK element as Org syntax.
1479 CONTENTS is the contents of the element."
1484 \f
1485 ;;; Elements
1486 ;;
1487 ;; For each element, a parser and an interpreter are also defined.
1488 ;; Both follow the same naming convention used for greater elements.
1489 ;;
1490 ;; Also, as for greater elements, adding a new element type is done
1491 ;; through the following steps: implement a parser and an interpreter,
1492 ;; tweak `org-element--current-element' so that it recognizes the new
1493 ;; type and add that new type to `org-element-all-elements'.
1494 ;;
1495 ;; As a special case, when the newly defined type is a block type,
1496 ;; `org-element-block-name-alist' has to be modified accordingly.
1499 ;;;; Babel Call
1502 "Parse a babel call.
1504 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1505 the buffer position at the beginning of the first affiliated
1506 keyword and CDR is a plist of affiliated keywords along with
1507 their value.
1509 Return a list whose CAR is `babel-call' and CDR is a plist
1510 containing `:begin', `:end', `:value', `:post-blank' and
1511 `:post-affiliated' as keywords."
1525 :end end
1526 :value value
1532 "Interpret BABEL-CALL element as Org syntax.
1533 CONTENTS is nil."
1537 ;;;; Clock
1540 "Parse a clock.
1542 LIMIT bounds the search.
1544 Return a list whose CAR is `clock' and CDR is a plist containing
1545 `:status', `:value', `:time', `:begin', `:end', `:post-blank' and
1546 `:post-affiliated' as keywords."
1566 :value value
1567 :duration duration
1568 :begin begin
1569 :end end
1570 :post-blank post-blank
1574 "Interpret CLOCK element as Org syntax.
1575 CONTENTS is nil."
1583 "%2s:%02s"
1587 ;;;; Comment
1590 "Parse a comment.
1592 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1593 the buffer position at the beginning of the first affiliated
1594 keyword and CDR is a plist of affiliated keywords along with
1595 their value.
1597 Return a list whose CAR is `comment' and CDR is a plist
1598 containing `:begin', `:end', `:value', `:post-blank',
1599 `:post-affiliated' keywords.
1601 Assume point is at comment beginning."
1610 ;; Get comments ending.
1613 ;; Accumulate lines without leading hash and first
1614 ;; whitespace.
1628 :end end
1629 :value value
1635 "Interpret COMMENT element as Org syntax.
1636 CONTENTS is nil."
1640 ;;;; Comment Block
1643 "Parse an export block.
1645 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1646 the buffer position at the beginning of the first affiliated
1647 keyword and CDR is a plist of affiliated keywords along with
1648 their value.
1650 Return a list whose CAR is `comment-block' and CDR is a plist
1651 containing `:begin', `:end', `:value', `:post-blank' and
1652 `:post-affiliated' keywords.
1654 Assume point is at comment block beginning."
1658 ;; Incomplete block: parse it as a paragraph.
1671 contents-begin contents-end)))
1675 :end end
1676 :value value
1682 "Interpret COMMENT-BLOCK element as Org syntax.
1683 CONTENTS is nil."
1690 ;;;; Diary Sexp
1693 "Parse a diary sexp.
1695 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1696 the buffer position at the beginning of the first affiliated
1697 keyword and CDR is a plist of affiliated keywords along with
1698 their value.
1700 Return a list whose CAR is `diary-sexp' and CDR is a plist
1701 containing `:begin', `:end', `:value', `:post-blank' and
1702 `:post-affiliated' keywords."
1714 :begin begin
1715 :end end
1721 "Interpret DIARY-SEXP as Org syntax.
1722 CONTENTS is nil."
1726 ;;;; Example Block
1729 "Parse an example block.
1731 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1732 the buffer position at the beginning of the first affiliated
1733 keyword and CDR is a plist of affiliated keywords along with
1734 their value.
1736 Return a list whose CAR is `example-block' and CDR is a plist
1737 containing `:begin', `:end', `:number-lines', `:preserve-indent',
1738 `:retain-labels', `:use-labels', `:label-fmt', `:switches',
1739 `:value', `:post-blank' and `:post-affiliated' keywords."
1743 ;; Incomplete block: parse it as a paragraph.
1751 ;; Switches analysis
1758 ;; Should labels be retained in (or stripped from) example
1759 ;; blocks?
1764 ;; What should code-references use - labels or
1765 ;; line-numbers?
1774 ;; Standard block parsing.
1782 contents-begin contents-end))
1783 block-ind))
1792 :end end
1793 :value value
1794 :switches switches
1795 :number-lines number-lines
1796 :preserve-indent preserve-indent
1797 :retain-labels retain-labels
1798 :use-labels use-labels
1799 :label-fmt label-fmt
1805 "Interpret EXAMPLE-BLOCK element as Org syntax.
1806 CONTENTS is nil."
1814 value
1819 ;;;; Export Block
1822 "Parse an export block.
1824 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1825 the buffer position at the beginning of the first affiliated
1826 keyword and CDR is a plist of affiliated keywords along with
1827 their value.
1829 Return a list whose CAR is `export-block' and CDR is a plist
1830 containing `:begin', `:end', `:type', `:value', `:post-blank' and
1831 `:post-affiliated' keywords.
1833 Assume point is at export-block beginning."
1840 ;; Incomplete block: parse it as a paragraph.
1853 contents-end)))
1857 :end end
1858 :type type
1859 :value value
1865 "Interpret EXPORT-BLOCK element as Org syntax.
1866 CONTENTS is nil."
1873 ;;;; Fixed-width
1876 "Parse a fixed-width section.
1878 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1879 the buffer position at the beginning of the first affiliated
1880 keyword and CDR is a plist of affiliated keywords along with
1881 their value.
1883 Return a list whose CAR is `fixed-width' and CDR is a plist
1884 containing `:begin', `:end', `:value', `:post-blank' and
1885 `:post-affiliated' keywords.
1887 Assume point is at the beginning of the fixed-width area."
1891 value
1896 ;; Accumulate text without starting colons.
1909 :end end
1910 :value value
1916 "Interpret FIXED-WIDTH element as Org syntax.
1917 CONTENTS is nil."
1925 ;;;; Horizontal Rule
1928 "Parse an horizontal rule.
1930 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1931 the buffer position at the beginning of the first affiliated
1932 keyword and CDR is a plist of affiliated keywords along with
1933 their value.
1935 Return a list whose CAR is `horizontal-rule' and CDR is a plist
1936 containing `:begin', `:end', `:post-blank' and `:post-affiliated'
1937 keywords."
1947 :end end
1953 "Interpret HORIZONTAL-RULE element as Org syntax.
1954 CONTENTS is nil."
1958 ;;;; Keyword
1961 "Parse a keyword at point.
1963 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1964 the buffer position at the beginning of the first affiliated
1965 keyword and CDR is a plist of affiliated keywords along with
1966 their value.
1968 Return a list whose CAR is `keyword' and CDR is a plist
1969 containing `:key', `:value', `:begin', `:end', `:post-blank' and
1970 `:post-affiliated' keywords."
1972 ;; An orphaned affiliated keyword is considered as a regular
1973 ;; keyword. In this case AFFILIATED is nil, so we take care of
1974 ;; this corner case.
1987 :value value
1988 :begin begin
1989 :end end
1995 "Interpret KEYWORD element as Org syntax.
1996 CONTENTS is nil."
2002 ;;;; Latex Environment
2006 "Regexp matching the beginning of a LaTeX environment.
2007 The environment is captured by the first group.
2013 "Format string matching the ending of a LaTeX environment.
2017 "Parse a LaTeX environment.
2019 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2020 the buffer position at the beginning of the first affiliated
2021 keyword and CDR is a plist of affiliated keywords along with
2022 their value.
2024 Return a list whose CAR is `latex-environment' and CDR is a plist
2025 containing `:begin', `:end', `:value', `:post-blank' and
2026 `:post-affiliated' keywords.
2028 Assume point is at the beginning of the latex environment."
2035 limit t))
2036 ;; Incomplete latex environment: parse it as a paragraph.
2046 :end end
2047 :value value
2053 "Interpret LATEX-ENVIRONMENT element as Org syntax.
2054 CONTENTS is nil."
2058 ;;;; Node Property
2061 "Parse a node-property at point.
2063 LIMIT bounds the search.
2065 Return a list whose CAR is `node-property' and CDR is a plist
2066 containing `:key', `:value', `:begin', `:end', `:post-blank' and
2067 `:post-affiliated' keywords."
2077 limit))))
2080 :value value
2081 :begin begin
2082 :end end
2087 "Interpret NODE-PROPERTY element as Org syntax.
2088 CONTENTS is nil."
2094 ;;;; Paragraph
2097 "Parse a paragraph.
2099 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2100 the buffer position at the beginning of the first affiliated
2101 keyword and CDR is a plist of affiliated keywords along with
2102 their value.
2104 Return a list whose CAR is `paragraph' and CDR is a plist
2105 containing `:begin', `:end', `:contents-begin' and
2106 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
2108 Assume point is at the beginning of the paragraph."
2117 limit
2118 ;; A matching `org-element-paragraph-separate' is not
2119 ;; necessarily the end of the paragraph. In
2120 ;; particular, lines starting with # or : as a first
2121 ;; non-space character are ambiguous. We have to
2122 ;; check if they are valid Org syntax (e.g., not an
2123 ;; incomplete keyword).
2127 ;; There's no ambiguity for other symbols or
2128 ;; empty lines: stop here.
2130 ;; Stop at valid fixed-width areas.
2132 ;; Stop at drawers.
2137 ;; Stop at valid comments.
2139 ;; Stop at valid dynamic blocks.
2144 ;; Stop at valid blocks.
2151 limit t)))
2152 ;; Stop at valid latex environments.
2159 limit t)))
2160 ;; Stop at valid keywords.
2162 ;; Skip everything else.
2179 :end end
2180 :contents-begin contents-begin
2181 :contents-end contents-end
2187 "Interpret PARAGRAPH element as Org syntax.
2188 CONTENTS is the contents of the element."
2189 contents)
2192 ;;;; Planning
2195 "Parse a planning.
2197 LIMIT bounds the search.
2199 Return a list whose CAR is `planning' and CDR is a plist
2200 containing `:closed', `:deadline', `:scheduled', `:begin',
2201 `:end', `:post-blank' and `:post-affiliated' keywords."
2211 closed deadline scheduled)
2223 :deadline deadline
2224 :scheduled scheduled
2225 :begin begin
2226 :end end
2227 :post-blank post-blank
2231 "Interpret PLANNING element as Org syntax.
2232 CONTENTS is nil."
2234 'identity
2251 ;;;; Src Block
2254 "Parse a src block.
2256 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2257 the buffer position at the beginning of the first affiliated
2258 keyword and CDR is a plist of affiliated keywords along with
2259 their value.
2261 Return a list whose CAR is `src-block' and CDR is a plist
2262 containing `:language', `:switches', `:parameters', `:begin',
2263 `:end', `:number-lines', `:retain-labels', `:use-labels',
2264 `:label-fmt', `:preserve-indent', `:value', `:post-blank' and
2265 `:post-affiliated' keywords.
2267 Assume point is at the beginning of the block."
2270 limit t)))
2271 ;; Incomplete block: parse it as a paragraph.
2277 ;; Get language as a string.
2286 ;; Get switches.
2288 ;; Get parameters.
2290 ;; Switches analysis
2301 ;; Should labels be retained in (or stripped from)
2302 ;; src blocks?
2307 ;; What should code-references use - labels or
2308 ;; line-numbers?
2313 ;; Indentation.
2315 ;; Retrieve code.
2320 block-ind))
2324 ;; Get position after ending blank lines.
2334 :begin begin
2335 :end end
2336 :number-lines number-lines
2337 :preserve-indent preserve-indent
2338 :retain-labels retain-labels
2339 :use-labels use-labels
2340 :label-fmt label-fmt
2341 :value value
2347 "Interpret SRC-BLOCK element as Org syntax.
2348 CONTENTS is nil."
2357 val)
2371 ;;;; Table
2374 "Parse a table at point.
2376 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2377 the buffer position at the beginning of the first affiliated
2378 keyword and CDR is a plist of affiliated keywords along with
2379 their value.
2381 Return a list whose CAR is `table' and CDR is a plist containing
2382 `:begin', `:end', `:tblfm', `:type', `:contents-begin',
2383 `:contents-end', `:value', `:post-blank' and `:post-affiliated'
2384 keywords.
2386 Assume point is at the beginning of the table."
2400 acc))
2407 :end end
2408 :type type
2409 :tblfm tblfm
2410 ;; Only `org' tables have contents. `table.el' tables
2411 ;; use a `:value' property to store raw table as
2412 ;; a string.
2417 table-begin table-end))
2423 "Interpret TABLE element as Org syntax.
2424 CONTENTS is a string, if table's type is `org', or nil."
2435 ;;;; Table Row
2438 "Parse table row at point.
2440 LIMIT bounds the search.
2442 Return a list whose CAR is `table-row' and CDR is a plist
2443 containing `:begin', `:end', `:contents-begin', `:contents-end',
2444 `:type', `:post-blank' and `:post-affiliated' keywords."
2448 ;; A table rule has no contents. In that case, ensure
2449 ;; CONTENTS-BEGIN matches CONTENTS-END.
2461 :begin begin
2462 :end end
2463 :contents-begin contents-begin
2464 :contents-end contents-end
2469 "Interpret TABLE-ROW element as Org syntax.
2470 CONTENTS is the contents of the table row."
2475 ;;;; Verse Block
2478 "Parse a verse block.
2480 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2481 the buffer position at the beginning of the first affiliated
2482 keyword and CDR is a plist of affiliated keywords along with
2483 their value.
2485 Return a list whose CAR is `verse-block' and CDR is a plist
2486 containing `:begin', `:end', `:contents-begin', `:contents-end',
2487 `:post-blank' and `:post-affiliated' keywords.
2489 Assume point is at beginning of the block."
2493 ;; Incomplete block: parse it as a paragraph.
2508 :end end
2509 :contents-begin contents-begin
2510 :contents-end contents-end
2516 "Interpret VERSE-BLOCK element as Org syntax.
2517 CONTENTS is verse block contents."
2521 \f
2522 ;;; Objects
2523 ;;
2524 ;; Unlike to elements, raw text can be found between objects. Hence,
2525 ;; `org-element--object-lex' is provided to find the next object in
2526 ;; buffer.
2527 ;;
2528 ;; Some object types (e.g., `italic') are recursive. Restrictions on
2529 ;; object types they can contain will be specified in
2530 ;; `org-element-object-restrictions'.
2531 ;;
2532 ;; Creating a new type of object requires to alter
2533 ;; `org-element--object-regexp' and `org-element--object-lex', add the
2534 ;; new type in `org-element-all-objects', and possibly add
2535 ;; restrictions in `org-element-object-restrictions'.
2537 ;;;; Bold
2540 "Parse bold object at point, if any.
2542 When at a bold object, return a list whose car is `bold' and cdr
2543 is a plist with `:begin', `:end', `:contents-begin' and
2544 `:contents-end' and `:post-blank' keywords. Otherwise, return
2545 nil.
2547 Assume point is at the first star marker."
2559 :end end
2560 :contents-begin contents-begin
2561 :contents-end contents-end
2565 "Interpret BOLD object as Org syntax.
2566 CONTENTS is the contents of the object."
2570 ;;;; Code
2573 "Parse code object at point, if any.
2575 When at a code object, return a list whose car is `code' and cdr
2576 is a plist with `:value', `:begin', `:end' and `:post-blank'
2577 keywords. Otherwise, return nil.
2579 Assume point is at the first tilde marker."
2590 :begin begin
2591 :end end
2595 "Interpret CODE object as Org syntax.
2596 CONTENTS is nil."
2600 ;;;; Entity
2603 "Parse entity at point, if any.
2605 When at an entity, return a list whose car is `entity' and cdr
2606 a plist with `:begin', `:end', `:latex', `:latex-math-p',
2607 `:html', `:latin1', `:utf-8', `:ascii', `:use-brackets-p' and
2608 `:post-blank' as keywords. Otherwise, return nil.
2610 Assume point is at the beginning of the entity."
2612 (when (looking-at "\\\\\\(there4\\|sup[123]\\|frac[13][24]\\|[a-zA-Z]+\\)\\($\\|{}\\|[^[:alpha:]]\\)")
2630 :begin begin
2631 :end end
2632 :use-brackets-p bracketsp
2636 "Interpret ENTITY object as Org syntax.
2637 CONTENTS is nil."
2643 ;;;; Export Snippet
2646 "Parse export snippet at point.
2648 When at an export snippet, return a list whose car is
2649 `export-snippet' and cdr a plist with `:begin', `:end',
2650 `:back-end', `:value' and `:post-blank' as keywords. Otherwise,
2651 return nil.
2653 Assume point is at the beginning of the snippet."
2669 :value value
2670 :begin begin
2671 :end end
2675 "Interpret EXPORT-SNIPPET object as Org syntax.
2676 CONTENTS is nil."
2682 ;;;; Footnote Reference
2685 "Parse footnote reference at point, if any.
2687 When at a footnote reference, return a list whose car is
2688 `footnote-reference' and cdr a plist with `:label', `:type',
2689 `:begin', `:end', `:content-begin', `:contents-end' and
2690 `:post-blank' as keywords. Otherwise, return nil."
2714 :type type
2715 :begin begin
2716 :end end
2722 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
2723 CONTENTS is its definition, when inline, or nil."
2729 ;;;; Inline Babel Call
2732 "Parse inline babel call at point, if any.
2734 When at an inline babel call, return a list whose car is
2735 `inline-babel-call' and cdr a plist with `:begin', `:end',
2736 `:value' and `:post-blank' as keywords. Otherwise, return nil.
2738 Assume point is at the beginning of the babel call."
2750 :end end
2751 :value value
2755 "Interpret INLINE-BABEL-CALL object as Org syntax.
2756 CONTENTS is nil."
2760 ;;;; Inline Src Block
2763 "Parse inline source block at point, if any.
2765 When at an inline source block, return a list whose car is
2766 `inline-src-block' and cdr a plist with `:begin', `:end',
2767 `:language', `:value', `:parameters' and `:post-blank' as
2768 keywords. Otherwise, return nil.
2770 Assume point is at the beginning of the inline src block."
2783 :value value
2784 :parameters parameters
2785 :begin begin
2786 :end end
2790 "Interpret INLINE-SRC-BLOCK object as Org syntax.
2791 CONTENTS is nil."
2796 language
2798 body)))
2800 ;;;; Italic
2803 "Parse italic object at point, if any.
2805 When at an italic object, return a list whose car is `italic' and
2806 cdr is a plist with `:begin', `:end', `:contents-begin' and
2807 `:contents-end' and `:post-blank' keywords. Otherwise, return
2808 nil.
2810 Assume point is at the first slash marker."
2822 :end end
2823 :contents-begin contents-begin
2824 :contents-end contents-end
2828 "Interpret ITALIC object as Org syntax.
2829 CONTENTS is the contents of the object."
2833 ;;;; Latex Fragment
2836 "Parse LaTeX fragment at point, if any.
2838 When at a LaTeX fragment, return a list whose car is
2839 `latex-fragment' and cdr a plist with `:value', `:begin', `:end',
2840 and `:post-blank' as keywords. Otherwise, return nil.
2842 Assume point is at the beginning of the LaTeX fragment."
2860 ;; Macro.
2869 :begin begin
2870 :end end
2874 "Interpret LATEX-FRAGMENT object as Org syntax.
2875 CONTENTS is nil."
2878 ;;;; Line Break
2881 "Parse line break at point, if any.
2883 When at a line break, return a list whose car is `line-break',
2884 and cdr a plist with `:begin', `:end' and `:post-blank' keywords.
2885 Otherwise, return nil.
2887 Assume point is at the beginning of the line break."
2896 "Interpret LINE-BREAK object as Org syntax.
2897 CONTENTS is nil."
2901 ;;;; Link
2904 "Parse link at point, if any.
2906 When at a link, return a list whose car is `link' and cdr a plist
2907 with `:type', `:path', `:raw-link', `:application',
2908 `:search-option', `:begin', `:end', `:contents-begin',
2909 `:contents-end' and `:post-blank' as keywords. Otherwise, return
2910 nil.
2912 Assume point is at the beginning of the link."
2915 end contents-begin contents-end link-end post-blank path type
2916 raw-link link search-option application)
2918 ;; Type 1: Text targeted from a radio target.
2927 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
2932 ;; RAW-LINK is the original link. Expand any
2933 ;; abbreviation in it.
2937 ;; Determine TYPE of link and set PATH accordingly.
2939 ;; File type.
2943 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
2946 ;; According to RFC 3986, extra whitespace should be
2947 ;; ignored when a URI is extracted.
2950 ;; Id type: PATH is the id.
2953 ;; Code-ref type: PATH is the name of the reference.
2956 ;; Custom-id type: PATH is the name of the custom id.
2959 ;; Fuzzy type: Internal link either matches a target, an
2960 ;; headline name or nothing. PATH is the target or
2961 ;; headline's name.
2963 ;; Type 3: Plain link, e.g., http://orgmode.org
2969 ;; Type 4: Angular link, e.g., <http://orgmode.org>
2977 ;; In any case, deduce end point after trailing white space from
2978 ;; LINK-END variable.
2982 ;; Special "file" type link processing.
2984 ;; Extract opening application and search option.
2992 ;; Normalize URI.
2996 ;; Make sure TYPE always reports "file".
3000 :path path
3002 :application application
3003 :search-option search-option
3004 :begin begin
3005 :end end
3006 :contents-begin contents-begin
3007 :contents-end contents-end
3011 "Interpret LINK object as Org syntax.
3012 CONTENTS is the contents of the object, or nil."
3017 raw-link
3021 ;;;; Macro
3024 "Parse macro at point, if any.
3026 When at a macro, return a list whose car is `macro' and cdr
3027 a plist with `:key', `:args', `:begin', `:end', `:value' and
3028 `:post-blank' as keywords. Otherwise, return nil.
3030 Assume point is at the macro."
3041 ;; Do not use `org-split-string' since empty
3042 ;; strings are meaningful here.
3050 args nil t)
3054 :value value
3055 :args args
3056 :begin begin
3057 :end end
3061 "Interpret MACRO object as Org syntax.
3062 CONTENTS is nil."
3066 ;;;; Radio-target
3069 "Parse radio target at point, if any.
3071 When at a radio target, return a list whose car is `radio-target'
3072 and cdr a plist with `:begin', `:end', `:contents-begin',
3073 `:contents-end', `:value' and `:post-blank' as keywords.
3074 Otherwise, return nil.
3076 Assume point is at the radio target."
3088 :end end
3089 :contents-begin contents-begin
3090 :contents-end contents-end
3091 :post-blank post-blank
3095 "Interpret TARGET object as Org syntax.
3096 CONTENTS is the contents of the object."
3100 ;;;; Statistics Cookie
3103 "Parse statistics cookie at point, if any.
3105 When at a statistics cookie, return a list whose car is
3106 `statistics-cookie', and cdr a plist with `:begin', `:end',
3107 `:value' and `:post-blank' keywords. Otherwise, return nil.
3109 Assume point is at the beginning of the statistics-cookie."
3120 :end end
3121 :value value
3125 "Interpret STATISTICS-COOKIE object as Org syntax.
3126 CONTENTS is nil."
3130 ;;;; Strike-Through
3133 "Parse strike-through object at point, if any.
3135 When at a strike-through object, return a list whose car is
3136 `strike-through' and cdr is a plist with `:begin', `:end',
3137 `:contents-begin' and `:contents-end' and `:post-blank' keywords.
3138 Otherwise, return nil.
3140 Assume point is at the first plus sign marker."
3152 :end end
3153 :contents-begin contents-begin
3154 :contents-end contents-end
3158 "Interpret STRIKE-THROUGH object as Org syntax.
3159 CONTENTS is the contents of the object."
3163 ;;;; Subscript
3166 "Parse subscript at point, if any.
3168 When at a subscript object, return a list whose car is
3169 `subscript' and cdr a plist with `:begin', `:end',
3170 `:contents-begin', `:contents-end', `:use-brackets-p' and
3171 `:post-blank' as keywords. Otherwise, return nil.
3173 Assume point is at the underscore."
3187 :end end
3188 :use-brackets-p bracketsp
3189 :contents-begin contents-begin
3190 :contents-end contents-end
3194 "Interpret SUBSCRIPT object as Org syntax.
3195 CONTENTS is the contents of the object."
3198 contents))
3201 ;;;; Superscript
3204 "Parse superscript at point, if any.
3206 When at a superscript object, return a list whose car is
3207 `superscript' and cdr a plist with `:begin', `:end',
3208 `:contents-begin', `:contents-end', `:use-brackets-p' and
3209 `:post-blank' as keywords. Otherwise, return nil.
3211 Assume point is at the caret."
3225 :end end
3226 :use-brackets-p bracketsp
3227 :contents-begin contents-begin
3228 :contents-end contents-end
3232 "Interpret SUPERSCRIPT object as Org syntax.
3233 CONTENTS is the contents of the object."
3236 contents))
3239 ;;;; Table Cell
3242 "Parse table cell at point.
3243 Return a list whose car is `table-cell' and cdr is a plist
3244 containing `:begin', `:end', `:contents-begin', `:contents-end'
3245 and `:post-blank' keywords."
3253 :end end
3254 :contents-begin contents-begin
3255 :contents-end contents-end
3259 "Interpret TABLE-CELL element as Org syntax.
3260 CONTENTS is the contents of the cell, or nil."
3264 ;;;; Target
3267 "Parse target at point, if any.
3269 When at a target, return a list whose car is `target' and cdr
3270 a plist with `:begin', `:end', `:value' and `:post-blank' as
3271 keywords. Otherwise, return nil.
3273 Assume point is at the target."
3283 :end end
3284 :value value
3288 "Interpret TARGET object as Org syntax.
3289 CONTENTS is nil."
3293 ;;;; Timestamp
3304 "Parse time stamp at point, if any.
3306 When at a time stamp, return a list whose car is `timestamp', and
3307 cdr a plist with `:type', `:raw-value', `:year-start',
3308 `:month-start', `:day-start', `:hour-start', `:minute-start',
3309 `:year-end', `:month-end', `:day-end', `:hour-end',
3310 `:minute-end', `:repeater-type', `:repeater-value',
3311 `:repeater-unit', `:warning-type', `:warning-value',
3312 `:warning-unit', `:begin', `:end' and `:post-blank' keywords.
3313 Otherwise, return nil.
3315 Assume point is at the beginning of the timestamp."
3334 date-start)
3345 raw-value)
3347 :repeater-type
3353 :repeater-unit
3362 :warning-unit
3365 year-start month-start day-start hour-start minute-start year-end
3366 month-end day-end hour-end minute-end)
3367 ;; Parse date-start.
3375 ;; Compute date-end. It can be provided directly in time-stamp,
3376 ;; or extracted from time range. Otherwise, it defaults to the
3377 ;; same values as date-start.
3387 :raw-value raw-value
3388 :year-start year-start
3389 :month-start month-start
3390 :day-start day-start
3391 :hour-start hour-start
3392 :minute-start minute-start
3393 :year-end year-end
3394 :month-end month-end
3395 :day-end day-end
3396 :hour-end hour-end
3397 :minute-end minute-end
3398 :begin begin
3399 :end end
3401 repeater-props
3402 warning-props))))))
3405 "Interpret TIMESTAMP object as Org syntax.
3406 CONTENTS is nil."
3425 ;; Build an Org timestamp string from TIME. ACTIVEP is
3426 ;; non-nil when time stamp is active. If WITH-TIME-P is
3427 ;; non-nil, add a time part. HOUR-END and MINUTE-END
3428 ;; specify a time range in the timestamp. REPEAT-STRING is
3429 ;; the repeater string, if any.
3433 org-time-stamp-formats)
3434 time)))
3440 nil nil ts)))
3445 " "
3446 s
3448 ;; Return value.
3449 ts)))
3461 build-ts-string
3480 0
3488 "--"
3500 ;;;; Underline
3503 "Parse underline object at point, if any.
3505 When at an underline object, return a list whose car is
3506 `underline' and cdr is a plist with `:begin', `:end',
3507 `:contents-begin' and `:contents-end' and `:post-blank' keywords.
3508 Otherwise, return nil.
3510 Assume point is at the first underscore marker."
3522 :end end
3523 :contents-begin contents-begin
3524 :contents-end contents-end
3528 "Interpret UNDERLINE object as Org syntax.
3529 CONTENTS is the contents of the object."
3533 ;;;; Verbatim
3536 "Parse verbatim object at point, if any.
3538 When at a verbatim object, return a list whose car is `verbatim'
3539 and cdr is a plist with `:value', `:begin', `:end' and
3540 `:post-blank' keywords. Otherwise, return nil.
3542 Assume point is at the first equal sign marker."
3553 :begin begin
3554 :end end
3558 "Interpret VERBATIM object as Org syntax.
3559 CONTENTS is nil."
3563 \f
3564 ;;; Parsing Element Starting At Point
3565 ;;
3566 ;; `org-element--current-element' is the core function of this section.
3567 ;; It returns the Lisp representation of the element starting at
3568 ;; point.
3569 ;;
3570 ;; `org-element--current-element' makes use of special modes. They
3571 ;; are activated for fixed element chaining (e.g., `plain-list' >
3572 ;; `item') or fixed conditional element chaining (e.g., `headline' >
3573 ;; `section'). Special modes are: `first-section', `item',
3574 ;; `node-property', `section' and `table-row'.
3577 "Parse the element starting at point.
3579 Return value is a list like (TYPE PROPS) where TYPE is the type
3580 of the element and PROPS a plist of properties associated to the
3581 element.
3583 Possible types are defined in `org-element-all-elements'.
3585 LIMIT bounds the search.
3587 Optional argument GRANULARITY determines the depth of the
3588 recursion. Allowed values are `headline', `greater-element',
3589 `element', `object' or nil. When it is broader than `object' (or
3590 nil), secondary values will not be parsed, since they only
3591 contain objects.
3593 Optional argument MODE, when non-nil, can be either
3594 `first-section', `section', `planning', `item', `node-property'
3595 and `table-row'.
3597 If STRUCTURE isn't provided but MODE is set to `item', it will be
3598 computed.
3600 This function assumes point is always at the beginning of the
3601 element it has to parse."
3604 ;; Determine if parsing depth allows for secondary strings
3605 ;; parsing. It only applies to elements referenced in
3606 ;; `org-element-secondary-value-alist'.
3609 ;; Item.
3612 ;; Table Row.
3614 ;; Node Property.
3616 ;; Headline.
3619 ;; Sections (must be checked after headline).
3624 limit)))
3625 ;; Planning.
3628 ;; Property drawer.
3632 ;; When not at bol, point is at the beginning of an item or
3633 ;; a footnote definition: next item is always a paragraph.
3635 ;; Clock.
3637 ;; Inlinetask.
3640 ;; From there, elements can have affiliated keywords.
3643 ;; Jumping over affiliated keywords put point off-limits.
3644 ;; Parse them as regular keywords.
3648 ;; LaTeX Environment.
3651 ;; Drawer and Property Drawer.
3654 ;; Fixed Width
3657 ;; Inline Comments, Blocks, Babel Calls, Dynamic Blocks and
3658 ;; Keywords.
3667 org-element-block-name-alist)))
3682 ;; Footnote Definition.
3685 ;; Horizontal Rule.
3688 ;; Diary Sexp.
3691 ;; Table.
3693 ;; List.
3696 limit affiliated
3698 ;; Default element: Paragraph.
3702 ;; Most elements can have affiliated keywords. When looking for an
3703 ;; element beginning, we want to move before them, as they belong to
3704 ;; that element, and, in the meantime, collect information they give
3705 ;; into appropriate properties. Hence the following function.
3708 "Collect affiliated keywords from point down to LIMIT.
3710 Return a list whose CAR is the position at the first of them and
3711 CDR a plist of keywords and values and move point to the
3712 beginning of the first line after them.
3714 As a special case, if element doesn't start at the beginning of
3715 the line (e.g., a paragraph starting an item), CAR is current
3716 position of point and CDR is nil."
3720 ;; RESTRICT is the list of objects allowed in parsed
3721 ;; keywords value.
3723 output)
3726 ;; Apply translation to RAW-KWD. From there, KWD is
3727 ;; the official keyword.
3729 org-element-keyword-translation-alist))
3730 raw-kwd))
3731 ;; Find main value for any keyword.
3737 ;; PARSEDP is non-nil when keyword should have its
3738 ;; value parsed.
3740 ;; If KWD is a dual keyword, find its secondary
3741 ;; value. Maybe parse it.
3748 ;; Attribute a property name to KWD.
3750 ;; Now set final shape for VALUE.
3756 ;; Attributes can always appear on multiple lines.
3759 ;; Eventually store the new value in OUTPUT.
3761 ;; Move to next keyword.
3763 ;; If affiliated keywords are orphaned: move back to first one.
3764 ;; They will be parsed as a paragraph.
3766 ;; Return value.
3770 \f
3771 ;;; The Org Parser
3772 ;;
3773 ;; The two major functions here are `org-element-parse-buffer', which
3774 ;; parses Org syntax inside the current buffer, taking into account
3775 ;; region, narrowing, or even visibility if specified, and
3776 ;; `org-element-parse-secondary-string', which parses objects within
3777 ;; a given string.
3778 ;;
3779 ;; The (almost) almighty `org-element-map' allows to apply a function
3780 ;; on elements or objects matching some type, and accumulate the
3781 ;; resulting values. In an export situation, it also skips unneeded
3782 ;; parts of the parse tree.
3785 "Recursively parse the buffer and return structure.
3786 If narrowing is in effect, only parse the visible part of the
3787 buffer.
3789 Optional argument GRANULARITY determines the depth of the
3790 recursion. It can be set to the following symbols:
3792 `headline' Only parse headlines.
3793 `greater-element' Don't recurse into greater elements excepted
3794 headlines and sections. Thus, elements
3795 parsed are the top-level ones.
3796 `element' Parse everything but objects and plain text.
3797 `object' Parse the complete buffer (default).
3799 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3800 elements.
3802 An element or an objects is represented as a list with the
3803 pattern (TYPE PROPERTIES CONTENTS), where :
3805 TYPE is a symbol describing the element or object. See
3806 `org-element-all-elements' and `org-element-all-objects' for an
3807 exhaustive list of such symbols. One can retrieve it with
3808 `org-element-type' function.
3810 PROPERTIES is the list of attributes attached to the element or
3811 object, as a plist. Although most of them are specific to the
3812 element or object type, all types share `:begin', `:end',
3813 `:post-blank' and `:parent' properties, which respectively
3814 refer to buffer position where the element or object starts,
3815 ends, the number of white spaces or blank lines after it, and
3816 the element or object containing it. Properties values can be
3817 obtained by using `org-element-property' function.
3819 CONTENTS is a list of elements, objects or raw strings
3820 contained in the current element or object, when applicable.
3821 One can access them with `org-element-contents' function.
3823 The Org buffer has `org-data' as type and nil as properties.
3824 `org-element-map' function can be used to find specific elements
3825 or objects within the parse tree.
3827 This function assumes that current major mode is `org-mode'."
3833 ;; Start in `first-section' mode so text before the first
3834 ;; headline belongs to a section.
3838 "Recursively parse objects in STRING and return structure.
3840 RESTRICTION is a symbol limiting the object types that will be
3841 looked after.
3843 Optional argument PARENT, when non-nil, is the element or object
3844 containing the secondary string. It is used to set correctly
3845 `:parent' property within the string."
3858 secondary))))
3862 "Map a function on selected elements or objects.
3864 DATA is a parse tree, an element, an object, a string, or a list
3865 of such constructs. TYPES is a symbol or list of symbols of
3866 elements or objects types (see `org-element-all-elements' and
3867 `org-element-all-objects' for a complete list of types). FUN is
3868 the function called on the matching element or object. It has to
3869 accept one argument: the element or object itself.
3871 When optional argument INFO is non-nil, it should be a plist
3872 holding export options. In that case, parts of the parse tree
3873 not exportable according to that property list will be skipped.
3875 When optional argument FIRST-MATCH is non-nil, stop at the first
3876 match for which FUN doesn't return nil, and return that value.
3878 Optional argument NO-RECURSION is a symbol or a list of symbols
3879 representing elements or objects types. `org-element-map' won't
3880 enter any recursive element or object whose type belongs to that
3881 list. Though, FUN can still be applied on them.
3883 When optional argument WITH-AFFILIATED is non-nil, FUN will also
3884 apply to matching objects within parsed affiliated keywords (see
3885 `org-element-parsed-keywords').
3887 Nil values returned from FUN do not appear in the results.
3890 Examples:
3891 ---------
3893 Assuming TREE is a variable containing an Org buffer parse tree,
3894 the following example will return a flat list of all `src-block'
3895 and `example-block' elements in it:
3897 \(org-element-map tree '(example-block src-block) 'identity)
3899 The following snippet will find the first headline with a level
3902 \(org-element-map tree 'headline
3903 \(lambda (hl)
3904 \(and (= (org-element-property :level hl) 1)
3906 \(org-element-property :begin hl)))
3907 nil t)
3909 The next example will return a flat list of all `plain-list' type
3910 elements in TREE that are not a sub-list themselves:
3912 \(org-element-map tree 'plain-list 'identity nil nil 'plain-list)
3914 Eventually, this example will return a flat list of all `bold'
3915 type objects containing a `latex-snippet' type object, even
3916 looking into captions:
3918 \(org-element-map tree 'bold
3919 \(lambda (b)
3920 \(and (org-element-map b 'latex-snippet 'identity nil t) b))
3921 nil nil nil t)"
3922 ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
3925 ;; Recursion depth is determined by --CATEGORY.
3932 ;; If one object is found, the function
3933 ;; has to recurse into every object.
3936 ;; If one regular element is found, the
3937 ;; function has to recurse, at least,
3938 ;; into every element it encounters.
3941 types)
3942 category)))
3943 ;; Compute properties for affiliated keywords if necessary.
3948 org-element-affiliated-keywords)))
3949 --acc
3950 --walk-tree
3954 ;; Recursively walk DATA. INFO, if non-nil, is a plist
3955 ;; holding contextual information.
3959 ;; Ignored element in an export context.
3961 ;; List of elements or objects.
3963 ;; Unconditionally enter parse trees.
3967 ;; Check if TYPE is matching among TYPES. If so,
3968 ;; apply FUN to --DATA and accumulate return value
3969 ;; into --ACC (or exit if FIRST-MATCH is non-nil).
3975 ;; If --DATA has a secondary string that can contain
3976 ;; objects with their type among TYPES, look into it.
3983 ;; If --DATA has any affiliated keywords and
3984 ;; WITH-AFFILIATED is non-nil, look for objects in
3985 ;; them.
3993 ;; Pay attention to the type of value.
3994 ;; Preserve order for multiple keywords.
4010 --affiliated-alist))
4011 ;; Determine if a recursion into --DATA is possible.
4013 ;; --TYPE is explicitly removed from recursion.
4015 ;; --DATA has no contents.
4017 ;; Looking for greater elements but --DATA is simply
4018 ;; an element or an object.
4021 ;; Looking for elements but --DATA is an object.
4024 ;; In any other case, map contents.
4028 ;; Return value in a proper order.
4032 ;; The following functions are internal parts of the parser.
4033 ;;
4034 ;; The first one, `org-element--parse-elements' acts at the element's
4035 ;; level.
4036 ;;
4037 ;; The second one, `org-element--parse-objects' applies on all objects
4038 ;; of a paragraph or a secondary string. It calls
4039 ;; `org-element--object-lex' to find the next object in the current
4040 ;; container.
4043 "Return next special mode according to TYPE, or nil.
4044 TYPE is a symbol representing the type of an element or object
4045 containing next element if PARENTP is non-nil, or before it
4046 otherwise. Modes can be either `first-section', `item',
4047 `node-property', `planning', `property-drawer', `section',
4048 `table-row' or nil."
4064 "Parse elements between BEG and END positions.
4066 MODE prioritizes some elements over the others. It can be set to
4067 `first-section', `section', `planning', `item', `node-property'
4068 or `table-row'.
4070 When value is `item', STRUCTURE will be used as the current list
4071 structure.
4073 GRANULARITY determines the depth of the recursion. See
4074 `org-element-parse-buffer' for more information.
4076 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
4077 elements.
4079 Elements are accumulated into ACC."
4082 ;; Visible only: skip invisible parts at the beginning of the
4083 ;; element.
4086 ;; When parsing only headlines, skip any text before first one.
4089 ;; Main loop start.
4091 ;; Find current element's type and parse it accordingly to
4092 ;; its category.
4094 end granularity mode structure))
4098 ;; Visible only: skip invisible parts between siblings.
4101 ;; Fill ELEMENT contents by side-effect.
4103 ;; If element has no contents, don't modify it.
4105 ;; Greater element: parse it between `contents-begin' and
4106 ;; `contents-end'. Make sure GRANULARITY allows the
4107 ;; recursion, or ELEMENT is a headline, in which case going
4108 ;; inside is mandatory, in order to get sub-level headings.
4116 ;; Possibly switch to a special mode.
4120 granularity visible-only element))
4121 ;; ELEMENT has contents. Parse objects inside, if
4122 ;; GRANULARITY allows it.
4128 ;; Update mode.
4130 ;; Return result.
4131 acc))
4137 ;; Sub/superscript.
4139 ;; Bold, code, italic, strike-through, underline and
4140 ;; verbatim.
4143 ;; Plain links.
4145 ;; Objects starting with "[": regular link, footnote
4146 ;; reference, statistics cookie, timestamp (inactive).
4148 ;; Objects starting with "@": export snippets.
4149 "@@"
4150 ;; Objects starting with "{": macro.
4151 "{{{"
4152 ;; Objects starting with "<" : timestamp (active,
4153 ;; diary), target, radio target and angular links.
4155 ;; Objects starting with "$": latex fragment.
4157 ;; Objects starting with "\": line break, entity,
4158 ;; latex fragment.
4160 ;; Objects starting with raw text: inline Babel
4161 ;; source block, inline Babel call.
4164 "Regexp possibly matching the beginning of an object.
4165 This regexp allows false positives. Dedicated parser (e.g.,
4166 `org-export-bold-parser') will take care of further filtering.
4167 Radio links are not matched by this regexp, as they are treated
4171 "Return next object in current buffer or nil.
4172 RESTRICTION is a list of object types, as symbols, that should be
4173 looked after. This function assumes that the buffer is narrowed
4174 to an appropriate container (e.g., a paragraph)."
4182 found)
4247 ;; This is probably a plain link.
4253 ;; Radio link.
4258 "Parse objects between BEG and END and return recursive structure.
4260 Objects are accumulated in ACC.
4262 RESTRICTION is a list of object successors which are allowed in
4263 the current object."
4271 ;; 1. Text before any object. Untabify it.
4276 acc
4280 ;; 2. Object...
4283 ;; Fill contents of NEXT-OBJECT by side-effect, if it has
4284 ;; a recursive type.
4292 ;; 3. Text after last object. Untabify it.
4296 acc
4300 ;; Result.
4301 acc)))
4304 \f
4305 ;;; Towards A Bijective Process
4306 ;;
4307 ;; The parse tree obtained with `org-element-parse-buffer' is really
4308 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
4309 ;; interpreted and expanded into a string with canonical Org syntax.
4310 ;; Hence `org-element-interpret-data'.
4311 ;;
4312 ;; The function relies internally on
4313 ;; `org-element--interpret-affiliated-keywords'.
4315 ;;;###autoload
4317 "Interpret DATA as Org syntax.
4319 DATA is a parse tree, an element, an object or a secondary string
4320 to interpret.
4322 Optional argument PSEUDO-OBJECTS is a list of symbols defining
4323 new types that should be treated as objects. An unknown type not
4324 belonging to this list is seen as a pseudo-element instead. Both
4325 pseudo-objects and pseudo-elements are transparent entities, i.e.
4326 only their contents are interpreted.
4328 Return Org syntax as a string."
4332 "Interpret DATA as Org syntax.
4334 DATA is a parse tree, an element, an object or a secondary string
4335 to interpret. PARENT is used for recursive calls. It contains
4336 the element or object containing data, or nil. PSEUDO-OBJECTS
4337 are list of symbols defining new element or object types.
4338 Unknown types that don't belong to this list are treated as
4339 pseudo-elements instead.
4341 Return Org syntax as a string."
4343 ;; Find interpreter for current object or element. If it
4344 ;; doesn't exist (e.g. this is a pseudo object or element),
4345 ;; return contents, if any.
4351 ;; Secondary string.
4357 ;; Full Org document.
4363 ;; Plain text: return it.
4365 ;; Element or object without contents.
4367 ;; Element or object with contents.
4370 ;; Recursively interpret contents.
4376 data
4377 ;; Fix indentation of elements containing
4378 ;; objects. We ignore `table-row' elements
4379 ;; as they are one line long anyway.
4381 data
4382 ;; When normalizing first paragraph of an
4383 ;; item or a footnote-definition, ignore
4384 ;; first line's indentation.
4391 ;; Build white spaces. If no `:post-blank' property is
4392 ;; specified, assume its value is 0.
4403 "Return ELEMENT's affiliated keywords as Org syntax.
4404 If there is no affiliated keyword, return the empty string."
4414 ": "
4417 value)
4425 ;; All attribute keywords can have multiple lines.
4431 ;; List all ELEMENT's properties matching an attribute line or an
4432 ;; affiliated keyword, but ignore translated keywords since they
4433 ;; cannot belong to the property list.
4440 org-element-keyword-translation-alist)))))
4441 collect prop)
4444 ;; Because interpretation of the parse tree must return the same
4445 ;; number of blank lines between elements and the same number of white
4446 ;; space after objects, some special care must be given to white
4447 ;; spaces.
4448 ;;
4449 ;; The first function, `org-element-normalize-string', ensures any
4450 ;; string different from the empty string will end with a single
4451 ;; newline character.
4452 ;;
4453 ;; The second function, `org-element-normalize-contents', removes
4454 ;; global indentation from the contents of the current element.
4457 "Ensure string S ends with a single newline character.
4459 If S isn't a string return it unchanged. If S is the empty
4460 string, return it. Otherwise, return a new string with a single
4461 newline character at its end."
4469 "Normalize plain text in ELEMENT's contents.
4471 ELEMENT must only contain plain text and objects.
4473 If optional argument IGNORE-FIRST is non-nil, ignore first line's
4474 indentation to compute maximal common indentation.
4476 Return the normalized element that is element with global
4477 indentation removed from its contents. The function assumes that
4478 indentation is not done with TAB characters."
4480 find-min-ind ; For byte-compiler.
4482 ;; Return minimal common indentation within BLOB. This is
4483 ;; done by walking recursively BLOB and updating MIN-IND
4484 ;; along the way. FIRST-FLAG is non-nil when the first
4485 ;; string hasn't been seen yet. It is required as this
4486 ;; string is the only one whose indentation doesn't happen
4487 ;; after a newline character.
4494 ;; An indentation of zero means no string will be
4495 ;; modified. Quit the process.
4505 ;; Find minimal indentation in ELEMENT.
4508 ;; Build ELEMENT back, replacing each string with the same
4509 ;; string minus common indentation.
4514 ;; Return BLOB with all its strings indentation
4515 ;; shortened from MIN-IND white spaces. FIRST-FLAG
4516 ;; is non-nil when the first string hasn't been seen
4517 ;; yet.
4532 org-element-recursive-objects)
4536 blob))))
4540 \f
4541 ;;; Cache
4542 ;;
4543 ;; Implement a caching mechanism for `org-element-at-point' and
4544 ;; `org-element-context', which see.
4545 ;;
4546 ;; A single public function is provided: `org-element-cache-reset'.
4547 ;;
4548 ;; Cache is enabled by default, but can be disabled globally with
4549 ;; `org-element-use-cache'. `org-element-cache-sync-idle-time',
4550 ;; org-element-cache-sync-duration' and `org-element-cache-sync-break'
4551 ;; can be tweaked to control caching behaviour.
4552 ;;
4553 ;; Internally, parsed elements are stored in an AVL tree,
4554 ;; `org-element--cache'. This tree is updated lazily: whenever
4555 ;; a change happens to the buffer, a synchronization request is
4556 ;; registered in `org-element--cache-sync-requests' (see
4557 ;; `org-element--cache-submit-request'). During idle time, requests
4558 ;; are processed by `org-element--cache-sync'. Synchronization also
4559 ;; happens when an element is required from the cache. In this case,
4560 ;; the process stops as soon as the needed element is up-to-date.
4561 ;;
4562 ;; A synchronization request can only apply on a synchronized part of
4563 ;; the cache. Therefore, the cache is updated at least to the
4564 ;; location where the new request applies. Thus, requests are ordered
4565 ;; from left to right and all elements starting before the first
4566 ;; request are correct. This property is used by functions like
4567 ;; `org-element--cache-find' to retrieve elements in the part of the
4568 ;; cache that can be trusted.
4569 ;;
4570 ;; A request applies to every element, starting from its original
4571 ;; location (or key, see below). When a request is processed, it
4572 ;; moves forward and may collide the next one. In this case, both
4573 ;; requests are merged into a new one that starts from that element.
4574 ;; As a consequence, the whole synchronization complexity does not
4575 ;; depend on the number of pending requests, but on the number of
4576 ;; elements the very first request will be applied on.
4577 ;;
4578 ;; Elements cannot be accessed through their beginning position, which
4579 ;; may or may not be up-to-date. Instead, each element in the tree is
4580 ;; associated to a key, obtained with `org-element--cache-key'. This
4581 ;; mechanism is robust enough to preserve total order among elements
4582 ;; even when the tree is only partially synchronized.
4583 ;;
4584 ;; Objects contained in an element are stored in a hash table,
4585 ;; `org-element--cache-objects'.
4589 "Non nil when Org parser should cache its results.
4596 "Maximum duration, as a time value, for a cache synchronization.
4597 If the synchronization is not over after this delay, the process
4598 pauses and resumes after `org-element-cache-sync-break'
4602 "Duration, as a time value, of the pause between synchronizations.
4606 ;;;; Data Structure
4609 "AVL tree used to cache elements.
4610 Each node of the tree contains an element. Comparison is done
4611 with `org-element--cache-compare'. This cache is used in
4615 "Hash table used as to cache objects.
4616 Key is an element, as returned by `org-element-at-point', and
4617 value is an alist where each association is:
4619 \(PARENT COMPLETEP . OBJECTS)
4621 where PARENT is an element or object, COMPLETEP is a boolean,
4622 non-nil when all direct children of parent are already cached and
4623 OBJECTS is a list of such children, as objects, from farthest to
4624 closest.
4627 contained within a paragraph
4631 If the paragraph is completely parsed, OBJECTS-DATA will be
4633 \((PARAGRAPH t BOLD-OBJECT ENTITY-OBJECT)
4634 \(BOLD-OBJECT t ENTITY-OBJECT))
4636 whereas in a partially parsed paragraph, it could be
4638 \((PARAGRAPH nil ENTITY-OBJECT))
4643 "List of pending synchronization requests.
4645 A request is a vector with the following pattern:
4647 \[NEXT BEG END OFFSET OUTREACH PARENT PHASE]
4649 Processing a synchronization request consists of three phases:
4651 0. Delete modified elements,
4652 1. Fill missing area in cache,
4653 2. Shift positions and re-parent elements after the changes.
4655 During phase 0, NEXT is the key of the first element to be
4656 removed, BEG and END is buffer position delimiting the
4657 modifications. Elements starting between them (inclusive) are
4658 removed and so are those contained within OUTREACH. PARENT, when
4659 non-nil, is the parent of the first element to be removed.
4661 During phase 1, NEXT is the key of the next known element in
4662 cache and BEG its beginning position. Parse buffer between that
4663 element and the one before it in order to determine the parent of
4664 the next element. Set PARENT to the element containing NEXT.
4666 During phase 2, NEXT is the key of the next element to shift in
4667 the parse tree. All elements starting from this one have their
4668 properties relatives to buffer positions shifted by integer
4669 OFFSET and, if they belong to element PARENT, are adopted by it.
4677 "Hash table used to store keys during synchronization.
4681 "Return a unique key for ELEMENT in cache tree.
4683 Keys are used to keep a total order among elements in the cache.
4684 Comparison is done with `org-element--cache-key-less-p'.
4686 When no synchronization is taking place, a key is simply the
4687 beginning position of the element, or that position plus one in
4688 the case of an first item (respectively row) in
4689 a list (respectively a table).
4691 During a synchronization, the key is the one the element had when
4692 the cache was synchronized for the last time. Elements added to
4693 cache during the synchronization get a new key generated with
4694 `org-element--cache-generate-key'.
4696 Such keys are stored in `org-element--cache-sync-keys'. The hash
4697 table is cleared once the synchronization is complete."
4700 ;; Increase beginning position of items (respectively
4701 ;; table rows) by one, so the first item can get
4702 ;; a different key from its parent list (respectively
4703 ;; table).
4706 begin)))
4709 key))))
4712 "Generate a key between LOWER and UPPER.
4714 LOWER and UPPER are integers or lists, possibly empty.
4716 If LOWER and UPPER are equals, return LOWER. Otherwise, return
4717 a unique key, as an integer or a list of integers, according to
4718 the following rules:
4720 - LOWER and UPPER are compared level-wise until values differ.
4722 - If, at a given level, LOWER and UPPER differ from more than
4723 2, the new key shares all the levels above with LOWER and
4724 gets a new level. Its value is the mean between LOWER and
4725 UPPER:
4727 \(1 2) + (1 4) --> (1 3)
4729 - If LOWER has no value to compare with, it is assumed that its
4730 value is `most-negative-fixnum'. E.g.,
4732 \(1 1) + (1 1 2)
4734 is equivalent to
4736 \(1 1 m) + (1 1 2)
4738 where m is `most-negative-fixnum'. Likewise, if UPPER is
4739 short of levels, the current value is `most-positive-fixnum'.
4741 - If they differ from only one, the new key inherits from
4742 current LOWER level and fork it at the next level. E.g.,
4744 \(2 1) + (3 3)
4746 is equivalent to
4748 \(2 1) + (2 M)
4750 where M is `most-positive-fixnum'.
4752 - If the key is only one level long, it is returned as an
4753 integer:
4755 \(1 2) + (3 2) --> 2
4757 When they are not equals, the function assumes that LOWER is
4758 lesser than UPPER, per `org-element--cache-key-less-p'."
4762 skip-upper key)
4773 ;; When at a given level, LOWER and UPPER differ from
4774 ;; 1, ignore UPPER altogether. Instead create a key
4775 ;; between LOWER and the greatest key with the same
4776 ;; prefix as LOWER so far.
4782 "Non-nil if key A is less than key B.
4783 A and B are either integers or lists of integers, as returned by
4784 `org-element--cache-key'."
4792 ;; If A is empty, either keys are equal (B is also empty) and
4793 ;; we return nil, or A is lesser than B (B is longer) and we
4794 ;; return a non-nil value.
4795 ;;
4796 ;; If A is not empty, B is necessarily empty and A is greater
4797 ;; than B (A is longer). Therefore, return nil.
4801 "Non-nil when element A is located before element B."
4806 "Return root value in cache.
4807 This function assumes `org-element--cache' is a valid AVL tree."
4811 ;;;; Tools
4814 "Non-nil when cache is active in current buffer."
4819 "Find element in cache starting at POS or before.
4821 POS refers to a buffer position.
4823 When optional argument SIDE is non-nil, the function checks for
4824 elements starting at or past POS instead. If SIDE is `both', the
4825 function returns a cons cell where car is the first element
4826 starting at or before POS and cdr the first element starting
4827 after POS.
4829 The function can only find elements in the synchronized part of
4830 the cache."
4834 lower upper)
4849 ;; We found an element in cache starting at POS. If `side'
4850 ;; is `both' we also want the next one in order to generate
4851 ;; a key in-between.
4852 ;;
4853 ;; If the element is the first row or item in a table or
4854 ;; a plain list, we always return the table or the plain
4855 ;; list.
4856 ;;
4857 ;; In any other case, we return the element found.
4866 lower parent
4867 upper parent)))))
4870 lower element
4871 upper element)))))
4878 "Store ELEMENT in current buffer's cache, if allowed.
4879 When optional argument DATA is non-nil, assume is it object data
4880 relative to ELEMENT and store it in the objects cache."
4884 ;; During synchronization, first build an appropriate key
4885 ;; for the new element so `avl-tree-enter' can insert it at
4886 ;; the right spot in the cache.
4895 org-element--cache-sync-keys)))
4897 ;; Headlines are not stored in cache, so objects in titles are
4898 ;; not stored either.
4903 "Remove ELEMENT from cache.
4904 Assume ELEMENT belongs to cache and that a cache is active."
4909 ;;;; Synchronization
4912 "Set idle timer for cache synchronization in BUFFER."
4919 org-element-cache-sync-idle-time))
4920 nil
4921 #'org-element--cache-sync
4922 buffer)))
4925 "Non-nil when synchronization process should be interrupted.
4926 TIME-LIMIT is a time value or nil."
4932 "Shift ELEMENT properties relative to buffer positions by OFFSET.
4934 Properties containing buffer positions are `:begin', `:end',
4935 `:contents-begin', `:contents-end' and `:structure'. When
4936 optional argument PROPS is a list of keywords, only shift
4937 properties provided in that list.
4939 Properties are modified by side-effect."
4941 ;; Shift `:structure' property for the first plain list only: it
4942 ;; is the only one that really matters and it prevents from
4943 ;; shifting it more than once.
4957 "Synchronize cache with recent modification in BUFFER.
4959 When optional argument THRESHOLD is non-nil, do the
4960 synchronization for all elements starting before or at threshold,
4961 then exit. Otherwise, synchronize cache for as long as
4962 `org-element-cache-sync-duration' or until Emacs leaves idle
4963 state.
4965 FUTURE-CHANGE, when non-nil, is a buffer position where changes
4966 not registered yet in the cache are going to happen. It is used
4967 in `org-element--cache-submit-request', where cache is partially
4968 updated before current modification are actually submitted."
4979 request
4981 threshold
4984 org-element-cache-sync-duration))
4985 future-change)
4986 ;; Request processed. Merge current and next offsets and
4987 ;; transfer ending position.
4993 ;; If more requests are awaiting, set idle timer accordingly.
4994 ;; Otherwise, reset keys.
5001 "Process synchronization REQUEST for all entries before NEXT.
5003 REQUEST is a vector, built by `org-element--cache-submit-request'.
5005 NEXT is a cache key, as returned by `org-element--cache-key'.
5007 When non-nil, THRESHOLD is a buffer position. Synchronization
5008 stops as soon as a shifted element begins after it.
5010 When non-nil, TIME-LIMIT is a time value. Synchronization stops
5011 after this time or when Emacs exits idle state.
5013 When non-nil, FUTURE-CHANGE is a buffer position where changes
5014 not registered yet in the cache are going to happen. See
5015 `org-element--cache-submit-request' for more information.
5017 Throw `interrupt' if the process stops before completing the
5018 request."
5021 ;; Phase 0.
5022 ;;
5023 ;; Delete all elements starting after BEG, but not after buffer
5024 ;; position END or past element with key NEXT.
5025 ;;
5026 ;; At each iteration, we start again at tree root since
5027 ;; a deletion modifies structure of the balanced tree.
5035 ;; Find first element in cache with key BEG or after it.
5045 data-key key
5048 data-key key
5049 node nil)))))
5058 up))
5064 ;; No element starting after modifications left in
5065 ;; cache: further processing is futile.
5068 ;; Phase 1.
5069 ;;
5070 ;; Phase 0 left a hole in the cache. Some elements after it
5071 ;; could have parents within. For example, in the following
5072 ;; buffer:
5073 ;;
5074 ;; - item
5075 ;;
5076 ;;
5077 ;; Paragraph1
5078 ;;
5079 ;; Paragraph2
5080 ;;
5081 ;; if we remove a blank line between "item" and "Paragraph1",
5082 ;; everything down to "Paragraph2" is removed from cache. But
5083 ;; the paragraph now belongs to the list, and its `:parent'
5084 ;; property no longer is accurate.
5085 ;;
5086 ;; Therefore we need to parse again elements in the hole, or at
5087 ;; least in its last section, so that we can re-parent
5088 ;; subsequent elements, during phase 2.
5089 ;;
5090 ;; Note that we only need to get the parent from the first
5091 ;; element in cache after the hole.
5092 ;;
5093 ;; When next key is lesser or equal to the current one, delegate
5094 ;; phase 1 processing to next request in order to preserve key
5095 ;; order among requests.
5103 ;; Next element will start at its beginning position plus
5104 ;; offset, since it hasn't been shifted yet. Therefore, LIMIT
5105 ;; contains the real beginning position of the first element to
5106 ;; shift and re-parent.
5110 ;; Changes are going to happen around this element and
5111 ;; they will trigger another phase 1 request. Skip the
5112 ;; current one.
5118 ;; Phase 2.
5119 ;;
5120 ;; Shift all elements starting from key START, but before NEXT, by
5121 ;; OFFSET, and re-parent them when appropriate.
5122 ;;
5123 ;; Elements are modified by side-effect so the tree structure
5124 ;; remains intact.
5125 ;;
5126 ;; Once THRESHOLD, if any, is reached, or once there is an input
5127 ;; pending, exit. Before leaving, the current synchronization
5128 ;; request is updated.
5135 exit-flag)
5136 ;; No re-parenting nor shifting planned: request is over.
5146 ;; We reached NEXT. Request is complete.
5148 ;; Handle interruption request. Update current request.
5153 ;; Shift element.
5156 ;; Shift associated objects data, if any.
5161 ;; Update PARENT and re-parent DATA, only when
5162 ;; necessary. Propagate new structures for lists.
5176 ;; Cache is up-to-date past THRESHOLD. Request
5177 ;; interruption.
5182 ;; We reached end of tree: synchronization complete.
5183 t)))
5186 "Parse elements in current section, down to POS.
5188 Start parsing from the closest between the last known element in
5189 cache or headline above. Return the smallest element containing
5190 POS.
5192 When optional argument SYNCP is non-nil, return the parent of the
5193 element containing POS instead. In that case, it is also
5194 possible to provide TIME-LIMIT, which is a time value specifying
5195 when the parsing should stop. The function throws `interrupt' if
5196 the process stopped before finding the expected result."
5203 element next mode)
5205 ;; Nothing in cache before point: start parsing from first
5206 ;; element following headline above, or first element in
5207 ;; buffer.
5214 ;; Cache returned exact match: return it.
5217 ;; There's a headline between cached value and POS: cached
5218 ;; value is invalid. Start parsing from first element
5219 ;; following the headline.
5226 ;; Check if CACHED or any of its ancestors contain point.
5227 ;;
5228 ;; If there is such an element, we inspect it in order to know
5229 ;; if we return it or if we need to parse its contents.
5230 ;; Otherwise, we just start parsing from current location,
5231 ;; which is right after the top-most element containing
5232 ;; CACHED.
5233 ;;
5234 ;; As a special case, if POS is at the end of the buffer, we
5235 ;; want to return the innermost element ending there.
5236 ;;
5237 ;; Also, if we find an ancestor and discover that we need to
5238 ;; parse its contents, make sure we don't start from
5239 ;; `:contents-begin', as we would otherwise go past CACHED
5240 ;; again. Instead, in that situation, we will resume parsing
5241 ;; from NEXT, which is located after CACHED or its higher
5242 ;; ancestor not containing point.
5254 ;; Parse successively each element until we reach POS.
5267 end 'element mode
5274 ;; Skip any element ending before point. Also skip
5275 ;; element ending at point (unless it is also the end of
5276 ;; buffer) since we're sure that another element begins
5277 ;; after it.
5281 ;; A non-greater element contains point: return it.
5284 ;; Otherwise, we have to decide if ELEMENT really
5285 ;; contains POS. In that case we start parsing from
5286 ;; contents' beginning.
5287 ;;
5288 ;; If POS is at contents' beginning but it is also at
5289 ;; the beginning of the first item in a list or a table.
5290 ;; In that case, we need to create an anchor for that
5291 ;; list or table, so return it.
5292 ;;
5293 ;; Also, if POS is at the end of the buffer, no element
5294 ;; can start after it, but more than one may end there.
5295 ;; Arbitrarily, we choose to return the innermost of
5296 ;; such elements.
5309 parent element
5310 end cend))))
5311 ;; Otherwise, return ELEMENT as it is the smallest
5312 ;; element containing POS.
5317 ;;;; Staging Buffer Changes
5323 ;; Blocks
5325 ;; LaTeX environments.
5327 ;; Drawers.
5330 "Regexp matching a sensitive line, structure wise.
5331 A sensitive line is a headline, inlinetask, block, drawer, or
5332 latex-environment boundary. When such a line is modified,
5333 structure changes in the document may propagate in the whole
5337 "Non-nil when a sensitive line is about to be changed.
5341 "Request extension of area going to be modified if needed.
5342 BEG and END are the beginning and end of the range of changed
5343 text. See `before-change-functions' for more information."
5353 'headline
5356 org-element--cache-sensitive-re bottom t)))))))))
5359 "Update buffer modifications for current buffer.
5360 BEG and END are the beginning and end of the range of changed
5361 text, and the length in bytes of the pre-change text replaced by
5362 that range. See `after-change-functions' for more information."
5370 ;; Determine if modified area needs to be extended, according
5371 ;; to both previous and current state. We make a special
5372 ;; case for headline editing: if a headline is modified but
5373 ;; not removed, do not extend.
5382 org-element--cache-sensitive-re bottom t))))
5383 ;; Effectively extend modified area.
5391 ;; Store synchronization request.
5394 ;; Activate a timer to process the request during idle time.
5398 "Return first element to remove from cache.
5400 BEG and END are buffer positions delimiting buffer modifications.
5401 OFFSET is the size of the changes.
5403 Returned element is usually the first element in cache containing
5404 any position between BEG and END. As an exception, greater
5405 elements around the changes that are robust to contents
5406 modifications are preserved and updated according to the
5407 changes."
5417 quote-block special-block))
5422 ;; UP is a robust greater element containing changes.
5423 ;; We only need to extend its ending boundaries.
5429 ;; We're at top level element containing ELEMENT: if it's
5430 ;; altered by buffer modifications, it is first element in
5431 ;; cache to be removed. Otherwise, that first element is the
5432 ;; following one.
5433 ;;
5434 ;; As a special case, do not remove BEFORE if it is a robust
5435 ;; container for current changes.
5437 before)))))
5440 "Submit a new cache synchronization request for current buffer.
5441 BEG and END are buffer positions delimiting the minimal area
5442 where cache data should be removed. OFFSET is the size of the
5443 change, as an integer."
5445 delete-to delete-from)
5450 ;; Current changes can be merged with first sync request: we
5451 ;; can save a partial cache synchronization.
5454 ;; If last change happened within area to be removed, extend
5455 ;; boundaries of robust parents, if any. Otherwise, find
5456 ;; first element to remove and update request accordingly.
5468 ;; Ensure cache is correct up to END. Also make sure that NEXT,
5469 ;; if any, is no longer a 0-phase request, thus ensuring that
5470 ;; phases are properly ordered. We need to provide OFFSET as
5471 ;; optional parameter since current modifications are not known
5472 ;; yet to the otherwise correct part of the cache (i.e, before
5473 ;; the first request).
5480 ;; When changes happen before the first known
5481 ;; element, re-parent and shift the rest of the
5482 ;; cache.
5484 ;; Otherwise, we find the first non robust
5485 ;; element containing END. All elements between
5486 ;; FIRST and this one are to be removed.
5487 ;;
5488 ;; Among them, some could be located outside the
5489 ;; synchronized part of the cache, in which case
5490 ;; comparing buffer positions to find them is
5491 ;; useless. Instead, we store the element
5492 ;; containing them in the request itself. All
5493 ;; its children will be removed.
5505 element up))
5508 org-element--cache-sync-requests)
5509 ;; No element to remove. No need to re-parent either.
5510 ;; Simply shift additional elements, if any, by OFFSET.
5515 ;;;; Public Functions
5517 ;;;###autoload
5519 "Reset cache in current buffer.
5520 When optional argument ALL is non-nil, reset cache in all Org
5521 buffers."
5539 ;;;###autoload
5541 "Refresh cache at position POS."
5548 \f
5549 ;;; The Toolbox
5550 ;;
5551 ;; The first move is to implement a way to obtain the smallest element
5552 ;; containing point. This is the job of `org-element-at-point'. It
5553 ;; basically jumps back to the beginning of section containing point
5554 ;; and proceed, one element after the other, with
5555 ;; `org-element--current-element' until the container is found. Note:
5556 ;; When using `org-element-at-point', secondary values are never
5557 ;; parsed since the function focuses on elements, not on objects.
5558 ;;
5559 ;; At a deeper level, `org-element-context' lists all elements and
5560 ;; objects containing point.
5561 ;;
5562 ;; `org-element-nested-p' and `org-element-swap-A-B' may be used
5563 ;; internally by navigation and manipulation tools.
5566 ;;;###autoload
5568 "Determine closest element around point.
5570 Return value is a list like (TYPE PROPS) where TYPE is the type
5571 of the element and PROPS a plist of properties associated to the
5572 element.
5574 Possible types are defined in `org-element-all-elements'.
5575 Properties depend on element or object type, but always include
5576 `:begin', `:end', `:parent' and `:post-blank' properties.
5578 As a special case, if point is at the very beginning of the first
5579 item in a list or sub-list, returned element will be that list
5580 instead of the item. Likewise, if point is at the beginning of
5581 the first row of a table, returned element will be the table
5582 instead of the first row.
5584 When point is at the end of the buffer, return the innermost
5585 element ending there."
5591 ;; Within blank lines at the beginning of buffer, return nil.
5593 ;; Within blank lines right after a headline, return that
5594 ;; headline.
5598 ;; Otherwise parse until we find element containing ORIGIN.
5605 ;;;###autoload
5607 "Return smallest element or object around point.
5609 Return value is a list like (TYPE PROPS) where TYPE is the type
5610 of the element or object and PROPS a plist of properties
5611 associated to it.
5613 Possible types are defined in `org-element-all-elements' and
5614 `org-element-all-objects'. Properties depend on element or
5615 object type, but always include `:begin', `:end', `:parent' and
5616 `:post-blank'.
5618 As a special case, if point is right after an object and not at
5619 the beginning of any other object, return that object.
5621 Optional argument ELEMENT, when non-nil, is the closest element
5622 containing point, as returned by `org-element-at-point'.
5623 Providing it allows for quicker computation."
5629 ;; If point is inside an element containing objects or
5630 ;; a secondary string, narrow buffer to the container and
5631 ;; proceed with parsing. Otherwise, return ELEMENT.
5633 ;; At a parsed affiliated keyword, check if we're inside main
5634 ;; or dual value.
5641 org-element-parsed-keywords))
5650 ;; Also change type to retrieve correct restrictions.
5652 ;; At an item, objects can only be located within tag, if any.
5662 ;; At an headline or inlinetask, objects are in title.
5669 ;; At a paragraph, a table-row or a verse block, objects are
5670 ;; located within their contents.
5674 ;; CBEG is nil for table rules.
5679 ;; At a parsed keyword, objects are located within value.
5682 org-element-document-properties))
5689 ;; At a planning line, if point is at a timestamp, return it,
5690 ;; otherwise, return element.
5698 ;; All other locations cannot contain objects: bail out.
5708 next object-data last)
5712 ;; When entering PARENT for the first time, get list
5713 ;; of objects within known so far. Store it in
5714 ;; OBJECT-DATA.
5719 ;; Find NEXT object for analysis.
5721 ;; If NEXT is non-nil, we already exhausted the
5722 ;; cache so we can parse buffer to find the object
5723 ;; after it.
5725 ;; Otherwise, check if cache can help us.
5736 ;; Cache contains the information needed.
5739 pos)
5741 pos)
5747 ;; If we have a new object to analyze, store it in
5748 ;; cache. Otherwise record that there is nothing
5749 ;; more to parse in this element at this depth.
5754 ;; Process NEXT, if any, in order to know if we need
5755 ;; to skip it, return it or move into it.
5762 ;; Skip objects ending before point. Also skip
5763 ;; objects ending at point unless it is also the
5764 ;; end of buffer, since we want to return the
5765 ;; innermost object.
5768 ;; For convenience, when object ends at POS,
5769 ;; without any space, store it in LAST, as we
5770 ;; will return it if no object starts here.
5774 ;; If POS is within a container object, move
5775 ;; into that object.
5779 ;; At contents' end, if there is no
5780 ;; space before point, also move into
5781 ;; object, for consistency with
5782 ;; convenience feature above.
5791 next nil
5792 object-data nil))
5793 ;; Otherwise, return NEXT.
5795 ;; Store results in cache, if applicable.
5799 "Non-nil when elements ELEM-A and ELEM-B are nested."
5808 "Swap elements ELEM-A and ELEM-B.
5809 Assume ELEM-B is after ELEM-A in the buffer. Leave point at the
5810 end of ELEM-A."
5812 ;; There are two special cases when an element doesn't start at bol:
5813 ;; the first paragraph in an item or in a footnote definition.
5815 ;; Only a paragraph without any affiliated keyword can be moved at
5816 ;; ELEM-A position in such a situation. Note that the case of
5817 ;; a footnote definition is impossible: it cannot contain two
5818 ;; paragraphs in a row because it cannot contain a blank line.
5824 ;; In a special situation, ELEM-A will have no indentation. We'll
5825 ;; give it ELEM-B's (which will in, in turn, have no indentation).
5839 ;; Store overlays responsible for visibility status. We
5840 ;; also need to store their boundaries as they will be
5841 ;; removed from buffer.
5848 ;; Get contents.
5856 ;; Restore ex ELEM-A overlays.
5865 ;; Restore ex ELEM-B overlays.
5873 "Remove maximum common indentation in string S and return it.
5874 When optional argument N is a positive integer, remove exactly
5875 that much characters from indentation, if possible, or return
5876 S as-is otherwise. Unlike to `org-remove-indentation', this
5877 function doesn't call `untabify' on S."
5882 ;; Find maximum common indentation, if not specified.
5890 min-ind)))
5892 ;; Remove exactly N indentation, but give up if not possible.
5905 ;; Local variables:
5906 ;; generated-autoload-file: "org-loaddefs.el"
5907 ;; End:
5909 ;;; org-element.el ends here