| blob | d8e3564c77b8ee07bfbe0d613f6d0ea0ab3a72dd |
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 program is free software; you can redistribute it and/or modify
9 ;; it under the terms of the GNU General Public License as published by
10 ;; the Free Software Foundation, either version 3 of the License, or
11 ;; (at your option) any later version.
13 ;; This program is distributed in the hope that it will be useful,
14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 ;; GNU General Public License for more details.
18 ;; This file is not part of GNU Emacs.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with this program. 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 (namely `babel-call', `clock', `headline', `item',
34 ;; `keyword', `planning', `property-drawer' and `section' types), it
35 ;; can also accept a fixed set of keywords as attributes. Those are
36 ;; called "affiliated keywords" to distinguish them from other
37 ;; keywords, which are full-fledged elements. Almost all affiliated
38 ;; keywords are referenced in `org-element-affiliated-keywords'; the
39 ;; others are export attributes and start with "ATTR_" prefix.
40 ;;
41 ;; Element containing other elements (and only elements) are called
42 ;; greater elements. Concerned types are: `center-block', `drawer',
43 ;; `dynamic-block', `footnote-definition', `headline', `inlinetask',
44 ;; `item', `plain-list', `quote-block', `section' and `special-block'.
45 ;;
46 ;; Other element types are: `babel-call', `clock', `comment',
47 ;; `comment-block', `example-block', `export-block', `fixed-width',
48 ;; `horizontal-rule', `keyword', `latex-environment', `paragraph',
49 ;; `planning', `property-drawer', `quote-section', `src-block',
50 ;; `table', `table-row' and `verse-block'. Among them, `paragraph'
51 ;; and `verse-block' types can contain Org objects and plain text.
52 ;;
53 ;; Objects are related to document's contents. Some of them are
54 ;; recursive. Associated types are of the following: `bold', `code',
55 ;; `entity', `export-snippet', `footnote-reference',
56 ;; `inline-babel-call', `inline-src-block', `italic',
57 ;; `latex-fragment', `line-break', `link', `macro', `radio-target',
58 ;; `statistics-cookie', `strike-through', `subscript', `superscript',
59 ;; `table-cell', `target', `timestamp', `underline' and `verbatim'.
60 ;;
61 ;; Some elements also have special properties whose value can hold
62 ;; objects themselves (i.e. an item tag or an headline name). Such
63 ;; values are called "secondary strings". Any object belongs to
64 ;; either an element or a secondary string.
65 ;;
66 ;; Notwithstanding affiliated keywords, each greater element, element
67 ;; and object has a fixed set of properties attached to it. Among
68 ;; them, four are shared by all types: `:begin' and `:end', which
69 ;; refer to the beginning and ending buffer positions of the
70 ;; considered element or object, `:post-blank', which holds the number
71 ;; of blank lines, or white spaces, at its end and `:parent' which
72 ;; refers to the element or object containing it. Greater elements
73 ;; and elements containing objects will also have `:contents-begin'
74 ;; and `:contents-end' properties to delimit contents.
75 ;;
76 ;; Lisp-wise, an element or an object can be represented as a list.
77 ;; It follows the pattern (TYPE PROPERTIES CONTENTS), where:
78 ;; TYPE is a symbol describing the Org element or object.
79 ;; PROPERTIES is the property list attached to it. See docstring of
80 ;; appropriate parsing function to get an exhaustive
81 ;; list.
82 ;; CONTENTS is a list of elements, objects or raw strings contained
83 ;; in the current element or object, when applicable.
84 ;;
85 ;; An Org buffer is a nested list of such elements and objects, whose
86 ;; type is `org-data' and properties is nil.
87 ;;
88 ;; The first part of this file defines Org syntax, while the second
89 ;; one provide accessors and setters functions.
90 ;;
91 ;; The next part implements a parser and an interpreter for each
92 ;; element and object type in Org syntax.
93 ;;
94 ;; The following part creates a fully recursive buffer parser. It
95 ;; also provides a tool to map a function to elements or objects
96 ;; matching some criteria in the parse tree. Functions of interest
97 ;; are `org-element-parse-buffer', `org-element-map' and, to a lesser
98 ;; extent, `org-element-parse-secondary-string'.
99 ;;
100 ;; The penultimate part is the cradle of an interpreter for the
101 ;; obtained parse tree: `org-element-interpret-data'.
102 ;;
103 ;; The library ends by furnishing `org-element-at-point' function, and
104 ;; a way to give information about document structure around point
105 ;; with `org-element-context'.
108 ;;; Code:
115 \f
116 ;;; Definitions And Rules
117 ;;
118 ;; Define elements, greater elements and specify recursive objects,
119 ;; along with the affiliated keywords recognized. Also set up
120 ;; restrictions on recursive objects combinations.
121 ;;
122 ;; These variables really act as a control center for the parsing
123 ;; process.
127 ;; Headlines, inlinetasks.
129 ;; Footnote definitions.
132 ;; Empty lines.
134 ;; Tables (any type).
136 ;; Blocks (any type), Babel calls, drawers (any type),
137 ;; fixed-width areas and keywords. Note: this is only an
138 ;; indication and need some thorough check.
140 ;; Horizontal rules.
142 ;; LaTeX environments.
144 ;; Planning and Clock lines.
146 org-deadline-string
147 org-closed-string
148 org-clock-string))
150 ;; Lists.
157 "Regexp to separate paragraphs in an Org buffer.
159 is not sufficient to know if point is at a paragraph ending. See
164 export-block fixed-width footnote-definition headline
165 horizontal-rule inlinetask item keyword latex-environment
166 babel-call paragraph plain-list planning property-drawer
167 quote-block quote-section section special-block src-block table
168 table-row verse-block)
173 item plain-list quote-block section special-block table)
178 latex-or-entity line-break link macro radio-target
179 statistics-cookie sub/superscript table-cell target
180 text-markup timestamp)
189 "Alist of translations between object type and successor name.
191 Sharing the same successor comes handy when, for example, the
196 inline-src-block italic line-break latex-fragment link macro
197 radio-target statistics-cookie strike-through subscript superscript
198 table-cell target timestamp underline verbatim)
203 table-cell underline)
213 "Alist between block names and the associated parsing function.
214 Names must be uppercase. Any block whose name has no association
220 Only these types can accept search options and an explicit
226 "List of affiliated keywords as strings.
232 ;; Regular affiliated keywords.
235 "Regexp matching any affiliated keyword.
237 Keyword name is put in match group 1. Moreover, if keyword
238 belongs to `org-element-dual-keywords', put the dual value in
239 match group 2.
247 "Alist of usual translations for keywords.
248 The key is the old name and the value the new one. The property
252 "List of affiliated keywords that can occur more that once in an element.
254 Their value will be consed into a list of strings, which will be
255 returned as the value of the property.
257 This list is checked after translations have been applied. See
258 `org-element-keyword-translation-alist'.
264 "List of keywords whose value can be parsed.
266 Their value will be stored as a secondary string: a list of
267 strings and objects.
269 This list is checked after translations have been applied. See
273 "List of keywords which can have a secondary value.
275 In Org syntax, they can be written with optional square brackets
276 before the colons. For example, results keyword can be
277 associated to a hash value with the following:
279 #+RESULTS[hash-string]: some-source
281 This list is checked after translations have been applied. See
288 inline-src-block latex-or-entity line-break link macro
289 radio-target sub/superscript target text-markup
290 timestamp)
292 radio-target statistics-cookie sub/superscript target text-markup
293 timestamp)
304 inline-src-block latex-or-entity line-break link macro
305 radio-target statistics-cookie sub/superscript target text-markup
306 timestamp)
309 latex-or-entity link radio-target sub/superscript target
310 text-markup timestamp)
321 latex-or-entity line-break link macro radio-target
323 "Alist of objects restrictions.
325 CAR is an element or object type containing objects and CDR is
326 a list of successors that will be called within an element or
327 object of such type.
329 For example, in a `radio-target' object, one can only find
330 entities, export snippets, latex-fragments, subscript and
331 superscript.
333 This alist also applies to secondary string. For example, an
334 `headline' type element doesn't directly contain objects, but
345 \f
346 ;;; Accessors and Setters
347 ;;
348 ;; Provide four accessors: `org-element-type', `org-element-property'
349 ;; `org-element-contents' and `org-element-restriction'.
350 ;;
351 ;; Setter functions allow to modify elements by side effect. There is
352 ;; `org-element-put-property', `org-element-set-contents',
353 ;; `org-element-set-element' and `org-element-adopt-element'. Note
354 ;; that `org-element-set-element' and `org-element-adopt-elements' are
355 ;; higher level functions since also update `:parent' property.
358 "Return type of ELEMENT.
360 The function returns the type of the element or object provided.
361 It can also return the following special value:
362 `plain-text' for a string
363 `org-data' for a complete document
364 nil in any other case."
370 "Extract the value from the PROPERTY of an ELEMENT."
374 "Extract contents from an ELEMENT."
378 "Return restriction associated to ELEMENT.
379 ELEMENT can be an element, an object or a symbol representing an
380 element or object type."
382 org-element-object-restrictions)))
385 "In ELEMENT set PROPERTY to VALUE.
386 Return modified element."
389 element)
392 "Set ELEMENT contents to CONTENTS.
393 Return modified element."
399 "Replace element or object OLD with element or object NEW.
400 The function takes care of setting `:parent' property for NEW."
401 ;; Since OLD is going to be changed into NEW by side-effect, first
402 ;; make sure that every element or object within NEW has OLD as
403 ;; parent.
406 ;; Transfer contents.
408 ;; Ensure NEW has same parent as OLD, then overwrite OLD properties
409 ;; with NEW's.
412 ;; Transfer type.
416 "Append elements to the contents of another element.
418 PARENT is an element or object. CHILDREN can be elements,
419 objects, or a strings.
421 The function takes care of setting `:parent' property for CHILD.
422 Return parent element."
424 ;; Link every child to PARENT.
428 children)
429 ;; Add CHILDREN at the end of PARENT contents.
431 parent
433 ;; Return modified PARENT element.
434 parent))
437 \f
438 ;;; Greater elements
439 ;;
440 ;; For each greater element type, we define a parser and an
441 ;; interpreter.
442 ;;
443 ;; A parser returns the element or object as the list described above.
444 ;; Most of them accepts no argument. Though, exceptions exist. Hence
445 ;; every element containing a secondary string (see
446 ;; `org-element-secondary-value-alist') will accept an optional
447 ;; argument to toggle parsing of that secondary string. Moreover,
448 ;; `item' parser requires current list's structure as its first
449 ;; element.
450 ;;
451 ;; An interpreter accepts two arguments: the list representation of
452 ;; the element or object, and its contents. The latter may be nil,
453 ;; depending on the element or object considered. It returns the
454 ;; appropriate Org syntax, as a string.
455 ;;
456 ;; Parsing functions must follow the naming convention:
457 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
458 ;; defined in `org-element-greater-elements'.
459 ;;
460 ;; Similarly, interpreting functions must follow the naming
461 ;; convention: org-element-TYPE-interpreter.
462 ;;
463 ;; With the exception of `headline' and `item' types, greater elements
464 ;; cannot contain other greater elements of their own type.
465 ;;
466 ;; Beside implementing a parser and an interpreter, adding a new
467 ;; greater element requires to tweak `org-element--current-element'.
468 ;; Moreover, the newly defined type must be added to both
469 ;; `org-element-all-elements' and `org-element-greater-elements'.
472 ;;;; Center Block
475 "Parse a center block.
477 LIMIT bounds the search.
479 Return a list whose CAR is `center-block' and CDR is a plist
480 containing `:begin', `:end', `:hiddenp', `:contents-begin',
481 `:contents-end' and `:post-blank' keywords.
483 Assume point is at the beginning of the block."
487 ;; Incomplete block: parse it as a paragraph.
492 ;; Empty blocks have no contents.
506 :end end
507 :hiddenp hidden
508 :contents-begin contents-begin
509 :contents-end contents-end
514 "Interpret CENTER-BLOCK element as Org syntax.
515 CONTENTS is the contents of the element."
519 ;;;; Drawer
522 "Parse a drawer.
524 LIMIT bounds the search.
526 Return a list whose CAR is `drawer' and CDR is a plist containing
527 `:drawer-name', `:begin', `:end', `:hiddenp', `:contents-begin',
528 `:contents-end' and `:post-blank' keywords.
530 Assume point is at beginning of drawer."
533 ;; Incomplete drawer: parse it as a paragraph.
542 ;; Empty drawers have no contents.
556 :end end
557 :drawer-name name
558 :hiddenp hidden
559 :contents-begin contents-begin
560 :contents-end contents-end
565 "Interpret DRAWER element as Org syntax.
566 CONTENTS is the contents of the element."
569 contents))
572 ;;;; Dynamic Block
575 "Parse a dynamic block.
577 LIMIT bounds the search.
579 Return a list whose CAR is `dynamic-block' and CDR is a plist
580 containing `:block-name', `:begin', `:end', `:hiddenp',
581 `:contents-begin', `:contents-end', `:arguments' and
582 `:post-blank' keywords.
584 Assume point is at beginning of dynamic block."
587 ;; Incomplete block: parse it as a paragraph.
596 ;; Empty blocks have no contents.
610 :end end
611 :block-name name
612 :arguments arguments
613 :hiddenp hidden
614 :contents-begin contents-begin
615 :contents-end contents-end
620 "Interpret DYNAMIC-BLOCK element as Org syntax.
621 CONTENTS is the contents of the element."
626 contents))
629 ;;;; Footnote Definition
632 "Parse a footnote definition.
634 LIMIT bounds the search.
636 Return a list whose CAR is `footnote-definition' and CDR is
637 a plist containing `:label', `:begin' `:end', `:contents-begin',
638 `:contents-end' and `:post-blank' keywords.
640 Assume point is at the beginning of the footnote definition."
665 :begin begin
666 :end end
667 :contents-begin contents-begin
668 :contents-end contents-end
673 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
674 CONTENTS is the contents of the footnote-definition."
676 " "
677 contents))
680 ;;;; Headline
683 "Parse an headline.
685 Return a list whose CAR is `headline' and CDR is a plist
686 containing `:raw-value', `:title', `:begin', `:end',
687 `:pre-blank', `:hiddenp', `:contents-begin' and `:contents-end',
688 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
689 `:scheduled', `:deadline', `:timestamp', `:clock', `:category',
690 `:quotedp', `:archivedp', `:commentedp' and `:footnote-section-p'
691 keywords.
693 The plist also contains any property set in the property drawer,
694 with its name in lowercase, the underscores replaced with hyphens
695 and colons at the beginning (i.e. `:custom-id').
697 When RAW-SECONDARY-P is non-nil, headline's title will not be
698 parsed as a secondary string, but as a plain string instead.
700 Assume point is at beginning of the headline."
719 ;; Normalize property names: ":SOME_PROP:" becomes
720 ;; ":some-prop".
732 plist))
750 ;; Clean RAW-VALUE from any quote or comment string.
755 ""
756 raw-value)))
757 ;; Clean TAGS from archive tag, if any.
763 :begin begin
764 :end end
765 :pre-blank
768 :hiddenp hidden
769 :contents-begin contents-begin
770 :contents-end contents-end
771 :level level
773 :tags tags
774 :todo-keyword todo
775 :todo-type todo-type
776 :scheduled scheduled
777 :deadline deadline
778 :timestamp timestamp
779 :clock clock
785 end)
786 :footnote-section-p footnote-section-p
787 :archivedp archivedp
788 :commentedp commentedp
790 standard-props))))
792 headline :title
798 "Interpret HEADLINE element as Org syntax.
799 CONTENTS is the contents of the element."
826 ;; Align tags.
834 ? )
835 tags))
839 tags))))
841 contents)))
844 ;;;; Inlinetask
847 "Parse an inline task.
849 Return a list whose CAR is `inlinetask' and CDR is a plist
850 containing `:title', `:begin', `:end', `:hiddenp',
851 `:contents-begin' and `:contents-end', `:level', `:priority',
852 `:tags', `:todo-keyword', `:todo-type', `:scheduled',
853 `:deadline', `:timestamp', `:clock' and `:post-blank' keywords.
855 The plist also contains any property set in the property drawer,
856 with its name in lowercase, the underscores replaced with hyphens
857 and colons at the beginning (i.e. `:custom-id').
859 When optional argument RAW-SECONDARY-P is non-nil, inline-task's
860 title will not be parsed as a secondary string, but as a plain
861 string instead.
863 Assume point is at beginning of the inline task."
873 ;; Normalize property names: ":SOME_PROP:" becomes
874 ;; ":some-prop".
886 plist))
910 :end end
911 :hiddenp hidden
912 :contents-begin contents-begin
913 :contents-end contents-end
916 :tags tags
917 :todo-keyword todo
918 :todo-type todo-type
919 :scheduled scheduled
920 :deadline deadline
921 :timestamp timestamp
922 :clock clock
924 standard-props
927 inlinetask :title
932 inlinetask))))))
935 "Interpret INLINETASK element as Org syntax.
936 CONTENTS is the contents of inlinetask."
951 ;; Align tags.
959 ? )
960 tags))
964 tags))))
965 ;; Prefer degenerate inlinetasks when there are no
966 ;; contents.
969 contents
973 ;;;; Item
976 "Parse an item.
978 STRUCT is the structure of the plain list.
980 Return a list whose CAR is `item' and CDR is a plist containing
981 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
982 `:checkbox', `:counter', `:tag', `:structure', `:hiddenp' and
983 `:post-blank' keywords.
985 When optional argument RAW-SECONDARY-P is non-nil, item's tag, if
986 any, will not be parsed as a secondary string, but as a plain
987 string instead.
989 Assume point is at the beginning of the item."
1013 ;; Ignore tags in un-ordered lists: they are just
1014 ;; a part of item's body.
1020 ;; If first line isn't empty, contents really start
1021 ;; at the text after item's meta-data.
1032 :begin begin
1033 :end end
1034 ;; CONTENTS-BEGIN and CONTENTS-END may be
1035 ;; mixed up in the case of an empty item
1036 ;; separated from the next by a blank line.
1037 ;; Thus ensure the former is always the
1038 ;; smallest.
1041 :checkbox checkbox
1042 :counter counter
1043 :hiddenp hidden
1044 :structure struct
1047 item :tag
1055 "Interpret ITEM element as Org syntax.
1056 CONTENTS is the contents of the element."
1062 ;; Compute indentation.
1067 ;; Indent contents.
1069 bullet
1082 ;;;; Plain List
1085 "Parse a plain list.
1087 Optional argument STRUCTURE, when non-nil, is the structure of
1088 the plain list being parsed.
1090 Return a list whose CAR is `plain-list' and CDR is a plist
1091 containing `:type', `:begin', `:end', `:contents-begin' and
1092 `:contents-end', `:structure' and `:post-blank' keywords.
1094 Assume point is at the beginning of the list."
1109 ;; Return value.
1113 :begin begin
1114 :end end
1115 :contents-begin contents-begin
1116 :contents-end contents-end
1117 :structure struct
1122 "Interpret PLAIN-LIST element as Org syntax.
1123 CONTENTS is the contents of the element."
1131 ;;;; Quote Block
1134 "Parse a quote block.
1136 LIMIT bounds the search.
1138 Return a list whose CAR is `quote-block' and CDR is a plist
1139 containing `:begin', `:end', `:hiddenp', `:contents-begin',
1140 `:contents-end' and `:post-blank' keywords.
1142 Assume point is at the beginning of the block."
1146 ;; Incomplete block: parse it as a paragraph.
1152 ;; Empty blocks have no contents.
1166 :end end
1167 :hiddenp hidden
1168 :contents-begin contents-begin
1169 :contents-end contents-end
1174 "Interpret QUOTE-BLOCK element as Org syntax.
1175 CONTENTS is the contents of the element."
1179 ;;;; Section
1182 "Parse a section.
1184 LIMIT bounds the search.
1186 Return a list whose CAR is `section' and CDR is a plist
1187 containing `:begin', `:end', `:contents-begin', `contents-end'
1188 and `:post-blank' keywords."
1190 ;; Beginning of section is the beginning of the first non-blank
1191 ;; line after previous headline.
1200 :end end
1201 :contents-begin begin
1202 :contents-end pos-before-blank
1206 "Interpret SECTION element as Org syntax.
1207 CONTENTS is the contents of the element."
1208 contents)
1211 ;;;; Special Block
1214 "Parse a special block.
1216 LIMIT bounds the search.
1218 Return a list whose CAR is `special-block' and CDR is a plist
1219 containing `:type', `:begin', `:end', `:hiddenp',
1220 `:contents-begin', `:contents-end' and `:post-blank' keywords.
1222 Assume point is at the beginning of the block."
1228 ;; Incomplete block: parse it as a paragraph.
1234 ;; Empty blocks have no contents.
1248 :begin begin
1249 :end end
1250 :hiddenp hidden
1251 :contents-begin contents-begin
1252 :contents-end contents-end
1257 "Interpret SPECIAL-BLOCK element as Org syntax.
1258 CONTENTS is the contents of the element."
1263 \f
1264 ;;; Elements
1265 ;;
1266 ;; For each element, a parser and an interpreter are also defined.
1267 ;; Both follow the same naming convention used for greater elements.
1268 ;;
1269 ;; Also, as for greater elements, adding a new element type is done
1270 ;; through the following steps: implement a parser and an interpreter,
1271 ;; tweak `org-element--current-element' so that it recognizes the new
1272 ;; type and add that new type to `org-element-all-elements'.
1273 ;;
1274 ;; As a special case, when the newly defined type is a block type,
1275 ;; `org-element-block-name-alist' has to be modified accordingly.
1278 ;;;; Babel Call
1281 "Parse a babel call.
1283 LIMIT bounds the search.
1285 Return a list whose CAR is `babel-call' and CDR is a plist
1286 containing `:begin', `:end', `:info' and `:post-blank' as
1287 keywords."
1298 :end end
1299 :info info
1303 "Interpret BABEL-CALL element as Org syntax.
1304 CONTENTS is nil."
1310 ;; Remove redundant square brackets.
1315 ;;;; Clock
1318 "Parse a clock.
1320 LIMIT bounds the search.
1322 Return a list whose CAR is `clock' and CDR is a plist containing
1323 `:status', `:value', `:time', `:begin', `:end' and `:post-blank'
1324 as keywords."
1343 :value value
1344 :time time
1345 :begin begin
1346 :end end
1350 "Interpret CLOCK element as Org syntax.
1351 CONTENTS is nil."
1358 "%2s:%02s"
1362 ;;;; Comment
1365 "Parse a comment.
1367 LIMIT bounds the search.
1369 Return a list whose CAR is `comment' and CDR is a plist
1370 containing `:begin', `:end', `:value' and `:post-blank'
1371 keywords.
1373 Assume point is at comment beginning."
1382 ;; Get comments ending.
1385 ;; Accumulate lines without leading hash and first
1386 ;; whitespace.
1400 :end end
1401 :value value
1406 "Interpret COMMENT element as Org syntax.
1407 CONTENTS is nil."
1411 ;;;; Comment Block
1414 "Parse an export block.
1416 LIMIT bounds the search.
1418 Return a list whose CAR is `comment-block' and CDR is a plist
1419 containing `:begin', `:end', `:hiddenp', `:value' and
1420 `:post-blank' keywords.
1422 Assume point is at comment block beginning."
1426 ;; Incomplete block: parse it as a paragraph.
1440 contents-begin contents-end)))
1444 :end end
1445 :value value
1446 :hiddenp hidden
1451 "Interpret COMMENT-BLOCK element as Org syntax.
1452 CONTENTS is nil."
1457 ;;;; Example Block
1460 "Parse an example block.
1462 LIMIT bounds the search.
1464 Return a list whose CAR is `example-block' and CDR is a plist
1465 containing `:begin', `:end', `:number-lines', `:preserve-indent',
1466 `:retain-labels', `:use-labels', `:label-fmt', `:hiddenp',
1467 `:switches', `:value' and `:post-blank' keywords."
1471 ;; Incomplete block: parse it as a paragraph.
1478 ;; Switches analysis
1483 ;; Should labels be retained in (or stripped from) example
1484 ;; blocks?
1489 ;; What should code-references use - labels or
1490 ;; line-numbers?
1497 ;; Standard block parsing.
1511 :end end
1512 :value value
1513 :switches switches
1514 :number-lines number-lines
1515 :preserve-indent preserve-indent
1516 :retain-labels retain-labels
1517 :use-labels use-labels
1518 :label-fmt label-fmt
1519 :hiddenp hidden
1524 "Interpret EXAMPLE-BLOCK element as Org syntax.
1525 CONTENTS is nil."
1533 ;;;; Export Block
1536 "Parse an export block.
1538 LIMIT bounds the search.
1540 Return a list whose CAR is `export-block' and CDR is a plist
1541 containing `:begin', `:end', `:type', `:hiddenp', `:value' and
1542 `:post-blank' keywords.
1544 Assume point is at export-block beginning."
1550 ;; Incomplete block: parse it as a paragraph.
1564 contents-end)))
1568 :end end
1569 :type type
1570 :value value
1571 :hiddenp hidden
1576 "Interpret EXPORT-BLOCK element as Org syntax.
1577 CONTENTS is nil."
1584 ;;;; Fixed-width
1587 "Parse a fixed-width section.
1589 LIMIT bounds the search.
1591 Return a list whose CAR is `fixed-width' and CDR is a plist
1592 containing `:begin', `:end', `:value' and `:post-blank' keywords.
1594 Assume point is at the beginning of the fixed-width area."
1598 value
1603 ;; Accumulate text without starting colons.
1616 :end end
1617 :value value
1622 "Interpret FIXED-WIDTH element as Org syntax.
1623 CONTENTS is nil."
1628 ;;;; Horizontal Rule
1631 "Parse an horizontal rule.
1633 LIMIT bounds the search.
1635 Return a list whose CAR is `horizontal-rule' and CDR is a plist
1636 containing `:begin', `:end' and `:post-blank' keywords."
1646 :end end
1651 "Interpret HORIZONTAL-RULE element as Org syntax.
1652 CONTENTS is nil."
1656 ;;;; Keyword
1659 "Parse a keyword at point.
1661 LIMIT bounds the search.
1663 Return a list whose CAR is `keyword' and CDR is a plist
1664 containing `:key', `:value', `:begin', `:end' and `:post-blank'
1665 keywords."
1678 :value value
1679 :begin begin
1680 :end end
1684 "Interpret KEYWORD element as Org syntax.
1685 CONTENTS is nil."
1691 ;;;; Latex Environment
1694 "Parse a LaTeX environment.
1696 LIMIT bounds the search.
1698 Return a list whose CAR is `latex-environment' and CDR is a plist
1699 containing `:begin', `:end', `:value' and `:post-blank'
1700 keywords.
1702 Assume point is at the beginning of the latex environment."
1720 :end end
1721 :value value
1726 "Interpret LATEX-ENVIRONMENT element as Org syntax.
1727 CONTENTS is nil."
1731 ;;;; Paragraph
1734 "Parse a paragraph.
1736 LIMIT bounds the search.
1738 Return a list whose CAR is `paragraph' and CDR is a plist
1739 containing `:begin', `:end', `:contents-begin' and
1740 `:contents-end' and `:post-blank' keywords.
1742 Assume point is at the beginning of the paragraph."
1745 ;; beginning of an item or a footnote reference. In that
1746 ;; case, we mustn't look for affiliated keywords since they
1747 ;; belong to the container.
1759 ;; Skip non-existent or incomplete drawer.
1767 ;; Stop at comments.
1771 ;; Skip incomplete dynamic blocks.
1778 ;; Skip incomplete blocks.
1786 limit t))))
1787 ;; Skip incomplete latex environments.
1795 limit t))))
1796 ;; Skip ill-formed keywords.
1810 :end end
1811 :contents-begin contents-begin
1812 :contents-end contents-end
1817 "Interpret PARAGRAPH element as Org syntax.
1818 CONTENTS is the contents of the element."
1819 contents)
1822 ;;;; Planning
1825 "Parse a planning.
1827 LIMIT bounds the search.
1829 Return a list whose CAR is `planning' and CDR is a plist
1830 containing `:closed', `:deadline', `:scheduled', `:begin', `:end'
1831 and `:post-blank' keywords."
1840 closed deadline scheduled)
1854 :deadline deadline
1855 :scheduled scheduled
1856 :begin begin
1857 :end end
1861 "Interpret PLANNING element as Org syntax.
1862 CONTENTS is nil."
1864 'identity
1876 ;;;; Property Drawer
1879 "Parse a property drawer.
1881 LIMIT bounds the search.
1883 Return a list whose CAR is `property-drawer' and CDR is a plist
1884 containing `:begin', `:end', `:hiddenp', `:contents-begin',
1885 `:contents-end', `:properties' and `:post-blank' keywords.
1887 Assume point is at the beginning of the property drawer."
1901 val))
1903 val))
1911 :end end
1912 :hiddenp hidden
1913 :properties properties
1917 "Interpret PROPERTY-DRAWER element as Org syntax.
1918 CONTENTS is nil."
1928 ;;;; Quote Section
1931 "Parse a quote section.
1933 LIMIT bounds the search.
1935 Return a list whose CAR is `quote-section' and CDR is a plist
1936 containing `:begin', `:end', `:value' and `:post-blank' keywords.
1938 Assume point is at beginning of the section."
1949 :end end
1950 :value value
1954 "Interpret QUOTE-SECTION element as Org syntax.
1955 CONTENTS is nil."
1959 ;;;; Src Block
1962 "Parse a src block.
1964 LIMIT bounds the search.
1966 Return a list whose CAR is `src-block' and CDR is a plist
1967 containing `:language', `:switches', `:parameters', `:begin',
1968 `:end', `:hiddenp', `:number-lines', `:retain-labels',
1969 `:use-labels', `:label-fmt', `:preserve-indent', `:value' and
1970 `:post-blank' keywords.
1972 Assume point is at the beginning of the block."
1975 ;; Incomplete block: parse it as a paragraph.
1980 ;; Get beginning position.
1982 ;; Get language as a string.
1991 ;; Get switches.
1993 ;; Get parameters.
1995 ;; Switches analysis
2003 ;; Should labels be retained in (or stripped from)
2004 ;; src blocks?
2009 ;; What should code-references use - labels or
2010 ;; line-numbers?
2014 ;; Get visibility status.
2016 ;; Retrieve code.
2021 ;; Get position after ending blank lines.
2031 :begin begin
2032 :end end
2033 :number-lines number-lines
2034 :preserve-indent preserve-indent
2035 :retain-labels retain-labels
2036 :use-labels use-labels
2037 :label-fmt label-fmt
2038 :hiddenp hidden
2039 :value value
2044 "Interpret SRC-BLOCK element as Org syntax.
2045 CONTENTS is nil."
2065 value
2069 ;;;; Table
2072 "Parse a table at point.
2074 LIMIT bounds the search.
2076 Return a list whose CAR is `table' and CDR is a plist containing
2077 `:begin', `:end', `:tblfm', `:type', `:contents-begin',
2078 `:contents-end', `:value' and `:post-blank' keywords.
2080 Assume point is at the beginning of the table."
2092 acc))
2099 :end end
2100 :type type
2101 :tblfm tblfm
2102 ;; Only `org' tables have contents. `table.el' tables
2103 ;; use a `:value' property to store raw table as
2104 ;; a string.
2109 table-begin table-end))
2114 "Interpret TABLE element as Org syntax.
2115 CONTENTS is nil."
2126 ;;;; Table Row
2129 "Parse table row at point.
2131 LIMIT bounds the search.
2133 Return a list whose CAR is `table-row' and CDR is a plist
2134 containing `:begin', `:end', `:contents-begin', `:contents-end',
2135 `:type' and `:post-blank' keywords."
2139 ;; A table rule has no contents. In that case, ensure
2140 ;; CONTENTS-BEGIN matches CONTENTS-END.
2152 :begin begin
2153 :end end
2154 :contents-begin contents-begin
2155 :contents-end contents-end
2159 "Interpret TABLE-ROW element as Org syntax.
2160 CONTENTS is the contents of the table row."
2165 ;;;; Verse Block
2168 "Parse a verse block.
2170 LIMIT bounds the search.
2172 Return a list whose CAR is `verse-block' and CDR is a plist
2173 containing `:begin', `:end', `:contents-begin', `:contents-end',
2174 `:hiddenp' and `:post-blank' keywords.
2176 Assume point is at beginning of the block."
2180 ;; Incomplete block: parse it as a paragraph.
2196 :end end
2197 :contents-begin contents-begin
2198 :contents-end contents-end
2199 :hiddenp hidden
2204 "Interpret VERSE-BLOCK element as Org syntax.
2205 CONTENTS is verse block contents."
2209 \f
2210 ;;; Objects
2211 ;;
2212 ;; Unlike to elements, interstices can be found between objects.
2213 ;; That's why, along with the parser, successor functions are provided
2214 ;; for each object. Some objects share the same successor (i.e. `code'
2215 ;; and `verbatim' objects).
2216 ;;
2217 ;; A successor must accept a single argument bounding the search. It
2218 ;; will return either a cons cell whose CAR is the object's type, as
2219 ;; a symbol, and CDR the position of its next occurrence, or nil.
2220 ;;
2221 ;; Successors follow the naming convention:
2222 ;; org-element-NAME-successor, where NAME is the name of the
2223 ;; successor, as defined in `org-element-all-successors'.
2224 ;;
2225 ;; Some object types (i.e. `italic') are recursive. Restrictions on
2226 ;; object types they can contain will be specified in
2227 ;; `org-element-object-restrictions'.
2228 ;;
2229 ;; Adding a new type of object is simple. Implement a successor,
2230 ;; a parser, and an interpreter for it, all following the naming
2231 ;; convention. Register type in `org-element-all-objects' and
2232 ;; successor in `org-element-all-successors'. Maybe tweak
2233 ;; restrictions about it, and that's it.
2236 ;;;; Bold
2239 "Parse bold object at point.
2241 Return a list whose CAR is `bold' and CDR is a plist with
2242 `:begin', `:end', `:contents-begin' and `:contents-end' and
2243 `:post-blank' keywords.
2245 Assume point is at the first star marker."
2257 :end end
2258 :contents-begin contents-begin
2259 :contents-end contents-end
2263 "Interpret BOLD object as Org syntax.
2264 CONTENTS is the contents of the object."
2268 "Search for the next text-markup object.
2270 LIMIT bounds the search.
2272 Return value is a cons cell whose CAR is a symbol among `bold',
2273 `italic', `underline', `strike-through', `code' and `verbatim'
2274 and CDR is beginning position."
2290 ;;;; Code
2293 "Parse code object at point.
2295 Return a list whose CAR is `code' and CDR is a plist with
2296 `:value', `:begin', `:end' and `:post-blank' keywords.
2298 Assume point is at the first tilde marker."
2309 :begin begin
2310 :end end
2314 "Interpret CODE object as Org syntax.
2315 CONTENTS is nil."
2319 ;;;; Entity
2322 "Parse entity at point.
2324 Return a list whose CAR is `entity' and CDR a plist with
2325 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
2326 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
2327 keywords.
2329 Assume point is at the beginning of the entity."
2331 (looking-at "\\\\\\(there4\\|sup[123]\\|frac[13][24]\\|[a-zA-Z]+\\)\\($\\|{}\\|[^[:alpha:]]\\)")
2347 :begin begin
2348 :end end
2349 :use-brackets-p bracketsp
2353 "Interpret ENTITY object as Org syntax.
2354 CONTENTS is nil."
2360 "Search for the next latex-fragment or entity object.
2362 LIMIT bounds the search.
2364 Return value is a cons cell whose CAR is `entity' or
2365 `latex-fragment' and CDR is beginning position."
2369 ;; ENTITY-RE matches both LaTeX commands and Org entities.
2376 limit t)
2379 ;; Determine if it's a real entity or a LaTeX command.
2382 ;; No entity nor command: point is at a LaTeX fragment.
2383 ;; Determine its type to get the correct beginning position.
2391 matchers)
2395 ;;;; Export Snippet
2398 "Parse export snippet at point.
2400 Return a list whose CAR is `export-snippet' and CDR a plist with
2401 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
2402 keywords.
2404 Assume point is at the beginning of the snippet."
2416 :value value
2417 :begin begin
2418 :end end
2422 "Interpret EXPORT-SNIPPET object as Org syntax.
2423 CONTENTS is nil."
2429 "Search for the next export-snippet object.
2431 LIMIT bounds the search.
2433 Return value is a cons cell whose CAR is `export-snippet' and CDR
2434 its beginning position."
2443 ;;;; Footnote Reference
2446 "Parse footnote reference at point.
2448 Return a list whose CAR is `footnote-reference' and CDR a plist
2449 with `:label', `:type', `:inline-definition', `:begin', `:end'
2450 and `:post-blank' as keywords."
2472 :type type
2473 :begin begin
2474 :end end
2477 footnote-reference :inline-definition
2482 footnote-reference))))))
2485 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
2486 CONTENTS is nil."
2496 "Search for the next footnote-reference object.
2498 LIMIT bounds the search.
2500 Return value is a cons cell whose CAR is `footnote-reference' and
2501 CDR is beginning position."
2515 ;;;; Inline Babel Call
2518 "Parse inline babel call at point.
2520 Return a list whose CAR is `inline-babel-call' and CDR a plist
2521 with `:begin', `:end', `:info' and `:post-blank' as keywords.
2523 Assume point is at the beginning of the babel call."
2534 :end end
2535 :info info
2539 "Interpret INLINE-BABEL-CALL object as Org syntax.
2540 CONTENTS is nil."
2546 ;; Remove redundant square brackets.
2549 main-source)
2553 "Search for the next inline-babel-call object.
2555 LIMIT bounds the search.
2557 Return value is a cons cell whose CAR is `inline-babel-call' and
2558 CDR is beginning position."
2560 ;; Use a simplified version of
2561 ;; `org-babel-inline-lob-one-liner-regexp'.
2564 limit t)
2568 ;;;; Inline Src Block
2571 "Parse inline source block at point.
2573 LIMIT bounds the search.
2575 Return a list whose CAR is `inline-src-block' and CDR a plist
2576 with `:begin', `:end', `:language', `:value', `:parameters' and
2577 `:post-blank' as keywords.
2579 Assume point is at the beginning of the inline src block."
2592 :value value
2593 :parameters parameters
2594 :begin begin
2595 :end end
2599 "Interpret INLINE-SRC-BLOCK object as Org syntax.
2600 CONTENTS is nil."
2605 language
2607 body)))
2610 "Search for the next inline-babel-call element.
2612 LIMIT bounds the search.
2614 Return value is a cons cell whose CAR is `inline-babel-call' and
2615 CDR is beginning position."
2620 ;;;; Italic
2623 "Parse italic object at point.
2625 Return a list whose CAR is `italic' and CDR is a plist with
2626 `:begin', `:end', `:contents-begin' and `:contents-end' and
2627 `:post-blank' keywords.
2629 Assume point is at the first slash marker."
2641 :end end
2642 :contents-begin contents-begin
2643 :contents-end contents-end
2647 "Interpret ITALIC object as Org syntax.
2648 CONTENTS is the contents of the object."
2652 ;;;; Latex Fragment
2655 "Parse latex fragment at point.
2657 Return a list whose CAR is `latex-fragment' and CDR a plist with
2658 `:value', `:begin', `:end', and `:post-blank' as keywords.
2660 Assume point is at the beginning of the latex fragment."
2674 ;; None found: it's a macro.
2683 :begin begin
2684 :end end
2688 "Interpret LATEX-FRAGMENT object as Org syntax.
2689 CONTENTS is nil."
2692 ;;;; Line Break
2695 "Parse line break at point.
2697 Return a list whose CAR is `line-break', and CDR a plist with
2698 `:begin', `:end' and `:post-blank' keywords.
2700 Assume point is at the beginning of the line break."
2704 "Interpret LINE-BREAK object as Org syntax.
2705 CONTENTS is nil."
2709 "Search for the next line-break object.
2711 LIMIT bounds the search.
2713 Return value is a cons cell whose CAR is `line-break' and CDR is
2714 beginning position."
2718 ;; A line break can only happen on a non-empty line.
2723 ;;;; Link
2726 "Parse link at point.
2728 Return a list whose CAR is `link' and CDR a plist with `:type',
2729 `:path', `:raw-link', `:application', `:search-option', `:begin',
2730 `:end', `:contents-begin', `:contents-end' and `:post-blank' as
2731 keywords.
2733 Assume point is at the beginning of the link."
2736 end contents-begin contents-end link-end post-blank path type
2737 raw-link link search-option application)
2739 ;; Type 1: Text targeted from a radio target.
2744 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
2749 ;; RAW-LINK is the original link.
2754 ;; Determine TYPE of link and set PATH accordingly.
2756 ;; File type.
2759 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
2762 ;; Id type: PATH is the id.
2765 ;; Code-ref type: PATH is the name of the reference.
2768 ;; Custom-id type: PATH is the name of the custom id.
2771 ;; Fuzzy type: Internal link either matches a target, an
2772 ;; headline name or nothing. PATH is the target or
2773 ;; headline's name.
2775 ;; Type 3: Plain link, i.e. http://orgmode.org
2781 ;; Type 4: Angular link, i.e. <http://orgmode.org>
2788 ;; In any case, deduce end point after trailing white space from
2789 ;; LINK-END variable.
2792 ;; Extract search option and opening application out of
2793 ;; "file"-type links.
2795 ;; Application.
2800 ;; Extract search option from PATH.
2804 ;; Make sure TYPE always report "file".
2808 :path path
2810 :application application
2811 :search-option search-option
2812 :begin begin
2813 :end end
2814 :contents-begin contents-begin
2815 :contents-end contents-end
2819 "Interpret LINK object as Org syntax.
2820 CONTENTS is the contents of the object, or nil."
2825 raw-link
2829 "Search for the next link object.
2831 LIMIT bounds the search.
2833 Return value is a cons cell whose CAR is `link' and CDR is
2834 beginning position."
2843 ;;;; Macro
2846 "Parse macro at point.
2848 Return a list whose CAR is `macro' and CDR a plist with `:key',
2849 `:args', `:begin', `:end', `:value' and `:post-blank' as
2850 keywords.
2852 Assume point is at the macro."
2866 ;; Repair bad splits.
2874 :value value
2875 :args args
2876 :begin begin
2877 :end end
2881 "Interpret MACRO object as Org syntax.
2882 CONTENTS is nil."
2886 "Search for the next macro object.
2888 LIMIT bounds the search.
2890 Return value is cons cell whose CAR is `macro' and CDR is
2891 beginning position."
2895 limit t)
2899 ;;;; Radio-target
2902 "Parse radio target at point.
2904 Return a list whose CAR is `radio-target' and CDR a plist with
2905 `:begin', `:end', `:contents-begin', `:contents-end', `:value'
2906 and `:post-blank' as keywords.
2908 Assume point is at the radio target."
2920 :end end
2921 :contents-begin contents-begin
2922 :contents-end contents-end
2923 :post-blank post-blank
2927 "Interpret TARGET object as Org syntax.
2928 CONTENTS is the contents of the object."
2932 "Search for the next radio-target object.
2934 LIMIT bounds the search.
2936 Return value is a cons cell whose CAR is `radio-target' and CDR
2937 is beginning position."
2943 ;;;; Statistics Cookie
2946 "Parse statistics cookie at point.
2948 Return a list whose CAR is `statistics-cookie', and CDR a plist
2949 with `:begin', `:end', `:value' and `:post-blank' keywords.
2951 Assume point is at the beginning of the statistics-cookie."
2962 :end end
2963 :value value
2967 "Interpret STATISTICS-COOKIE object as Org syntax.
2968 CONTENTS is nil."
2972 "Search for the next statistics cookie object.
2974 LIMIT bounds the search.
2976 Return value is a cons cell whose CAR is `statistics-cookie' and
2977 CDR is beginning position."
2983 ;;;; Strike-Through
2986 "Parse strike-through object at point.
2988 Return a list whose CAR is `strike-through' and CDR is a plist
2989 with `:begin', `:end', `:contents-begin' and `:contents-end' and
2990 `:post-blank' keywords.
2992 Assume point is at the first plus sign marker."
3004 :end end
3005 :contents-begin contents-begin
3006 :contents-end contents-end
3010 "Interpret STRIKE-THROUGH object as Org syntax.
3011 CONTENTS is the contents of the object."
3015 ;;;; Subscript
3018 "Parse subscript at point.
3020 Return a list whose CAR is `subscript' and CDR a plist with
3021 `:begin', `:end', `:contents-begin', `:contents-end',
3022 `:use-brackets-p' and `:post-blank' as keywords.
3024 Assume point is at the underscore."
3028 t
3039 :end end
3040 :use-brackets-p bracketsp
3041 :contents-begin contents-begin
3042 :contents-end contents-end
3046 "Interpret SUBSCRIPT object as Org syntax.
3047 CONTENTS is the contents of the object."
3050 contents))
3053 "Search for the next sub/superscript object.
3055 LIMIT bounds the search.
3057 Return value is a cons cell whose CAR is either `subscript' or
3058 `superscript' and CDR is beginning position."
3065 ;;;; Superscript
3068 "Parse superscript at point.
3070 Return a list whose CAR is `superscript' and CDR a plist with
3071 `:begin', `:end', `:contents-begin', `:contents-end',
3072 `:use-brackets-p' and `:post-blank' as keywords.
3074 Assume point is at the caret."
3088 :end end
3089 :use-brackets-p bracketsp
3090 :contents-begin contents-begin
3091 :contents-end contents-end
3095 "Interpret SUPERSCRIPT object as Org syntax.
3096 CONTENTS is the contents of the object."
3099 contents))
3102 ;;;; Table Cell
3105 "Parse table cell at point.
3107 Return a list whose CAR is `table-cell' and CDR is a plist
3108 containing `:begin', `:end', `:contents-begin', `:contents-end'
3109 and `:post-blank' keywords."
3117 :end end
3118 :contents-begin contents-begin
3119 :contents-end contents-end
3123 "Interpret TABLE-CELL element as Org syntax.
3124 CONTENTS is the contents of the cell, or nil."
3128 "Search for the next table-cell object.
3130 LIMIT bounds the search.
3132 Return value is a cons cell whose CAR is `table-cell' and CDR is
3133 beginning position."
3137 ;;;; Target
3140 "Parse target at point.
3142 Return a list whose CAR is `target' and CDR a plist with
3143 `:begin', `:end', `:value' and `:post-blank' as keywords.
3145 Assume point is at the target."
3155 :end end
3156 :value value
3160 "Interpret TARGET object as Org syntax.
3161 CONTENTS is nil."
3165 "Search for the next target object.
3167 LIMIT bounds the search.
3169 Return value is a cons cell whose CAR is `target' and CDR is
3170 beginning position."
3176 ;;;; Timestamp
3179 "Parse time stamp at point.
3181 Return a list whose CAR is `timestamp', and CDR a plist with
3182 `:type', `:begin', `:end', `:value' and `:post-blank' keywords.
3184 Assume point is at the beginning of the timestamp."
3203 :value main-value
3204 :range-end range-end
3205 :begin begin
3206 :end end
3210 "Interpret TIMESTAMP object as Org syntax.
3211 CONTENTS is nil."
3220 range-end)))))))
3223 "Search for the next timestamp object.
3225 LIMIT bounds the search.
3227 Return value is a cons cell whose CAR is `timestamp' and CDR is
3228 beginning position."
3236 limit t)
3240 ;;;; Underline
3243 "Parse underline object at point.
3245 Return a list whose CAR is `underline' and CDR is a plist with
3246 `:begin', `:end', `:contents-begin' and `:contents-end' and
3247 `:post-blank' keywords.
3249 Assume point is at the first underscore marker."
3261 :end end
3262 :contents-begin contents-begin
3263 :contents-end contents-end
3267 "Interpret UNDERLINE object as Org syntax.
3268 CONTENTS is the contents of the object."
3272 ;;;; Verbatim
3275 "Parse verbatim object at point.
3277 Return a list whose CAR is `verbatim' and CDR is a plist with
3278 `:value', `:begin', `:end' and `:post-blank' keywords.
3280 Assume point is at the first equal sign marker."
3291 :begin begin
3292 :end end
3296 "Interpret VERBATIM object as Org syntax.
3297 CONTENTS is nil."
3301 \f
3302 ;;; Parsing Element Starting At Point
3303 ;;
3304 ;; `org-element--current-element' is the core function of this section.
3305 ;; It returns the Lisp representation of the element starting at
3306 ;; point.
3307 ;;
3308 ;; `org-element--current-element' makes use of special modes. They
3309 ;; are activated for fixed element chaining (i.e. `plain-list' >
3310 ;; `item') or fixed conditional element chaining (i.e. `headline' >
3311 ;; `section'). Special modes are: `first-section', `section',
3312 ;; `quote-section', `item' and `table-row'.
3316 "Parse the element starting at point.
3318 LIMIT bounds the search.
3320 Return value is a list like (TYPE PROPS) where TYPE is the type
3321 of the element and PROPS a plist of properties associated to the
3322 element.
3324 Possible types are defined in `org-element-all-elements'.
3326 Optional argument GRANULARITY determines the depth of the
3327 recursion. Allowed values are `headline', `greater-element',
3328 `element', `object' or nil. When it is broader than `object' (or
3329 nil), secondary values will not be parsed, since they only
3330 contain objects.
3332 Optional argument SPECIAL, when non-nil, can be either
3333 `first-section', `section', `quote-section', `table-row' and
3334 `item'.
3336 If STRUCTURE isn't provided but SPECIAL is set to `item', it will
3337 be computed.
3339 This function assumes point is always at the beginning of the
3340 element it has to parse."
3342 ;; If point is at an affiliated keyword, try moving to the
3343 ;; beginning of the associated element. If none is found, the
3344 ;; keyword is orphaned and will be treated as plain text.
3350 ;; Determine if parsing depth allows for secondary strings
3351 ;; parsing. It only applies to elements referenced in
3352 ;; `org-element-secondary-value-alist'.
3355 ;; Item.
3358 ;; Table Row.
3360 ;; Headline.
3363 ;; Sections (must be checked after headline).
3369 limit)))
3370 ;; Planning and Clock.
3375 ;; Inlinetask.
3378 ;; LaTeX Environment.
3384 nil t))
3387 ;; Drawer and Property Drawer.
3397 ;; Fixed Width
3400 ;; Inline Comments, Blocks, Babel Calls, Dynamic Blocks and
3401 ;; Keywords.
3410 org-element-block-name-alist)))
3425 ;; Footnote Definition.
3428 ;; Horizontal Rule.
3431 ;; Table.
3433 ;; List.
3436 ;; Default element: Paragraph.
3440 ;; Most elements can have affiliated keywords. When looking for an
3441 ;; element beginning, we want to move before them, as they belong to
3442 ;; that element, and, in the meantime, collect information they give
3443 ;; into appropriate properties. Hence the following function.
3444 ;;
3445 ;; Usage of optional arguments may not be obvious at first glance:
3446 ;;
3447 ;; - TRANS-LIST is used to polish keywords names that have evolved
3448 ;; during Org history. In example, even though =result= and
3449 ;; =results= coexist, we want to have them under the same =result=
3450 ;; property. It's also true for "srcname" and "name", where the
3451 ;; latter seems to be preferred nowadays (thus the "name" property).
3452 ;;
3453 ;; - CONSED allows to regroup multi-lines keywords under the same
3454 ;; property, while preserving their own identity. This is mostly
3455 ;; used for "attr_latex" and al.
3456 ;;
3457 ;; - PARSED prepares a keyword value for export. This is useful for
3458 ;; "caption". Objects restrictions for such keywords are defined in
3459 ;; `org-element-object-restrictions'.
3460 ;;
3461 ;; - DUALS is used to take care of keywords accepting a main and an
3462 ;; optional secondary values. For example "results" has its
3463 ;; source's name as the main value, and may have an hash string in
3464 ;; optional square brackets as the secondary one.
3465 ;;
3466 ;; A keyword may belong to more than one category.
3470 "Collect affiliated keywords before point.
3472 Optional argument KEY-RE is a regexp matching keywords, which
3473 puts matched keyword in group 1. It defaults to
3474 `org-element--affiliated-re'.
3476 TRANS-LIST is an alist where key is the keyword and value the
3477 property name it should be translated to, without the colons. It
3478 defaults to `org-element-keyword-translation-alist'.
3480 CONSED is a list of strings. Any keyword belonging to that list
3481 will have its value consed. The check is done after keyword
3482 translation. It defaults to `org-element-multiple-keywords'.
3484 PARSED is a list of strings. Any keyword member of this list
3485 will have its value parsed. The check is done after keyword
3486 translation. If a keyword is a member of both CONSED and PARSED,
3487 it's value will be a list of parsed strings. It defaults to
3488 `org-element-parsed-keywords'.
3490 DUALS is a list of strings. Any keyword member of this list can
3491 have two parts: one mandatory and one optional. Its value is
3492 a cons cell whose CAR is the former, and the CDR the latter. If
3493 a keyword is a member of both PARSED and DUALS, both values will
3494 be parsed. It defaults to `org-element-dual-keywords'.
3496 Return a list whose CAR is the position at the first of them and
3497 CDR a plist of keywords and values."
3505 ;; RESTRICT is the list of objects allowed in parsed
3506 ;; keywords value.
3508 output)
3512 ;; Apply translation to RAW-KWD. From there, KWD is
3513 ;; the official keyword.
3515 ;; Find main value for any keyword.
3521 ;; If KWD is a dual keyword, find its secondary
3522 ;; value. Maybe parse it.
3528 ;; Attribute a property name to KWD.
3530 ;; Now set final shape for VALUE.
3534 ;; VALUE is mandatory. Set it to nil if there is none.
3536 ;; Attributes are always consed.
3539 ;; Eventually store the new value in OUTPUT.
3545 \f
3546 ;;; The Org Parser
3547 ;;
3548 ;; The two major functions here are `org-element-parse-buffer', which
3549 ;; parses Org syntax inside the current buffer, taking into account
3550 ;; region, narrowing, or even visibility if specified, and
3551 ;; `org-element-parse-secondary-string', which parses objects within
3552 ;; a given string.
3553 ;;
3554 ;; The (almost) almighty `org-element-map' allows to apply a function
3555 ;; on elements or objects matching some type, and accumulate the
3556 ;; resulting values. In an export situation, it also skips unneeded
3557 ;; parts of the parse tree.
3560 "Recursively parse the buffer and return structure.
3561 If narrowing is in effect, only parse the visible part of the
3562 buffer.
3564 Optional argument GRANULARITY determines the depth of the
3565 recursion. It can be set to the following symbols:
3567 `headline' Only parse headlines.
3568 `greater-element' Don't recurse into greater elements excepted
3569 headlines and sections. Thus, elements
3570 parsed are the top-level ones.
3571 `element' Parse everything but objects and plain text.
3572 `object' Parse the complete buffer (default).
3574 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3575 elements.
3577 Assume buffer is in Org mode."
3583 ;; Start in `first-section' mode so text before the first
3584 ;; headline belongs to a section.
3588 "Recursively parse objects in STRING and return structure.
3590 RESTRICTION is a symbol limiting the object types that will be
3591 looked after.
3593 Optional argument PARENT, when non-nil, is the element or object
3594 containing the secondary string. It is used to set correctly
3595 `:parent' property within the string."
3601 secondary))))
3604 "Map a function on selected elements or objects.
3606 DATA is the parsed tree, as returned by, i.e,
3607 `org-element-parse-buffer'. TYPES is a symbol or list of symbols
3608 of elements or objects types. FUN is the function called on the
3609 matching element or object. It must accept one arguments: the
3610 element or object itself.
3612 When optional argument INFO is non-nil, it should be a plist
3613 holding export options. In that case, parts of the parse tree
3614 not exportable according to that property list will be skipped.
3616 When optional argument FIRST-MATCH is non-nil, stop at the first
3617 match for which FUN doesn't return nil, and return that value.
3619 Optional argument NO-RECURSION is a symbol or a list of symbols
3620 representing elements or objects types. `org-element-map' won't
3621 enter any recursive element or object whose type belongs to that
3622 list. Though, FUN can still be applied on them.
3624 Nil values returned from FUN do not appear in the results."
3625 ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
3628 ;; Recursion depth is determined by --CATEGORY.
3635 ;; If one object is found, the function
3636 ;; has to recurse into every object.
3639 ;; If one regular element is found, the
3640 ;; function has to recurse, at least,
3641 ;; into every element it encounters.
3644 types)
3645 category)))
3646 --acc
3647 --walk-tree
3651 ;; Recursively walk DATA. INFO, if non-nil, is a plist
3652 ;; holding contextual information.
3656 ;; Ignored element in an export context.
3658 ;; Secondary string: only objects can be found there.
3661 ;; Unconditionally enter parse trees.
3665 ;; Check if TYPE is matching among TYPES. If so,
3666 ;; apply FUN to --DATA and accumulate return value
3667 ;; into --ACC (or exit if FIRST-MATCH is non-nil).
3673 ;; If --DATA has a secondary string that can contain
3674 ;; objects with their type among TYPES, look into it.
3681 ;; Determine if a recursion into --DATA is possible.
3683 ;; --TYPE is explicitly removed from recursion.
3685 ;; --DATA has no contents.
3687 ;; Looking for greater elements but --DATA is simply
3688 ;; an element or an object.
3691 ;; Looking for elements but --DATA is an object.
3694 ;; In any other case, map contents.
3698 ;; Return value in a proper order.
3701 ;; The following functions are internal parts of the parser.
3702 ;;
3703 ;; The first one, `org-element--parse-elements' acts at the element's
3704 ;; level.
3705 ;;
3706 ;; The second one, `org-element--parse-objects' applies on all objects
3707 ;; of a paragraph or a secondary string. It uses
3708 ;; `org-element--get-next-object-candidates' to optimize the search of
3709 ;; the next object in the buffer.
3710 ;;
3711 ;; More precisely, that function looks for every allowed object type
3712 ;; first. Then, it discards failed searches, keeps further matches,
3713 ;; and searches again types matched behind point, for subsequent
3714 ;; calls. Thus, searching for a given type fails only once, and every
3715 ;; object is searched only once at top level (but sometimes more for
3716 ;; nested types).
3720 "Parse elements between BEG and END positions.
3722 SPECIAL prioritize some elements over the others. It can be set
3723 to `first-section', `quote-section', `section' `item' or
3724 `table-row'.
3726 When value is `item', STRUCTURE will be used as the current list
3727 structure.
3729 GRANULARITY determines the depth of the recursion. See
3730 `org-element-parse-buffer' for more information.
3732 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3733 elements.
3735 Elements are accumulated into ACC."
3738 ;; When parsing only headlines, skip any text before first one.
3741 ;; Main loop start.
3743 ;; Find current element's type and parse it accordingly to
3744 ;; its category.
3746 end granularity special structure))
3750 ;; Fill ELEMENT contents by side-effect.
3752 ;; If VISIBLE-ONLY is true and element is hidden or if it has
3753 ;; no contents, don't modify it.
3756 ;; Greater element: parse it between `contents-begin' and
3757 ;; `contents-end'. Make sure GRANULARITY allows the
3758 ;; recursion, or ELEMENT is an headline, in which case going
3759 ;; inside is mandatory, in order to get sub-level headings.
3767 ;; Possibly switch to a special mode.
3775 granularity visible-only element))
3776 ;; ELEMENT has contents. Parse objects inside, if
3777 ;; GRANULARITY allows it.
3783 ;; Return result.
3784 acc))
3787 "Parse objects between BEG and END and return recursive structure.
3789 Objects are accumulated in ACC.
3791 RESTRICTION is a list of object types which are allowed in the
3792 current object."
3798 end restriction candidates)))
3805 ;; 1. Text before any object. Untabify it.
3810 acc
3814 ;; 2. Object...
3817 ;; Fill contents of NEXT-OBJECT by side-effect, if it has
3818 ;; a recursive type.
3823 cont-beg
3830 ;; 3. Text after last object. Untabify it.
3834 acc
3838 ;; Result.
3839 acc)))
3842 "Return an alist of candidates for the next object.
3844 LIMIT bounds the search, and RESTRICTION narrows candidates to
3845 some object types.
3847 Return value is an alist whose CAR is position and CDR the object
3848 type, as a symbol.
3850 OBJECTS is the previous candidates alist."
3852 ;; If no previous result, search every object type in RESTRICTION.
3853 ;; Otherwise, keep potential candidates (old objects located after
3854 ;; point) and ask to search again those which had matched before.
3859 objects))
3860 ;; Call the appropriate successor function for each type to search
3861 ;; and accumulate matches.
3868 type))))
3871 types-to-search)
3872 ;; Return alist.
3873 next-candidates))
3876 \f
3877 ;;; Towards A Bijective Process
3878 ;;
3879 ;; The parse tree obtained with `org-element-parse-buffer' is really
3880 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
3881 ;; interpreted and expanded into a string with canonical Org syntax.
3882 ;; Hence `org-element-interpret-data'.
3883 ;;
3884 ;; The function relies internally on
3885 ;; `org-element--interpret-affiliated-keywords'.
3887 ;;;###autoload
3889 "Interpret DATA as Org syntax.
3891 DATA is a parse tree, an element, an object or a secondary string
3892 to interpret.
3894 Optional argument PARENT is used for recursive calls. It contains
3895 the element or object containing data, or nil.
3897 Return Org syntax as a string."
3901 ;; Secondary string.
3906 ;; Full Org document.
3911 ;; Plain text.
3913 ;; Element/Object without contents.
3916 data nil))
3917 ;; Element/Object with contents.
3927 ;; Elements directly containing objects must
3928 ;; have their indentation normalized first.
3930 data
3931 ;; When normalizing first paragraph of an
3932 ;; item or a footnote-definition, ignore
3933 ;; first line's indentation.
3940 data
3942 contents)))))))
3944 ;; Build white spaces. If no `:post-blank' property is
3945 ;; specified, assume its value is 0.
3955 "Return ELEMENT's affiliated keywords as Org syntax.
3956 If there is no affiliated keyword, return the empty string."
3966 ": "
3969 value)
3977 ;; All attribute keywords can have multiple lines.
3980 value
3983 ;; List all ELEMENT's properties matching an attribute line or an
3984 ;; affiliated keyword, but ignore translated keywords since they
3985 ;; cannot belong to the property list.
3992 org-element-keyword-translation-alist)))))
3993 collect prop)
3996 ;; Because interpretation of the parse tree must return the same
3997 ;; number of blank lines between elements and the same number of white
3998 ;; space after objects, some special care must be given to white
3999 ;; spaces.
4000 ;;
4001 ;; The first function, `org-element-normalize-string', ensures any
4002 ;; string different from the empty string will end with a single
4003 ;; newline character.
4004 ;;
4005 ;; The second function, `org-element-normalize-contents', removes
4006 ;; global indentation from the contents of the current element.
4009 "Ensure string S ends with a single newline character.
4011 If S isn't a string return it unchanged. If S is the empty
4012 string, return it. Otherwise, return a new string with a single
4013 newline character at its end."
4021 "Normalize plain text in ELEMENT's contents.
4023 ELEMENT must only contain plain text and objects.
4025 If optional argument IGNORE-FIRST is non-nil, ignore first line's
4026 indentation to compute maximal common indentation.
4028 Return the normalized element that is element with global
4029 indentation removed from its contents. The function assumes that
4030 indentation is not done with TAB characters."
4032 collect-inds ; for byte-compiler
4035 ;; Return list of indentations within BLOB. This is done by
4036 ;; walking recursively BLOB and updating IND-LIST along the
4037 ;; way. FIRST-FLAG is non-nil when the first string hasn't
4038 ;; been seen yet. It is required as this string is the only
4039 ;; one whose indentation doesn't happen after a newline
4040 ;; character.
4048 ;; An indentation of zero means no string will be
4049 ;; modified. Quit the process.
4055 ;; Avoid matching blank or empty lines.
4063 ;; Collect indentation list in ELEMENT. Possibly remove first
4064 ;; value if IGNORE-FIRST is non-nil.
4067 ;; Build ELEMENT back, replacing each string with the same
4068 ;; string minus common indentation.
4073 ;; Return BLOB with all its strings indentation
4074 ;; shortened from MCI white spaces. FIRST-FLAG is
4075 ;; non-nil when the first string hasn't been seen
4076 ;; yet.
4090 org-element-recursive-objects)
4094 blob))))
4098 \f
4099 ;;; The Toolbox
4100 ;;
4101 ;; The first move is to implement a way to obtain the smallest element
4102 ;; containing point. This is the job of `org-element-at-point'. It
4103 ;; basically jumps back to the beginning of section containing point
4104 ;; and moves, element after element, with
4105 ;; `org-element--current-element' until the container is found. Note:
4106 ;; When using `org-element-at-point', secondary values are never
4107 ;; parsed since the function focuses on elements, not on objects.
4108 ;;
4109 ;; At a deeper level, `org-element-context' lists all elements and
4110 ;; objects containing point.
4111 ;;
4112 ;; `org-element-nested-p' and `org-element-swap-A-B' may be used
4113 ;; internally by navigation and manipulation tools.
4115 ;;;###autoload
4117 "Determine closest element around point.
4119 Return value is a list like (TYPE PROPS) where TYPE is the type
4120 of the element and PROPS a plist of properties associated to the
4121 element.
4123 Possible types are defined in `org-element-all-elements'.
4124 Properties depend on element or object type, but always
4125 include :begin, :end, :parent and :post-blank properties.
4127 As a special case, if point is at the very beginning of a list or
4128 sub-list, returned element will be that list instead of the first
4129 item. In the same way, if point is at the beginning of the first
4130 row of a table, returned element will be the table instead of the
4131 first row.
4133 If optional argument KEEP-TRAIL is non-nil, the function returns
4134 a list of of elements leading to element at point. The list's
4135 CAR is always the element at point. Following positions contain
4136 element's siblings, then parents, siblings of parents, until the
4137 first element of current section."
4139 ;; If at an headline, parse it. It is the sole element that
4140 ;; doesn't require to know about context. Be sure to disallow
4141 ;; secondary string parsing, though.
4147 ;; Otherwise move at the beginning of the section containing
4148 ;; point.
4152 element type special-flag trail struct prevs parent)
4160 ;; Parse successively each element, skipping those ending
4161 ;; before original position.
4170 ;; 1. Skip any element ending before point. Also skip
4171 ;; element ending at point when we're sure that another
4172 ;; element has started.
4177 ;; 2. An element containing point is always the element at
4178 ;; point.
4181 ;; 3. At any other greater element type, if point is
4182 ;; within contents, move into it.
4187 ;; Create an anchor for tables and plain lists:
4188 ;; when point is at the very beginning of these
4189 ;; elements, ignoring affiliated keywords,
4190 ;; target them instead of their contents.
4192 ;; When point is at contents end, do not move
4193 ;; into elements with an explicit ending, but
4194 ;; return that element instead.
4198 drawer dynamic-block inlinetask item
4199 plain-list quote-block special-block))))
4211 ;;;###autoload
4213 "Return closest element or object around point.
4215 Return value is a list like (TYPE PROPS) where TYPE is the type
4216 of the element or object and PROPS a plist of properties
4217 associated to it.
4219 Possible types are defined in `org-element-all-elements' and
4220 `org-element-all-objects'. Properties depend on element or
4221 object type, but always include :begin, :end, :parent
4222 and :post-blank properties."
4227 end)
4228 ;; Check if point is inside an element containing objects or at
4229 ;; a secondary string. In that case, move to beginning of the
4230 ;; element or secondary string and set END to the other side.
4239 (<= origin
4240 ;; `1+' is required so some
4241 ;; successors can match
4242 ;; properly their object.
4256 element
4259 candidates)
4262 end restriction candidates))
4264 candidates)))
4265 ;; If ORIGIN is before next object in element, there's
4266 ;; no point in looking further.
4275 ;; ORIGIN is after OBJECT, so skip it.
4278 ;; ORIGIN is within a non-recursive object or at an
4279 ;; object boundaries: Return that object.
4283 ;; Otherwise, move within current object and restrict
4284 ;; search to the end of its contents.
4288 parent))))))
4291 "Non-nil when elements ELEM-A and ELEM-B are nested."
4300 "Swap elements ELEM-A and ELEM-B.
4301 Assume ELEM-B is after ELEM-A in the buffer. Leave point at the
4302 end of ELEM-A."
4304 ;; There are two special cases when an element doesn't start at bol:
4305 ;; the first paragraph in an item or in a footnote definition.
4307 ;; Only a paragraph without any affiliated keyword can be moved at
4308 ;; ELEM-A position in such a situation. Note that the case of
4309 ;; a footnote definition is impossible: it cannot contain two
4310 ;; paragraphs in a row because it cannot contain a blank line.
4316 ;; In a special situation, ELEM-A will have no indentation. We'll
4317 ;; give it ELEM-B's (which will in, in turn, have no indentation).
4331 ;; Store overlays responsible for visibility status. We
4332 ;; also need to store their boundaries as they will be
4333 ;; removed from buffer.
4340 ;; Get contents.
4348 ;; Restore ex ELEM-A overlays.
4357 ;; Restore ex ELEM-B overlays.
4366 ;;; org-element.el ends here