| blob | 2f2fc45b8f16ecbc4ae762b31afff6f82c0e7f21 |
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', `example-block', `export-block', `fixed-width',
50 ;; `horizontal-rule', `keyword', `latex-environment', `node-property',
51 ;; `paragraph', `planning', `quote-section', `src-block', `table',
52 ;; `table-row' and `verse-block'. Among them, `paragraph' and
53 ;; `verse-block' types can contain Org objects and plain text.
54 ;;
55 ;; Objects are related to document's contents. Some of them are
56 ;; recursive. Associated types are of the following: `bold', `code',
57 ;; `entity', `export-snippet', `footnote-reference',
58 ;; `inline-babel-call', `inline-src-block', `italic',
59 ;; `latex-fragment', `line-break', `link', `macro', `radio-target',
60 ;; `statistics-cookie', `strike-through', `subscript', `superscript',
61 ;; `table-cell', `target', `timestamp', `underline' and `verbatim'.
62 ;;
63 ;; Some elements also have special properties whose value can hold
64 ;; objects themselves (i.e. an item tag or an headline name). Such
65 ;; values are called "secondary strings". Any object belongs to
66 ;; either an element or a secondary string.
67 ;;
68 ;; Notwithstanding affiliated keywords, each greater element, element
69 ;; and object has a fixed set of properties attached to it. Among
70 ;; them, four are shared by all types: `:begin' and `:end', which
71 ;; refer to the beginning and ending buffer positions of the
72 ;; considered element or object, `:post-blank', which holds the number
73 ;; of blank lines, or white spaces, at its end and `:parent' which
74 ;; refers to the element or object containing it. Greater elements
75 ;; and elements containing objects will also have `:contents-begin'
76 ;; and `:contents-end' properties to delimit contents.
77 ;;
78 ;; Lisp-wise, an element or an object can be represented as a list.
79 ;; It follows the pattern (TYPE PROPERTIES CONTENTS), where:
80 ;; TYPE is a symbol describing the Org element or object.
81 ;; PROPERTIES is the property list attached to it. See docstring of
82 ;; appropriate parsing function to get an exhaustive
83 ;; list.
84 ;; CONTENTS is a list of elements, objects or raw strings contained
85 ;; in the current element or object, when applicable.
86 ;;
87 ;; An Org buffer is a nested list of such elements and objects, whose
88 ;; type is `org-data' and properties is nil.
89 ;;
90 ;; The first part of this file defines Org syntax, while the second
91 ;; one provide accessors and setters functions.
92 ;;
93 ;; The next part implements a parser and an interpreter for each
94 ;; element and object type in Org syntax.
95 ;;
96 ;; The following part creates a fully recursive buffer parser. It
97 ;; also provides a tool to map a function to elements or objects
98 ;; matching some criteria in the parse tree. Functions of interest
99 ;; are `org-element-parse-buffer', `org-element-map' and, to a lesser
100 ;; extent, `org-element-parse-secondary-string'.
101 ;;
102 ;; The penultimate part is the cradle of an interpreter for the
103 ;; obtained parse tree: `org-element-interpret-data'.
104 ;;
105 ;; The library ends by furnishing `org-element-at-point' function, and
106 ;; a way to give information about document structure around point
107 ;; with `org-element-context'.
110 ;;; Code:
116 \f
117 ;;; Definitions And Rules
118 ;;
119 ;; Define elements, greater elements and specify recursive objects,
120 ;; along with the affiliated keywords recognized. Also set up
121 ;; restrictions on recursive objects combinations.
122 ;;
123 ;; These variables really act as a control center for the parsing
124 ;; process.
128 ;; Headlines, inlinetasks.
130 ;; Footnote definitions.
133 ;; Empty lines.
135 ;; Tables (any type).
137 ;; Blocks (any type), Babel calls, drawers (any type),
138 ;; fixed-width areas and keywords. Note: this is only an
139 ;; indication and need some thorough check.
141 ;; Horizontal rules.
143 ;; LaTeX environments.
145 ;; Planning and Clock lines.
147 org-deadline-string
148 org-closed-string
149 org-clock-string))
151 ;; Lists.
158 "Regexp to separate paragraphs in an Org buffer.
160 is not sufficient to know if point is at a paragraph ending. See
165 example-block export-block fixed-width footnote-definition
166 headline horizontal-rule inlinetask item keyword
167 latex-environment node-property paragraph plain-list planning
168 property-drawer quote-block quote-section section special-block
169 src-block table table-row verse-block)
174 item plain-list property-drawer quote-block section
175 special-block table)
180 latex-or-entity line-break link macro radio-target
181 statistics-cookie sub/superscript table-cell target
182 text-markup timestamp)
191 "Alist of translations between object type and successor name.
193 Sharing the same successor comes handy when, for example, the
198 inline-src-block italic line-break latex-fragment link macro
199 radio-target statistics-cookie strike-through subscript superscript
200 table-cell target timestamp underline verbatim)
205 table-cell underline)
215 "Alist between block names and the associated parsing function.
216 Names must be uppercase. Any block whose name has no association
222 Only these types can accept search options and an explicit
228 "List of affiliated keywords as strings.
234 ;; Regular affiliated keywords.
237 "Regexp matching any affiliated keyword.
239 Keyword name is put in match group 1. Moreover, if keyword
240 belongs to `org-element-dual-keywords', put the dual value in
241 match group 2.
249 "Alist of usual translations for keywords.
250 The key is the old name and the value the new one. The property
254 "List of affiliated keywords that can occur more than once in an element.
256 Their value will be consed into a list of strings, which will be
257 returned as the value of the property.
259 This list is checked after translations have been applied. See
260 `org-element-keyword-translation-alist'.
266 "List of keywords whose value can be parsed.
268 Their value will be stored as a secondary string: a list of
269 strings and objects.
271 This list is checked after translations have been applied. See
275 "List of keywords which can have a secondary value.
277 In Org syntax, they can be written with optional square brackets
278 before the colons. For example, results keyword can be
279 associated to a hash value with the following:
281 #+RESULTS[hash-string]: some-source
283 This list is checked after translations have been applied. See
290 inline-src-block latex-or-entity line-break link macro
291 radio-target sub/superscript target text-markup
292 timestamp)
294 radio-target statistics-cookie sub/superscript target text-markup
295 timestamp)
306 inline-src-block latex-or-entity line-break link macro
307 radio-target statistics-cookie sub/superscript target text-markup
308 timestamp)
311 latex-or-entity link radio-target sub/superscript target
312 text-markup timestamp)
323 latex-or-entity line-break link macro radio-target
325 "Alist of objects restrictions.
327 CAR is an element or object type containing objects and CDR is
328 a list of successors that will be called within an element or
329 object of such type.
331 For example, in a `radio-target' object, one can only find
332 entities, export snippets, latex-fragments, subscript and
333 superscript.
335 This alist also applies to secondary string. For example, an
336 `headline' type element doesn't directly contain objects, but
347 \f
348 ;;; Accessors and Setters
349 ;;
350 ;; Provide four accessors: `org-element-type', `org-element-property'
351 ;; `org-element-contents' and `org-element-restriction'.
352 ;;
353 ;; Setter functions allow to modify elements by side effect. There is
354 ;; `org-element-put-property', `org-element-set-contents',
355 ;; `org-element-set-element' and `org-element-adopt-element'. Note
356 ;; that `org-element-set-element' and `org-element-adopt-elements' are
357 ;; higher level functions since also update `:parent' property.
360 "Return type of ELEMENT.
362 The function returns the type of the element or object provided.
363 It can also return the following special value:
364 `plain-text' for a string
365 `org-data' for a complete document
366 nil in any other case."
372 "Extract the value from the PROPERTY of an ELEMENT."
376 "Extract contents from an ELEMENT."
380 "Return restriction associated to ELEMENT.
381 ELEMENT can be an element, an object or a symbol representing an
382 element or object type."
384 org-element-object-restrictions)))
387 "In ELEMENT set PROPERTY to VALUE.
388 Return modified element."
391 element)
394 "Set ELEMENT contents to CONTENTS.
395 Return modified element."
401 "Replace element or object OLD with element or object NEW.
402 The function takes care of setting `:parent' property for NEW."
403 ;; Since OLD is going to be changed into NEW by side-effect, first
404 ;; make sure that every element or object within NEW has OLD as
405 ;; parent.
408 ;; Transfer contents.
410 ;; Ensure NEW has same parent as OLD, then overwrite OLD properties
411 ;; with NEW's.
414 ;; Transfer type.
418 "Append elements to the contents of another element.
420 PARENT is an element or object. CHILDREN can be elements,
421 objects, or a strings.
423 The function takes care of setting `:parent' property for CHILD.
424 Return parent element."
426 ;; Link every child to PARENT.
430 children)
431 ;; Add CHILDREN at the end of PARENT contents.
433 parent
435 ;; Return modified PARENT element.
436 parent))
439 \f
440 ;;; Greater elements
441 ;;
442 ;; For each greater element type, we define a parser and an
443 ;; interpreter.
444 ;;
445 ;; A parser returns the element or object as the list described above.
446 ;; Most of them accepts no argument. Though, exceptions exist. Hence
447 ;; every element containing a secondary string (see
448 ;; `org-element-secondary-value-alist') will accept an optional
449 ;; argument to toggle parsing of that secondary string. Moreover,
450 ;; `item' parser requires current list's structure as its first
451 ;; element.
452 ;;
453 ;; An interpreter accepts two arguments: the list representation of
454 ;; the element or object, and its contents. The latter may be nil,
455 ;; depending on the element or object considered. It returns the
456 ;; appropriate Org syntax, as a string.
457 ;;
458 ;; Parsing functions must follow the naming convention:
459 ;; org-element-TYPE-parser, where TYPE is greater element's type, as
460 ;; defined in `org-element-greater-elements'.
461 ;;
462 ;; Similarly, interpreting functions must follow the naming
463 ;; convention: org-element-TYPE-interpreter.
464 ;;
465 ;; With the exception of `headline' and `item' types, greater elements
466 ;; cannot contain other greater elements of their own type.
467 ;;
468 ;; Beside implementing a parser and an interpreter, adding a new
469 ;; greater element requires to tweak `org-element--current-element'.
470 ;; Moreover, the newly defined type must be added to both
471 ;; `org-element-all-elements' and `org-element-greater-elements'.
474 ;;;; Center Block
477 "Parse a center block.
479 LIMIT bounds the search. AFFILIATED is a list of which CAR is
480 the buffer position at the beginning of the first affiliated
481 keyword and CDR is a plist of affiliated keywords along with
482 their value.
484 Return a list whose CAR is `center-block' and CDR is a plist
485 containing `:begin', `:end', `:hiddenp', `:contents-begin',
486 `:contents-end' and `:post-blank' keywords.
488 Assume point is at the beginning of the block."
492 ;; Incomplete block: parse it as a paragraph.
496 ;; Empty blocks have no contents.
510 :end end
511 :hiddenp hidden
512 :contents-begin contents-begin
513 :contents-end contents-end
518 "Interpret CENTER-BLOCK element as Org syntax.
519 CONTENTS is the contents of the element."
523 ;;;; Drawer
526 "Parse a drawer.
528 LIMIT bounds the search. AFFILIATED is a list of which CAR is
529 the buffer position at the beginning of the first affiliated
530 keyword and CDR is a plist of affiliated keywords along with
531 their value.
533 Return a list whose CAR is `drawer' and CDR is a plist containing
534 `:drawer-name', `:begin', `:end', `:hiddenp', `:contents-begin',
535 `:contents-end' and `:post-blank' keywords.
537 Assume point is at beginning of drawer."
540 ;; Incomplete drawer: parse it as a paragraph.
547 ;; Empty drawers have no contents.
561 :end end
562 :drawer-name name
563 :hiddenp hidden
564 :contents-begin contents-begin
565 :contents-end contents-end
570 "Interpret DRAWER element as Org syntax.
571 CONTENTS is the contents of the element."
574 contents))
577 ;;;; Dynamic Block
580 "Parse a dynamic block.
582 LIMIT bounds the search. AFFILIATED is a list of which CAR is
583 the buffer position at the beginning of the first affiliated
584 keyword and CDR is a plist of affiliated keywords along with
585 their value.
587 Return a list whose CAR is `dynamic-block' and CDR is a plist
588 containing `:block-name', `:begin', `:end', `:hiddenp',
589 `:contents-begin', `:contents-end', `:arguments' and
590 `:post-blank' keywords.
592 Assume point is at beginning of dynamic block."
595 ;; Incomplete block: parse it as a paragraph.
603 ;; Empty blocks have no contents.
617 :end end
618 :block-name name
619 :arguments arguments
620 :hiddenp hidden
621 :contents-begin contents-begin
622 :contents-end contents-end
627 "Interpret DYNAMIC-BLOCK element as Org syntax.
628 CONTENTS is the contents of the element."
633 contents))
636 ;;;; Footnote Definition
639 "Parse a footnote definition.
641 LIMIT bounds the search. AFFILIATED is a list of which CAR is
642 the buffer position at the beginning of the first affiliated
643 keyword and CDR is a plist of affiliated keywords along with
644 their value.
646 Return a list whose CAR is `footnote-definition' and CDR is
647 a plist containing `:label', `:begin' `:end', `:contents-begin',
648 `:contents-end' and `:post-blank' keywords.
650 Assume point is at the beginning of the footnote definition."
674 :begin begin
675 :end end
676 :contents-begin contents-begin
677 :contents-end contents-end
682 "Interpret FOOTNOTE-DEFINITION element as Org syntax.
683 CONTENTS is the contents of the footnote-definition."
685 " "
686 contents))
689 ;;;; Headline
692 "Parse an headline.
694 Return a list whose CAR is `headline' and CDR is a plist
695 containing `:raw-value', `:title', `:begin', `:end',
696 `:pre-blank', `:hiddenp', `:contents-begin' and `:contents-end',
697 `:level', `:priority', `:tags', `:todo-keyword',`:todo-type',
698 `:scheduled', `:deadline', `:timestamp', `:clock', `:category',
699 `:quotedp', `:archivedp', `:commentedp' and `:footnote-section-p'
700 keywords.
702 The plist also contains any property set in the property drawer,
703 with its name in lowercase, the underscores replaced with hyphens
704 and colons at the beginning (i.e. `:custom-id').
706 When RAW-SECONDARY-P is non-nil, headline's title will not be
707 parsed as a secondary string, but as a plain string instead.
709 Assume point is at beginning of the headline."
722 raw-value)))
726 raw-value)))
730 ;; Normalize property names: ":SOME_PROP:" becomes
731 ;; ":some-prop".
743 plist))
761 ;; Clean RAW-VALUE from any quote or comment string.
766 ""
767 raw-value)))
768 ;; Clean TAGS from archive tag, if any.
774 :begin begin
775 :end end
776 :pre-blank
779 :hiddenp hidden
780 :contents-begin contents-begin
781 :contents-end contents-end
782 :level level
784 :tags tags
785 :todo-keyword todo
786 :todo-type todo-type
787 :scheduled scheduled
788 :deadline deadline
789 :timestamp timestamp
790 :clock clock
796 end)
797 :footnote-section-p footnote-section-p
798 :archivedp archivedp
799 :commentedp commentedp
801 standard-props))))
803 headline :title
809 "Interpret HEADLINE element as Org syntax.
810 CONTENTS is the contents of the element."
837 ;; Align tags.
845 ? )
846 tags))
850 tags))))
852 contents)))
855 ;;;; Inlinetask
858 "Parse an inline task.
860 Return a list whose CAR is `inlinetask' and CDR is a plist
861 containing `:title', `:begin', `:end', `:hiddenp',
862 `:contents-begin' and `:contents-end', `:level', `:priority',
863 `:raw-value', `:tags', `:todo-keyword', `:todo-type',
864 `:scheduled', `:deadline', `:timestamp', `:clock' and
865 `:post-blank' keywords.
867 The plist also contains any property set in the property drawer,
868 with its name in lowercase, the underscores replaced with hyphens
869 and colons at the beginning (i.e. `:custom-id').
871 When optional argument RAW-SECONDARY-P is non-nil, inline-task's
872 title will not be parsed as a secondary string, but as a plain
873 string instead.
875 Assume point is at beginning of the inline task."
886 ;; Normalize property names: ":SOME_PROP:" becomes
887 ;; ":some-prop".
899 plist))
923 :begin begin
924 :end end
925 :hiddenp hidden
926 :contents-begin contents-begin
927 :contents-end contents-end
930 :tags tags
931 :todo-keyword todo
932 :todo-type todo-type
933 :scheduled scheduled
934 :deadline deadline
935 :timestamp timestamp
936 :clock clock
938 standard-props
941 inlinetask :title
944 raw-value
946 inlinetask))))))
949 "Interpret INLINETASK element as Org syntax.
950 CONTENTS is the contents of inlinetask."
965 ;; Align tags.
973 ? )
974 tags))
978 tags))))
979 ;; Prefer degenerate inlinetasks when there are no
980 ;; contents.
983 contents
987 ;;;; Item
990 "Parse an item.
992 STRUCT is the structure of the plain list.
994 Return a list whose CAR is `item' and CDR is a plist containing
995 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
996 `:checkbox', `:counter', `:tag', `:structure', `:hiddenp' and
997 `:post-blank' keywords.
999 When optional argument RAW-SECONDARY-P is non-nil, item's tag, if
1000 any, will not be parsed as a secondary string, but as a plain
1001 string instead.
1003 Assume point is at the beginning of the item."
1027 ;; Ignore tags in un-ordered lists: they are just
1028 ;; a part of item's body.
1034 ;; If first line isn't empty, contents really start
1035 ;; at the text after item's meta-data.
1046 :begin begin
1047 :end end
1048 ;; CONTENTS-BEGIN and CONTENTS-END may be
1049 ;; mixed up in the case of an empty item
1050 ;; separated from the next by a blank line.
1051 ;; Thus ensure the former is always the
1052 ;; smallest.
1055 :checkbox checkbox
1056 :counter counter
1057 :hiddenp hidden
1058 :structure struct
1061 item :tag
1069 "Interpret ITEM element as Org syntax.
1070 CONTENTS is the contents of the element."
1076 ;; Compute indentation.
1081 ;; Indent contents.
1083 bullet
1096 ;;;; Plain List
1099 "Parse a plain list.
1101 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1102 the buffer position at the beginning of the first affiliated
1103 keyword and CDR is a plist of affiliated keywords along with
1104 their value. STRUCTURE is the structure of the plain list being
1105 parsed.
1107 Return a list whose CAR is `plain-list' and CDR is a plist
1108 containing `:type', `:begin', `:end', `:contents-begin' and
1109 `:contents-end', `:structure' and `:post-blank' keywords.
1111 Assume point is at the beginning of the list."
1125 ;; Return value.
1129 :begin begin
1130 :end end
1131 :contents-begin contents-begin
1132 :contents-end contents-end
1133 :structure struct
1138 "Interpret PLAIN-LIST element as Org syntax.
1139 CONTENTS is the contents of the element."
1147 ;;;; Property Drawer
1150 "Parse a property drawer.
1152 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1153 the buffer position at the beginning of the first affiliated
1154 keyword and CDR is a plist of affiliated keywords along with
1155 their value.
1157 Return a list whose CAR is `property-drawer' and CDR is a plist
1158 containing `:begin', `:end', `:hiddenp', `:contents-begin',
1159 `:contents-end' and `:post-blank' keywords.
1161 Assume point is at the beginning of the property drawer."
1166 ;; Incomplete drawer: parse it as a paragraph.
1184 :end end
1185 :hiddenp hidden
1186 :contents-begin contents-begin
1187 :contents-end contents-end
1192 "Interpret PROPERTY-DRAWER element as Org syntax.
1193 CONTENTS is the properties within the drawer."
1197 ;;;; Quote Block
1200 "Parse a quote block.
1202 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1203 the buffer position at the beginning of the first affiliated
1204 keyword and CDR is a plist of affiliated keywords along with
1205 their value.
1207 Return a list whose CAR is `quote-block' and CDR is a plist
1208 containing `:begin', `:end', `:hiddenp', `:contents-begin',
1209 `:contents-end' and `:post-blank' keywords.
1211 Assume point is at the beginning of the block."
1215 ;; Incomplete block: parse it as a paragraph.
1220 ;; Empty blocks have no contents.
1234 :end end
1235 :hiddenp hidden
1236 :contents-begin contents-begin
1237 :contents-end contents-end
1242 "Interpret QUOTE-BLOCK element as Org syntax.
1243 CONTENTS is the contents of the element."
1247 ;;;; Section
1250 "Parse a section.
1252 LIMIT bounds the search.
1254 Return a list whose CAR is `section' and CDR is a plist
1255 containing `:begin', `:end', `:contents-begin', `contents-end'
1256 and `:post-blank' keywords."
1258 ;; Beginning of section is the beginning of the first non-blank
1259 ;; line after previous headline.
1268 :end end
1269 :contents-begin begin
1270 :contents-end pos-before-blank
1274 "Interpret SECTION element as Org syntax.
1275 CONTENTS is the contents of the element."
1276 contents)
1279 ;;;; Special Block
1282 "Parse a special block.
1284 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1285 the buffer position at the beginning of the first affiliated
1286 keyword and CDR is a plist of affiliated keywords along with
1287 their value.
1289 Return a list whose CAR is `special-block' and CDR is a plist
1290 containing `:type', `:begin', `:end', `:hiddenp',
1291 `:contents-begin', `:contents-end' and `:post-blank' keywords.
1293 Assume point is at the beginning of the block."
1299 ;; Incomplete block: parse it as a paragraph.
1304 ;; Empty blocks have no contents.
1318 :begin begin
1319 :end end
1320 :hiddenp hidden
1321 :contents-begin contents-begin
1322 :contents-end contents-end
1327 "Interpret SPECIAL-BLOCK element as Org syntax.
1328 CONTENTS is the contents of the element."
1333 \f
1334 ;;; Elements
1335 ;;
1336 ;; For each element, a parser and an interpreter are also defined.
1337 ;; Both follow the same naming convention used for greater elements.
1338 ;;
1339 ;; Also, as for greater elements, adding a new element type is done
1340 ;; through the following steps: implement a parser and an interpreter,
1341 ;; tweak `org-element--current-element' so that it recognizes the new
1342 ;; type and add that new type to `org-element-all-elements'.
1343 ;;
1344 ;; As a special case, when the newly defined type is a block type,
1345 ;; `org-element-block-name-alist' has to be modified accordingly.
1348 ;;;; Babel Call
1351 "Parse a babel call.
1353 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1354 the buffer position at the beginning of the first affiliated
1355 keyword and CDR is a plist of affiliated keywords along with
1356 their value.
1358 Return a list whose CAR is `babel-call' and CDR is a plist
1359 containing `:begin', `:end', `:info' and `:post-blank' as
1360 keywords."
1372 :end end
1373 :info info
1378 "Interpret BABEL-CALL element as Org syntax.
1379 CONTENTS is nil."
1385 ;; Remove redundant square brackets.
1390 ;;;; Clock
1393 "Parse a clock.
1395 LIMIT bounds the search.
1397 Return a list whose CAR is `clock' and CDR is a plist containing
1398 `:status', `:value', `:time', `:begin', `:end' and `:post-blank'
1399 as keywords."
1418 :value value
1419 :time time
1420 :begin begin
1421 :end end
1425 "Interpret CLOCK element as Org syntax.
1426 CONTENTS is nil."
1433 "%2s:%02s"
1437 ;;;; Comment
1440 "Parse a comment.
1442 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1443 the buffer position at the beginning of the first affiliated
1444 keyword and CDR is a plist of affiliated keywords along with
1445 their value.
1447 Return a list whose CAR is `comment' and CDR is a plist
1448 containing `:begin', `:end', `:value' and `:post-blank'
1449 keywords.
1451 Assume point is at comment beginning."
1459 ;; Get comments ending.
1462 ;; Accumulate lines without leading hash and first
1463 ;; whitespace.
1477 :end end
1478 :value value
1483 "Interpret COMMENT element as Org syntax.
1484 CONTENTS is nil."
1488 ;;;; Comment Block
1491 "Parse an export block.
1493 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1494 the buffer position at the beginning of the first affiliated
1495 keyword and CDR is a plist of affiliated keywords along with
1496 their value.
1498 Return a list whose CAR is `comment-block' and CDR is a plist
1499 containing `:begin', `:end', `:hiddenp', `:value' and
1500 `:post-blank' keywords.
1502 Assume point is at comment block beginning."
1506 ;; Incomplete block: parse it as a paragraph.
1519 contents-begin contents-end)))
1523 :end end
1524 :value value
1525 :hiddenp hidden
1530 "Interpret COMMENT-BLOCK element as Org syntax.
1531 CONTENTS is nil."
1536 ;;;; Example Block
1539 "Parse an example block.
1541 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1542 the buffer position at the beginning of the first affiliated
1543 keyword and CDR is a plist of affiliated keywords along with
1544 their value.
1546 Return a list whose CAR is `example-block' and CDR is a plist
1547 containing `:begin', `:end', `:number-lines', `:preserve-indent',
1548 `:retain-labels', `:use-labels', `:label-fmt', `:hiddenp',
1549 `:switches', `:value' and `:post-blank' keywords."
1553 ;; Incomplete block: parse it as a paragraph.
1560 ;; Switches analysis
1565 ;; Should labels be retained in (or stripped from) example
1566 ;; blocks?
1571 ;; What should code-references use - labels or
1572 ;; line-numbers?
1579 ;; Standard block parsing.
1592 :end end
1593 :value value
1594 :switches switches
1595 :number-lines number-lines
1596 :preserve-indent preserve-indent
1597 :retain-labels retain-labels
1598 :use-labels use-labels
1599 :label-fmt label-fmt
1600 :hiddenp hidden
1605 "Interpret EXAMPLE-BLOCK element as Org syntax.
1606 CONTENTS is nil."
1614 ;;;; Export Block
1617 "Parse an export block.
1619 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1620 the buffer position at the beginning of the first affiliated
1621 keyword and CDR is a plist of affiliated keywords along with
1622 their value.
1624 Return a list whose CAR is `export-block' and CDR is a plist
1625 containing `:begin', `:end', `:type', `:hiddenp', `:value' and
1626 `:post-blank' keywords.
1628 Assume point is at export-block beginning."
1634 ;; Incomplete block: parse it as a paragraph.
1647 contents-end)))
1651 :end end
1652 :type type
1653 :value value
1654 :hiddenp hidden
1659 "Interpret EXPORT-BLOCK element as Org syntax.
1660 CONTENTS is nil."
1667 ;;;; Fixed-width
1670 "Parse a fixed-width section.
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 `fixed-width' and CDR is a plist
1678 containing `:begin', `:end', `:value' and `:post-blank' keywords.
1680 Assume point is at the beginning of the fixed-width area."
1683 value
1688 ;; Accumulate text without starting colons.
1701 :end end
1702 :value value
1707 "Interpret FIXED-WIDTH element as Org syntax.
1708 CONTENTS is nil."
1713 ;;;; Horizontal Rule
1716 "Parse an horizontal rule.
1718 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1719 the buffer position at the beginning of the first affiliated
1720 keyword and CDR is a plist of affiliated keywords along with
1721 their value.
1723 Return a list whose CAR is `horizontal-rule' and CDR is a plist
1724 containing `:begin', `:end' and `:post-blank' keywords."
1733 :end end
1738 "Interpret HORIZONTAL-RULE element as Org syntax.
1739 CONTENTS is nil."
1743 ;;;; Keyword
1746 "Parse a keyword at point.
1748 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1749 the buffer position at the beginning of the first affiliated
1750 keyword and CDR is a plist of affiliated keywords along with
1751 their value.
1753 Return a list whose CAR is `keyword' and CDR is a plist
1754 containing `:key', `:value', `:begin', `:end' and `:post-blank'
1755 keywords."
1769 :value value
1770 :begin begin
1771 :end end
1776 "Interpret KEYWORD element as Org syntax.
1777 CONTENTS is nil."
1783 ;;;; Latex Environment
1786 "Parse a LaTeX environment.
1788 LIMIT bounds the search. AFFILIATED is a list of which CAR is
1789 the buffer position at the beginning of the first affiliated
1790 keyword and CDR is a plist of affiliated keywords along with
1791 their value.
1793 Return a list whose CAR is `latex-environment' and CDR is a plist
1794 containing `:begin', `:end', `:value' and `:post-blank'
1795 keywords.
1797 Assume point is at the beginning of the latex environment."
1814 :end end
1815 :value value
1820 "Interpret LATEX-ENVIRONMENT element as Org syntax.
1821 CONTENTS is nil."
1825 ;;;; Node Property
1828 "Parse a node-property at point.
1830 LIMIT bounds the search.
1832 Return a list whose CAR is `node-property' and CDR is a plist
1833 containing `:key', `:value', `:begin', `:end' and `:post-blank'
1834 keywords."
1846 :value value
1847 :begin begin
1848 :end end
1852 "Interpret NODE-PROPERTY element as Org syntax.
1853 CONTENTS is nil."
1859 ;;;; Paragraph
1862 "Parse a paragraph.
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 `paragraph' and CDR is a plist
1870 containing `:begin', `:end', `:contents-begin' and
1871 `:contents-end' and `:post-blank' keywords.
1873 Assume point is at the beginning of the paragraph."
1883 ;; Skip non-existent or incomplete drawer.
1891 ;; Stop at comments.
1895 ;; Skip incomplete dynamic blocks.
1902 ;; Skip incomplete blocks.
1910 limit t))))
1911 ;; Skip incomplete latex environments.
1919 limit t))))
1920 ;; Skip ill-formed keywords.
1934 :end end
1935 :contents-begin contents-begin
1936 :contents-end contents-end
1941 "Interpret PARAGRAPH element as Org syntax.
1942 CONTENTS is the contents of the element."
1943 contents)
1946 ;;;; Planning
1949 "Parse a planning.
1951 LIMIT bounds the search.
1953 Return a list whose CAR is `planning' and CDR is a plist
1954 containing `:closed', `:deadline', `:scheduled', `:begin', `:end'
1955 and `:post-blank' keywords."
1964 closed deadline scheduled)
1978 :deadline deadline
1979 :scheduled scheduled
1980 :begin begin
1981 :end end
1985 "Interpret PLANNING element as Org syntax.
1986 CONTENTS is nil."
1988 'identity
2000 ;;;; Quote Section
2003 "Parse a quote section.
2005 LIMIT bounds the search.
2007 Return a list whose CAR is `quote-section' and CDR is a plist
2008 containing `:begin', `:end', `:value' and `:post-blank' keywords.
2010 Assume point is at beginning of the section."
2021 :end end
2022 :value value
2026 "Interpret QUOTE-SECTION element as Org syntax.
2027 CONTENTS is nil."
2031 ;;;; Src Block
2034 "Parse a src block.
2036 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2037 the buffer position at the beginning of the first affiliated
2038 keyword and CDR is a plist of affiliated keywords along with
2039 their value.
2041 Return a list whose CAR is `src-block' and CDR is a plist
2042 containing `:language', `:switches', `:parameters', `:begin',
2043 `:end', `:hiddenp', `:number-lines', `:retain-labels',
2044 `:use-labels', `:label-fmt', `:preserve-indent', `:value' and
2045 `:post-blank' keywords.
2047 Assume point is at the beginning of the block."
2050 ;; Incomplete block: parse it as a paragraph.
2055 ;; Get language as a string.
2064 ;; Get switches.
2066 ;; Get parameters.
2068 ;; Switches analysis
2076 ;; Should labels be retained in (or stripped from)
2077 ;; src blocks?
2082 ;; What should code-references use - labels or
2083 ;; line-numbers?
2087 ;; Get visibility status.
2089 ;; Retrieve code.
2094 ;; Get position after ending blank lines.
2104 :begin begin
2105 :end end
2106 :number-lines number-lines
2107 :preserve-indent preserve-indent
2108 :retain-labels retain-labels
2109 :use-labels use-labels
2110 :label-fmt label-fmt
2111 :hiddenp hidden
2112 :value value
2117 "Interpret SRC-BLOCK element as Org syntax.
2118 CONTENTS is nil."
2138 value
2142 ;;;; Table
2145 "Parse a table at point.
2147 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2148 the buffer position at the beginning of the first affiliated
2149 keyword and CDR is a plist of affiliated keywords along with
2150 their value.
2152 Return a list whose CAR is `table' and CDR is a plist containing
2153 `:begin', `:end', `:tblfm', `:type', `:contents-begin',
2154 `:contents-end', `:value' and `:post-blank' keywords.
2156 Assume point is at the beginning of the table."
2168 acc))
2175 :end end
2176 :type type
2177 :tblfm tblfm
2178 ;; Only `org' tables have contents. `table.el' tables
2179 ;; use a `:value' property to store raw table as
2180 ;; a string.
2185 table-begin table-end))
2190 "Interpret TABLE element as Org syntax.
2191 CONTENTS is nil."
2202 ;;;; Table Row
2205 "Parse table row at point.
2207 LIMIT bounds the search.
2209 Return a list whose CAR is `table-row' and CDR is a plist
2210 containing `:begin', `:end', `:contents-begin', `:contents-end',
2211 `:type' and `:post-blank' keywords."
2215 ;; A table rule has no contents. In that case, ensure
2216 ;; CONTENTS-BEGIN matches CONTENTS-END.
2228 :begin begin
2229 :end end
2230 :contents-begin contents-begin
2231 :contents-end contents-end
2235 "Interpret TABLE-ROW element as Org syntax.
2236 CONTENTS is the contents of the table row."
2241 ;;;; Verse Block
2244 "Parse a verse block.
2246 LIMIT bounds the search. AFFILIATED is a list of which CAR is
2247 the buffer position at the beginning of the first affiliated
2248 keyword and CDR is a plist of affiliated keywords along with
2249 their value.
2251 Return a list whose CAR is `verse-block' and CDR is a plist
2252 containing `:begin', `:end', `:contents-begin', `:contents-end',
2253 `:hiddenp' and `:post-blank' keywords.
2255 Assume point is at beginning of the block."
2259 ;; Incomplete block: parse it as a paragraph.
2274 :end end
2275 :contents-begin contents-begin
2276 :contents-end contents-end
2277 :hiddenp hidden
2282 "Interpret VERSE-BLOCK element as Org syntax.
2283 CONTENTS is verse block contents."
2287 \f
2288 ;;; Objects
2289 ;;
2290 ;; Unlike to elements, interstices can be found between objects.
2291 ;; That's why, along with the parser, successor functions are provided
2292 ;; for each object. Some objects share the same successor (i.e. `code'
2293 ;; and `verbatim' objects).
2294 ;;
2295 ;; A successor must accept a single argument bounding the search. It
2296 ;; will return either a cons cell whose CAR is the object's type, as
2297 ;; a symbol, and CDR the position of its next occurrence, or nil.
2298 ;;
2299 ;; Successors follow the naming convention:
2300 ;; org-element-NAME-successor, where NAME is the name of the
2301 ;; successor, as defined in `org-element-all-successors'.
2302 ;;
2303 ;; Some object types (i.e. `italic') are recursive. Restrictions on
2304 ;; object types they can contain will be specified in
2305 ;; `org-element-object-restrictions'.
2306 ;;
2307 ;; Adding a new type of object is simple. Implement a successor,
2308 ;; a parser, and an interpreter for it, all following the naming
2309 ;; convention. Register type in `org-element-all-objects' and
2310 ;; successor in `org-element-all-successors'. Maybe tweak
2311 ;; restrictions about it, and that's it.
2314 ;;;; Bold
2317 "Parse bold object at point.
2319 Return a list whose CAR is `bold' and CDR is a plist with
2320 `:begin', `:end', `:contents-begin' and `:contents-end' and
2321 `:post-blank' keywords.
2323 Assume point is at the first star marker."
2335 :end end
2336 :contents-begin contents-begin
2337 :contents-end contents-end
2341 "Interpret BOLD object as Org syntax.
2342 CONTENTS is the contents of the object."
2346 "Search for the next text-markup object.
2348 LIMIT bounds the search.
2350 Return value is a cons cell whose CAR is a symbol among `bold',
2351 `italic', `underline', `strike-through', `code' and `verbatim'
2352 and CDR is beginning position."
2368 ;;;; Code
2371 "Parse code object at point.
2373 Return a list whose CAR is `code' and CDR is a plist with
2374 `:value', `:begin', `:end' and `:post-blank' keywords.
2376 Assume point is at the first tilde marker."
2387 :begin begin
2388 :end end
2392 "Interpret CODE object as Org syntax.
2393 CONTENTS is nil."
2397 ;;;; Entity
2400 "Parse entity at point.
2402 Return a list whose CAR is `entity' and CDR a plist with
2403 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
2404 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
2405 keywords.
2407 Assume point is at the beginning of the entity."
2409 (looking-at "\\\\\\(there4\\|sup[123]\\|frac[13][24]\\|[a-zA-Z]+\\)\\($\\|{}\\|[^[:alpha:]]\\)")
2425 :begin begin
2426 :end end
2427 :use-brackets-p bracketsp
2431 "Interpret ENTITY object as Org syntax.
2432 CONTENTS is nil."
2438 "Search for the next latex-fragment or entity object.
2440 LIMIT bounds the search.
2442 Return value is a cons cell whose CAR is `entity' or
2443 `latex-fragment' and CDR is beginning position."
2447 ;; ENTITY-RE matches both LaTeX commands and Org entities.
2454 limit t)
2457 ;; Determine if it's a real entity or a LaTeX command.
2460 ;; No entity nor command: point is at a LaTeX fragment.
2461 ;; Determine its type to get the correct beginning position.
2469 matchers)
2473 ;;;; Export Snippet
2476 "Parse export snippet at point.
2478 Return a list whose CAR is `export-snippet' and CDR a plist with
2479 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
2480 keywords.
2482 Assume point is at the beginning of the snippet."
2494 :value value
2495 :begin begin
2496 :end end
2500 "Interpret EXPORT-SNIPPET object as Org syntax.
2501 CONTENTS is nil."
2507 "Search for the next export-snippet object.
2509 LIMIT bounds the search.
2511 Return value is a cons cell whose CAR is `export-snippet' and CDR
2512 its beginning position."
2521 ;;;; Footnote Reference
2524 "Parse footnote reference at point.
2526 Return a list whose CAR is `footnote-reference' and CDR a plist
2527 with `:label', `:type', `:inline-definition', `:begin', `:end'
2528 and `:post-blank' as keywords."
2550 :type type
2551 :begin begin
2552 :end end
2555 footnote-reference :inline-definition
2560 footnote-reference))))))
2563 "Interpret FOOTNOTE-REFERENCE object as Org syntax.
2564 CONTENTS is nil."
2574 "Search for the next footnote-reference object.
2576 LIMIT bounds the search.
2578 Return value is a cons cell whose CAR is `footnote-reference' and
2579 CDR is beginning position."
2593 ;;;; Inline Babel Call
2596 "Parse inline babel call at point.
2598 Return a list whose CAR is `inline-babel-call' and CDR a plist
2599 with `:begin', `:end', `:info' and `:post-blank' as keywords.
2601 Assume point is at the beginning of the babel call."
2612 :end end
2613 :info info
2617 "Interpret INLINE-BABEL-CALL object as Org syntax.
2618 CONTENTS is nil."
2624 ;; Remove redundant square brackets.
2627 main-source)
2631 "Search for the next inline-babel-call object.
2633 LIMIT bounds the search.
2635 Return value is a cons cell whose CAR is `inline-babel-call' and
2636 CDR is beginning position."
2638 ;; Use a simplified version of
2639 ;; `org-babel-inline-lob-one-liner-regexp'.
2642 limit t)
2646 ;;;; Inline Src Block
2649 "Parse inline source block at point.
2651 LIMIT bounds the search.
2653 Return a list whose CAR is `inline-src-block' and CDR a plist
2654 with `:begin', `:end', `:language', `:value', `:parameters' and
2655 `:post-blank' as keywords.
2657 Assume point is at the beginning of the inline src block."
2670 :value value
2671 :parameters parameters
2672 :begin begin
2673 :end end
2677 "Interpret INLINE-SRC-BLOCK object as Org syntax.
2678 CONTENTS is nil."
2683 language
2685 body)))
2688 "Search for the next inline-babel-call element.
2690 LIMIT bounds the search.
2692 Return value is a cons cell whose CAR is `inline-babel-call' and
2693 CDR is beginning position."
2699 ;;;; Italic
2702 "Parse italic object at point.
2704 Return a list whose CAR is `italic' and CDR is a plist with
2705 `:begin', `:end', `:contents-begin' and `:contents-end' and
2706 `:post-blank' keywords.
2708 Assume point is at the first slash marker."
2720 :end end
2721 :contents-begin contents-begin
2722 :contents-end contents-end
2726 "Interpret ITALIC object as Org syntax.
2727 CONTENTS is the contents of the object."
2731 ;;;; Latex Fragment
2734 "Parse latex fragment at point.
2736 Return a list whose CAR is `latex-fragment' and CDR a plist with
2737 `:value', `:begin', `:end', and `:post-blank' as keywords.
2739 Assume point is at the beginning of the latex fragment."
2753 ;; None found: it's a macro.
2762 :begin begin
2763 :end end
2767 "Interpret LATEX-FRAGMENT object as Org syntax.
2768 CONTENTS is nil."
2771 ;;;; Line Break
2774 "Parse line break at point.
2776 Return a list whose CAR is `line-break', and CDR a plist with
2777 `:begin', `:end' and `:post-blank' keywords.
2779 Assume point is at the beginning of the line break."
2783 "Interpret LINE-BREAK object as Org syntax.
2784 CONTENTS is nil."
2788 "Search for the next line-break object.
2790 LIMIT bounds the search.
2792 Return value is a cons cell whose CAR is `line-break' and CDR is
2793 beginning position."
2797 ;; A line break can only happen on a non-empty line.
2802 ;;;; Link
2805 "Parse link at point.
2807 Return a list whose CAR is `link' and CDR a plist with `:type',
2808 `:path', `:raw-link', `:application', `:search-option', `:begin',
2809 `:end', `:contents-begin', `:contents-end' and `:post-blank' as
2810 keywords.
2812 Assume point is at the beginning of the link."
2815 end contents-begin contents-end link-end post-blank path type
2816 raw-link link search-option application)
2818 ;; Type 1: Text targeted from a radio target.
2823 ;; Type 2: Standard link, i.e. [[http://orgmode.org][homepage]]
2828 ;; RAW-LINK is the original link.
2833 ;; Determine TYPE of link and set PATH accordingly.
2835 ;; File type.
2838 ;; Explicit type (http, irc, bbdb...). See `org-link-types'.
2841 ;; Id type: PATH is the id.
2844 ;; Code-ref type: PATH is the name of the reference.
2847 ;; Custom-id type: PATH is the name of the custom id.
2850 ;; Fuzzy type: Internal link either matches a target, an
2851 ;; headline name or nothing. PATH is the target or
2852 ;; headline's name.
2854 ;; Type 3: Plain link, i.e. http://orgmode.org
2860 ;; Type 4: Angular link, i.e. <http://orgmode.org>
2867 ;; In any case, deduce end point after trailing white space from
2868 ;; LINK-END variable.
2871 ;; Extract search option and opening application out of
2872 ;; "file"-type links.
2874 ;; Application.
2879 ;; Extract search option from PATH.
2883 ;; Make sure TYPE always report "file".
2887 :path path
2889 :application application
2890 :search-option search-option
2891 :begin begin
2892 :end end
2893 :contents-begin contents-begin
2894 :contents-end contents-end
2898 "Interpret LINK object as Org syntax.
2899 CONTENTS is the contents of the object, or nil."
2904 raw-link
2908 "Search for the next link object.
2910 LIMIT bounds the search.
2912 Return value is a cons cell whose CAR is `link' and CDR is
2913 beginning position."
2922 ;;;; Macro
2925 "Parse macro at point.
2927 Return a list whose CAR is `macro' and CDR a plist with `:key',
2928 `:args', `:begin', `:end', `:value' and `:post-blank' as
2929 keywords.
2931 Assume point is at the macro."
2945 ;; Repair bad splits.
2953 :value value
2954 :args args
2955 :begin begin
2956 :end end
2960 "Interpret MACRO object as Org syntax.
2961 CONTENTS is nil."
2965 "Search for the next macro object.
2967 LIMIT bounds the search.
2969 Return value is cons cell whose CAR is `macro' and CDR is
2970 beginning position."
2974 limit t)
2978 ;;;; Radio-target
2981 "Parse radio target at point.
2983 Return a list whose CAR is `radio-target' and CDR a plist with
2984 `:begin', `:end', `:contents-begin', `:contents-end', `:value'
2985 and `:post-blank' as keywords.
2987 Assume point is at the radio target."
2999 :end end
3000 :contents-begin contents-begin
3001 :contents-end contents-end
3002 :post-blank post-blank
3006 "Interpret TARGET object as Org syntax.
3007 CONTENTS is the contents of the object."
3011 "Search for the next radio-target object.
3013 LIMIT bounds the search.
3015 Return value is a cons cell whose CAR is `radio-target' and CDR
3016 is beginning position."
3022 ;;;; Statistics Cookie
3025 "Parse statistics cookie at point.
3027 Return a list whose CAR is `statistics-cookie', and CDR a plist
3028 with `:begin', `:end', `:value' and `:post-blank' keywords.
3030 Assume point is at the beginning of the statistics-cookie."
3041 :end end
3042 :value value
3046 "Interpret STATISTICS-COOKIE object as Org syntax.
3047 CONTENTS is nil."
3051 "Search for the next statistics cookie object.
3053 LIMIT bounds the search.
3055 Return value is a cons cell whose CAR is `statistics-cookie' and
3056 CDR is beginning position."
3062 ;;;; Strike-Through
3065 "Parse strike-through object at point.
3067 Return a list whose CAR is `strike-through' and CDR is a plist
3068 with `:begin', `:end', `:contents-begin' and `:contents-end' and
3069 `:post-blank' keywords.
3071 Assume point is at the first plus sign marker."
3083 :end end
3084 :contents-begin contents-begin
3085 :contents-end contents-end
3089 "Interpret STRIKE-THROUGH object as Org syntax.
3090 CONTENTS is the contents of the object."
3094 ;;;; Subscript
3097 "Parse subscript at point.
3099 Return a list whose CAR is `subscript' and CDR a plist with
3100 `:begin', `:end', `:contents-begin', `:contents-end',
3101 `:use-brackets-p' and `:post-blank' as keywords.
3103 Assume point is at the underscore."
3107 t
3118 :end end
3119 :use-brackets-p bracketsp
3120 :contents-begin contents-begin
3121 :contents-end contents-end
3125 "Interpret SUBSCRIPT object as Org syntax.
3126 CONTENTS is the contents of the object."
3129 contents))
3132 "Search for the next sub/superscript object.
3134 LIMIT bounds the search.
3136 Return value is a cons cell whose CAR is either `subscript' or
3137 `superscript' and CDR is beginning position."
3144 ;;;; Superscript
3147 "Parse superscript at point.
3149 Return a list whose CAR is `superscript' and CDR a plist with
3150 `:begin', `:end', `:contents-begin', `:contents-end',
3151 `:use-brackets-p' and `:post-blank' as keywords.
3153 Assume point is at the caret."
3167 :end end
3168 :use-brackets-p bracketsp
3169 :contents-begin contents-begin
3170 :contents-end contents-end
3174 "Interpret SUPERSCRIPT object as Org syntax.
3175 CONTENTS is the contents of the object."
3178 contents))
3181 ;;;; Table Cell
3184 "Parse table cell at point.
3186 Return a list whose CAR is `table-cell' and CDR is a plist
3187 containing `:begin', `:end', `:contents-begin', `:contents-end'
3188 and `:post-blank' keywords."
3196 :end end
3197 :contents-begin contents-begin
3198 :contents-end contents-end
3202 "Interpret TABLE-CELL element as Org syntax.
3203 CONTENTS is the contents of the cell, or nil."
3207 "Search for the next table-cell object.
3209 LIMIT bounds the search.
3211 Return value is a cons cell whose CAR is `table-cell' and CDR is
3212 beginning position."
3216 ;;;; Target
3219 "Parse target at point.
3221 Return a list whose CAR is `target' and CDR a plist with
3222 `:begin', `:end', `:value' and `:post-blank' as keywords.
3224 Assume point is at the target."
3234 :end end
3235 :value value
3239 "Interpret TARGET object as Org syntax.
3240 CONTENTS is nil."
3244 "Search for the next target object.
3246 LIMIT bounds the search.
3248 Return value is a cons cell whose CAR is `target' and CDR is
3249 beginning position."
3255 ;;;; Timestamp
3258 "Parse time stamp at point.
3260 Return a list whose CAR is `timestamp', and CDR a plist with
3261 `:type', `:begin', `:end', `:value' and `:post-blank' keywords.
3263 Assume point is at the beginning of the timestamp."
3282 :value main-value
3283 :range-end range-end
3284 :begin begin
3285 :end end
3289 "Interpret TIMESTAMP object as Org syntax.
3290 CONTENTS is nil."
3299 range-end)))))))
3302 "Search for the next timestamp object.
3304 LIMIT bounds the search.
3306 Return value is a cons cell whose CAR is `timestamp' and CDR is
3307 beginning position."
3315 limit t)
3319 ;;;; Underline
3322 "Parse underline object at point.
3324 Return a list whose CAR is `underline' and CDR is a plist with
3325 `:begin', `:end', `:contents-begin' and `:contents-end' and
3326 `:post-blank' keywords.
3328 Assume point is at the first underscore marker."
3340 :end end
3341 :contents-begin contents-begin
3342 :contents-end contents-end
3346 "Interpret UNDERLINE object as Org syntax.
3347 CONTENTS is the contents of the object."
3351 ;;;; Verbatim
3354 "Parse verbatim object at point.
3356 Return a list whose CAR is `verbatim' and CDR is a plist with
3357 `:value', `:begin', `:end' and `:post-blank' keywords.
3359 Assume point is at the first equal sign marker."
3370 :begin begin
3371 :end end
3375 "Interpret VERBATIM object as Org syntax.
3376 CONTENTS is nil."
3380 \f
3381 ;;; Parsing Element Starting At Point
3382 ;;
3383 ;; `org-element--current-element' is the core function of this section.
3384 ;; It returns the Lisp representation of the element starting at
3385 ;; point.
3386 ;;
3387 ;; `org-element--current-element' makes use of special modes. They
3388 ;; are activated for fixed element chaining (i.e. `plain-list' >
3389 ;; `item') or fixed conditional element chaining (i.e. `headline' >
3390 ;; `section'). Special modes are: `first-section', `item',
3391 ;; `node-property', `quote-section', `section' and `table-row'.
3395 "Parse the element starting at point.
3397 LIMIT bounds the search.
3399 Return value is a list like (TYPE PROPS) where TYPE is the type
3400 of the element and PROPS a plist of properties associated to the
3401 element.
3403 Possible types are defined in `org-element-all-elements'.
3405 Optional argument GRANULARITY determines the depth of the
3406 recursion. Allowed values are `headline', `greater-element',
3407 `element', `object' or nil. When it is broader than `object' (or
3408 nil), secondary values will not be parsed, since they only
3409 contain objects.
3411 Optional argument SPECIAL, when non-nil, can be either
3412 `first-section', `item', `node-property', `quote-section',
3413 `section', and `table-row'.
3415 If STRUCTURE isn't provided but SPECIAL is set to `item', it will
3416 be computed.
3418 This function assumes point is always at the beginning of the
3419 element it has to parse."
3422 ;; Determine if parsing depth allows for secondary strings
3423 ;; parsing. It only applies to elements referenced in
3424 ;; `org-element-secondary-value-alist'.
3427 ;; Item.
3430 ;; Table Row.
3432 ;; Node Property.
3434 ;; Headline.
3437 ;; Sections (must be checked after headline).
3443 limit)))
3444 ;; When not at bol, point is at the beginning of an item or
3445 ;; a footnote definition: next item is always a paragraph.
3447 ;; Planning and Clock.
3452 ;; Inlinetask.
3455 ;; From there, elements can have affiliated keywords.
3458 ;; LaTeX Environment.
3464 nil t))
3467 ;; Drawer and Property Drawer.
3477 ;; Fixed Width
3480 ;; Inline Comments, Blocks, Babel Calls, Dynamic Blocks and
3481 ;; Keywords.
3490 org-element-block-name-alist)))
3505 ;; Footnote Definition.
3508 ;; Horizontal Rule.
3511 ;; Table.
3513 ;; List.
3517 ;; Default element: Paragraph.
3521 ;; Most elements can have affiliated keywords. When looking for an
3522 ;; element beginning, we want to move before them, as they belong to
3523 ;; that element, and, in the meantime, collect information they give
3524 ;; into appropriate properties. Hence the following function.
3527 "Collect affiliated keywords from point.
3529 Return a list whose CAR is the position at the first of them and
3530 CDR a plist of keywords and values and move point to the
3531 beginning of the first line after them.
3533 As a special case, if element doesn't start at the beginning of
3534 the line (i.e. a paragraph starting an item), CAR is current
3535 position of point and CDR is nil."
3539 ;; RESTRICT is the list of objects allowed in parsed
3540 ;; keywords value.
3542 output)
3545 ;; Apply translation to RAW-KWD. From there, KWD is
3546 ;; the official keyword.
3548 org-element-keyword-translation-alist))
3549 raw-kwd))
3550 ;; Find main value for any keyword.
3556 ;; PARSEDP is non-nil when keyword should have its
3557 ;; value parsed.
3559 ;; If KWD is a dual keyword, find its secondary
3560 ;; value. Maybe parse it.
3567 ;; Attribute a property name to KWD.
3569 ;; Now set final shape for VALUE.
3574 ;; Attributes can always appear on multiple lines.
3577 ;; Eventually store the new value in OUTPUT.
3579 ;; Move to next keyword.
3581 ;; If affiliated keywords are orphaned: move back to first one.
3582 ;; They will be parsed as a paragraph.
3584 ;; Return value.
3588 \f
3589 ;;; The Org Parser
3590 ;;
3591 ;; The two major functions here are `org-element-parse-buffer', which
3592 ;; parses Org syntax inside the current buffer, taking into account
3593 ;; region, narrowing, or even visibility if specified, and
3594 ;; `org-element-parse-secondary-string', which parses objects within
3595 ;; a given string.
3596 ;;
3597 ;; The (almost) almighty `org-element-map' allows to apply a function
3598 ;; on elements or objects matching some type, and accumulate the
3599 ;; resulting values. In an export situation, it also skips unneeded
3600 ;; parts of the parse tree.
3603 "Recursively parse the buffer and return structure.
3604 If narrowing is in effect, only parse the visible part of the
3605 buffer.
3607 Optional argument GRANULARITY determines the depth of the
3608 recursion. It can be set to the following symbols:
3610 `headline' Only parse headlines.
3611 `greater-element' Don't recurse into greater elements excepted
3612 headlines and sections. Thus, elements
3613 parsed are the top-level ones.
3614 `element' Parse everything but objects and plain text.
3615 `object' Parse the complete buffer (default).
3617 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3618 elements.
3620 Assume buffer is in Org mode."
3626 ;; Start in `first-section' mode so text before the first
3627 ;; headline belongs to a section.
3631 "Recursively parse objects in STRING and return structure.
3633 RESTRICTION is a symbol limiting the object types that will be
3634 looked after.
3636 Optional argument PARENT, when non-nil, is the element or object
3637 containing the secondary string. It is used to set correctly
3638 `:parent' property within the string."
3644 secondary))))
3647 "Map a function on selected elements or objects.
3649 DATA is the parsed tree, as returned by, i.e,
3650 `org-element-parse-buffer'. TYPES is a symbol or list of symbols
3651 of elements or objects types. FUN is the function called on the
3652 matching element or object. It must accept one arguments: the
3653 element or object itself.
3655 When optional argument INFO is non-nil, it should be a plist
3656 holding export options. In that case, parts of the parse tree
3657 not exportable according to that property list will be skipped.
3659 When optional argument FIRST-MATCH is non-nil, stop at the first
3660 match for which FUN doesn't return nil, and return that value.
3662 Optional argument NO-RECURSION is a symbol or a list of symbols
3663 representing elements or objects types. `org-element-map' won't
3664 enter any recursive element or object whose type belongs to that
3665 list. Though, FUN can still be applied on them.
3667 Nil values returned from FUN do not appear in the results."
3668 ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
3671 ;; Recursion depth is determined by --CATEGORY.
3678 ;; If one object is found, the function
3679 ;; has to recurse into every object.
3682 ;; If one regular element is found, the
3683 ;; function has to recurse, at least,
3684 ;; into every element it encounters.
3687 types)
3688 category)))
3689 --acc
3690 --walk-tree
3694 ;; Recursively walk DATA. INFO, if non-nil, is a plist
3695 ;; holding contextual information.
3699 ;; Ignored element in an export context.
3701 ;; Secondary string: only objects can be found there.
3704 ;; Unconditionally enter parse trees.
3708 ;; Check if TYPE is matching among TYPES. If so,
3709 ;; apply FUN to --DATA and accumulate return value
3710 ;; into --ACC (or exit if FIRST-MATCH is non-nil).
3716 ;; If --DATA has a secondary string that can contain
3717 ;; objects with their type among TYPES, look into it.
3724 ;; Determine if a recursion into --DATA is possible.
3726 ;; --TYPE is explicitly removed from recursion.
3728 ;; --DATA has no contents.
3730 ;; Looking for greater elements but --DATA is simply
3731 ;; an element or an object.
3734 ;; Looking for elements but --DATA is an object.
3737 ;; In any other case, map contents.
3741 ;; Return value in a proper order.
3744 ;; The following functions are internal parts of the parser.
3745 ;;
3746 ;; The first one, `org-element--parse-elements' acts at the element's
3747 ;; level.
3748 ;;
3749 ;; The second one, `org-element--parse-objects' applies on all objects
3750 ;; of a paragraph or a secondary string. It uses
3751 ;; `org-element--get-next-object-candidates' to optimize the search of
3752 ;; the next object in the buffer.
3753 ;;
3754 ;; More precisely, that function looks for every allowed object type
3755 ;; first. Then, it discards failed searches, keeps further matches,
3756 ;; and searches again types matched behind point, for subsequent
3757 ;; calls. Thus, searching for a given type fails only once, and every
3758 ;; object is searched only once at top level (but sometimes more for
3759 ;; nested types).
3763 "Parse elements between BEG and END positions.
3765 SPECIAL prioritize some elements over the others. It can be set
3766 to `first-section', `quote-section', `section' `item' or
3767 `table-row'.
3769 When value is `item', STRUCTURE will be used as the current list
3770 structure.
3772 GRANULARITY determines the depth of the recursion. See
3773 `org-element-parse-buffer' for more information.
3775 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
3776 elements.
3778 Elements are accumulated into ACC."
3781 ;; When parsing only headlines, skip any text before first one.
3784 ;; Main loop start.
3786 ;; Find current element's type and parse it accordingly to
3787 ;; its category.
3789 end granularity special structure))
3793 ;; Fill ELEMENT contents by side-effect.
3795 ;; If VISIBLE-ONLY is true and element is hidden or if it has
3796 ;; no contents, don't modify it.
3799 ;; Greater element: parse it between `contents-begin' and
3800 ;; `contents-end'. Make sure GRANULARITY allows the
3801 ;; recursion, or ELEMENT is an headline, in which case going
3802 ;; inside is mandatory, in order to get sub-level headings.
3810 ;; Possibly switch to a special mode.
3819 granularity visible-only element))
3820 ;; ELEMENT has contents. Parse objects inside, if
3821 ;; GRANULARITY allows it.
3827 ;; Return result.
3828 acc))
3831 "Parse objects between BEG and END and return recursive structure.
3833 Objects are accumulated in ACC.
3835 RESTRICTION is a list of object types which are allowed in the
3836 current object."
3842 end restriction candidates)))
3849 ;; 1. Text before any object. Untabify it.
3854 acc
3858 ;; 2. Object...
3861 ;; Fill contents of NEXT-OBJECT by side-effect, if it has
3862 ;; a recursive type.
3867 cont-beg
3874 ;; 3. Text after last object. Untabify it.
3878 acc
3882 ;; Result.
3883 acc)))
3886 "Return an alist of candidates for the next object.
3888 LIMIT bounds the search, and RESTRICTION narrows candidates to
3889 some object types.
3891 Return value is an alist whose CAR is position and CDR the object
3892 type, as a symbol.
3894 OBJECTS is the previous candidates alist."
3896 ;; If no previous result, search every object type in RESTRICTION.
3897 ;; Otherwise, keep potential candidates (old objects located after
3898 ;; point) and ask to search again those which had matched before.
3903 objects))
3904 ;; Call the appropriate successor function for each type to search
3905 ;; and accumulate matches.
3912 type))))
3915 types-to-search)
3916 ;; Return alist.
3917 next-candidates))
3920 \f
3921 ;;; Towards A Bijective Process
3922 ;;
3923 ;; The parse tree obtained with `org-element-parse-buffer' is really
3924 ;; a snapshot of the corresponding Org buffer. Therefore, it can be
3925 ;; interpreted and expanded into a string with canonical Org syntax.
3926 ;; Hence `org-element-interpret-data'.
3927 ;;
3928 ;; The function relies internally on
3929 ;; `org-element--interpret-affiliated-keywords'.
3931 ;;;###autoload
3933 "Interpret DATA as Org syntax.
3935 DATA is a parse tree, an element, an object or a secondary string
3936 to interpret.
3938 Optional argument PARENT is used for recursive calls. It contains
3939 the element or object containing data, or nil.
3941 Return Org syntax as a string."
3945 ;; Secondary string.
3950 ;; Full Org document.
3955 ;; Plain text.
3957 ;; Element/Object without contents.
3960 data nil))
3961 ;; Element/Object with contents.
3971 ;; Elements directly containing objects must
3972 ;; have their indentation normalized first.
3974 data
3975 ;; When normalizing first paragraph of an
3976 ;; item or a footnote-definition, ignore
3977 ;; first line's indentation.
3984 data
3986 contents)))))))
3988 ;; Build white spaces. If no `:post-blank' property is
3989 ;; specified, assume its value is 0.
3999 "Return ELEMENT's affiliated keywords as Org syntax.
4000 If there is no affiliated keyword, return the empty string."
4010 ": "
4013 value)
4021 ;; All attribute keywords can have multiple lines.
4027 ;; List all ELEMENT's properties matching an attribute line or an
4028 ;; affiliated keyword, but ignore translated keywords since they
4029 ;; cannot belong to the property list.
4036 org-element-keyword-translation-alist)))))
4037 collect prop)
4040 ;; Because interpretation of the parse tree must return the same
4041 ;; number of blank lines between elements and the same number of white
4042 ;; space after objects, some special care must be given to white
4043 ;; spaces.
4044 ;;
4045 ;; The first function, `org-element-normalize-string', ensures any
4046 ;; string different from the empty string will end with a single
4047 ;; newline character.
4048 ;;
4049 ;; The second function, `org-element-normalize-contents', removes
4050 ;; global indentation from the contents of the current element.
4053 "Ensure string S ends with a single newline character.
4055 If S isn't a string return it unchanged. If S is the empty
4056 string, return it. Otherwise, return a new string with a single
4057 newline character at its end."
4065 "Normalize plain text in ELEMENT's contents.
4067 ELEMENT must only contain plain text and objects.
4069 If optional argument IGNORE-FIRST is non-nil, ignore first line's
4070 indentation to compute maximal common indentation.
4072 Return the normalized element that is element with global
4073 indentation removed from its contents. The function assumes that
4074 indentation is not done with TAB characters."
4076 collect-inds ; for byte-compiler
4079 ;; Return list of indentations within BLOB. This is done by
4080 ;; walking recursively BLOB and updating IND-LIST along the
4081 ;; way. FIRST-FLAG is non-nil when the first string hasn't
4082 ;; been seen yet. It is required as this string is the only
4083 ;; one whose indentation doesn't happen after a newline
4084 ;; character.
4092 ;; An indentation of zero means no string will be
4093 ;; modified. Quit the process.
4099 ;; Avoid matching blank or empty lines.
4107 ;; Collect indentation list in ELEMENT. Possibly remove first
4108 ;; value if IGNORE-FIRST is non-nil.
4111 ;; Build ELEMENT back, replacing each string with the same
4112 ;; string minus common indentation.
4117 ;; Return BLOB with all its strings indentation
4118 ;; shortened from MCI white spaces. FIRST-FLAG is
4119 ;; non-nil when the first string hasn't been seen
4120 ;; yet.
4134 org-element-recursive-objects)
4138 blob))))
4142 \f
4143 ;;; The Toolbox
4144 ;;
4145 ;; The first move is to implement a way to obtain the smallest element
4146 ;; containing point. This is the job of `org-element-at-point'. It
4147 ;; basically jumps back to the beginning of section containing point
4148 ;; and moves, element after element, with
4149 ;; `org-element--current-element' until the container is found. Note:
4150 ;; When using `org-element-at-point', secondary values are never
4151 ;; parsed since the function focuses on elements, not on objects.
4152 ;;
4153 ;; At a deeper level, `org-element-context' lists all elements and
4154 ;; objects containing point.
4155 ;;
4156 ;; `org-element-nested-p' and `org-element-swap-A-B' may be used
4157 ;; internally by navigation and manipulation tools.
4159 ;;;###autoload
4161 "Determine closest element around point.
4163 Return value is a list like (TYPE PROPS) where TYPE is the type
4164 of the element and PROPS a plist of properties associated to the
4165 element.
4167 Possible types are defined in `org-element-all-elements'.
4168 Properties depend on element or object type, but always
4169 include :begin, :end, :parent and :post-blank properties.
4171 As a special case, if point is at the very beginning of a list or
4172 sub-list, returned element will be that list instead of the first
4173 item. In the same way, if point is at the beginning of the first
4174 row of a table, returned element will be the table instead of the
4175 first row.
4177 If optional argument KEEP-TRAIL is non-nil, the function returns
4178 a list of of elements leading to element at point. The list's
4179 CAR is always the element at point. Following positions contain
4180 element's siblings, then parents, siblings of parents, until the
4181 first element of current section."
4183 ;; If at an headline, parse it. It is the sole element that
4184 ;; doesn't require to know about context. Be sure to disallow
4185 ;; secondary string parsing, though.
4191 ;; Otherwise move at the beginning of the section containing
4192 ;; point.
4196 element type special-flag trail struct prevs parent)
4204 ;; Parse successively each element, skipping those ending
4205 ;; before original position.
4214 ;; 1. Skip any element ending before point. Also skip
4215 ;; element ending at point when we're sure that another
4216 ;; element has started.
4221 ;; 2. An element containing point is always the element at
4222 ;; point.
4225 ;; 3. At any other greater element type, if point is
4226 ;; within contents, move into it.
4231 ;; Create an anchor for tables and plain lists:
4232 ;; when point is at the very beginning of these
4233 ;; elements, ignoring affiliated keywords,
4234 ;; target them instead of their contents.
4236 ;; When point is at contents end, do not move
4237 ;; into elements with an explicit ending, but
4238 ;; return that element instead.
4242 drawer dynamic-block inlinetask item
4243 plain-list property-drawer quote-block
4244 special-block))))
4257 ;;;###autoload
4259 "Return closest element or object around point.
4261 Return value is a list like (TYPE PROPS) where TYPE is the type
4262 of the element or object and PROPS a plist of properties
4263 associated to it.
4265 Possible types are defined in `org-element-all-elements' and
4266 `org-element-all-objects'. Properties depend on element or
4267 object type, but always include :begin, :end, :parent
4268 and :post-blank properties."
4273 end)
4274 ;; Check if point is inside an element containing objects or at
4275 ;; a secondary string. In that case, move to beginning of the
4276 ;; element or secondary string and set END to the other side.
4285 (<= origin
4286 ;; `1+' is required so some
4287 ;; successors can match
4288 ;; properly their object.
4302 element
4305 candidates)
4308 end restriction candidates))
4310 candidates)))
4311 ;; If ORIGIN is before next object in element, there's
4312 ;; no point in looking further.
4321 ;; ORIGIN is after OBJECT, so skip it.
4324 ;; ORIGIN is within a non-recursive object or at an
4325 ;; object boundaries: Return that object.
4329 ;; Otherwise, move within current object and restrict
4330 ;; search to the end of its contents.
4334 parent))))))
4337 "Non-nil when elements ELEM-A and ELEM-B are nested."
4346 "Swap elements ELEM-A and ELEM-B.
4347 Assume ELEM-B is after ELEM-A in the buffer. Leave point at the
4348 end of ELEM-A."
4350 ;; There are two special cases when an element doesn't start at bol:
4351 ;; the first paragraph in an item or in a footnote definition.
4353 ;; Only a paragraph without any affiliated keyword can be moved at
4354 ;; ELEM-A position in such a situation. Note that the case of
4355 ;; a footnote definition is impossible: it cannot contain two
4356 ;; paragraphs in a row because it cannot contain a blank line.
4362 ;; In a special situation, ELEM-A will have no indentation. We'll
4363 ;; give it ELEM-B's (which will in, in turn, have no indentation).
4377 ;; Store overlays responsible for visibility status. We
4378 ;; also need to store their boundaries as they will be
4379 ;; removed from buffer.
4386 ;; Get contents.
4394 ;; Restore ex ELEM-A overlays.
4403 ;; Restore ex ELEM-B overlays.
4412 ;;; org-element.el ends here