| blob | 1e185530bd3f7146f6f0bf3e981740124d635027 |
1 ;;; org-element.el --- Parser And Applications for Org syntax
3 ;; Copyright (C) 2012 Free Software Foundation, Inc.
5 ;; Author: Nicolas Goaziou <n.goaziou at gmail dot com>
6 ;; Keywords: outlines, hypermedia, calendar, wp
8 ;; This 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 an 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 ;; and elements containing objects will also have `:contents-begin'
77 ;; and `:contents-end' properties to delimit contents and
78 ;; a `:post-affiliated', referring to the buffer position after any
79 ;; affiliated keyword, if applicable.
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'.
116 ;;; 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 radio-target
191 statistics-cookie sub/superscript table-cell target
192 text-markup timestamp)
201 "Alist of translations between object type and successor name.
203 Sharing the same successor comes handy when, for example, the
208 inline-src-block italic line-break latex-fragment link macro
209 radio-target statistics-cookie strike-through subscript superscript
210 table-cell target timestamp underline verbatim)
215 table-cell underline)
225 "Alist between block names and the associated parsing function.
226 Names must be uppercase. Any block whose name has no association
232 Only these types can accept search options and an explicit
238 "List of affiliated keywords as strings.
244 ;; Regular affiliated keywords.
247 "Regexp matching any affiliated keyword.
249 Keyword name is put in match group 1. Moreover, if keyword
250 belongs to `org-element-dual-keywords', put the dual value in
251 match group 2.
259 "Alist of usual translations for keywords.
260 The key is the old name and the value the new one. The property
264 "List of affiliated keywords that can occur more than once in an element.
266 Their value will be consed into a list of strings, which will be
267 returned as the value of the property.
269 This list is checked after translations have been applied. See
270 `org-element-keyword-translation-alist'.
276 "List of affiliated keywords whose value can be parsed.
278 Their value will be stored as a secondary string: a list of
279 strings and objects.
281 This list is checked after translations have been applied. See
285 "List of affiliated keywords which can have a secondary value.
287 In Org syntax, they can be written with optional square brackets
288 before the colons. For example, RESULTS keyword can be
289 associated to a hash value with the following:
291 #+RESULTS[hash-string]: some-source
293 This list is checked after translations have been applied. See
297 "List of properties associated to the whole document.
298 Any keyword in this list will have its value parsed and stored as
305 inline-src-block latex-or-entity line-break link macro
306 radio-target sub/superscript target text-markup
307 timestamp)
309 radio-target statistics-cookie sub/superscript target text-markup
310 timestamp)
322 inline-src-block latex-or-entity line-break link macro
323 radio-target statistics-cookie sub/superscript target text-markup
324 timestamp)
327 latex-or-entity link radio-target sub/superscript target
328 text-markup timestamp)
339 latex-or-entity line-break link macro radio-target
341 "Alist of objects restrictions.
343 CAR is an element or object type containing objects and CDR is
344 a list of successors that will be called within an element or
345 object of such type.
347 For example, in a `radio-target' object, one can only find
348 entities, export snippets, latex-fragments, subscript and
349 superscript.
351 This alist also applies to secondary string. For example, an
352 `headline' type element doesn't directly contain objects, but
363 \f
364 ;;; Accessors and Setters
365 ;;
366 ;; Provide four accessors: `org-element-type', `org-element-property'
367 ;; `org-element-contents' and `org-element-restriction'.
368 ;;
369 ;; Setter functions allow to modify elements by side effect. There is
370 ;; `org-element-put-property', `org-element-set-contents',
371 ;; `org-element-set-element' and `org-element-adopt-element'. Note
372 ;; that `org-element-set-element' and `org-element-adopt-elements' are
373 ;; higher level functions since also update `:parent' property.
376 "Return type of ELEMENT.
378 The function returns the type of the element or object provided.
379 It can also return the following special value:
380 `plain-text' for a string
381 `org-data' for a complete document
382 nil in any other case."
388 "Extract the value from the PROPERTY of an ELEMENT."
393 "Extract contents from an ELEMENT."
399 "Return restriction associated to ELEMENT.
400 ELEMENT can be an element, an object or a symbol representing an
401 element or object type."
403 org-element-object-restrictions)))
406 "In ELEMENT set PROPERTY to VALUE.
407 Return modified element."
410 element))
413 "Set ELEMENT contents to CONTENTS.
414 Return modified element."
421 "Replace element or object OLD with element or object NEW.
422 The function takes care of setting `:parent' property for NEW."
423 ;; Since OLD is going to be changed into NEW by side-effect, first
424 ;; make sure that every element or object within NEW has OLD as
425 ;; parent.
428 ;; Transfer contents.
430 ;; Ensure NEW has same parent as OLD, then overwrite OLD properties
431 ;; with NEW's.
434 ;; Transfer type.
438 "Append elements to the contents of another element.
440 PARENT is an element or object. CHILDREN can be elements,
441 objects, or a strings.
443 The function takes care of setting `:parent' property for CHILD.
444 Return parent element."
445 ;; Link every child to PARENT. If PARENT is nil, it is a secondary
446 ;; string: parent is the list itself.
449 children)
450 ;; Add CHILDREN at the end of PARENT contents.
453 parent
455 ;; Return modified PARENT element.
459 \f
460 ;;; Greater elements
461 ;;
462 ;; For each greater element type, we define a parser and an
463 ;; interpreter.
464 ;;
465 ;; A parser returns the element or object as the list described above.
466 ;; Most of them accepts no argument. Though, exceptions exist. Hence
467 ;; every element containing a secondary string (see
468 ;; `org-element-secondary-value-alist') will accept an optional
469 ;; argument to toggle parsing of that secondary string. Moreover,
470 ;; `item' parser requires current list's structure as its first
471 ;; element.
472 ;;
473 ;; An interpreter accepts two arguments: the list representation of
474 ;; the element or object, and its contents. The latter may be nil,
475 ;; depending on the element or object considered. It returns the
476 ;; appropriate Org syntax, as a string.
477 ;;
478 ;; Parsing functions must follow the naming convention:
479 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
480 ;; defined in `org-element-greater-elements'.
481 ;;
482 ;; Similarly, interpreting functions must follow the naming
483 ;; convention: org-element-TYPE-interpreter.
484 ;;
485 ;; With the exception of `headline' and `item' types, greater elements
486 ;; cannot contain other greater elements of their own type.
487 ;;
488 ;; Beside implementing a parser and an interpreter, adding a new
489 ;; greater element requires to tweak `org-element--current-element'.
490 ;; Moreover, the newly defined type must be added to both
491 ;; `org-element-all-elements' and `org-element-greater-elements'.
494 ;;;; Center Block
497 "Parse a center block.
499 LIMIT bounds the search. AFFILIATED is a list of which CAR is
500 the buffer position at the beginning of the first affiliated
501 keyword and CDR is a plist of affiliated keywords along with
502 their value.
504 Return a list whose CAR is `center-block' and CDR is a plist
505 containing `:begin', `:end', `:hiddenp', `:contents-begin',
506 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
508 Assume point is at the beginning of the block."
512 ;; Incomplete block: parse it as a paragraph.
517 ;; Empty blocks have no contents.
532 :end end
533 :hiddenp hidden
534 :contents-begin contents-begin
535 :contents-end contents-end
541 "Interpret CENTER-BLOCK element as Org syntax.
542 CONTENTS is the contents of the element."
546 ;;;; Drawer
549 "Parse a drawer.
551 LIMIT bounds the search. AFFILIATED is a list of which CAR is
552 the buffer position at the beginning of the first affiliated
553 keyword and CDR is a plist of affiliated keywords along with
554 their value.
556 Return a list whose CAR is `drawer' and CDR is a plist containing
557 `:drawer-name', `:begin', `:end', `:hiddenp', `:contents-begin',
558 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
560 Assume point is at beginning of drawer."
563 ;; Incomplete drawer: parse it as a paragraph.
571 ;; Empty drawers have no contents.
586 :end end
587 :drawer-name name
588 :hiddenp hidden
589 :contents-begin contents-begin
590 :contents-end contents-end
596 "Interpret DRAWER element as Org syntax.
597 CONTENTS is the contents of the element."
600 contents))
603 ;;;; Dynamic Block
606 "Parse a dynamic block.
608 LIMIT bounds the search. AFFILIATED is a list of which CAR is
609 the buffer position at the beginning of the first affiliated
610 keyword and CDR is a plist of affiliated keywords along with
611 their value.
613 Return a list whose CAR is `dynamic-block' and CDR is a plist
614 containing `:block-name', `:begin', `:end', `:hiddenp',
615 `:contents-begin', `:contents-end', `:arguments', `:post-blank'
616 and `:post-affiliated' keywords.
618 Assume point is at beginning of dynamic block."
622 ;; Incomplete block: parse it as a paragraph.
631 ;; Empty blocks have no contents.
646 :end end
647 :block-name name
648 :arguments arguments
649 :hiddenp hidden
650 :contents-begin contents-begin
651 :contents-end contents-end
657 "Interpret DYNAMIC-BLOCK element as Org syntax.
658 CONTENTS is the contents of the element."
663 contents))
666 ;;;; Footnote Definition
669 "Parse a footnote definition.
671 LIMIT bounds the search. AFFILIATED is a list of which CAR is
672 the buffer position at the beginning of the first affiliated
673 keyword and CDR is a plist of affiliated keywords along with
674 their value.
676 Return a list whose CAR is `footnote-definition' and CDR is
677 a plist containing `:label', `:begin' `:end', `:contents-begin',
678 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
680 Assume point is at the beginning of the footnote definition."
706 :begin begin
707 :end end
708 :contents-begin contents-begin
709 :contents-end contents-end
715 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
716 CONTENTS is the contents of the footnote-definition."
718 " "
719 contents))
722 ;;;; Headline
725 "Parse an headline.
727 Return a list whose CAR is `headline' and CDR is a plist
728 containing `:raw-value', `:title', `:begin', `:end',
729 `:pre-blank', `:hiddenp', `:contents-begin' and `:contents-end',
730 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
731 `:scheduled', `:deadline', `:closed', `:clockedp', `:quotedp',
732 `:archivedp', `:commentedp' and `:footnote-section-p' keywords.
734 The plist also contains any property set in the property drawer,
735 with its name in lowercase, the underscores replaced with hyphens
736 and colons at the beginning (i.e. `:custom-id').
738 When RAW-SECONDARY-P is non-nil, headline's title will not be
739 parsed as a secondary string, but as a plain string instead.
741 Assume point is at beginning of the headline."
754 raw-value)))
758 raw-value)))
762 ;; Normalize property names: ":SOME_PROP:" becomes
763 ;; ":some-prop".
775 plist))
777 ;; Read time properties on the line below the headline.
783 org-keyword-time-not-clock-regexp end t)
793 plist))))
813 ;; Clean RAW-VALUE from any quote or comment string.
821 ""
822 raw-value))))
823 ;; Clean TAGS from archive tag, if any.
829 :begin begin
830 :end end
831 :pre-blank
834 :hiddenp hidden
835 :contents-begin contents-begin
836 :contents-end contents-end
837 :level level
839 :tags tags
840 :todo-keyword todo
841 :todo-type todo-type
847 end)
848 :footnote-section-p footnote-section-p
849 :archivedp archivedp
850 :clockedp clockedp
851 :commentedp commentedp
853 time-props
854 standard-props))))
856 headline :title
862 "Interpret HEADLINE element as Org syntax.
863 CONTENTS is the contents of the element."
890 ;; Align tags.
898 ? )
899 tags))
903 tags))))
905 contents)))
908 ;;;; Inlinetask
911 "Parse an inline task.
913 Return a list whose CAR is `inlinetask' and CDR is a plist
914 containing `:title', `:begin', `:end', `:hiddenp',
915 `:contents-begin' and `:contents-end', `:level', `:priority',
916 `:raw-value', `:tags', `:todo-keyword', `:todo-type',
917 `:scheduled', `:deadline', `:clockedp', `:closed' and
918 `:post-blank' keywords.
920 The plist also contains any property set in the property drawer,
921 with its name in lowercase, the underscores replaced with hyphens
922 and colons at the beginning (i.e. `:custom-id').
924 When optional argument RAW-SECONDARY-P is non-nil, inline-task's
925 title will not be parsed as a secondary string, but as a plain
926 string instead.
928 Assume point is at beginning of the inline task."
938 ;; Normalize property names: ":SOME_PROP:" becomes
939 ;; ":some-prop".
951 plist))
953 ;; Read time properties on the line below the inlinetask
954 ;; opening string.
960 org-keyword-time-not-clock-regexp end t)
970 plist))))
995 :begin begin
996 :end end
997 :hiddenp hidden
998 :contents-begin contents-begin
999 :contents-end contents-end
1002 :tags tags
1003 :todo-keyword todo
1004 :todo-type todo-type
1005 :clockedp clockedp
1007 time-props
1008 standard-props))))
1010 inlinetask :title
1013 raw-value
1015 inlinetask))))))
1018 "Interpret INLINETASK element as Org syntax.
1019 CONTENTS is the contents of inlinetask."
1034 ;; Align tags.
1042 ? )
1043 tags))
1047 tags))))
1048 ;; Prefer degenerate inlinetasks when there are no
1049 ;; contents.
1052 contents
1056 ;;;; Item
1059 "Parse an item.
1061 STRUCT is the structure of the plain list.
1063 Return a list whose CAR is `item' and CDR is a plist containing
1064 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
1065 `:checkbox', `:counter', `:tag', `:structure', `:hiddenp' and
1066 `:post-blank' keywords.
1068 When optional argument RAW-SECONDARY-P is non-nil, item's tag, if
1069 any, will not be parsed as a secondary string, but as a plain
1070 string instead.
1072 Assume point is at the beginning of the item."
1096 ;; Ignore tags in un-ordered lists: they are just
1097 ;; a part of item's body.
1103 ;; If first line isn't empty, contents really start
1104 ;; at the text after item's meta-data.
1115 :begin begin
1116 :end end
1117 ;; CONTENTS-BEGIN and CONTENTS-END may be
1118 ;; mixed up in the case of an empty item
1119 ;; separated from the next by a blank line.
1120 ;; Thus ensure the former is always the
1121 ;; smallest.
1124 :checkbox checkbox
1125 :counter counter
1126 :hiddenp hidden
1127 :structure struct
1130 item :tag
1138 "Interpret ITEM element as Org syntax.
1139 CONTENTS is the contents of the element."
1145 ;; Compute indentation.
1150 ;; Indent contents.
1152 bullet
1165 ;;;; Plain List
1168 "Parse a plain list.
1170 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1171 the buffer position at the beginning of the first affiliated
1172 keyword and CDR is a plist of affiliated keywords along with
1173 their value. STRUCTURE is the structure of the plain list being
1174 parsed.
1176 Return a list whose CAR is `plain-list' and CDR is a plist
1177 containing `:type', `:begin', `:end', `:contents-begin' and
1178 `:contents-end', `:structure', `:post-blank' and
1179 `:post-affiliated' keywords.
1181 Assume point is at the beginning of the list."
1196 ;; Return value.
1200 :begin begin
1201 :end end
1202 :contents-begin contents-begin
1203 :contents-end contents-end
1204 :structure struct
1210 "Interpret PLAIN-LIST element as Org syntax.
1211 CONTENTS is the contents of the element."
1219 ;;;; Property Drawer
1222 "Parse a property drawer.
1224 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1225 the buffer position at the beginning of the first affiliated
1226 keyword and CDR is a plist of affiliated keywords along with
1227 their value.
1229 Return a list whose CAR is `property-drawer' and CDR is a plist
1230 containing `:begin', `:end', `:hiddenp', `:contents-begin',
1231 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
1233 Assume point is at the beginning of the property drawer."
1238 ;; Incomplete drawer: parse it as a paragraph.
1258 :end end
1259 :hiddenp hidden
1260 :contents-begin contents-begin
1261 :contents-end contents-end
1267 "Interpret PROPERTY-DRAWER element as Org syntax.
1268 CONTENTS is the properties within the drawer."
1272 ;;;; Quote Block
1275 "Parse a quote block.
1277 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1278 the buffer position at the beginning of the first affiliated
1279 keyword and CDR is a plist of affiliated keywords along with
1280 their value.
1282 Return a list whose CAR is `quote-block' and CDR is a plist
1283 containing `:begin', `:end', `:hiddenp', `:contents-begin',
1284 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
1286 Assume point is at the beginning of the block."
1290 ;; Incomplete block: parse it as a paragraph.
1296 ;; Empty blocks have no contents.
1311 :end end
1312 :hiddenp hidden
1313 :contents-begin contents-begin
1314 :contents-end contents-end
1320 "Interpret QUOTE-BLOCK element as Org syntax.
1321 CONTENTS is the contents of the element."
1325 ;;;; Section
1328 "Parse a section.
1330 LIMIT bounds the search.
1332 Return a list whose CAR is `section' and CDR is a plist
1333 containing `:begin', `:end', `:contents-begin', `contents-end'
1334 and `:post-blank' keywords."
1336 ;; Beginning of section is the beginning of the first non-blank
1337 ;; line after previous headline.
1346 :end end
1347 :contents-begin begin
1348 :contents-end pos-before-blank
1352 "Interpret SECTION element as Org syntax.
1353 CONTENTS is the contents of the element."
1354 contents)
1357 ;;;; Special Block
1360 "Parse a special block.
1362 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1363 the buffer position at the beginning of the first affiliated
1364 keyword and CDR is a plist of affiliated keywords along with
1365 their value.
1367 Return a list whose CAR is `special-block' and CDR is a plist
1368 containing `:type', `:begin', `:end', `:hiddenp',
1369 `:contents-begin', `:contents-end', `:post-blank' and
1370 `:post-affiliated' keywords.
1372 Assume point is at the beginning of the block."
1379 ;; Incomplete block: parse it as a paragraph.
1385 ;; Empty blocks have no contents.
1400 :begin begin
1401 :end end
1402 :hiddenp hidden
1403 :contents-begin contents-begin
1404 :contents-end contents-end
1410 "Interpret SPECIAL-BLOCK element as Org syntax.
1411 CONTENTS is the contents of the element."
1416 \f
1417 ;;; Elements
1418 ;;
1419 ;; For each element, a parser and an interpreter are also defined.
1420 ;; Both follow the same naming convention used for greater elements.
1421 ;;
1422 ;; Also, as for greater elements, adding a new element type is done
1423 ;; through the following steps: implement a parser and an interpreter,
1424 ;; tweak `org-element--current-element' so that it recognizes the new
1425 ;; type and add that new type to `org-element-all-elements'.
1426 ;;
1427 ;; As a special case, when the newly defined type is a block type,
1428 ;; `org-element-block-name-alist' has to be modified accordingly.
1431 ;;;; Babel Call
1434 "Parse a babel call.
1436 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1437 the buffer position at the beginning of the first affiliated
1438 keyword and CDR is a plist of affiliated keywords along with
1439 their value.
1441 Return a list whose CAR is `babel-call' and CDR is a plist
1442 containing `:begin', `:end', `:info', `:post-blank' and
1443 `:post-affiliated' as keywords."
1457 :end end
1458 :info info
1464 "Interpret BABEL-CALL element as Org syntax.
1465 CONTENTS is nil."
1471 ;; Remove redundant square brackets.
1476 ;;;; Clock
1479 "Parse a clock.
1481 LIMIT bounds the search.
1483 Return a list whose CAR is `clock' and CDR is a plist containing
1484 `:status', `:value', `:time', `:begin', `:end' and `:post-blank'
1485 as keywords."
1505 :value value
1506 :duration duration
1507 :begin begin
1508 :end end
1512 "Interpret CLOCK element as Org syntax.
1513 CONTENTS is nil."
1521 "%2s:%02s"
1525 ;;;; Comment
1528 "Parse a comment.
1530 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1531 the buffer position at the beginning of the first affiliated
1532 keyword and CDR is a plist of affiliated keywords along with
1533 their value.
1535 Return a list whose CAR is `comment' and CDR is a plist
1536 containing `:begin', `:end', `:value', `:post-blank',
1537 `:post-affiliated' keywords.
1539 Assume point is at comment beginning."
1548 ;; Get comments ending.
1551 ;; Accumulate lines without leading hash and first
1552 ;; whitespace.
1567 :end end
1568 :value value
1574 "Interpret COMMENT element as Org syntax.
1575 CONTENTS is nil."
1579 ;;;; Comment Block
1582 "Parse an export block.
1584 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1585 the buffer position at the beginning of the first affiliated
1586 keyword and CDR is a plist of affiliated keywords along with
1587 their value.
1589 Return a list whose CAR is `comment-block' and CDR is a plist
1590 containing `:begin', `:end', `:hiddenp', `:value', `:post-blank'
1591 and `:post-affiliated' keywords.
1593 Assume point is at comment block beginning."
1597 ;; Incomplete block: parse it as a paragraph.
1612 contents-begin contents-end)))
1616 :end end
1617 :value value
1618 :hiddenp hidden
1624 "Interpret COMMENT-BLOCK element as Org syntax.
1625 CONTENTS is nil."
1630 ;;;; Diary Sexp
1633 "Parse a diary sexp.
1635 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1636 the buffer position at the beginning of the first affiliated
1637 keyword and CDR is a plist of affiliated keywords along with
1638 their value.
1640 Return a list whose CAR is `diary-sexp' and CDR is a plist
1641 containing `:begin', `:end', `:value', `:post-blank' and
1642 `:post-affiliated' keywords."
1655 :begin begin
1656 :end end
1662 "Interpret DIARY-SEXP as Org syntax.
1663 CONTENTS is nil."
1667 ;;;; Example Block
1670 "Parse an example block.
1672 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1673 the buffer position at the beginning of the first affiliated
1674 keyword and CDR is a plist of affiliated keywords along with
1675 their value.
1677 Return a list whose CAR is `example-block' and CDR is a plist
1678 containing `:begin', `:end', `:number-lines', `:preserve-indent',
1679 `:retain-labels', `:use-labels', `:label-fmt', `:hiddenp',
1680 `:switches', `:value', `:post-blank' and `:post-affiliated'
1681 keywords."
1685 ;; Incomplete block: parse it as a paragraph.
1692 ;; Switches analysis
1697 ;; Should labels be retained in (or stripped from) example
1698 ;; blocks?
1703 ;; What should code-references use - labels or
1704 ;; line-numbers?
1711 ;; Standard block parsing.
1718 contents-begin contents-end)))
1728 :end end
1729 :value value
1730 :switches switches
1731 :number-lines number-lines
1732 :preserve-indent preserve-indent
1733 :retain-labels retain-labels
1734 :use-labels use-labels
1735 :label-fmt label-fmt
1736 :hiddenp hidden
1742 "Interpret EXAMPLE-BLOCK element as Org syntax.
1743 CONTENTS is nil."
1752 ;;;; Export Block
1755 "Parse an export block.
1757 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1758 the buffer position at the beginning of the first affiliated
1759 keyword and CDR is a plist of affiliated keywords along with
1760 their value.
1762 Return a list whose CAR is `export-block' and CDR is a plist
1763 containing `:begin', `:end', `:type', `:hiddenp', `:value',
1764 `:post-blank' and `:post-affiliated' keywords.
1766 Assume point is at export-block beginning."
1773 ;; Incomplete block: parse it as a paragraph.
1788 contents-end)))
1792 :end end
1793 :type type
1794 :value value
1795 :hiddenp hidden
1801 "Interpret EXPORT-BLOCK element as Org syntax.
1802 CONTENTS is nil."
1809 ;;;; Fixed-width
1812 "Parse a fixed-width section.
1814 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1815 the buffer position at the beginning of the first affiliated
1816 keyword and CDR is a plist of affiliated keywords along with
1817 their value.
1819 Return a list whose CAR is `fixed-width' and CDR is a plist
1820 containing `:begin', `:end', `:value', `:post-blank' and
1821 `:post-affiliated' keywords.
1823 Assume point is at the beginning of the fixed-width area."
1827 value
1832 ;; Accumulate text without starting colons.
1846 :end end
1847 :value value
1853 "Interpret FIXED-WIDTH element as Org syntax.
1854 CONTENTS is nil."
1859 ;;;; Horizontal Rule
1862 "Parse an horizontal rule.
1864 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1865 the buffer position at the beginning of the first affiliated
1866 keyword and CDR is a plist of affiliated keywords along with
1867 their value.
1869 Return a list whose CAR is `horizontal-rule' and CDR is a plist
1870 containing `:begin', `:end', `:post-blank' and `:post-affiliated'
1871 keywords."
1882 :end end
1888 "Interpret HORIZONTAL-RULE element as Org syntax.
1889 CONTENTS is nil."
1893 ;;;; Keyword
1896 "Parse a keyword at point.
1898 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1899 the buffer position at the beginning of the first affiliated
1900 keyword and CDR is a plist of affiliated keywords along with
1901 their value.
1903 Return a list whose CAR is `keyword' and CDR is a plist
1904 containing `:key', `:value', `:begin', `:end', `:post-blank' and
1905 `:post-affiliated' keywords."
1920 :value value
1921 :begin begin
1922 :end end
1928 "Interpret KEYWORD element as Org syntax.
1929 CONTENTS is nil."
1935 ;;;; Latex Environment
1938 "Parse a LaTeX environment.
1940 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1941 the buffer position at the beginning of the first affiliated
1942 keyword and CDR is a plist of affiliated keywords along with
1943 their value.
1945 Return a list whose CAR is `latex-environment' and CDR is a plist
1946 containing `:begin', `:end', `:value', `:post-blank' and
1947 `:post-affiliated' keywords.
1949 Assume point is at the beginning of the latex environment."
1956 limit t))
1957 ;; Incomplete latex environment: parse it as a paragraph.
1969 :end end
1970 :value value
1976 "Interpret LATEX-ENVIRONMENT element as Org syntax.
1977 CONTENTS is nil."
1981 ;;;; Node Property
1984 "Parse a node-property at point.
1986 LIMIT bounds the search.
1988 Return a list whose CAR is `node-property' and CDR is a plist
1989 containing `:key', `:value', `:begin', `:end' and `:post-blank'
1990 keywords."
2002 :value value
2003 :begin begin
2004 :end end
2008 "Interpret NODE-PROPERTY element as Org syntax.
2009 CONTENTS is nil."
2015 ;;;; Paragraph
2018 "Parse a paragraph.
2020 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2021 the buffer position at the beginning of the first affiliated
2022 keyword and CDR is a plist of affiliated keywords along with
2023 their value.
2025 Return a list whose CAR is `paragraph' and CDR is a plist
2026 containing `:begin', `:end', `:contents-begin' and
2027 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
2029 Assume point is at the beginning of the paragraph."
2038 limit
2039 ;; A matching `org-element-paragraph-separate' is not
2040 ;; necessarily the end of the paragraph. In
2041 ;; particular, lines starting with # or : as a first
2042 ;; non-space character are ambiguous. We have check
2043 ;; if they are valid Org syntax (i.e. not an
2044 ;; incomplete keyword).
2048 ;; There's no ambiguity for other symbols or
2049 ;; empty lines: stop here.
2051 ;; Stop at valid fixed-width areas.
2053 ;; Stop at drawers.
2058 ;; Stop at valid comments.
2060 ;; Stop at valid dynamic blocks.
2065 ;; Stop at valid blocks.
2072 limit t)))
2073 ;; Stop at valid latex environments.
2080 limit t)))
2081 ;; Stop at valid keywords.
2083 ;; Skip everything else.
2101 :end end
2102 :contents-begin contents-begin
2103 :contents-end contents-end
2109 "Interpret PARAGRAPH element as Org syntax.
2110 CONTENTS is the contents of the element."
2111 contents)
2114 ;;;; Planning
2117 "Parse a planning.
2119 LIMIT bounds the search.
2121 Return a list whose CAR is `planning' and CDR is a plist
2122 containing `:closed', `:deadline', `:scheduled', `:begin', `:end'
2123 and `:post-blank' keywords."
2133 closed deadline scheduled)
2145 :deadline deadline
2146 :scheduled scheduled
2147 :begin begin
2148 :end end
2152 "Interpret PLANNING element as Org syntax.
2153 CONTENTS is nil."
2155 'identity
2172 ;;;; Quote Section
2175 "Parse a quote section.
2177 LIMIT bounds the search.
2179 Return a list whose CAR is `quote-section' and CDR is a plist
2180 containing `:begin', `:end', `:value' and `:post-blank' keywords.
2182 Assume point is at beginning of the section."
2193 :end end
2194 :value value
2198 "Interpret QUOTE-SECTION element as Org syntax.
2199 CONTENTS is nil."
2203 ;;;; Src Block
2206 "Parse a src block.
2208 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2209 the buffer position at the beginning of the first affiliated
2210 keyword and CDR is a plist of affiliated keywords along with
2211 their value.
2213 Return a list whose CAR is `src-block' and CDR is a plist
2214 containing `:language', `:switches', `:parameters', `:begin',
2215 `:end', `:hiddenp', `:number-lines', `:retain-labels',
2216 `:use-labels', `:label-fmt', `:preserve-indent', `:value',
2217 `:post-blank' and `:post-affiliated' keywords.
2219 Assume point is at the beginning of the block."
2222 limit t)))
2223 ;; Incomplete block: parse it as a paragraph.
2229 ;; Get language as a string.
2238 ;; Get switches.
2240 ;; Get parameters.
2242 ;; Switches analysis
2250 ;; Should labels be retained in (or stripped from)
2251 ;; src blocks?
2256 ;; What should code-references use - labels or
2257 ;; line-numbers?
2261 ;; Get visibility status.
2263 ;; Retrieve code.
2269 ;; Get position after ending blank lines.
2280 :begin begin
2281 :end end
2282 :number-lines number-lines
2283 :preserve-indent preserve-indent
2284 :retain-labels retain-labels
2285 :use-labels use-labels
2286 :label-fmt label-fmt
2287 :hiddenp hidden
2288 :value value
2294 "Interpret SRC-BLOCK element as Org syntax.
2295 CONTENTS is nil."
2318 ;;;; Table
2321 "Parse a table at point.
2323 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2324 the buffer position at the beginning of the first affiliated
2325 keyword and CDR is a plist of affiliated keywords along with
2326 their value.
2328 Return a list whose CAR is `table' and CDR is a plist containing
2329 `:begin', `:end', `:tblfm', `:type', `:contents-begin',
2330 `:contents-end', `:value', `:post-blank' and `:post-affiliated'
2331 keywords.
2333 Assume point is at the beginning of the table."
2347 acc))
2355 :end end
2356 :type type
2357 :tblfm tblfm
2358 ;; Only `org' tables have contents. `table.el' tables
2359 ;; use a `:value' property to store raw table as
2360 ;; a string.
2365 table-begin table-end))
2371 "Interpret TABLE element as Org syntax.
2372 CONTENTS is nil."
2383 ;;;; Table Row
2386 "Parse table row at point.
2388 LIMIT bounds the search.
2390 Return a list whose CAR is `table-row' and CDR is a plist
2391 containing `:begin', `:end', `:contents-begin', `:contents-end',
2392 `:type' and `:post-blank' keywords."
2396 ;; A table rule has no contents. In that case, ensure
2397 ;; CONTENTS-BEGIN matches CONTENTS-END.
2409 :begin begin
2410 :end end
2411 :contents-begin contents-begin
2412 :contents-end contents-end
2416 "Interpret TABLE-ROW element as Org syntax.
2417 CONTENTS is the contents of the table row."
2422 ;;;; Verse Block
2425 "Parse a verse block.
2427 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2428 the buffer position at the beginning of the first affiliated
2429 keyword and CDR is a plist of affiliated keywords along with
2430 their value.
2432 Return a list whose CAR is `verse-block' and CDR is a plist
2433 containing `:begin', `:end', `:contents-begin', `:contents-end',
2434 `:hiddenp', `:post-blank' and `:post-affiliated' keywords.
2436 Assume point is at beginning of the block."
2440 ;; Incomplete block: parse it as a paragraph.
2457 :end end
2458 :contents-begin contents-begin
2459 :contents-end contents-end
2460 :hiddenp hidden
2466 "Interpret VERSE-BLOCK element as Org syntax.
2467 CONTENTS is verse block contents."
2471 \f
2472 ;;; Objects
2473 ;;
2474 ;; Unlike to elements, interstices can be found between objects.
2475 ;; That's why, along with the parser, successor functions are provided
2476 ;; for each object. Some objects share the same successor (i.e. `code'
2477 ;; and `verbatim' objects).
2478 ;;
2479 ;; A successor must accept a single argument bounding the search. It
2480 ;; will return either a cons cell whose CAR is the object's type, as
2481 ;; a symbol, and CDR the position of its next occurrence, or nil.
2482 ;;
2483 ;; Successors follow the naming convention:
2484 ;; org-element-NAME-successor, where NAME is the name of the
2485 ;; successor, as defined in `org-element-all-successors'.
2486 ;;
2487 ;; Some object types (i.e. `italic') are recursive. Restrictions on
2488 ;; object types they can contain will be specified in
2489 ;; `org-element-object-restrictions'.
2490 ;;
2491 ;; Adding a new type of object is simple. Implement a successor,
2492 ;; a parser, and an interpreter for it, all following the naming
2493 ;; convention. Register type in `org-element-all-objects' and
2494 ;; successor in `org-element-all-successors'. Maybe tweak
2495 ;; restrictions about it, and that's it.
2498 ;;;; Bold
2501 "Parse bold object at point.
2503 Return a list whose CAR is `bold' and CDR is a plist with
2504 `:begin', `:end', `:contents-begin' and `:contents-end' and
2505 `:post-blank' keywords.
2507 Assume point is at the first star marker."
2519 :end end
2520 :contents-begin contents-begin
2521 :contents-end contents-end
2525 "Interpret BOLD object as Org syntax.
2526 CONTENTS is the contents of the object."
2530 "Search for the next text-markup object.
2532 LIMIT bounds the search.
2534 Return value is a cons cell whose CAR is a symbol among `bold',
2535 `italic', `underline', `strike-through', `code' and `verbatim'
2536 and CDR is beginning position."
2552 ;;;; Code
2555 "Parse code object at point.
2557 Return a list whose CAR is `code' and CDR is a plist with
2558 `:value', `:begin', `:end' and `:post-blank' keywords.
2560 Assume point is at the first tilde marker."
2571 :begin begin
2572 :end end
2576 "Interpret CODE object as Org syntax.
2577 CONTENTS is nil."
2581 ;;;; Entity
2584 "Parse entity at point.
2586 Return a list whose CAR is `entity' and CDR a plist with
2587 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
2588 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
2589 keywords.
2591 Assume point is at the beginning of the entity."
2593 (looking-at "\\\\\\(there4\\|sup[123]\\|frac[13][24]\\|[a-zA-Z]+\\)\\($\\|{}\\|[^[:alpha:]]\\)")
2609 :begin begin
2610 :end end
2611 :use-brackets-p bracketsp
2615 "Interpret ENTITY object as Org syntax.
2616 CONTENTS is nil."
2622 "Search for the next latex-fragment or entity object.
2624 LIMIT bounds the search.
2626 Return value is a cons cell whose CAR is `entity' or
2627 `latex-fragment' and CDR is beginning position."
2632 ;; ENTITY-RE matches both LaTeX commands and Org entities.
2639 limit t)
2642 ;; Determine if it's a real entity or a LaTeX command.
2645 ;; No entity nor command: point is at a LaTeX fragment.
2646 ;; Determine its type to get the correct beginning position.
2654 matchers)
2658 ;;;; Export Snippet
2661 "Parse export snippet at point.
2663 Return a list whose CAR is `export-snippet' and CDR a plist with
2664 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
2665 keywords.
2667 Assume point is at the beginning of the snippet."
2679 :value value
2680 :begin begin
2681 :end end
2685 "Interpret EXPORT-SNIPPET object as Org syntax.
2686 CONTENTS is nil."
2692 "Search for the next export-snippet object.
2694 LIMIT bounds the search.
2696 Return value is a cons cell whose CAR is `export-snippet' and CDR
2697 its beginning position."
2706 ;;;; Footnote Reference
2709 "Parse footnote reference at point.
2711 Return a list whose CAR is `footnote-reference' and CDR a plist
2712 with `:label', `:type', `:inline-definition', `:begin', `:end'
2713 and `:post-blank' as keywords."
2735 :type type
2736 :begin begin
2737 :end end
2740 footnote-reference :inline-definition
2745 footnote-reference))))))
2748 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
2749 CONTENTS is nil."
2759 "Search for the next footnote-reference object.
2761 LIMIT bounds the search.
2763 Return value is a cons cell whose CAR is `footnote-reference' and
2764 CDR is beginning position."
2778 ;;;; Inline Babel Call
2781 "Parse inline babel call at point.
2783 Return a list whose CAR is `inline-babel-call' and CDR a plist
2784 with `:begin', `:end', `:info' and `:post-blank' as keywords.
2786 Assume point is at the beginning of the babel call."
2797 :end end
2798 :info info
2802 "Interpret INLINE-BABEL-CALL object as Org syntax.
2803 CONTENTS is nil."
2809 ;; Remove redundant square brackets.
2812 main-source)
2816 "Search for the next inline-babel-call object.
2818 LIMIT bounds the search.
2820 Return value is a cons cell whose CAR is `inline-babel-call' and
2821 CDR is beginning position."
2823 ;; Use a simplified version of
2824 ;; `org-babel-inline-lob-one-liner-regexp'.
2827 limit t)
2831 ;;;; Inline Src Block
2834 "Parse inline source block at point.
2836 LIMIT bounds the search.
2838 Return a list whose CAR is `inline-src-block' and CDR a plist
2839 with `:begin', `:end', `:language', `:value', `:parameters' and
2840 `:post-blank' as keywords.
2842 Assume point is at the beginning of the inline src block."
2855 :value value
2856 :parameters parameters
2857 :begin begin
2858 :end end
2862 "Interpret INLINE-SRC-BLOCK object as Org syntax.
2863 CONTENTS is nil."
2868 language
2870 body)))
2873 "Search for the next inline-babel-call element.
2875 LIMIT bounds the search.
2877 Return value is a cons cell whose CAR is `inline-babel-call' and
2878 CDR is beginning position."
2884 ;;;; Italic
2887 "Parse italic object at point.
2889 Return a list whose CAR is `italic' and CDR is a plist with
2890 `:begin', `:end', `:contents-begin' and `:contents-end' and
2891 `:post-blank' keywords.
2893 Assume point is at the first slash marker."
2905 :end end
2906 :contents-begin contents-begin
2907 :contents-end contents-end
2911 "Interpret ITALIC object as Org syntax.
2912 CONTENTS is the contents of the object."
2916 ;;;; Latex Fragment
2919 "Parse latex fragment at point.
2921 Return a list whose CAR is `latex-fragment' and CDR a plist with
2922 `:value', `:begin', `:end', and `:post-blank' as keywords.
2924 Assume point is at the beginning of the latex fragment."
2938 ;; None found: it's a macro.
2947 :begin begin
2948 :end end
2952 "Interpret LATEX-FRAGMENT object as Org syntax.
2953 CONTENTS is nil."
2956 ;;;; Line Break
2959 "Parse line break at point.
2961 Return a list whose CAR is `line-break', and CDR a plist with
2962 `:begin', `:end' and `:post-blank' keywords.
2964 Assume point is at the beginning of the line break."
2968 "Interpret LINE-BREAK object as Org syntax.
2969 CONTENTS is nil."
2973 "Search for the next line-break object.
2975 LIMIT bounds the search.
2977 Return value is a cons cell whose CAR is `line-break' and CDR is
2978 beginning position."
2982 ;; A line break can only happen on a non-empty line.
2987 ;;;; Link
2990 "Parse link at point.
2992 Return a list whose CAR is `link' and CDR a plist with `:type',
2993 `:path', `:raw-link', `:application', `:search-option', `:begin',
2994 `:end', `:contents-begin', `:contents-end' and `:post-blank' as
2995 keywords.
2997 Assume point is at the beginning of the link."
3000 end contents-begin contents-end link-end post-blank path type
3001 raw-link link search-option application)
3003 ;; Type 1: Text targeted from a radio target.
3008 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
3013 ;; RAW-LINK is the original link.
3018 ;; Determine TYPE of link and set PATH accordingly.
3020 ;; File type.
3023 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
3026 ;; Id type: PATH is the id.
3029 ;; Code-ref type: PATH is the name of the reference.
3032 ;; Custom-id type: PATH is the name of the custom id.
3035 ;; Fuzzy type: Internal link either matches a target, an
3036 ;; headline name or nothing. PATH is the target or
3037 ;; headline's name.
3039 ;; Type 3: Plain link, i.e. http://orgmode.org
3045 ;; Type 4: Angular link, i.e. <http://orgmode.org>
3052 ;; In any case, deduce end point after trailing white space from
3053 ;; LINK-END variable.
3056 ;; Extract search option and opening application out of
3057 ;; "file"-type links.
3059 ;; Application.
3064 ;; Extract search option from PATH.
3068 ;; Make sure TYPE always report "file".
3072 :path path
3074 :application application
3075 :search-option search-option
3076 :begin begin
3077 :end end
3078 :contents-begin contents-begin
3079 :contents-end contents-end
3083 "Interpret LINK object as Org syntax.
3084 CONTENTS is the contents of the object, or nil."
3089 raw-link
3093 "Search for the next link object.
3095 LIMIT bounds the search.
3097 Return value is a cons cell whose CAR is `link' and CDR is
3098 beginning position."
3107 ;;;; Macro
3110 "Parse macro at point.
3112 Return a list whose CAR is `macro' and CDR a plist with `:key',
3113 `:args', `:begin', `:end', `:value' and `:post-blank' as
3114 keywords.
3116 Assume point is at the macro."
3130 ;; Repair bad splits.
3138 :value value
3139 :args args
3140 :begin begin
3141 :end end
3145 "Interpret MACRO object as Org syntax.
3146 CONTENTS is nil."
3150 "Search for the next macro object.
3152 LIMIT bounds the search.
3154 Return value is cons cell whose CAR is `macro' and CDR is
3155 beginning position."
3159 limit t)
3163 ;;;; Radio-target
3166 "Parse radio target at point.
3168 Return a list whose CAR is `radio-target' and CDR a plist with
3169 `:begin', `:end', `:contents-begin', `:contents-end', `:value'
3170 and `:post-blank' as keywords.
3172 Assume point is at the radio target."
3184 :end end
3185 :contents-begin contents-begin
3186 :contents-end contents-end
3187 :post-blank post-blank
3191 "Interpret TARGET object as Org syntax.
3192 CONTENTS is the contents of the object."
3196 "Search for the next radio-target object.
3198 LIMIT bounds the search.
3200 Return value is a cons cell whose CAR is `radio-target' and CDR
3201 is beginning position."
3207 ;;;; Statistics Cookie
3210 "Parse statistics cookie at point.
3212 Return a list whose CAR is `statistics-cookie', and CDR a plist
3213 with `:begin', `:end', `:value' and `:post-blank' keywords.
3215 Assume point is at the beginning of the statistics-cookie."
3226 :end end
3227 :value value
3231 "Interpret STATISTICS-COOKIE object as Org syntax.
3232 CONTENTS is nil."
3236 "Search for the next statistics cookie object.
3238 LIMIT bounds the search.
3240 Return value is a cons cell whose CAR is `statistics-cookie' and
3241 CDR is beginning position."
3247 ;;;; Strike-Through
3250 "Parse strike-through object at point.
3252 Return a list whose CAR is `strike-through' and CDR is a plist
3253 with `:begin', `:end', `:contents-begin' and `:contents-end' and
3254 `:post-blank' keywords.
3256 Assume point is at the first plus sign marker."
3268 :end end
3269 :contents-begin contents-begin
3270 :contents-end contents-end
3274 "Interpret STRIKE-THROUGH object as Org syntax.
3275 CONTENTS is the contents of the object."
3279 ;;;; Subscript
3282 "Parse subscript at point.
3284 Return a list whose CAR is `subscript' and CDR a plist with
3285 `:begin', `:end', `:contents-begin', `:contents-end',
3286 `:use-brackets-p' and `:post-blank' as keywords.
3288 Assume point is at the underscore."
3292 t
3303 :end end
3304 :use-brackets-p bracketsp
3305 :contents-begin contents-begin
3306 :contents-end contents-end
3310 "Interpret SUBSCRIPT object as Org syntax.
3311 CONTENTS is the contents of the object."
3314 contents))
3317 "Search for the next sub/superscript object.
3319 LIMIT bounds the search.
3321 Return value is a cons cell whose CAR is either `subscript' or
3322 `superscript' and CDR is beginning position."
3330 ;;;; Superscript
3333 "Parse superscript at point.
3335 Return a list whose CAR is `superscript' and CDR a plist with
3336 `:begin', `:end', `:contents-begin', `:contents-end',
3337 `:use-brackets-p' and `:post-blank' as keywords.
3339 Assume point is at the caret."
3353 :end end
3354 :use-brackets-p bracketsp
3355 :contents-begin contents-begin
3356 :contents-end contents-end
3360 "Interpret SUPERSCRIPT object as Org syntax.
3361 CONTENTS is the contents of the object."
3364 contents))
3367 ;;;; Table Cell
3370 "Parse table cell at point.
3372 Return a list whose CAR is `table-cell' and CDR is a plist
3373 containing `:begin', `:end', `:contents-begin', `:contents-end'
3374 and `:post-blank' keywords."
3382 :end end
3383 :contents-begin contents-begin
3384 :contents-end contents-end
3388 "Interpret TABLE-CELL element as Org syntax.
3389 CONTENTS is the contents of the cell, or nil."
3393 "Search for the next table-cell object.
3395 LIMIT bounds the search.
3397 Return value is a cons cell whose CAR is `table-cell' and CDR is
3398 beginning position."
3402 ;;;; Target
3405 "Parse target at point.
3407 Return a list whose CAR is `target' and CDR a plist with
3408 `:begin', `:end', `:value' and `:post-blank' as keywords.
3410 Assume point is at the target."
3420 :end end
3421 :value value
3425 "Interpret TARGET object as Org syntax.
3426 CONTENTS is nil."
3430 "Search for the next target object.
3432 LIMIT bounds the search.
3434 Return value is a cons cell whose CAR is `target' and CDR is
3435 beginning position."
3441 ;;;; Timestamp
3444 "Parse time stamp at point.
3446 Return a list whose CAR is `timestamp', and CDR a plist with
3447 `:type', `:begin', `:end', `:value' and `:post-blank' keywords.
3449 Assume point is at the beginning of the timestamp."
3472 raw-value)
3474 :repeater-type
3480 :repeater-unit
3483 time-range year-start month-start day-start hour-start minute-start
3484 year-end month-end day-end hour-end minute-end)
3485 ;; Extract time range, if any, and remove it from date start.
3490 date-start)
3495 ;; Parse date-start.
3503 ;; Compute date-end. It can be provided directly in time-stamp,
3504 ;; or extracted from time range. Otherwise, it defaults to the
3505 ;; same values as date-start.
3515 :raw-value raw-value
3516 :year-start year-start
3517 :month-start month-start
3518 :day-start day-start
3519 :hour-start hour-start
3520 :minute-start minute-start
3521 :year-end year-end
3522 :month-end month-end
3523 :day-end day-end
3524 :hour-end hour-end
3525 :minute-end minute-end
3526 :begin begin
3527 :end end
3529 repeater-props)))))
3532 "Interpret TIMESTAMP object as Org syntax.
3533 CONTENTS is nil."
3534 ;; Use `:raw-value' if specified.
3536 ;; Otherwise, build timestamp string.
3538 ;; Build an Org timestamp string from TIME. ACTIVEP is
3539 ;; non-nil when time stamp is active. If WITH-TIME-P is
3540 ;; non-nil, add a time part. HOUR-END and MINUTE-END
3541 ;; specify a time range in the timestamp. REPEAT-STRING
3542 ;; is the repeater string, if any.
3547 org-time-stamp-formats)
3548 time)))
3554 nil nil ts)))
3558 " "
3559 repeat-string
3561 ;; Return value.
3562 ts)))
3574 build-ts-string
3597 0
3605 "--"
3617 "Search for the next timestamp object.
3619 LIMIT bounds the search.
3621 Return value is a cons cell whose CAR is `timestamp' and CDR is
3622 beginning position."
3630 limit t)
3634 ;;;; Underline
3637 "Parse underline object at point.
3639 Return a list whose CAR is `underline' and CDR is a plist with
3640 `:begin', `:end', `:contents-begin' and `:contents-end' and
3641 `:post-blank' keywords.
3643 Assume point is at the first underscore marker."
3655 :end end
3656 :contents-begin contents-begin
3657 :contents-end contents-end
3661 "Interpret UNDERLINE object as Org syntax.
3662 CONTENTS is the contents of the object."
3666 ;;;; Verbatim
3669 "Parse verbatim object at point.
3671 Return a list whose CAR is `verbatim' and CDR is a plist with
3672 `:value', `:begin', `:end' and `:post-blank' keywords.
3674 Assume point is at the first equal sign marker."
3685 :begin begin
3686 :end end
3690 "Interpret VERBATIM object as Org syntax.
3691 CONTENTS is nil."
3695 \f
3696 ;;; Parsing Element Starting At Point
3697 ;;
3698 ;; `org-element--current-element' is the core function of this section.
3699 ;; It returns the Lisp representation of the element starting at
3700 ;; point.
3701 ;;
3702 ;; `org-element--current-element' makes use of special modes. They
3703 ;; are activated for fixed element chaining (i.e. `plain-list' >
3704 ;; `item') or fixed conditional element chaining (i.e. `headline' >
3705 ;; `section'). Special modes are: `first-section', `item',
3706 ;; `node-property', `quote-section', `section' and `table-row'.
3710 "Parse the element starting at point.
3712 LIMIT bounds the search.
3714 Return value is a list like (TYPE PROPS) where TYPE is the type
3715 of the element and PROPS a plist of properties associated to the
3716 element.
3718 Possible types are defined in `org-element-all-elements'.
3720 Optional argument GRANULARITY determines the depth of the
3721 recursion. Allowed values are `headline', `greater-element',
3722 `element', `object' or nil. When it is broader than `object' (or
3723 nil), secondary values will not be parsed, since they only
3724 contain objects.
3726 Optional argument SPECIAL, when non-nil, can be either
3727 `first-section', `item', `node-property', `quote-section',
3728 `section', and `table-row'.
3730 If STRUCTURE isn't provided but SPECIAL is set to `item', it will
3731 be computed.
3733 This function assumes point is always at the beginning of the
3734 element it has to parse."
3737 ;; Determine if parsing depth allows for secondary strings
3738 ;; parsing. It only applies to elements referenced in
3739 ;; `org-element-secondary-value-alist'.
3742 ;; Item.
3745 ;; Table Row.
3747 ;; Node Property.
3749 ;; Headline.
3752 ;; Sections (must be checked after headline).
3758 limit)))
3759 ;; When not at bol, point is at the beginning of an item or
3760 ;; a footnote definition: next item is always a paragraph.
3762 ;; Planning and Clock.
3767 ;; Inlinetask.
3770 ;; From there, elements can have affiliated keywords.
3773 ;; LaTeX Environment.
3776 ;; Drawer and Property Drawer.
3781 ;; Fixed Width
3784 ;; Inline Comments, Blocks, Babel Calls, Dynamic Blocks and
3785 ;; Keywords.
3794 org-element-block-name-alist)))
3809 ;; Footnote Definition.
3812 ;; Horizontal Rule.
3815 ;; Diary Sexp.
3818 ;; Table.
3820 ;; List.
3824 ;; Default element: Paragraph.
3828 ;; Most elements can have affiliated keywords. When looking for an
3829 ;; element beginning, we want to move before them, as they belong to
3830 ;; that element, and, in the meantime, collect information they give
3831 ;; into appropriate properties. Hence the following function.
3834 "Collect affiliated keywords from point.
3836 Return a list whose CAR is the position at the first of them and
3837 CDR a plist of keywords and values and move point to the
3838 beginning of the first line after them.
3840 As a special case, if element doesn't start at the beginning of
3841 the line (i.e. a paragraph starting an item), CAR is current
3842 position of point and CDR is nil."
3846 ;; RESTRICT is the list of objects allowed in parsed
3847 ;; keywords value.
3849 output)
3852 ;; Apply translation to RAW-KWD. From there, KWD is
3853 ;; the official keyword.
3855 org-element-keyword-translation-alist))
3856 raw-kwd))
3857 ;; Find main value for any keyword.
3863 ;; PARSEDP is non-nil when keyword should have its
3864 ;; value parsed.
3866 ;; If KWD is a dual keyword, find its secondary
3867 ;; value. Maybe parse it.
3874 ;; Attribute a property name to KWD.
3876 ;; Now set final shape for VALUE.
3882 ;; Attributes can always appear on multiple lines.
3885 ;; Eventually store the new value in OUTPUT.
3887 ;; Move to next keyword.
3889 ;; If affiliated keywords are orphaned: move back to first one.
3890 ;; They will be parsed as a paragraph.
3892 ;; Return value.
3896 \f
3897 ;;; The Org Parser
3898 ;;
3899 ;; The two major functions here are `org-element-parse-buffer', which
3900 ;; parses Org syntax inside the current buffer, taking into account
3901 ;; region, narrowing, or even visibility if specified, and
3902 ;; `org-element-parse-secondary-string', which parses objects within
3903 ;; a given string.
3904 ;;
3905 ;; The (almost) almighty `org-element-map' allows to apply a function
3906 ;; on elements or objects matching some type, and accumulate the
3907 ;; resulting values. In an export situation, it also skips unneeded
3908 ;; parts of the parse tree.
3911 "Recursively parse the buffer and return structure.
3912 If narrowing is in effect, only parse the visible part of the
3913 buffer.
3915 Optional argument GRANULARITY determines the depth of the
3916 recursion. It can be set to the following symbols:
3918 `headline' Only parse headlines.
3919 `greater-element' Don't recurse into greater elements excepted
3920 headlines and sections. Thus, elements
3921 parsed are the top-level ones.
3922 `element' Parse everything but objects and plain text.
3923 `object' Parse the complete buffer (default).
3925 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3926 elements.
3928 Assume buffer is in Org mode."
3934 ;; Start in `first-section' mode so text before the first
3935 ;; headline belongs to a section.
3939 "Recursively parse objects in STRING and return structure.
3941 RESTRICTION is a symbol limiting the object types that will be
3942 looked after.
3944 Optional argument PARENT, when non-nil, is the element or object
3945 containing the secondary string. It is used to set correctly
3946 `:parent' property within the string."
3953 secondary))
3954 secondary)))
3958 "Map a function on selected elements or objects.
3960 DATA is the parsed tree, as returned by, i.e,
3961 `org-element-parse-buffer'. TYPES is a symbol or list of symbols
3962 of elements or objects types. FUN is the function called on the
3963 matching element or object. It must accept one arguments: the
3964 element or object itself.
3966 When optional argument INFO is non-nil, it should be a plist
3967 holding export options. In that case, parts of the parse tree
3968 not exportable according to that property list will be skipped.
3970 When optional argument FIRST-MATCH is non-nil, stop at the first
3971 match for which FUN doesn't return nil, and return that value.
3973 Optional argument NO-RECURSION is a symbol or a list of symbols
3974 representing elements or objects types. `org-element-map' won't
3975 enter any recursive element or object whose type belongs to that
3976 list. Though, FUN can still be applied on them.
3978 When optional argument WITH-AFFILIATED is non-nil, also move into
3979 affiliated keywords to find objects.
3981 Nil values returned from FUN do not appear in the results."
3982 ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
3985 ;; Recursion depth is determined by --CATEGORY.
3992 ;; If one object is found, the function
3993 ;; has to recurse into every object.
3996 ;; If one regular element is found, the
3997 ;; function has to recurse, at least,
3998 ;; into every element it encounters.
4001 types)
4002 category)))
4003 ;; Compute properties for affiliated keywords if necessary.
4008 org-element-affiliated-keywords)))
4009 --acc
4010 --walk-tree
4014 ;; Recursively walk DATA. INFO, if non-nil, is a plist
4015 ;; holding contextual information.
4019 ;; Ignored element in an export context.
4021 ;; Secondary string: only objects can be found there.
4024 ;; Unconditionally enter parse trees.
4028 ;; Check if TYPE is matching among TYPES. If so,
4029 ;; apply FUN to --DATA and accumulate return value
4030 ;; into --ACC (or exit if FIRST-MATCH is non-nil).
4036 ;; If --DATA has a secondary string that can contain
4037 ;; objects with their type among TYPES, look into it.
4044 ;; If --DATA has any affiliated keywords and
4045 ;; WITH-AFFILIATED is non-nil, look for objects in
4046 ;; them.
4054 ;; Pay attention to the type of value.
4055 ;; Preserve order for multiple keywords.
4071 --affiliated-alist))
4072 ;; Determine if a recursion into --DATA is possible.
4074 ;; --TYPE is explicitly removed from recursion.
4076 ;; --DATA has no contents.
4078 ;; Looking for greater elements but --DATA is simply
4079 ;; an element or an object.
4082 ;; Looking for elements but --DATA is an object.
4085 ;; In any other case, map contents.
4089 ;; Return value in a proper order.
4092 ;; The following functions are internal parts of the parser.
4093 ;;
4094 ;; The first one, `org-element--parse-elements' acts at the element's
4095 ;; level.
4096 ;;
4097 ;; The second one, `org-element--parse-objects' applies on all objects
4098 ;; of a paragraph or a secondary string. It uses
4099 ;; `org-element--get-next-object-candidates' to optimize the search of
4100 ;; the next object in the buffer.
4101 ;;
4102 ;; More precisely, that function looks for every allowed object type
4103 ;; first. Then, it discards failed searches, keeps further matches,
4104 ;; and searches again types matched behind point, for subsequent
4105 ;; calls. Thus, searching for a given type fails only once, and every
4106 ;; object is searched only once at top level (but sometimes more for
4107 ;; nested types).
4111 "Parse elements between BEG and END positions.
4113 SPECIAL prioritize some elements over the others. It can be set
4114 to `first-section', `quote-section', `section' `item' or
4115 `table-row'.
4117 When value is `item', STRUCTURE will be used as the current list
4118 structure.
4120 GRANULARITY determines the depth of the recursion. See
4121 `org-element-parse-buffer' for more information.
4123 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
4124 elements.
4126 Elements are accumulated into ACC."
4129 ;; When parsing only headlines, skip any text before first one.
4132 ;; Main loop start.
4134 ;; Find current element's type and parse it accordingly to
4135 ;; its category.
4137 end granularity special structure))
4141 ;; Fill ELEMENT contents by side-effect.
4143 ;; If VISIBLE-ONLY is true and element is hidden or if it has
4144 ;; no contents, don't modify it.
4147 ;; Greater element: parse it between `contents-begin' and
4148 ;; `contents-end'. Make sure GRANULARITY allows the
4149 ;; recursion, or ELEMENT is an headline, in which case going
4150 ;; inside is mandatory, in order to get sub-level headings.
4158 ;; Possibly switch to a special mode.
4167 granularity visible-only element))
4168 ;; ELEMENT has contents. Parse objects inside, if
4169 ;; GRANULARITY allows it.
4175 ;; Return result.
4176 acc))
4179 "Parse objects between BEG and END and return recursive structure.
4181 Objects are accumulated in ACC.
4183 RESTRICTION is a list of object types which are allowed in the
4184 current object."
4190 end restriction candidates)))
4197 ;; 1. Text before any object. Untabify it.
4202 acc
4206 ;; 2. Object...
4209 ;; Fill contents of NEXT-OBJECT by side-effect, if it has
4210 ;; a recursive type.
4215 cont-beg
4222 ;; 3. Text after last object. Untabify it.
4226 acc
4230 ;; Result.
4231 acc)))
4234 "Return an alist of candidates for the next object.
4236 LIMIT bounds the search, and RESTRICTION narrows candidates to
4237 some object types.
4239 Return value is an alist whose CAR is position and CDR the object
4240 type, as a symbol.
4242 OBJECTS is the previous candidates alist."
4243 ;; Filter out any object found but not belonging to RESTRICTION.
4249 type)
4250 restriction)))
4251 objects))
4253 ;; If no previous result, search every object type in RESTRICTION.
4254 ;; Otherwise, keep potential candidates (old objects located after
4255 ;; point) and ask to search again those which had matched before.
4260 objects))
4261 ;; Call the appropriate successor function for each type to search
4262 ;; and accumulate matches.
4269 type))))
4272 types-to-search)
4273 ;; Return alist.
4274 next-candidates))
4277 \f
4278 ;;; Towards A Bijective Process
4279 ;;
4280 ;; The parse tree obtained with `org-element-parse-buffer' is really
4281 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
4282 ;; interpreted and expanded into a string with canonical Org syntax.
4283 ;; Hence `org-element-interpret-data'.
4284 ;;
4285 ;; The function relies internally on
4286 ;; `org-element--interpret-affiliated-keywords'.
4288 ;;;###autoload
4290 "Interpret DATA as Org syntax.
4292 DATA is a parse tree, an element, an object or a secondary string
4293 to interpret.
4295 Optional argument PARENT is used for recursive calls. It contains
4296 the element or object containing data, or nil.
4298 Return Org syntax as a string."
4302 ;; Secondary string.
4307 ;; Full Org document.
4312 ;; Plain text.
4314 ;; Element/Object without contents.
4317 data nil))
4318 ;; Element/Object with contents.
4328 ;; Elements directly containing objects must
4329 ;; have their indentation normalized first.
4331 data
4332 ;; When normalizing first paragraph of an
4333 ;; item or a footnote-definition, ignore
4334 ;; first line's indentation.
4341 data
4343 contents)))))))
4345 ;; Build white spaces. If no `:post-blank' property is
4346 ;; specified, assume its value is 0.
4356 "Return ELEMENT's affiliated keywords as Org syntax.
4357 If there is no affiliated keyword, return the empty string."
4367 ": "
4370 value)
4378 ;; All attribute keywords can have multiple lines.
4384 ;; List all ELEMENT's properties matching an attribute line or an
4385 ;; affiliated keyword, but ignore translated keywords since they
4386 ;; cannot belong to the property list.
4393 org-element-keyword-translation-alist)))))
4394 collect prop)
4397 ;; Because interpretation of the parse tree must return the same
4398 ;; number of blank lines between elements and the same number of white
4399 ;; space after objects, some special care must be given to white
4400 ;; spaces.
4401 ;;
4402 ;; The first function, `org-element-normalize-string', ensures any
4403 ;; string different from the empty string will end with a single
4404 ;; newline character.
4405 ;;
4406 ;; The second function, `org-element-normalize-contents', removes
4407 ;; global indentation from the contents of the current element.
4410 "Ensure string S ends with a single newline character.
4412 If S isn't a string return it unchanged. If S is the empty
4413 string, return it. Otherwise, return a new string with a single
4414 newline character at its end."
4422 "Normalize plain text in ELEMENT's contents.
4424 ELEMENT must only contain plain text and objects.
4426 If optional argument IGNORE-FIRST is non-nil, ignore first line's
4427 indentation to compute maximal common indentation.
4429 Return the normalized element that is element with global
4430 indentation removed from its contents. The function assumes that
4431 indentation is not done with TAB characters."
4433 collect-inds ; for byte-compiler
4436 ;; Return list of indentations within BLOB. This is done by
4437 ;; walking recursively BLOB and updating IND-LIST along the
4438 ;; way. FIRST-FLAG is non-nil when the first string hasn't
4439 ;; been seen yet. It is required as this string is the only
4440 ;; one whose indentation doesn't happen after a newline
4441 ;; character.
4449 ;; An indentation of zero means no string will be
4450 ;; modified. Quit the process.
4456 ;; Avoid matching blank or empty lines.
4464 ;; Collect indentation list in ELEMENT. Possibly remove first
4465 ;; value if IGNORE-FIRST is non-nil.
4468 ;; Build ELEMENT back, replacing each string with the same
4469 ;; string minus common indentation.
4474 ;; Return BLOB with all its strings indentation
4475 ;; shortened from MCI white spaces. FIRST-FLAG is
4476 ;; non-nil when the first string hasn't been seen
4477 ;; yet.
4491 org-element-recursive-objects)
4495 blob))))
4499 \f
4500 ;;; The Toolbox
4501 ;;
4502 ;; The first move is to implement a way to obtain the smallest element
4503 ;; containing point. This is the job of `org-element-at-point'. It
4504 ;; basically jumps back to the beginning of section containing point
4505 ;; and moves, element after element, with
4506 ;; `org-element--current-element' until the container is found. Note:
4507 ;; When using `org-element-at-point', secondary values are never
4508 ;; parsed since the function focuses on elements, not on objects.
4509 ;;
4510 ;; At a deeper level, `org-element-context' lists all elements and
4511 ;; objects containing point.
4512 ;;
4513 ;; `org-element-nested-p' and `org-element-swap-A-B' may be used
4514 ;; internally by navigation and manipulation tools.
4516 ;;;###autoload
4518 "Determine closest element around point.
4520 Return value is a list like (TYPE PROPS) where TYPE is the type
4521 of the element and PROPS a plist of properties associated to the
4522 element.
4524 Possible types are defined in `org-element-all-elements'.
4525 Properties depend on element or object type, but always
4526 include :begin, :end, :parent and :post-blank properties.
4528 As a special case, if point is at the very beginning of a list or
4529 sub-list, returned element will be that list instead of the first
4530 item. In the same way, if point is at the beginning of the first
4531 row of a table, returned element will be the table instead of the
4532 first row.
4534 If optional argument KEEP-TRAIL is non-nil, the function returns
4535 a list of of elements leading to element at point. The list's
4536 CAR is always the element at point. Following positions contain
4537 element's siblings, then parents, siblings of parents, until the
4538 first element of current section."
4540 ;; If at an headline, parse it. It is the sole element that
4541 ;; doesn't require to know about context. Be sure to disallow
4542 ;; secondary string parsing, though.
4548 ;; Otherwise move at the beginning of the section containing
4549 ;; point.
4553 element type special-flag trail struct prevs parent)
4561 ;; Parse successively each element, skipping those ending
4562 ;; before original position.
4571 ;; 1. Skip any element ending before point. Also skip
4572 ;; element ending at point when we're sure that another
4573 ;; element has started.
4578 ;; 2. An element containing point is always the element at
4579 ;; point.
4582 ;; 3. At any other greater element type, if point is
4583 ;; within contents, move into it.
4588 ;; Create an anchor for tables and plain lists:
4589 ;; when point is at the very beginning of these
4590 ;; elements, ignoring affiliated keywords,
4591 ;; target them instead of their contents.
4593 ;; When point is at contents end, do not move
4594 ;; into elements with an explicit ending, but
4595 ;; return that element instead.
4599 drawer dynamic-block inlinetask item
4600 plain-list property-drawer quote-block
4601 special-block))))
4614 ;;;###autoload
4616 "Return closest element or object around point.
4618 Return value is a list like (TYPE PROPS) where TYPE is the type
4619 of the element or object and PROPS a plist of properties
4620 associated to it.
4622 Possible types are defined in `org-element-all-elements' and
4623 `org-element-all-objects'. Properties depend on element or
4624 object type, but always include :begin, :end, :parent
4625 and :post-blank properties."
4630 end)
4631 ;; Check if point is inside an element containing objects or at
4632 ;; a secondary string. In that case, move to beginning of the
4633 ;; element or secondary string and set END to the other side.
4640 org-element-parsed-keywords))
4641 ;; We're at an affiliated keyword. Change
4642 ;; type to retrieve correct restrictions.
4644 ;; Determine if we're at main or dual value.
4658 (<= origin
4659 ;; `1+' is required so some
4660 ;; successors can match
4661 ;; properly their object.
4682 element
4685 candidates)
4688 end restriction candidates))
4690 candidates)))
4691 ;; If ORIGIN is before next object in element, there's
4692 ;; no point in looking further.
4701 ;; ORIGIN is after OBJECT, so skip it.
4704 ;; ORIGIN is within a non-recursive object or at an
4705 ;; object boundaries: Return that object.
4709 ;; Otherwise, move within current object and restrict
4710 ;; search to the end of its contents.
4715 end cend)))))))
4716 parent))))))
4719 "Non-nil when elements ELEM-A and ELEM-B are nested."
4728 "Swap elements ELEM-A and ELEM-B.
4729 Assume ELEM-B is after ELEM-A in the buffer. Leave point at the
4730 end of ELEM-A."
4732 ;; There are two special cases when an element doesn't start at bol:
4733 ;; the first paragraph in an item or in a footnote definition.
4735 ;; Only a paragraph without any affiliated keyword can be moved at
4736 ;; ELEM-A position in such a situation. Note that the case of
4737 ;; a footnote definition is impossible: it cannot contain two
4738 ;; paragraphs in a row because it cannot contain a blank line.
4744 ;; In a special situation, ELEM-A will have no indentation. We'll
4745 ;; give it ELEM-B's (which will in, in turn, have no indentation).
4759 ;; Store overlays responsible for visibility status. We
4760 ;; also need to store their boundaries as they will be
4761 ;; removed from buffer.
4768 ;; Get contents.
4776 ;; Restore ex ELEM-A overlays.
4785 ;; Restore ex ELEM-B overlays.
4794 ;; Local variables:
4795 ;; generated-autoload-file: "org-loaddefs.el"
4796 ;; End:
4798 ;;; org-element.el ends here