| blob | 1c617c99aaa4f4de38dd6130ac2d204cf0e291da |
1 ;;; org-element.el --- Parser And Applications for Org syntax
3 ;; Copyright (C) 2012-2013 Free Software Foundation, Inc.
5 ;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
6 ;; Keywords: outlines, hypermedia, calendar, wp
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
23 ;;; Commentary:
24 ;;
25 ;; Org syntax can be divided into three categories: "Greater
26 ;; elements", "Elements" and "Objects".
27 ;;
28 ;; Elements are related to the structure of the document. Indeed, all
29 ;; elements are a cover for the document: each position within belongs
30 ;; to at least one element.
31 ;;
32 ;; An element always starts and ends at the beginning of a line. With
33 ;; a few exceptions (`clock', `headline', `inlinetask', `item',
34 ;; `planning', `node-property', `quote-section' `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', `quote-section',
52 ;; `src-block', `table', `table-row' and `verse-block'. Among them,
53 ;; `paragraph' and `verse-block' types can contain Org objects and
54 ;; plain text.
55 ;;
56 ;; Objects are related to document's contents. Some of them are
57 ;; recursive. Associated types are of the following: `bold', `code',
58 ;; `entity', `export-snippet', `footnote-reference',
59 ;; `inline-babel-call', `inline-src-block', `italic',
60 ;; `latex-fragment', `line-break', `link', `macro', `radio-target',
61 ;; `statistics-cookie', `strike-through', `subscript', `superscript',
62 ;; `table-cell', `target', `timestamp', `underline' and `verbatim'.
63 ;;
64 ;; Some elements also have special properties whose value can hold
65 ;; objects themselves (i.e. an item tag or a headline name). Such
66 ;; values are called "secondary strings". Any object belongs to
67 ;; either an element or a secondary string.
68 ;;
69 ;; Notwithstanding affiliated keywords, each greater element, element
70 ;; and object has a fixed set of properties attached to it. Among
71 ;; them, four are shared by all types: `:begin' and `:end', which
72 ;; refer to the beginning and ending buffer positions of the
73 ;; considered element or object, `:post-blank', which holds the number
74 ;; of blank lines, or white spaces, at its end and `:parent' which
75 ;; refers to the element or object containing it. Greater elements,
76 ;; elements and objects containing objects will also have
77 ;; `:contents-begin' and `:contents-end' properties to delimit
78 ;; contents. Eventually, greater elements and elements accepting
79 ;; affiliated keywords will have a `:post-affiliated' property,
80 ;; referring to the buffer position after all such keywords.
81 ;;
82 ;; At the lowest level, a `:parent' property is also attached to any
83 ;; string, as a text property.
84 ;;
85 ;; Lisp-wise, an element or an object can be represented as a list.
86 ;; It follows the pattern (TYPE PROPERTIES CONTENTS), where:
87 ;; TYPE is a symbol describing the Org element or object.
88 ;; PROPERTIES is the property list attached to it. See docstring of
89 ;; appropriate parsing function to get an exhaustive
90 ;; list.
91 ;; CONTENTS is a list of elements, objects or raw strings contained
92 ;; in the current element or object, when applicable.
93 ;;
94 ;; An Org buffer is a nested list of such elements and objects, whose
95 ;; type is `org-data' and properties is nil.
96 ;;
97 ;; The first part of this file defines Org syntax, while the second
98 ;; one provide accessors and setters functions.
99 ;;
100 ;; The next part implements a parser and an interpreter for each
101 ;; element and object type in Org syntax.
102 ;;
103 ;; The following part creates a fully recursive buffer parser. It
104 ;; also provides a tool to map a function to elements or objects
105 ;; matching some criteria in the parse tree. Functions of interest
106 ;; are `org-element-parse-buffer', `org-element-map' and, to a lesser
107 ;; extent, `org-element-parse-secondary-string'.
108 ;;
109 ;; The penultimate part is the cradle of an interpreter for the
110 ;; obtained parse tree: `org-element-interpret-data'.
111 ;;
112 ;; The library ends by furnishing `org-element-at-point' function, and
113 ;; a way to give information about document structure around point
114 ;; with `org-element-context'. A simple cache mechanism is also
115 ;; provided for these functions.
118 ;;; 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, drawers (any type),
148 ;; fixed-width areas and keywords. Note: this is only an
149 ;; indication and need some thorough check.
151 ;; Horizontal rules.
153 ;; LaTeX environments.
155 ;; Planning and Clock lines.
157 org-deadline-string
158 org-closed-string
159 org-clock-string))
161 ;; Lists.
168 "Regexp to separate paragraphs in an Org buffer.
170 is not sufficient to know if point is at a paragraph ending. See
175 dynamic-block example-block export-block fixed-width
176 footnote-definition headline horizontal-rule inlinetask item
177 keyword latex-environment node-property paragraph plain-list
178 planning property-drawer quote-block quote-section section
179 special-block src-block table table-row verse-block)
184 item plain-list property-drawer quote-block section
185 special-block table)
190 latex-or-entity line-break link macro plain-link radio-target
191 statistics-cookie sub/superscript table-cell target
192 text-markup timestamp)
201 "Alist of translations between object type and successor name.
202 Sharing the same successor comes handy when, for example, the
207 inline-src-block italic line-break latex-fragment link macro
208 radio-target statistics-cookie strike-through subscript superscript
209 table-cell target timestamp underline verbatim)
214 table-cell underline)
224 "Alist between block names and the associated parsing function.
225 Names must be uppercase. Any block whose name has no association
231 Only these types can accept search options and an explicit
237 "List of affiliated keywords as strings.
243 ;; Regular affiliated keywords.
246 "Regexp matching any affiliated keyword.
248 Keyword name is put in match group 1. Moreover, if keyword
249 belongs to `org-element-dual-keywords', put the dual value in
250 match group 2.
258 "Alist of usual translations for keywords.
259 The key is the old name and the value the new one. The property
263 "List of affiliated keywords that can occur more than once in an element.
265 Their value will be consed into a list of strings, which will be
266 returned as the value of the property.
268 This list is checked after translations have been applied. See
269 `org-element-keyword-translation-alist'.
275 "List of affiliated keywords whose value can be parsed.
277 Their value will be stored as a secondary string: a list of
278 strings and objects.
280 This list is checked after translations have been applied. See
284 "List of affiliated keywords which can have a secondary value.
286 In Org syntax, they can be written with optional square brackets
287 before the colons. For example, RESULTS keyword can be
288 associated to a hash value with the following:
290 #+RESULTS[hash-string]: some-source
292 This list is checked after translations have been applied. See
296 "List of properties associated to the whole document.
297 Any keyword in this list will have its value parsed and stored as
311 ;; Ignore all links excepted plain links in a link description.
312 ;; Also ignore radio-targets and line breaks.
316 ;; Remove any variable object from radio target as it would
317 ;; prevent it from being properly recognized.
322 ;; Ignore inline babel call and inline src block as formulas are
323 ;; possible. Also ignore line breaks and statistics cookies.
329 "Alist of objects restrictions.
331 CAR is an element or object type containing objects and CDR is
332 a list of successors that will be called within an element or
333 object of such type.
335 For example, in a `radio-target' object, one can only find
336 entities, latex-fragments, subscript and superscript.
338 This alist also applies to secondary string. For example, an
339 `headline' type element doesn't directly contain objects, but
350 "List of buffer-local variables used when parsing objects.
351 These variables are copied to the temporary buffer created by
355 \f
356 ;;; Accessors and Setters
357 ;;
358 ;; Provide four accessors: `org-element-type', `org-element-property'
359 ;; `org-element-contents' and `org-element-restriction'.
360 ;;
361 ;; Setter functions allow to modify elements by side effect. There is
362 ;; `org-element-put-property', `org-element-set-contents',
363 ;; `org-element-set-element' and `org-element-adopt-element'. Note
364 ;; that `org-element-set-element' and `org-element-adopt-elements' are
365 ;; higher level functions since also update `:parent' property.
368 "Return type of ELEMENT.
370 The function returns the type of the element or object provided.
371 It can also return the following special value:
372 `plain-text' for a string
373 `org-data' for a complete document
374 nil in any other case."
380 "Extract the value from the PROPERTY of an ELEMENT."
385 "Extract contents from an ELEMENT."
391 "Return restriction associated to ELEMENT.
392 ELEMENT can be an element, an object or a symbol representing an
393 element or object type."
395 org-element-object-restrictions)))
398 "In ELEMENT set PROPERTY to VALUE.
399 Return modified element."
402 element))
405 "Set ELEMENT contents to CONTENTS.
406 Return modified element."
413 "Replace element or object OLD with element or object NEW.
414 The function takes care of setting `:parent' property for NEW."
415 ;; Since OLD is going to be changed into NEW by side-effect, first
416 ;; make sure that every element or object within NEW has OLD as
417 ;; parent.
420 ;; Transfer contents.
422 ;; Ensure NEW has same parent as OLD, then overwrite OLD properties
423 ;; with NEW's.
426 ;; Transfer type.
430 "Append elements to the contents of another element.
432 PARENT is an element or object. CHILDREN can be elements,
433 objects, or a strings.
435 The function takes care of setting `:parent' property for CHILD.
436 Return parent element."
437 ;; Link every child to PARENT. If PARENT is nil, it is a secondary
438 ;; string: parent is the list itself.
441 children)
442 ;; Add CHILDREN at the end of PARENT contents.
445 parent
447 ;; Return modified PARENT element.
451 \f
452 ;;; Greater elements
453 ;;
454 ;; For each greater element type, we define a parser and an
455 ;; interpreter.
456 ;;
457 ;; A parser returns the element or object as the list described above.
458 ;; Most of them accepts no argument. Though, exceptions exist. Hence
459 ;; every element containing a secondary string (see
460 ;; `org-element-secondary-value-alist') will accept an optional
461 ;; argument to toggle parsing of that secondary string. Moreover,
462 ;; `item' parser requires current list's structure as its first
463 ;; element.
464 ;;
465 ;; An interpreter accepts two arguments: the list representation of
466 ;; the element or object, and its contents. The latter may be nil,
467 ;; depending on the element or object considered. It returns the
468 ;; appropriate Org syntax, as a string.
469 ;;
470 ;; Parsing functions must follow the naming convention:
471 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
472 ;; defined in `org-element-greater-elements'.
473 ;;
474 ;; Similarly, interpreting functions must follow the naming
475 ;; convention: org-element-TYPE-interpreter.
476 ;;
477 ;; With the exception of `headline' and `item' types, greater elements
478 ;; cannot contain other greater elements of their own type.
479 ;;
480 ;; Beside implementing a parser and an interpreter, adding a new
481 ;; greater element requires to tweak `org-element--current-element'.
482 ;; Moreover, the newly defined type must be added to both
483 ;; `org-element-all-elements' and `org-element-greater-elements'.
486 ;;;; Center Block
489 "Parse a center block.
491 LIMIT bounds the search. AFFILIATED is a list of which CAR is
492 the buffer position at the beginning of the first affiliated
493 keyword and CDR is a plist of affiliated keywords along with
494 their value.
496 Return a list whose CAR is `center-block' and CDR is a plist
497 containing `:begin', `:end', `:contents-begin', `:contents-end',
498 `:post-blank' and `:post-affiliated' keywords.
500 Assume point is at the beginning of the block."
504 ;; Incomplete block: parse it as a paragraph.
509 ;; Empty blocks have no contents.
523 :end end
524 :contents-begin contents-begin
525 :contents-end contents-end
531 "Interpret CENTER-BLOCK element as Org syntax.
532 CONTENTS is the contents of the element."
536 ;;;; Drawer
539 "Parse a drawer.
541 LIMIT bounds the search. AFFILIATED is a list of which CAR is
542 the buffer position at the beginning of the first affiliated
543 keyword and CDR is a plist of affiliated keywords along with
544 their value.
546 Return a list whose CAR is `drawer' and CDR is a plist containing
547 `:drawer-name', `:begin', `:end', `:contents-begin',
548 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
550 Assume point is at beginning of drawer."
553 ;; Incomplete drawer: parse it as a paragraph.
561 ;; Empty drawers have no contents.
575 :end end
576 :drawer-name name
577 :contents-begin contents-begin
578 :contents-end contents-end
584 "Interpret DRAWER element as Org syntax.
585 CONTENTS is the contents of the element."
588 contents))
591 ;;;; Dynamic Block
594 "Parse a dynamic block.
596 LIMIT bounds the search. AFFILIATED is a list of which CAR is
597 the buffer position at the beginning of the first affiliated
598 keyword and CDR is a plist of affiliated keywords along with
599 their value.
601 Return a list whose CAR is `dynamic-block' and CDR is a plist
602 containing `:block-name', `:begin', `:end', `:contents-begin',
603 `:contents-end', `:arguments', `:post-blank' and
604 `:post-affiliated' keywords.
606 Assume point is at beginning of dynamic block."
610 ;; Incomplete block: parse it as a paragraph.
619 ;; Empty blocks have no contents.
633 :end end
634 :block-name name
635 :arguments arguments
636 :contents-begin contents-begin
637 :contents-end contents-end
643 "Interpret DYNAMIC-BLOCK element as Org syntax.
644 CONTENTS is the contents of the element."
649 contents))
652 ;;;; Footnote Definition
655 "Parse a footnote definition.
657 LIMIT bounds the search. AFFILIATED is a list of which CAR is
658 the buffer position at the beginning of the first affiliated
659 keyword and CDR is a plist of affiliated keywords along with
660 their value.
662 Return a list whose CAR is `footnote-definition' and CDR is
663 a plist containing `:label', `:begin' `:end', `:contents-begin',
664 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
666 Assume point is at the beginning of the footnote definition."
695 :begin begin
696 :end end
697 :contents-begin contents-begin
698 :contents-end contents-end
704 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
705 CONTENTS is the contents of the footnote-definition."
707 " "
708 contents))
711 ;;;; Headline
714 "Parse a headline.
716 Return a list whose CAR is `headline' and CDR is a plist
717 containing `:raw-value', `:title', `:alt-title', `:begin',
718 `:end', `:pre-blank', `:contents-begin' and `:contents-end',
719 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
720 `:scheduled', `:deadline', `:closed', `:quotedp', `:archivedp',
721 `:commentedp' and `:footnote-section-p' keywords.
723 The plist also contains any property set in the property drawer,
724 with its name in upper cases and colons added at the
725 beginning (i.e. `:CUSTOM_ID').
727 When RAW-SECONDARY-P is non-nil, headline's title will not be
728 parsed as a secondary string, but as a plain string instead.
730 Assume point is at beginning of the headline."
743 raw-value)))
747 raw-value)))
751 ;; Upcase property names. It avoids confusion between
752 ;; properties obtained through property drawer and default
753 ;; properties from the parser (e.g. `:end' and :END:)
763 plist))
765 ;; Read time properties on the line below the headline.
771 org-keyword-time-not-clock-regexp end t)
781 plist))))
793 ;; Clean RAW-VALUE from any quote or comment string.
801 ""
802 raw-value))))
803 ;; Clean TAGS from archive tag, if any.
809 :begin begin
810 :end end
811 :pre-blank
814 :contents-begin contents-begin
815 :contents-end contents-end
816 :level level
818 :tags tags
819 :todo-keyword todo
820 :todo-type todo-type
826 end)
827 :footnote-section-p footnote-section-p
828 :archivedp archivedp
829 :commentedp commentedp
831 time-props
832 standard-props))))
836 headline :alt-title
841 headline :title
847 "Interpret HEADLINE element as Org syntax.
848 CONTENTS is the contents of the element."
875 ;; Align tags.
883 ? )
884 tags))
888 tags))))
890 contents)))
893 ;;;; Inlinetask
896 "Parse an inline task.
898 Return a list whose CAR is `inlinetask' and CDR is a plist
899 containing `:title', `:begin', `:end', `:contents-begin' and
900 `:contents-end', `:level', `:priority', `:raw-value', `:tags',
901 `:todo-keyword', `:todo-type', `:scheduled', `:deadline',
902 `:closed' and `:post-blank' keywords.
904 The plist also contains any property set in the property drawer,
905 with its name in upper cases and colons added at the
906 beginning (i.e. `:CUSTOM_ID').
908 When optional argument RAW-SECONDARY-P is non-nil, inline-task's
909 title will not be parsed as a secondary string, but as a plain
910 string instead.
912 Assume point is at beginning of the inline task."
922 ;; Upcase property names. It avoids confusion between
923 ;; properties obtained through property drawer and default
924 ;; properties from the parser (e.g. `:end' and :END:)
934 plist))
936 ;; Read time properties on the line below the inlinetask
937 ;; opening string.
943 org-keyword-time-not-clock-regexp end t)
953 plist))))
972 :begin begin
973 :end end
974 :contents-begin contents-begin
975 :contents-end contents-end
978 :tags tags
979 :todo-keyword todo
980 :todo-type todo-type
982 time-props
983 standard-props))))
985 inlinetask :title
988 raw-value
990 inlinetask))))))
993 "Interpret INLINETASK element as Org syntax.
994 CONTENTS is the contents of inlinetask."
1009 ;; Align tags.
1017 ? )
1018 tags))
1022 tags))))
1023 ;; Prefer degenerate inlinetasks when there are no
1024 ;; contents.
1027 contents
1031 ;;;; Item
1034 "Parse an item.
1036 STRUCT is the structure of the plain list.
1038 Return a list whose CAR is `item' and CDR is a plist containing
1039 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
1040 `:checkbox', `:counter', `:tag', `:structure' and `:post-blank'
1041 keywords.
1043 When optional argument RAW-SECONDARY-P is non-nil, item's tag, if
1044 any, will not be parsed as a secondary string, but as a plain
1045 string instead.
1047 Assume point is at the beginning of the item."
1071 ;; Ignore tags in un-ordered lists: they are just
1072 ;; a part of item's body.
1078 ;; If first line isn't empty, contents really start
1079 ;; at the text after item's meta-data.
1088 :begin begin
1089 :end end
1090 ;; CONTENTS-BEGIN and CONTENTS-END may be
1091 ;; mixed up in the case of an empty item
1092 ;; separated from the next by a blank line.
1093 ;; Thus ensure the former is always the
1094 ;; smallest.
1097 :checkbox checkbox
1098 :counter counter
1099 :structure struct
1102 item :tag
1110 "Interpret ITEM element as Org syntax.
1111 CONTENTS is the contents of the element."
1121 ;; Compute indentation.
1126 ;; Indent contents.
1128 bullet
1142 ;;;; Plain List
1145 ;; Return structure of list at point. Internal function. See
1146 ;; `org-list-struct' for details.
1151 items struct)
1156 ;; At limit: end all items.
1165 ;; At list end: end all items.
1170 ;; At a new item: end previous sibling.
1182 ind
1183 bullet
1186 ;; Description tag.
1190 ;; Ending position, unknown so far.
1191 nil)))
1192 items))
1194 ;; Skip empty lines.
1196 ;; Skip inline tasks and blank lines along the way.
1203 ;; At some text line. Check if it ends any previous item.
1215 ;; Skip blocks (any type) and drawers contents.
1221 limit t)))
1227 "Parse a plain list.
1229 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1230 the buffer position at the beginning of the first affiliated
1231 keyword and CDR is a plist of affiliated keywords along with
1232 their value. STRUCTURE is the structure of the plain list being
1233 parsed.
1235 Return a list whose CAR is `plain-list' and CDR is a plist
1236 containing `:type', `:begin', `:end', `:contents-begin' and
1237 `:contents-end', `:structure', `:post-blank' and
1238 `:post-affiliated' keywords.
1240 Assume point is at the beginning of the list."
1253 ;; Return value.
1257 :begin begin
1258 :end end
1259 :contents-begin contents-begin
1260 :contents-end contents-end
1261 :structure struct
1267 "Interpret PLAIN-LIST element as Org syntax.
1268 CONTENTS is the contents of the element."
1276 ;;;; Property Drawer
1279 "Parse a property drawer.
1281 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1282 the buffer position at the beginning of the first affiliated
1283 keyword and CDR is a plist of affiliated keywords along with
1284 their value.
1286 Return a list whose CAR is `property-drawer' and CDR is a plist
1287 containing `:begin', `:end', `:contents-begin', `:contents-end',
1288 `:post-blank' and `:post-affiliated' keywords.
1290 Assume point is at the beginning of the property drawer."
1295 ;; Incomplete drawer: parse it as a paragraph.
1314 :end end
1315 :contents-begin contents-begin
1316 :contents-end contents-end
1322 "Interpret PROPERTY-DRAWER element as Org syntax.
1323 CONTENTS is the properties within the drawer."
1327 ;;;; Quote Block
1330 "Parse a quote block.
1332 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1333 the buffer position at the beginning of the first affiliated
1334 keyword and CDR is a plist of affiliated keywords along with
1335 their value.
1337 Return a list whose CAR is `quote-block' and CDR is a plist
1338 containing `:begin', `:end', `:contents-begin', `:contents-end',
1339 `:post-blank' and `:post-affiliated' keywords.
1341 Assume point is at the beginning of the block."
1345 ;; Incomplete block: parse it as a paragraph.
1351 ;; Empty blocks have no contents.
1365 :end end
1366 :contents-begin contents-begin
1367 :contents-end contents-end
1373 "Interpret QUOTE-BLOCK element as Org syntax.
1374 CONTENTS is the contents of the element."
1378 ;;;; Section
1381 "Parse a section.
1383 LIMIT bounds the search.
1385 Return a list whose CAR is `section' and CDR is a plist
1386 containing `:begin', `:end', `:contents-begin', `contents-end'
1387 and `:post-blank' keywords."
1389 ;; Beginning of section is the beginning of the first non-blank
1390 ;; line after previous headline.
1399 :end end
1400 :contents-begin begin
1401 :contents-end pos-before-blank
1405 "Interpret SECTION element as Org syntax.
1406 CONTENTS is the contents of the element."
1407 contents)
1410 ;;;; Special Block
1413 "Parse a special block.
1415 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1416 the buffer position at the beginning of the first affiliated
1417 keyword and CDR is a plist of affiliated keywords along with
1418 their value.
1420 Return a list whose CAR is `special-block' and CDR is a plist
1421 containing `:type', `:begin', `:end', `:contents-begin',
1422 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
1424 Assume point is at the beginning of the block."
1431 limit t)))
1432 ;; Incomplete block: parse it as a paragraph.
1438 ;; Empty blocks have no contents.
1452 :begin begin
1453 :end end
1454 :contents-begin contents-begin
1455 :contents-end contents-end
1461 "Interpret SPECIAL-BLOCK element as Org syntax.
1462 CONTENTS is the contents of the element."
1467 \f
1468 ;;; Elements
1469 ;;
1470 ;; For each element, a parser and an interpreter are also defined.
1471 ;; Both follow the same naming convention used for greater elements.
1472 ;;
1473 ;; Also, as for greater elements, adding a new element type is done
1474 ;; through the following steps: implement a parser and an interpreter,
1475 ;; tweak `org-element--current-element' so that it recognizes the new
1476 ;; type and add that new type to `org-element-all-elements'.
1477 ;;
1478 ;; As a special case, when the newly defined type is a block type,
1479 ;; `org-element-block-name-alist' has to be modified accordingly.
1482 ;;;; Babel Call
1485 "Parse a babel call.
1487 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1488 the buffer position at the beginning of the first affiliated
1489 keyword and CDR is a plist of affiliated keywords along with
1490 their value.
1492 Return a list whose CAR is `babel-call' and CDR is a plist
1493 containing `:begin', `:end', `:value', `:post-blank' and
1494 `:post-affiliated' as keywords."
1509 :end end
1510 :value value
1516 "Interpret BABEL-CALL element as Org syntax.
1517 CONTENTS is nil."
1521 ;;;; Clock
1524 "Parse a clock.
1526 LIMIT bounds the search.
1528 Return a list whose CAR is `clock' and CDR is a plist containing
1529 `:status', `:value', `:time', `:begin', `:end' and `:post-blank'
1530 as keywords."
1550 :value value
1551 :duration duration
1552 :begin begin
1553 :end end
1557 "Interpret CLOCK element as Org syntax.
1558 CONTENTS is nil."
1566 "%2s:%02s"
1570 ;;;; Comment
1573 "Parse a comment.
1575 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1576 the buffer position at the beginning of the first affiliated
1577 keyword and CDR is a plist of affiliated keywords along with
1578 their value.
1580 Return a list whose CAR is `comment' and CDR is a plist
1581 containing `:begin', `:end', `:value', `:post-blank',
1582 `:post-affiliated' keywords.
1584 Assume point is at comment beginning."
1593 ;; Get comments ending.
1596 ;; Accumulate lines without leading hash and first
1597 ;; whitespace.
1612 :end end
1613 :value value
1619 "Interpret COMMENT element as Org syntax.
1620 CONTENTS is nil."
1624 ;;;; Comment Block
1627 "Parse an export block.
1629 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1630 the buffer position at the beginning of the first affiliated
1631 keyword and CDR is a plist of affiliated keywords along with
1632 their value.
1634 Return a list whose CAR is `comment-block' and CDR is a plist
1635 containing `:begin', `:end', `:value', `:post-blank' and
1636 `:post-affiliated' keywords.
1638 Assume point is at comment block beginning."
1642 ;; Incomplete block: parse it as a paragraph.
1656 contents-begin contents-end)))
1660 :end end
1661 :value value
1667 "Interpret COMMENT-BLOCK element as Org syntax.
1668 CONTENTS is nil."
1673 ;;;; Diary Sexp
1676 "Parse a diary sexp.
1678 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1679 the buffer position at the beginning of the first affiliated
1680 keyword and CDR is a plist of affiliated keywords along with
1681 their value.
1683 Return a list whose CAR is `diary-sexp' and CDR is a plist
1684 containing `:begin', `:end', `:value', `:post-blank' and
1685 `:post-affiliated' keywords."
1698 :begin begin
1699 :end end
1705 "Interpret DIARY-SEXP as Org syntax.
1706 CONTENTS is nil."
1710 ;;;; Example Block
1713 "Parse an example block.
1715 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1716 the buffer position at the beginning of the first affiliated
1717 keyword and CDR is a plist of affiliated keywords along with
1718 their value.
1720 Return a list whose CAR is `example-block' and CDR is a plist
1721 containing `:begin', `:end', `:number-lines', `:preserve-indent',
1722 `:retain-labels', `:use-labels', `:label-fmt', `:switches',
1723 `:value', `:post-blank' and `:post-affiliated' keywords."
1727 ;; Incomplete block: parse it as a paragraph.
1735 ;; Switches analysis
1742 ;; Should labels be retained in (or stripped from) example
1743 ;; blocks?
1748 ;; What should code-references use - labels or
1749 ;; line-numbers?
1758 ;; Standard block parsing.
1766 contents-begin contents-end))
1767 block-ind))
1777 :end end
1778 :value value
1779 :switches switches
1780 :number-lines number-lines
1781 :preserve-indent preserve-indent
1782 :retain-labels retain-labels
1783 :use-labels use-labels
1784 :label-fmt label-fmt
1790 "Interpret EXAMPLE-BLOCK element as Org syntax.
1791 CONTENTS is nil."
1798 value
1803 ;;;; Export Block
1806 "Parse an export block.
1808 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1809 the buffer position at the beginning of the first affiliated
1810 keyword and CDR is a plist of affiliated keywords along with
1811 their value.
1813 Return a list whose CAR is `export-block' and CDR is a plist
1814 containing `:begin', `:end', `:type', `:value', `:post-blank' and
1815 `:post-affiliated' keywords.
1817 Assume point is at export-block beginning."
1824 ;; Incomplete block: parse it as a paragraph.
1838 contents-end)))
1842 :end end
1843 :type type
1844 :value value
1850 "Interpret EXPORT-BLOCK element as Org syntax.
1851 CONTENTS is nil."
1858 ;;;; Fixed-width
1861 "Parse a fixed-width section.
1863 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1864 the buffer position at the beginning of the first affiliated
1865 keyword and CDR is a plist of affiliated keywords along with
1866 their value.
1868 Return a list whose CAR is `fixed-width' and CDR is a plist
1869 containing `:begin', `:end', `:value', `:post-blank' and
1870 `:post-affiliated' keywords.
1872 Assume point is at the beginning of the fixed-width area."
1876 value
1881 ;; Accumulate text without starting colons.
1895 :end end
1896 :value value
1902 "Interpret FIXED-WIDTH element as Org syntax.
1903 CONTENTS is nil."
1911 ;;;; Horizontal Rule
1914 "Parse an horizontal rule.
1916 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1917 the buffer position at the beginning of the first affiliated
1918 keyword and CDR is a plist of affiliated keywords along with
1919 their value.
1921 Return a list whose CAR is `horizontal-rule' and CDR is a plist
1922 containing `:begin', `:end', `:post-blank' and `:post-affiliated'
1923 keywords."
1934 :end end
1940 "Interpret HORIZONTAL-RULE element as Org syntax.
1941 CONTENTS is nil."
1945 ;;;; Keyword
1948 "Parse a keyword at point.
1950 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1951 the buffer position at the beginning of the first affiliated
1952 keyword and CDR is a plist of affiliated keywords along with
1953 their value.
1955 Return a list whose CAR is `keyword' and CDR is a plist
1956 containing `:key', `:value', `:begin', `:end', `:post-blank' and
1957 `:post-affiliated' keywords."
1972 :value value
1973 :begin begin
1974 :end end
1980 "Interpret KEYWORD element as Org syntax.
1981 CONTENTS is nil."
1987 ;;;; Latex Environment
1990 "Parse a LaTeX environment.
1992 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1993 the buffer position at the beginning of the first affiliated
1994 keyword and CDR is a plist of affiliated keywords along with
1995 their value.
1997 Return a list whose CAR is `latex-environment' and CDR is a plist
1998 containing `:begin', `:end', `:value', `:post-blank' and
1999 `:post-affiliated' keywords.
2001 Assume point is at the beginning of the latex environment."
2008 limit t))
2009 ;; Incomplete latex environment: parse it as a paragraph.
2020 :end end
2021 :value value
2027 "Interpret LATEX-ENVIRONMENT element as Org syntax.
2028 CONTENTS is nil."
2032 ;;;; Node Property
2035 "Parse a node-property at point.
2037 LIMIT bounds the search.
2039 Return a list whose CAR is `node-property' and CDR is a plist
2040 containing `:key', `:value', `:begin', `:end' and `:post-blank'
2041 keywords."
2053 :value value
2054 :begin begin
2055 :end end
2059 "Interpret NODE-PROPERTY element as Org syntax.
2060 CONTENTS is nil."
2066 ;;;; Paragraph
2069 "Parse a paragraph.
2071 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2072 the buffer position at the beginning of the first affiliated
2073 keyword and CDR is a plist of affiliated keywords along with
2074 their value.
2076 Return a list whose CAR is `paragraph' and CDR is a plist
2077 containing `:begin', `:end', `:contents-begin' and
2078 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
2080 Assume point is at the beginning of the paragraph."
2089 limit
2090 ;; A matching `org-element-paragraph-separate' is not
2091 ;; necessarily the end of the paragraph. In
2092 ;; particular, lines starting with # or : as a first
2093 ;; non-space character are ambiguous. We have check
2094 ;; if they are valid Org syntax (i.e. not an
2095 ;; incomplete keyword).
2099 ;; There's no ambiguity for other symbols or
2100 ;; empty lines: stop here.
2102 ;; Stop at valid fixed-width areas.
2104 ;; Stop at drawers.
2109 ;; Stop at valid comments.
2111 ;; Stop at valid dynamic blocks.
2116 ;; Stop at valid blocks.
2123 limit t)))
2124 ;; Stop at valid latex environments.
2132 limit t)))
2133 ;; Stop at valid keywords.
2135 ;; Skip everything else.
2153 :end end
2154 :contents-begin contents-begin
2155 :contents-end contents-end
2161 "Interpret PARAGRAPH element as Org syntax.
2162 CONTENTS is the contents of the element."
2163 contents)
2166 ;;;; Planning
2169 "Parse a planning.
2171 LIMIT bounds the search.
2173 Return a list whose CAR is `planning' and CDR is a plist
2174 containing `:closed', `:deadline', `:scheduled', `:begin', `:end'
2175 and `:post-blank' keywords."
2185 closed deadline scheduled)
2197 :deadline deadline
2198 :scheduled scheduled
2199 :begin begin
2200 :end end
2204 "Interpret PLANNING element as Org syntax.
2205 CONTENTS is nil."
2207 'identity
2224 ;;;; Quote Section
2227 "Parse a quote section.
2229 LIMIT bounds the search.
2231 Return a list whose CAR is `quote-section' and CDR is a plist
2232 containing `:begin', `:end', `:value' and `:post-blank' keywords.
2234 Assume point is at beginning of the section."
2245 :end end
2246 :value value
2250 "Interpret QUOTE-SECTION element as Org syntax.
2251 CONTENTS is nil."
2255 ;;;; Src Block
2258 "Parse a src block.
2260 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2261 the buffer position at the beginning of the first affiliated
2262 keyword and CDR is a plist of affiliated keywords along with
2263 their value.
2265 Return a list whose CAR is `src-block' and CDR is a plist
2266 containing `:language', `:switches', `:parameters', `:begin',
2267 `:end', `:number-lines', `:retain-labels', `:use-labels',
2268 `:label-fmt', `:preserve-indent', `:value', `:post-blank' and
2269 `:post-affiliated' keywords.
2271 Assume point is at the beginning of the block."
2274 limit t)))
2275 ;; Incomplete block: parse it as a paragraph.
2281 ;; Get language as a string.
2290 ;; Get switches.
2292 ;; Get parameters.
2294 ;; Switches analysis
2305 ;; Should labels be retained in (or stripped from)
2306 ;; src blocks?
2311 ;; What should code-references use - labels or
2312 ;; line-numbers?
2317 ;; Indentation.
2319 ;; Retrieve code.
2324 block-ind))
2328 ;; Get position after ending blank lines.
2339 :begin begin
2340 :end end
2341 :number-lines number-lines
2342 :preserve-indent preserve-indent
2343 :retain-labels retain-labels
2344 :use-labels use-labels
2345 :label-fmt label-fmt
2346 :value value
2352 "Interpret SRC-BLOCK element as Org syntax.
2353 CONTENTS is nil."
2362 val)
2376 ;;;; Table
2379 "Parse a table at point.
2381 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2382 the buffer position at the beginning of the first affiliated
2383 keyword and CDR is a plist of affiliated keywords along with
2384 their value.
2386 Return a list whose CAR is `table' and CDR is a plist containing
2387 `:begin', `:end', `:tblfm', `:type', `:contents-begin',
2388 `:contents-end', `:value', `:post-blank' and `:post-affiliated'
2389 keywords.
2391 Assume point is at the beginning of the table."
2405 acc))
2413 :end end
2414 :type type
2415 :tblfm tblfm
2416 ;; Only `org' tables have contents. `table.el' tables
2417 ;; use a `:value' property to store raw table as
2418 ;; a string.
2423 table-begin table-end))
2429 "Interpret TABLE element as Org syntax.
2430 CONTENTS is nil."
2441 ;;;; Table Row
2444 "Parse table row at point.
2446 LIMIT bounds the search.
2448 Return a list whose CAR is `table-row' and CDR is a plist
2449 containing `:begin', `:end', `:contents-begin', `:contents-end',
2450 `:type' and `:post-blank' keywords."
2454 ;; A table rule has no contents. In that case, ensure
2455 ;; CONTENTS-BEGIN matches CONTENTS-END.
2467 :begin begin
2468 :end end
2469 :contents-begin contents-begin
2470 :contents-end contents-end
2474 "Interpret TABLE-ROW element as Org syntax.
2475 CONTENTS is the contents of the table row."
2480 ;;;; Verse Block
2483 "Parse a verse block.
2485 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2486 the buffer position at the beginning of the first affiliated
2487 keyword and CDR is a plist of affiliated keywords along with
2488 their value.
2490 Return a list whose CAR is `verse-block' and CDR is a plist
2491 containing `:begin', `:end', `:contents-begin', `:contents-end',
2492 `:post-blank' and `:post-affiliated' keywords.
2494 Assume point is at beginning of the block."
2498 ;; Incomplete block: parse it as a paragraph.
2514 :end end
2515 :contents-begin contents-begin
2516 :contents-end contents-end
2522 "Interpret VERSE-BLOCK element as Org syntax.
2523 CONTENTS is verse block contents."
2527 \f
2528 ;;; Objects
2529 ;;
2530 ;; Unlike to elements, interstices can be found between objects.
2531 ;; That's why, along with the parser, successor functions are provided
2532 ;; for each object. Some objects share the same successor (i.e. `code'
2533 ;; and `verbatim' objects).
2534 ;;
2535 ;; A successor must accept a single argument bounding the search. It
2536 ;; will return either a cons cell whose CAR is the object's type, as
2537 ;; a symbol, and CDR the position of its next occurrence, or nil.
2538 ;;
2539 ;; Successors follow the naming convention:
2540 ;; org-element-NAME-successor, where NAME is the name of the
2541 ;; successor, as defined in `org-element-all-successors'.
2542 ;;
2543 ;; Some object types (i.e. `italic') are recursive. Restrictions on
2544 ;; object types they can contain will be specified in
2545 ;; `org-element-object-restrictions'.
2546 ;;
2547 ;; Adding a new type of object is simple. Implement a successor,
2548 ;; a parser, and an interpreter for it, all following the naming
2549 ;; convention. Register type in `org-element-all-objects' and
2550 ;; successor in `org-element-all-successors'. Maybe tweak
2551 ;; restrictions about it, and that's it.
2554 ;;;; Bold
2557 "Parse bold object at point.
2559 Return a list whose CAR is `bold' and CDR is a plist with
2560 `:begin', `:end', `:contents-begin' and `:contents-end' and
2561 `:post-blank' keywords.
2563 Assume point is at the first star marker."
2575 :end end
2576 :contents-begin contents-begin
2577 :contents-end contents-end
2581 "Interpret BOLD object as Org syntax.
2582 CONTENTS is the contents of the object."
2586 "Search for the next text-markup object.
2588 Return value is a cons cell whose CAR is a symbol among `bold',
2589 `italic', `underline', `strike-through', `code' and `verbatim'
2590 and CDR is beginning position."
2606 ;;;; Code
2609 "Parse code object at point.
2611 Return a list whose CAR is `code' and CDR is a plist with
2612 `:value', `:begin', `:end' and `:post-blank' keywords.
2614 Assume point is at the first tilde marker."
2625 :begin begin
2626 :end end
2630 "Interpret CODE object as Org syntax.
2631 CONTENTS is nil."
2635 ;;;; Entity
2638 "Parse entity at point.
2640 Return a list whose CAR is `entity' and CDR a plist with
2641 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
2642 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
2643 keywords.
2645 Assume point is at the beginning of the entity."
2647 (looking-at "\\\\\\(there4\\|sup[123]\\|frac[13][24]\\|[a-zA-Z]+\\)\\($\\|{}\\|[^[:alpha:]]\\)")
2663 :begin begin
2664 :end end
2665 :use-brackets-p bracketsp
2669 "Interpret ENTITY object as Org syntax.
2670 CONTENTS is nil."
2676 "Search for the next latex-fragment or entity object.
2678 Return value is a cons cell whose CAR is `entity' or
2679 `latex-fragment' and CDR is beginning position."
2683 ;; ENTITY-RE matches both LaTeX commands and Org entities.
2690 ;; Determine if it's a real entity or a LaTeX command.
2693 ;; No entity nor command: point is at a LaTeX fragment.
2694 ;; Determine its type to get the correct beginning position.
2703 ;;;; Export Snippet
2706 "Parse export snippet at point.
2708 Return a list whose CAR is `export-snippet' and CDR a plist with
2709 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
2710 keywords.
2712 Assume point is at the beginning of the snippet."
2724 :value value
2725 :begin begin
2726 :end end
2730 "Interpret EXPORT-SNIPPET object as Org syntax.
2731 CONTENTS is nil."
2737 "Search for the next export-snippet object.
2739 Return value is a cons cell whose CAR is `export-snippet' and CDR
2740 its beginning position."
2749 ;;;; Footnote Reference
2752 "Parse footnote reference at point.
2754 Return a list whose CAR is `footnote-reference' and CDR a plist
2755 with `:label', `:type', `:inline-definition', `:begin', `:end'
2756 and `:post-blank' as keywords."
2778 :type type
2779 :begin begin
2780 :end end
2783 footnote-reference :inline-definition
2788 footnote-reference))))))
2791 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
2792 CONTENTS is nil."
2802 "Search for the next footnote-reference object.
2804 Return value is a cons cell whose CAR is `footnote-reference' and
2805 CDR is beginning position."
2819 ;;;; Inline Babel Call
2822 "Parse inline babel call at point.
2824 Return a list whose CAR is `inline-babel-call' and CDR a plist
2825 with `:begin', `:end', `:value' and `:post-blank' as keywords.
2827 Assume point is at the beginning of the babel call."
2839 :end end
2840 :value value
2844 "Interpret INLINE-BABEL-CALL object as Org syntax.
2845 CONTENTS is nil."
2849 "Search for the next inline-babel-call object.
2851 Return value is a cons cell whose CAR is `inline-babel-call' and
2852 CDR is beginning position."
2854 ;; Use a simplified version of
2855 ;; `org-babel-inline-lob-one-liner-regexp'.
2858 nil t)
2862 ;;;; Inline Src Block
2865 "Parse inline source block at point.
2867 Return a list whose CAR is `inline-src-block' and CDR a plist
2868 with `:begin', `:end', `:language', `:value', `:parameters' and
2869 `:post-blank' as keywords.
2871 Assume point is at the beginning of the inline src block."
2884 :value value
2885 :parameters parameters
2886 :begin begin
2887 :end end
2891 "Interpret INLINE-SRC-BLOCK object as Org syntax.
2892 CONTENTS is nil."
2897 language
2899 body)))
2902 "Search for the next inline-babel-call element.
2904 Return value is a cons cell whose CAR is `inline-babel-call' and
2905 CDR is beginning position."
2911 ;;;; Italic
2914 "Parse italic object at point.
2916 Return a list whose CAR is `italic' and CDR is a plist with
2917 `:begin', `:end', `:contents-begin' and `:contents-end' and
2918 `:post-blank' keywords.
2920 Assume point is at the first slash marker."
2932 :end end
2933 :contents-begin contents-begin
2934 :contents-end contents-end
2938 "Interpret ITALIC object as Org syntax.
2939 CONTENTS is the contents of the object."
2943 ;;;; Latex Fragment
2946 "Parse LaTeX fragment at point.
2948 Return a list whose CAR is `latex-fragment' and CDR a plist with
2949 `:value', `:begin', `:end', and `:post-blank' as keywords.
2951 Assume point is at the beginning of the LaTeX fragment."
2964 ;; None found: it's a macro.
2973 :begin begin
2974 :end end
2978 "Interpret LATEX-FRAGMENT object as Org syntax.
2979 CONTENTS is nil."
2982 ;;;; Line Break
2985 "Parse line break at point.
2987 Return a list whose CAR is `line-break', and CDR a plist with
2988 `:begin', `:end' and `:post-blank' keywords.
2990 Assume point is at the beginning of the line break."
2997 "Interpret LINE-BREAK object as Org syntax.
2998 CONTENTS is nil."
3002 "Search for the next line-break object.
3004 Return value is a cons cell whose CAR is `line-break' and CDR is
3005 beginning position."
3009 ;; A line break can only happen on a non-empty line.
3014 ;;;; Link
3017 "Parse link at point.
3019 Return a list whose CAR is `link' and CDR a plist with `:type',
3020 `:path', `:raw-link', `:application', `:search-option', `:begin',
3021 `:end', `:contents-begin', `:contents-end' and `:post-blank' as
3022 keywords.
3024 Assume point is at the beginning of the link."
3027 end contents-begin contents-end link-end post-blank path type
3028 raw-link link search-option application)
3030 ;; Type 1: Text targeted from a radio target.
3035 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
3040 ;; RAW-LINK is the original link. Expand any
3041 ;; abbreviation in it.
3045 ;; Determine TYPE of link and set PATH accordingly.
3047 ;; File type.
3051 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
3054 ;; Id type: PATH is the id.
3057 ;; Code-ref type: PATH is the name of the reference.
3060 ;; Custom-id type: PATH is the name of the custom id.
3063 ;; Fuzzy type: Internal link either matches a target, an
3064 ;; headline name or nothing. PATH is the target or
3065 ;; headline's name.
3067 ;; Type 3: Plain link, i.e. http://orgmode.org
3073 ;; Type 4: Angular link, i.e. <http://orgmode.org>
3080 ;; In any case, deduce end point after trailing white space from
3081 ;; LINK-END variable.
3084 ;; Extract search option and opening application out of
3085 ;; "file"-type links.
3087 ;; Application.
3092 ;; Extract search option from PATH.
3096 ;; Make sure TYPE always reports "file".
3100 :path path
3102 :application application
3103 :search-option search-option
3104 :begin begin
3105 :end end
3106 :contents-begin contents-begin
3107 :contents-end contents-end
3111 "Interpret LINK object as Org syntax.
3112 CONTENTS is the contents of the object, or nil."
3117 raw-link
3121 "Search for the next link object.
3123 Return value is a cons cell whose CAR is `link' and CDR is
3124 beginning position."
3133 "Search for the next plain link object.
3135 Return value is a cons cell whose CAR is `link' and CDR is
3136 beginning position."
3141 ;;;; Macro
3144 "Parse macro at point.
3146 Return a list whose CAR is `macro' and CDR a plist with `:key',
3147 `:args', `:begin', `:end', `:value' and `:post-blank' as
3148 keywords.
3150 Assume point is at the macro."
3161 ;; Do not use `org-split-string' since empty
3162 ;; strings are meaningful here.
3170 args nil t)
3174 :value value
3175 :args args
3176 :begin begin
3177 :end end
3181 "Interpret MACRO object as Org syntax.
3182 CONTENTS is nil."
3186 "Search for the next macro object.
3188 Return value is cons cell whose CAR is `macro' and CDR is
3189 beginning position."
3193 nil t)
3197 ;;;; Radio-target
3200 "Parse radio target at point.
3202 Return a list whose CAR is `radio-target' and CDR a plist with
3203 `:begin', `:end', `:contents-begin', `:contents-end', `:value'
3204 and `:post-blank' as keywords.
3206 Assume point is at the radio target."
3218 :end end
3219 :contents-begin contents-begin
3220 :contents-end contents-end
3221 :post-blank post-blank
3225 "Interpret TARGET object as Org syntax.
3226 CONTENTS is the contents of the object."
3230 "Search for the next radio-target object.
3232 Return value is a cons cell whose CAR is `radio-target' and CDR
3233 is beginning position."
3239 ;;;; Statistics Cookie
3242 "Parse statistics cookie at point.
3244 Return a list whose CAR is `statistics-cookie', and CDR a plist
3245 with `:begin', `:end', `:value' and `:post-blank' keywords.
3247 Assume point is at the beginning of the statistics-cookie."
3258 :end end
3259 :value value
3263 "Interpret STATISTICS-COOKIE object as Org syntax.
3264 CONTENTS is nil."
3268 "Search for the next statistics cookie object.
3270 Return value is a cons cell whose CAR is `statistics-cookie' and
3271 CDR is beginning position."
3277 ;;;; Strike-Through
3280 "Parse strike-through object at point.
3282 Return a list whose CAR is `strike-through' and CDR is a plist
3283 with `:begin', `:end', `:contents-begin' and `:contents-end' and
3284 `:post-blank' keywords.
3286 Assume point is at the first plus sign marker."
3298 :end end
3299 :contents-begin contents-begin
3300 :contents-end contents-end
3304 "Interpret STRIKE-THROUGH object as Org syntax.
3305 CONTENTS is the contents of the object."
3309 ;;;; Subscript
3312 "Parse subscript at point.
3314 Return a list whose CAR is `subscript' and CDR a plist with
3315 `:begin', `:end', `:contents-begin', `:contents-end',
3316 `:use-brackets-p' and `:post-blank' as keywords.
3318 Assume point is at the underscore."
3322 t
3333 :end end
3334 :use-brackets-p bracketsp
3335 :contents-begin contents-begin
3336 :contents-end contents-end
3340 "Interpret SUBSCRIPT object as Org syntax.
3341 CONTENTS is the contents of the object."
3344 contents))
3347 "Search for the next sub/superscript object.
3349 Return value is a cons cell whose CAR is either `subscript' or
3350 `superscript' and CDR is beginning position."
3358 ;;;; Superscript
3361 "Parse superscript at point.
3363 Return a list whose CAR is `superscript' and CDR a plist with
3364 `:begin', `:end', `:contents-begin', `:contents-end',
3365 `:use-brackets-p' and `:post-blank' as keywords.
3367 Assume point is at the caret."
3381 :end end
3382 :use-brackets-p bracketsp
3383 :contents-begin contents-begin
3384 :contents-end contents-end
3388 "Interpret SUPERSCRIPT object as Org syntax.
3389 CONTENTS is the contents of the object."
3392 contents))
3395 ;;;; Table Cell
3398 "Parse table cell at point.
3400 Return a list whose CAR is `table-cell' and CDR is a plist
3401 containing `:begin', `:end', `:contents-begin', `:contents-end'
3402 and `:post-blank' keywords."
3410 :end end
3411 :contents-begin contents-begin
3412 :contents-end contents-end
3416 "Interpret TABLE-CELL element as Org syntax.
3417 CONTENTS is the contents of the cell, or nil."
3421 "Search for the next table-cell object.
3423 Return value is a cons cell whose CAR is `table-cell' and CDR is
3424 beginning position."
3428 ;;;; Target
3431 "Parse target at point.
3433 Return a list whose CAR is `target' and CDR a plist with
3434 `:begin', `:end', `:value' and `:post-blank' as keywords.
3436 Assume point is at the target."
3446 :end end
3447 :value value
3451 "Interpret TARGET object as Org syntax.
3452 CONTENTS is nil."
3456 "Search for the next target object.
3458 Return value is a cons cell whose CAR is `target' and CDR is
3459 beginning position."
3465 ;;;; Timestamp
3468 "Parse time stamp at point.
3470 Return a list whose CAR is `timestamp', and CDR a plist with
3471 `:type', `:raw-value', `:year-start', `:month-start',
3472 `:day-start', `:hour-start', `:minute-start', `:year-end',
3473 `:month-end', `:day-end', `:hour-end', `:minute-end',
3474 `:repeater-type', `:repeater-value', `:repeater-unit',
3475 `:warning-type', `:warning-value', `:warning-unit', `:begin',
3476 `:end', `:value' and `:post-blank' keywords.
3478 Assume point is at the beginning of the timestamp."
3496 date-start)
3507 raw-value)
3509 :repeater-type
3515 :repeater-unit
3524 :warning-unit
3527 year-start month-start day-start hour-start minute-start year-end
3528 month-end day-end hour-end minute-end)
3529 ;; Parse date-start.
3537 ;; Compute date-end. It can be provided directly in time-stamp,
3538 ;; or extracted from time range. Otherwise, it defaults to the
3539 ;; same values as date-start.
3549 :raw-value raw-value
3550 :year-start year-start
3551 :month-start month-start
3552 :day-start day-start
3553 :hour-start hour-start
3554 :minute-start minute-start
3555 :year-end year-end
3556 :month-end month-end
3557 :day-end day-end
3558 :hour-end hour-end
3559 :minute-end minute-end
3560 :begin begin
3561 :end end
3563 repeater-props
3564 warning-props)))))
3567 "Interpret TIMESTAMP object as Org syntax.
3568 CONTENTS is nil."
3569 ;; Use `:raw-value' if specified.
3571 ;; Otherwise, build timestamp string.
3590 ;; Build an Org timestamp string from TIME. ACTIVEP is
3591 ;; non-nil when time stamp is active. If WITH-TIME-P is
3592 ;; non-nil, add a time part. HOUR-END and MINUTE-END
3593 ;; specify a time range in the timestamp. REPEAT-STRING
3594 ;; is the repeater string, if any.
3598 org-time-stamp-formats)
3599 time)))
3605 nil nil ts)))
3610 " "
3611 s
3613 ;; Return value.
3614 ts)))
3626 build-ts-string
3645 0
3653 "--"
3665 "Search for the next timestamp object.
3667 Return value is a cons cell whose CAR is `timestamp' and CDR is
3668 beginning position."
3676 nil t)
3680 ;;;; Underline
3683 "Parse underline object at point.
3685 Return a list whose CAR is `underline' and CDR is a plist with
3686 `:begin', `:end', `:contents-begin' and `:contents-end' and
3687 `:post-blank' keywords.
3689 Assume point is at the first underscore marker."
3701 :end end
3702 :contents-begin contents-begin
3703 :contents-end contents-end
3707 "Interpret UNDERLINE object as Org syntax.
3708 CONTENTS is the contents of the object."
3712 ;;;; Verbatim
3715 "Parse verbatim object at point.
3717 Return a list whose CAR is `verbatim' and CDR is a plist with
3718 `:value', `:begin', `:end' and `:post-blank' keywords.
3720 Assume point is at the first equal sign marker."
3731 :begin begin
3732 :end end
3736 "Interpret VERBATIM object as Org syntax.
3737 CONTENTS is nil."
3741 \f
3742 ;;; Parsing Element Starting At Point
3743 ;;
3744 ;; `org-element--current-element' is the core function of this section.
3745 ;; It returns the Lisp representation of the element starting at
3746 ;; point.
3747 ;;
3748 ;; `org-element--current-element' makes use of special modes. They
3749 ;; are activated for fixed element chaining (i.e. `plain-list' >
3750 ;; `item') or fixed conditional element chaining (i.e. `headline' >
3751 ;; `section'). Special modes are: `first-section', `item',
3752 ;; `node-property', `quote-section', `section' and `table-row'.
3756 "Parse the element starting at point.
3758 Return value is a list like (TYPE PROPS) where TYPE is the type
3759 of the element and PROPS a plist of properties associated to the
3760 element.
3762 Possible types are defined in `org-element-all-elements'.
3764 LIMIT bounds the search.
3766 Optional argument GRANULARITY determines the depth of the
3767 recursion. Allowed values are `headline', `greater-element',
3768 `element', `object' or nil. When it is broader than `object' (or
3769 nil), secondary values will not be parsed, since they only
3770 contain objects.
3772 Optional argument SPECIAL, when non-nil, can be either
3773 `first-section', `item', `node-property', `quote-section',
3774 `section', and `table-row'.
3776 If STRUCTURE isn't provided but SPECIAL is set to `item', it will
3777 be computed.
3779 This function assumes point is always at the beginning of the
3780 element it has to parse."
3783 ;; Determine if parsing depth allows for secondary strings
3784 ;; parsing. It only applies to elements referenced in
3785 ;; `org-element-secondary-value-alist'.
3788 ;; Item.
3791 ;; Table Row.
3793 ;; Node Property.
3795 ;; Headline.
3798 ;; Sections (must be checked after headline).
3804 limit)))
3805 ;; When not at bol, point is at the beginning of an item or
3806 ;; a footnote definition: next item is always a paragraph.
3808 ;; Planning and Clock.
3813 ;; Inlinetask.
3816 ;; From there, elements can have affiliated keywords.
3819 ;; Jumping over affiliated keywords put point off-limits.
3820 ;; Parse them as regular keywords.
3824 ;; LaTeX Environment.
3828 ;; Drawer and Property Drawer.
3833 ;; Fixed Width
3836 ;; Inline Comments, Blocks, Babel Calls, Dynamic Blocks and
3837 ;; Keywords.
3846 org-element-block-name-alist)))
3861 ;; Footnote Definition.
3864 ;; Horizontal Rule.
3867 ;; Diary Sexp.
3870 ;; Table.
3872 ;; List.
3875 limit affiliated
3877 ;; Default element: Paragraph.
3881 ;; Most elements can have affiliated keywords. When looking for an
3882 ;; element beginning, we want to move before them, as they belong to
3883 ;; that element, and, in the meantime, collect information they give
3884 ;; into appropriate properties. Hence the following function.
3887 "Collect affiliated keywords from point down to LIMIT.
3889 Return a list whose CAR is the position at the first of them and
3890 CDR a plist of keywords and values and move point to the
3891 beginning of the first line after them.
3893 As a special case, if element doesn't start at the beginning of
3894 the line (i.e. a paragraph starting an item), CAR is current
3895 position of point and CDR is nil."
3899 ;; RESTRICT is the list of objects allowed in parsed
3900 ;; keywords value.
3902 output)
3905 ;; Apply translation to RAW-KWD. From there, KWD is
3906 ;; the official keyword.
3908 org-element-keyword-translation-alist))
3909 raw-kwd))
3910 ;; Find main value for any keyword.
3916 ;; PARSEDP is non-nil when keyword should have its
3917 ;; value parsed.
3919 ;; If KWD is a dual keyword, find its secondary
3920 ;; value. Maybe parse it.
3927 ;; Attribute a property name to KWD.
3929 ;; Now set final shape for VALUE.
3935 ;; Attributes can always appear on multiple lines.
3938 ;; Eventually store the new value in OUTPUT.
3940 ;; Move to next keyword.
3942 ;; If affiliated keywords are orphaned: move back to first one.
3943 ;; They will be parsed as a paragraph.
3945 ;; Return value.
3949 \f
3950 ;;; The Org Parser
3951 ;;
3952 ;; The two major functions here are `org-element-parse-buffer', which
3953 ;; parses Org syntax inside the current buffer, taking into account
3954 ;; region, narrowing, or even visibility if specified, and
3955 ;; `org-element-parse-secondary-string', which parses objects within
3956 ;; a given string.
3957 ;;
3958 ;; The (almost) almighty `org-element-map' allows to apply a function
3959 ;; on elements or objects matching some type, and accumulate the
3960 ;; resulting values. In an export situation, it also skips unneeded
3961 ;; parts of the parse tree.
3964 "Recursively parse the buffer and return structure.
3965 If narrowing is in effect, only parse the visible part of the
3966 buffer.
3968 Optional argument GRANULARITY determines the depth of the
3969 recursion. It can be set to the following symbols:
3971 `headline' Only parse headlines.
3972 `greater-element' Don't recurse into greater elements excepted
3973 headlines and sections. Thus, elements
3974 parsed are the top-level ones.
3975 `element' Parse everything but objects and plain text.
3976 `object' Parse the complete buffer (default).
3978 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3979 elements.
3981 An element or an objects is represented as a list with the
3982 pattern (TYPE PROPERTIES CONTENTS), where :
3984 TYPE is a symbol describing the element or object. See
3985 `org-element-all-elements' and `org-element-all-objects' for an
3986 exhaustive list of such symbols. One can retrieve it with
3987 `org-element-type' function.
3989 PROPERTIES is the list of attributes attached to the element or
3990 object, as a plist. Although most of them are specific to the
3991 element or object type, all types share `:begin', `:end',
3992 `:post-blank' and `:parent' properties, which respectively
3993 refer to buffer position where the element or object starts,
3994 ends, the number of white spaces or blank lines after it, and
3995 the element or object containing it. Properties values can be
3996 obtained by using `org-element-property' function.
3998 CONTENTS is a list of elements, objects or raw strings
3999 contained in the current element or object, when applicable.
4000 One can access them with `org-element-contents' function.
4002 The Org buffer has `org-data' as type and nil as properties.
4003 `org-element-map' function can be used to find specific elements
4004 or objects within the parse tree.
4006 This function assumes that current major mode is `org-mode'."
4012 ;; Start in `first-section' mode so text before the first
4013 ;; headline belongs to a section.
4017 "Recursively parse objects in STRING and return structure.
4019 RESTRICTION is a symbol limiting the object types that will be
4020 looked after.
4022 Optional argument PARENT, when non-nil, is the element or object
4023 containing the secondary string. It is used to set correctly
4024 `:parent' property within the string."
4025 ;; Copy buffer-local variables listed in
4026 ;; `org-element-object-variables' into temporary buffer. This is
4027 ;; required since object parsing is dependent on these variables.
4031 org-element-object-variables))))
4039 secondary))
4040 secondary))))
4044 "Map a function on selected elements or objects.
4046 DATA is a parse tree, an element, an object, a string, or a list
4047 of such constructs. TYPES is a symbol or list of symbols of
4048 elements or objects types (see `org-element-all-elements' and
4049 `org-element-all-objects' for a complete list of types). FUN is
4050 the function called on the matching element or object. It has to
4051 accept one argument: the element or object itself.
4053 When optional argument INFO is non-nil, it should be a plist
4054 holding export options. In that case, parts of the parse tree
4055 not exportable according to that property list will be skipped.
4057 When optional argument FIRST-MATCH is non-nil, stop at the first
4058 match for which FUN doesn't return nil, and return that value.
4060 Optional argument NO-RECURSION is a symbol or a list of symbols
4061 representing elements or objects types. `org-element-map' won't
4062 enter any recursive element or object whose type belongs to that
4063 list. Though, FUN can still be applied on them.
4065 When optional argument WITH-AFFILIATED is non-nil, FUN will also
4066 apply to matching objects within parsed affiliated keywords (see
4067 `org-element-parsed-keywords').
4069 Nil values returned from FUN do not appear in the results.
4072 Examples:
4073 ---------
4075 Assuming TREE is a variable containing an Org buffer parse tree,
4076 the following example will return a flat list of all `src-block'
4077 and `example-block' elements in it:
4079 \(org-element-map tree '(example-block src-block) 'identity)
4081 The following snippet will find the first headline with a level
4084 \(org-element-map tree 'headline
4085 \(lambda (hl)
4086 \(and (= (org-element-property :level hl) 1)
4088 \(org-element-property :begin hl)))
4089 nil t)
4091 The next example will return a flat list of all `plain-list' type
4092 elements in TREE that are not a sub-list themselves:
4094 \(org-element-map tree 'plain-list 'identity nil nil 'plain-list)
4096 Eventually, this example will return a flat list of all `bold'
4097 type objects containing a `latex-snippet' type object, even
4098 looking into captions:
4100 \(org-element-map tree 'bold
4101 \(lambda (b)
4102 \(and (org-element-map b 'latex-snippet 'identity nil t) b))
4103 nil nil nil t)"
4104 ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
4107 ;; Recursion depth is determined by --CATEGORY.
4114 ;; If one object is found, the function
4115 ;; has to recurse into every object.
4118 ;; If one regular element is found, the
4119 ;; function has to recurse, at least,
4120 ;; into every element it encounters.
4123 types)
4124 category)))
4125 ;; Compute properties for affiliated keywords if necessary.
4130 org-element-affiliated-keywords)))
4131 --acc
4132 --walk-tree
4136 ;; Recursively walk DATA. INFO, if non-nil, is a plist
4137 ;; holding contextual information.
4141 ;; Ignored element in an export context.
4143 ;; List of elements or objects.
4145 ;; Unconditionally enter parse trees.
4149 ;; Check if TYPE is matching among TYPES. If so,
4150 ;; apply FUN to --DATA and accumulate return value
4151 ;; into --ACC (or exit if FIRST-MATCH is non-nil).
4157 ;; If --DATA has a secondary string that can contain
4158 ;; objects with their type among TYPES, look into it.
4165 ;; If --DATA has any affiliated keywords and
4166 ;; WITH-AFFILIATED is non-nil, look for objects in
4167 ;; them.
4175 ;; Pay attention to the type of value.
4176 ;; Preserve order for multiple keywords.
4192 --affiliated-alist))
4193 ;; Determine if a recursion into --DATA is possible.
4195 ;; --TYPE is explicitly removed from recursion.
4197 ;; --DATA has no contents.
4199 ;; Looking for greater elements but --DATA is simply
4200 ;; an element or an object.
4203 ;; Looking for elements but --DATA is an object.
4206 ;; In any other case, map contents.
4210 ;; Return value in a proper order.
4214 ;; The following functions are internal parts of the parser.
4215 ;;
4216 ;; The first one, `org-element--parse-elements' acts at the element's
4217 ;; level.
4218 ;;
4219 ;; The second one, `org-element--parse-objects' applies on all objects
4220 ;; of a paragraph or a secondary string. It uses
4221 ;; `org-element--get-next-object-candidates' to optimize the search of
4222 ;; the next object in the buffer.
4223 ;;
4224 ;; More precisely, that function looks for every allowed object type
4225 ;; first. Then, it discards failed searches, keeps further matches,
4226 ;; and searches again types matched behind point, for subsequent
4227 ;; calls. Thus, searching for a given type fails only once, and every
4228 ;; object is searched only once at top level (but sometimes more for
4229 ;; nested types).
4233 "Parse elements between BEG and END positions.
4235 SPECIAL prioritize some elements over the others. It can be set
4236 to `first-section', `quote-section', `section' `item' or
4237 `table-row'.
4239 When value is `item', STRUCTURE will be used as the current list
4240 structure.
4242 GRANULARITY determines the depth of the recursion. See
4243 `org-element-parse-buffer' for more information.
4245 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
4246 elements.
4248 Elements are accumulated into ACC."
4251 ;; Visible only: skip invisible parts at the beginning of the
4252 ;; element.
4255 ;; When parsing only headlines, skip any text before first one.
4258 ;; Main loop start.
4260 ;; Find current element's type and parse it accordingly to
4261 ;; its category.
4263 end granularity special structure))
4267 ;; Visible only: skip invisible parts between siblings.
4270 ;; Fill ELEMENT contents by side-effect.
4272 ;; If element has no contents, don't modify it.
4274 ;; Greater element: parse it between `contents-begin' and
4275 ;; `contents-end'. Make sure GRANULARITY allows the
4276 ;; recursion, or ELEMENT is a headline, in which case going
4277 ;; inside is mandatory, in order to get sub-level headings.
4285 ;; Possibly switch to a special mode.
4295 granularity visible-only element))
4296 ;; ELEMENT has contents. Parse objects inside, if
4297 ;; GRANULARITY allows it.
4303 ;; Return result.
4304 acc))
4307 "Parse objects between BEG and END and return recursive structure.
4309 Objects are accumulated in ACC.
4311 RESTRICTION is a list of object successors which are allowed in
4312 the current object."
4321 restriction candidates)))
4328 ;; 1. Text before any object. Untabify it.
4333 acc
4337 ;; 2. Object...
4340 ;; Fill contents of NEXT-OBJECT by side-effect, if it has
4341 ;; a recursive type.
4349 ;; 3. Text after last object. Untabify it.
4353 acc
4357 ;; Result.
4358 acc))))
4361 "Return an alist of candidates for the next object.
4363 RESTRICTION is a list of object types, as symbols. Only
4364 candidates with such types are looked after.
4366 OBJECTS is the previous candidates alist. If it is set to
4367 `initial', no search has been done before, and all symbols in
4368 RESTRICTION should be looked after.
4370 Return value is an alist whose CAR is the object type and CDR its
4371 beginning position."
4373 nil
4375 ;; When searching for the first time, look for every successor
4376 ;; allowed in RESTRICTION.
4380 restriction)
4381 ;; Focus on objects returned during last search. Keep those
4382 ;; still after point. Search again objects before it.
4388 type)))
4391 objects))))
4394 \f
4395 ;;; Towards A Bijective Process
4396 ;;
4397 ;; The parse tree obtained with `org-element-parse-buffer' is really
4398 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
4399 ;; interpreted and expanded into a string with canonical Org syntax.
4400 ;; Hence `org-element-interpret-data'.
4401 ;;
4402 ;; The function relies internally on
4403 ;; `org-element--interpret-affiliated-keywords'.
4405 ;;;###autoload
4407 "Interpret DATA as Org syntax.
4409 DATA is a parse tree, an element, an object or a secondary string
4410 to interpret.
4412 Optional argument PARENT is used for recursive calls. It contains
4413 the element or object containing data, or nil.
4415 Return Org syntax as a string."
4419 ;; Secondary string.
4424 ;; Full Org document.
4429 ;; Plain text: remove `:parent' text property from output.
4431 ;; Element/Object without contents.
4434 data nil))
4435 ;; Element/Object with contents.
4445 ;; Elements directly containing objects must
4446 ;; have their indentation normalized first.
4448 data
4449 ;; When normalizing first paragraph of an
4450 ;; item or a footnote-definition, ignore
4451 ;; first line's indentation.
4458 data
4460 contents)))))))
4462 ;; Build white spaces. If no `:post-blank' property is
4463 ;; specified, assume its value is 0.
4473 "Return ELEMENT's affiliated keywords as Org syntax.
4474 If there is no affiliated keyword, return the empty string."
4484 ": "
4487 value)
4495 ;; All attribute keywords can have multiple lines.
4501 ;; List all ELEMENT's properties matching an attribute line or an
4502 ;; affiliated keyword, but ignore translated keywords since they
4503 ;; cannot belong to the property list.
4510 org-element-keyword-translation-alist)))))
4511 collect prop)
4514 ;; Because interpretation of the parse tree must return the same
4515 ;; number of blank lines between elements and the same number of white
4516 ;; space after objects, some special care must be given to white
4517 ;; spaces.
4518 ;;
4519 ;; The first function, `org-element-normalize-string', ensures any
4520 ;; string different from the empty string will end with a single
4521 ;; newline character.
4522 ;;
4523 ;; The second function, `org-element-normalize-contents', removes
4524 ;; global indentation from the contents of the current element.
4527 "Ensure string S ends with a single newline character.
4529 If S isn't a string return it unchanged. If S is the empty
4530 string, return it. Otherwise, return a new string with a single
4531 newline character at its end."
4539 "Normalize plain text in ELEMENT's contents.
4541 ELEMENT must only contain plain text and objects.
4543 If optional argument IGNORE-FIRST is non-nil, ignore first line's
4544 indentation to compute maximal common indentation.
4546 Return the normalized element that is element with global
4547 indentation removed from its contents. The function assumes that
4548 indentation is not done with TAB characters."
4550 collect-inds ; for byte-compiler
4553 ;; Return list of indentations within BLOB. This is done by
4554 ;; walking recursively BLOB and updating IND-LIST along the
4555 ;; way. FIRST-FLAG is non-nil when the first string hasn't
4556 ;; been seen yet. It is required as this string is the only
4557 ;; one whose indentation doesn't happen after a newline
4558 ;; character.
4566 ;; An indentation of zero means no string will be
4567 ;; modified. Quit the process.
4573 ;; Avoid matching blank or empty lines.
4581 ;; Collect indentation list in ELEMENT. Possibly remove first
4582 ;; value if IGNORE-FIRST is non-nil.
4585 ;; Build ELEMENT back, replacing each string with the same
4586 ;; string minus common indentation.
4591 ;; Return BLOB with all its strings indentation
4592 ;; shortened from MCI white spaces. FIRST-FLAG is
4593 ;; non-nil when the first string hasn't been seen
4594 ;; yet.
4608 org-element-recursive-objects)
4612 blob))))
4616 \f
4617 ;;; The Toolbox
4618 ;;
4619 ;; The first move is to implement a way to obtain the smallest element
4620 ;; containing point. This is the job of `org-element-at-point'. It
4621 ;; basically jumps back to the beginning of section containing point
4622 ;; and proceed, one element after the other, with
4623 ;; `org-element--current-element' until the container is found. Note:
4624 ;; When using `org-element-at-point', secondary values are never
4625 ;; parsed since the function focuses on elements, not on objects.
4626 ;;
4627 ;; At a deeper level, `org-element-context' lists all elements and
4628 ;; objects containing point.
4629 ;;
4630 ;; Both functions benefit from a simple caching mechanism. It is
4631 ;; enabled by default, but can be disabled globally with
4632 ;; `org-element-use-cache'. Also `org-element-cache-reset' clears or
4633 ;; initializes cache for current buffer. Values are retrieved and put
4634 ;; into cache with respectively, `org-element-cache-get' and
4635 ;; `org-element-cache-put'. `org-element--cache-sync-idle-time' and
4636 ;; `org-element--cache-merge-changes-threshold' are used internally to
4637 ;; control caching behaviour.
4638 ;;
4639 ;; Eventually `org-element-nested-p' and `org-element-swap-A-B' may be
4640 ;; used internally by navigation and manipulation tools.
4646 "Hash table used as a cache for parser.
4647 Key is a buffer position and value is a cons cell with the
4648 pattern:
4650 \(ELEMENT . OBJECTS-DATA)
4652 where ELEMENT is the element starting at the key and OBJECTS-DATA
4653 is an alist where each association is:
4655 \(POS CANDIDATES . OBJECTS)
4657 where POS is a buffer position, CANDIDATES is the last know list
4658 of successors (see `org-element--get-next-object-candidates') in
4659 container starting at POS and OBJECTS is a list of objects known
4660 to live within that container, from farthest to closest.
4663 at, respectively, positions 1, 7 and 8,
4667 If the paragraph is completely parsed, OBJECTS-DATA will be
4669 \((1 nil BOLD-OBJECT ENTITY-OBJECT)
4670 \(8 nil ENTITY-OBJECT))
4672 whereas in a partially parsed paragraph, it could be
4674 \((1 ((entity . 1) (bold . 7)) ENTITY-OBJECT))
4676 This cache is used in both `org-element-at-point' and
4677 `org-element-context'. The former uses ELEMENT only and the
4681 "Number of seconds of idle time wait before syncing buffer cache.
4682 Syncing also happens when current modification is too distant
4683 from the stored one (for more information, see
4687 "Number of characters triggering cache syncing.
4689 The cache mechanism only stores one buffer modification at any
4690 given time. When another change happens, it replaces it with
4691 a change containing both the stored modification and the current
4692 one. This is a trade-off, as merging them prevents another
4693 syncing, but every element between them is then lost.
4695 This variable determines the maximum size, in characters, we
4699 "Contains data about cache validity for current buffer.
4701 Value is a vector of seven elements,
4703 [ACTIVEP BEGIN END OFFSET TIMER PREVIOUS-STATE]
4705 ACTIVEP is a boolean non-nil when changes described in the other
4706 slots are valid for current buffer.
4708 BEGIN and END are the beginning and ending position of the area
4709 for which cache cannot be trusted.
4711 OFFSET it an integer specifying the number to add to position of
4712 elements after that area.
4714 TIMER is a timer used to apply these changes to cache when Emacs
4715 is idle.
4717 PREVIOUS-STATE is a symbol referring to the state of the buffer
4718 before a change happens. It is used to know if sensitive
4719 areas (block boundaries, headlines) were modified. It can be set
4722 ;;;###autoload
4724 "Reset cache in current buffer.
4725 When optional argument ALL is non-nil, reset cache in all Org
4726 buffers. This function will do nothing if
4727 `org-element-use-cache' is nil."
4744 "Non-nil when changes are not integrated in cache yet."
4749 "Push change to current buffer staging area.
4750 BEG and END and the beginning and ending position of the
4751 modification area. OFFSET is the size of the change, as an
4752 integer."
4760 nil
4761 #'org-element--cache-sync
4766 "Remove any cache change set for current buffer."
4772 "Return expected key for ELEMENT in cache."
4777 begin))
4778 ;; Special key for first item (resp. table-row) in a plain
4779 ;; list (resp. table).
4781 begin)))
4784 "Return data stored at key POS in current buffer cache.
4785 When optional argument TYPE is `element', retrieve the element
4786 starting at POS. When it is `objects', return the list of object
4787 types along with their beginning position within that element.
4788 Otherwise, return the full data. In any case, return nil if no
4789 data is found, or if caching is not allowed."
4791 ;; If there are pending changes, first sync them.
4801 "Store data in current buffer's cache, if allowed.
4802 POS is a buffer position, which will be used as a key. DATA is
4803 the value to store. Nothing will be stored if
4804 `org-element-use-cache' is nil. Return DATA in any case."
4810 "Shift ELEMENT properties relative to buffer positions by OFFSET.
4811 Properties containing buffer positions are `:begin', `:end',
4812 `:contents-begin', `:contents-end' and `:structure'. They are
4813 modified by side-effect. Return modified element."
4815 ;; Shift :structure property for the first plain list only: it is
4816 ;; the only one that really matters and it prevents from shifting
4817 ;; it more than once.
4829 element)
4837 "Regexp matching an element opening line.
4838 When such a line is modified, modifications may propagate after
4839 modified area. In that situation, every element between that
4848 "Regexp matching an element closing line.
4849 When such a line is modified, modifications may propagate before
4850 modified area. In that situation, every element between that
4854 "Request extension of area going to be modified if needed.
4855 BEG and END are the beginning and end of the range of changed
4856 text. See `before-change-functions' for more information."
4864 ;; A sensitive line is a headline or a block (or drawer,
4865 ;; or latex-environment) boundary. Inserting one can
4866 ;; modify buffer drastically both above and below that
4867 ;; line, possibly making cache invalid. Therefore, we
4868 ;; need to pay special attention to changes happening to
4869 ;; them.
4873 org-element--cache-opening-line)))
4886 "Update buffer modifications for current buffer.
4888 BEG and END are the beginning and end of the range of changed
4889 text, and the length in bytes of the pre-change text replaced by
4890 that range. See `after-change-functions' for more information.
4892 If there are already pending changes, try to merge them into
4893 a bigger change record. If that's not possible, the function
4894 will first synchronize cache with previous change and store the
4895 new one."
4905 ;; Determine if modified area needs to be extended,
4906 ;; according to both previous and current state. We make
4907 ;; a special case for headline editing: if a headline is
4908 ;; modified but not removed, do not extend.
4913 org-element--cache-opening-line)))
4924 ;; Effectively extend modified area.
4927 ;; Headline above is inclusive.
4931 ;; Headline below is exclusive.
4933 ;; Store changes.
4936 ;; No pending changes. Store the new ones.
4943 ;; If we cannot merge two change sets (i.e. they
4944 ;; modify distinct buffer parts) first apply current
4945 ;; change set and store new one. This way, there is
4946 ;; never more than one pending change set, which
4947 ;; avoids handling costly merges.
4951 ;; Change sets can be merged. We can expand the area
4952 ;; that requires an update, and postpone the sync.
4961 "Synchronize cache with recent modification in BUFFER.
4962 Elements ending before modification area are kept in cache.
4963 Elements starting after modification area have their position
4964 shifted by the size of the modification. Every other element is
4965 removed from the cache."
4973 new-keys)
4979 ;; Shift every element starting after END by OFFSET.
4980 ;; We also need to shift keys, since they refer to
4981 ;; buffer positions.
4982 ;;
4983 ;; Upon shifting a key a conflict can occur if the
4984 ;; shifted key also refers to some element in the
4985 ;; cache. In this case, we temporarily associate
4986 ;; both elements, as a cons cell, to the shifted key,
4987 ;; following the pattern (SHIFTED . CURRENT).
4988 ;;
4989 ;; Such a conflict can only occur if shifted key hash
4990 ;; hasn't been processed by `maphash' yet.
4994 ;; Shift element part.
4996 ;; Shift objects part.
5003 ;; Shift key-value pair.
5006 ;; Put new value to shifted key.
5007 ;;
5008 ;; If one already exists, do not overwrite it:
5009 ;; store it as the car of a cons cell instead,
5010 ;; and handle it when `maphash' reaches
5011 ;; NEW-KEY.
5012 ;;
5013 ;; If there is no element stored at NEW-KEY or
5014 ;; if NEW-KEY is going to be removed anyway
5015 ;; (i.e., it is before END), just store new
5016 ;; value there and make sure it will not be
5017 ;; processed again by storing NEW-KEY in
5018 ;; NEW-KEYS.
5023 value-to-shift)
5024 org-element--cache)
5025 ;; If current value contains two elements, car
5026 ;; should be the new value, since cdr has been
5027 ;; shifted already.
5031 ;; Remove every element between BEG and END, since
5032 ;; this is where changes happened.
5034 ;; Preserve any element ending before BEG. If it
5035 ;; overlaps the BEG-END area, remove it.
5038 org-element--cache)
5039 ;; Signal cache as up-to-date.
5042 ;;;###autoload
5044 "Determine closest element around point.
5046 Return value is a list like (TYPE PROPS) where TYPE is the type
5047 of the element and PROPS a plist of properties associated to the
5048 element.
5050 Possible types are defined in `org-element-all-elements'.
5051 Properties depend on element or object type, but always include
5052 `:begin', `:end', `:parent' and `:post-blank' properties.
5054 As a special case, if point is at the very beginning of a list or
5055 sub-list, returned element will be that list instead of the first
5056 item. In the same way, if point is at the beginning of the first
5057 row of a table, returned element will be the table instead of the
5058 first row.
5060 If optional argument KEEP-TRAIL is non-nil, the function returns
5061 a list of elements leading to element at point. The list's CAR
5062 is always the element at point. The following positions contain
5063 element's siblings, then parents, siblings of parents, until the
5064 first element of current section."
5066 ;; If at a headline, parse it. It is the sole element that
5067 ;; doesn't require to know about context. Be sure to disallow
5068 ;; secondary string parsing, though.
5079 ;; Otherwise move at the beginning of the section containing
5080 ;; point.
5084 ;; In empty lines at buffer's beginning, return nil.
5092 ;; In blank lines just after the headline, point still
5093 ;; belongs to the headline.
5108 element type special-flag trail struct parent)
5109 ;; Parse successively each element, skipping those ending
5110 ;; before original position.
5115 ;; First item (resp. row) in plain
5116 ;; list (resp. table) gets
5117 ;; a special key in cache.
5127 element))
5128 ;; When changes happened in the middle of a list,
5129 ;; its structure ends up being invalid.
5130 ;; Therefore, we make sure to use a valid one.
5138 ;; 1. Skip any element ending before point. Also skip
5139 ;; element ending at point when we're sure that
5140 ;; another element has started.
5145 ;; 2. An element containing point is always the element at
5146 ;; point.
5149 ;; 3. At any other greater element type, if point is
5150 ;; within contents, move into it.
5155 ;; Create an anchor for tables and plain
5156 ;; lists: when point is at the very beginning
5157 ;; of these elements, ignoring affiliated
5158 ;; keywords, target them instead of their
5159 ;; contents.
5161 ;; When point is at contents end, do not move
5162 ;; into elements with an explicit ending, but
5163 ;; return that element instead.
5167 drawer dynamic-block inlinetask
5168 property-drawer quote-block
5169 special-block))
5170 ;; Corner case: if a list ends at
5171 ;; the end of a buffer without
5172 ;; a final new line, return last
5173 ;; element in last item instead.
5191 ;;;###autoload
5193 "Return closest element or object around point.
5195 Return value is a list like (TYPE PROPS) where TYPE is the type
5196 of the element or object and PROPS a plist of properties
5197 associated to it.
5199 Possible types are defined in `org-element-all-elements' and
5200 `org-element-all-objects'. Properties depend on element or
5201 object type, but always include `:begin', `:end', `:parent' and
5202 `:post-blank'.
5204 Optional argument ELEMENT, when non-nil, is the closest element
5205 containing point, as returned by `org-element-at-point'.
5206 Providing it allows for quicker computation."
5212 ;; If point is inside an element containing objects or
5213 ;; a secondary string, narrow buffer to the container and
5214 ;; proceed with parsing. Otherwise, return ELEMENT.
5216 ;; At a parsed affiliated keyword, check if we're inside main
5217 ;; or dual value.
5232 ;; Also change type to retrieve correct restrictions.
5234 ;; At an item, objects can only be located within tag, if any.
5244 ;; At an headline or inlinetask, objects are in title.
5251 ;; At a paragraph, a table-row or a verse block, objects are
5252 ;; located within their contents.
5256 ;; CBEG is nil for table rules.
5260 ;; At a parsed keyword, objects are located within value.
5263 org-element-document-properties))
5270 ;; All other locations cannot contain objects: bail out.
5278 objects-data next update-cache-flag)
5282 ;; Get list of next object candidates in CANDIDATES.
5283 ;; When entering for the first time PARENT, grab it
5284 ;; from cache, if available, or compute it. Then,
5285 ;; for each subsequent iteration in PARENT, always
5286 ;; compute it since we're beyond cache anyway.
5291 cache))))
5295 restriction candidates))
5299 ;; Compare ORIGIN with next object starting position,
5300 ;; if any.
5301 ;;
5302 ;; If ORIGIN is lesser or if there is no object
5303 ;; following, look for a previous object that might
5304 ;; contain it in cache. If there is no cache, we
5305 ;; didn't miss any object so simply return PARENT.
5306 ;;
5307 ;; If ORIGIN is greater or equal, parse next
5308 ;; candidate for further processing.
5312 candidates))))
5318 ;; Object ends before ORIGIN and we
5319 ;; know next one in cache starts
5320 ;; after it: bail out.
5330 ;; Process NEXT to know if we need to skip it, return
5331 ;; it or move into it.
5336 ;; ORIGIN is after NEXT, so skip it.
5338 ;; ORIGIN is within a non-recursive next or
5339 ;; at an object boundaries: Return that object.
5343 ;; Otherwise, move into NEXT and reset flags as we
5344 ;; shift parent.
5350 next nil
5351 objects-data nil
5353 ;; Update cache if required.
5358 "Non-nil when elements ELEM-A and ELEM-B are nested."
5367 "Swap elements ELEM-A and ELEM-B.
5368 Assume ELEM-B is after ELEM-A in the buffer. Leave point at the
5369 end of ELEM-A."
5371 ;; There are two special cases when an element doesn't start at bol:
5372 ;; the first paragraph in an item or in a footnote definition.
5374 ;; Only a paragraph without any affiliated keyword can be moved at
5375 ;; ELEM-A position in such a situation. Note that the case of
5376 ;; a footnote definition is impossible: it cannot contain two
5377 ;; paragraphs in a row because it cannot contain a blank line.
5383 ;; In a special situation, ELEM-A will have no indentation. We'll
5384 ;; give it ELEM-B's (which will in, in turn, have no indentation).
5398 ;; Store overlays responsible for visibility status. We
5399 ;; also need to store their boundaries as they will be
5400 ;; removed from buffer.
5407 ;; Get contents.
5415 ;; Restore ex ELEM-A overlays.
5424 ;; Restore ex ELEM-B overlays.
5432 "Remove maximum common indentation in string S and return it.
5433 When optional argument N is a positive integer, remove exactly
5434 that much characters from indentation, if possible, or return
5435 S as-is otherwise. Unlike to `org-remove-indentation', this
5436 function doesn't call `untabify' on S."
5441 ;; Find maximum common indentation, if not specified.
5449 min-ind)))
5451 ;; Remove exactly N indentation, but give up if not possible.
5463 ;; Local variables:
5464 ;; generated-autoload-file: "org-loaddefs.el"
5465 ;; End:
5467 ;;; org-element.el ends here