exporters/org-element-docstrings.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
   5 #+TITLE:      Docstrings from 'org-element.el'
   6 #+AUTHOR:     Thorsten Jolitz
   7 #+EMAIL:      tjolitz[at]gmail[dot]com
   8 #+LANGUAGE:   en
   9 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
  10 #+LINK_UP:    ../ox-overview.html
  11 #+LINK_HOME:  http://orgmode.org/worg/
  12 #+EXCLUDE_TAGS: noexport
  13
  14 [[file:index.org][{Back to Worg's index}]]
  15
  16
  17 * org-element.el --- Parser And Applications for Org syntax
  18
  19 Copyright (C) 2012-2013 Free Software Foundation, Inc.
  20
  21 Author: Nicolas Goaziou <n.goaziou at gmail dot com>
  22 Keywords: outlines, hypermedia, calendar, wp
  23
  24 This file is part of GNU Emacs.
  25
  26 GNU Emacs is free software: you can redistribute it and/or modify
  27 it under the terms of the GNU General Public License as published by
  28 the Free Software Foundation, either version 3 of the License, or
  29 (at your option) any later version.
  30
  31 GNU Emacs is distributed in the hope that it will be useful,
  32 but WITHOUT ANY WARRANTY; without even the implied warranty of
  33 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  34 GNU General Public License for more details.
  35
  36 You should have received a copy of the GNU General Public License
  37 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  38
  39 * Commentary:
  40
  41 Org syntax can be divided into three categories: "Greater elements",
  42 "Elements" and "Objects".
  43
  44 Elements are related to the structure of the document.  Indeed, all
  45 elements are a cover for the document: each position within belongs
  46 to at least one element.
  47
  48 An element always starts and ends at the beginning of a line.  With
  49 a few exceptions (`clock', `headline', `inlinetask', `item',
  50 `planning', `node-property', `quote-section' `section' and
  51 `table-row' types), it can also accept a fixed set of keywords as
  52 attributes.  Those are called "affiliated keywords" to distinguish
  53 them from other keywords, which are full-fledged elements.  Almost
  54 all affiliated keywords are referenced in
  55 `org-element-affiliated-keywords'; the others are export attributes
  56 and start with "ATTR_" prefix.
  57
  58 Element containing other elements (and only elements) are called
  59 greater elements.  Concerned types are: `center-block', `drawer',
  60 `dynamic-block', `footnote-definition', `headline', `inlinetask',
  61 `item', `plain-list', `property-drawer', `quote-block', `section'
  62 and `special-block'.
  63
  64 Other element types are: `babel-call', `clock', `comment',
  65 `comment-block', `diary-sexp', `example-block', `export-block',
  66 `fixed-width', `horizontal-rule', `keyword', `latex-environment',
  67 `node-property', `paragraph', `planning', `quote-section',
  68 `src-block', `table', `table-row' and `verse-block'.  Among them,
  69 `paragraph' and `verse-block' types can contain Org objects and
  70 plain text.
  71
  72 Objects are related to document's contents.  Some of them are
  73 recursive.  Associated types are of the following: `bold', `code',
  74 `entity', `export-snippet', `footnote-reference',
  75 `inline-babel-call', `inline-src-block', `italic',
  76 `latex-fragment', `line-break', `link', `macro', `radio-target',
  77 `statistics-cookie', `strike-through', `subscript', `superscript',
  78 `table-cell', `target', `timestamp', `underline' and `verbatim'.
  79
  80 Some elements also have special properties whose value can hold
  81 objects themselves (i.e. an item tag or a headline name).  Such
  82 values are called "secondary strings".  Any object belongs to
  83 either an element or a secondary string.
  84
  85 Notwithstanding affiliated keywords, each greater element, element
  86 and object has a fixed set of properties attached to it.  Among
  87 them, four are shared by all types: `:begin' and `:end', which
  88 refer to the beginning and ending buffer positions of the
  89 considered element or object, `:post-blank', which holds the number
  90 of blank lines, or white spaces, at its end and `:parent' which
  91 refers to the element or object containing it.  Greater elements,
  92 elements and objects containing objects will also have
  93 `:contents-begin' and `:contents-end' properties to delimit
  94 contents.  Eventually, greater elements and elements accepting
  95 affiliated keywords will have a `:post-affiliated' property,
  96 referring to the buffer position after all such keywords.
  97
  98 At the lowest level, a `:parent' property is also attached to any
  99 string, as a text property.
 100
 101 Lisp-wise, an element or an object can be represented as a list.
 102 It follows the pattern (TYPE PROPERTIES CONTENTS), where:
 103   TYPE is a symbol describing the Org element or object.
 104   PROPERTIES is the property list attached to it.  See docstring of
 105              appropriate parsing function to get an exhaustive
 106              list.
 107   CONTENTS is a list of elements, objects or raw strings contained
 108            in the current element or object, when applicable.
 109
 110 An Org buffer is a nested list of such elements and objects, whose
 111 type is `org-data' and properties is nil.
 112
 113 The first part of this file defines Org syntax, while the second
 114 one provide accessors and setters functions.
 115
 116 The next part implements a parser and an interpreter for each
 117 element and object type in Org syntax.
 118
 119 The following part creates a fully recursive buffer parser.  It
 120 also provides a tool to map a function to elements or objects
 121 matching some criteria in the parse tree.  Functions of interest
 122 are `org-element-parse-buffer', `org-element-map' and, to a lesser
 123 extent, `org-element-parse-secondary-string'.
 124
 125 The penultimate part is the cradle of an interpreter for the
 126 obtained parse tree: `org-element-interpret-data'.
 127
 128 The library ends by furnishing `org-element-at-point' function, and
 129 a way to give information about document structure around point
 130 with `org-element-context'.
 131
 132
 133 * Code:
 134
 135 #+begin_src emacs-lisp
 136 (eval-when-compile (require 'cl))
 137 (require 'org)
 138 #+end_src
 139
 140 * Definitions And Rules
 141
 142 Define elements, greater elements and specify recursive objects,
 143 along with the affiliated keywords recognized.  Also set up
 144 restrictions on recursive objects combinations.
 145
 146 These variables really act as a control center for the parsing
 147 process.
 148
 149 #+begin_src emacs-lisp
 150 (defconst org-element-paragraph-separate
 151   (concat "^\\(?:"
 152           ;; Headlines, inlinetasks.
 153           org-outline-regexp "\\|"
 154           ;; Footnote definitions.
 155           "\\[\\(?:[0-9]+\\|fn:[-_[:word:]]+\\)\\]" "\\|"
 156           ;; Diary sexps.
 157           "%%(" "\\|"
 158           "[ \t]*\\(?:"
 159           ;; Empty lines.
 160           "$" "\\|"
 161           ;; Tables (any type).
 162           "\\(?:|\\|\\+-[-+]\\)" "\\|"
 163           ;; Blocks (any type), Babel calls, drawers (any type),
 164           ;; fixed-width areas and keywords.  Note: this is only an
 165           ;; indication and need some thorough check.
 166           "[#:]" "\\|"
 167           ;; Horizontal rules.
 168           "-\\{5,\\}[ \t]*$" "\\|"
 169           ;; LaTeX environments.
 170           "\\\\begin{\\([A-Za-z0-9]+\\*?\\)}" "\\|"
 171           ;; Planning and Clock lines.
 172           (regexp-opt (list org-scheduled-string
 173                             org-deadline-string
 174                             org-closed-string
 175                             org-clock-string))
 176           "\\|"
 177           ;; Lists.
 178           (let ((term (case org-plain-list-ordered-item-terminator
 179                         (?\) ")") (?. "\\.") (otherwise "[.)]")))
 180                 (alpha (and org-list-allow-alphabetical "\\|[A-Za-z]")))
 181             (concat "\\(?:[-+*]\\|\\(?:[0-9]+" alpha "\\)" term "\\)"
 182                     "\\(?:[ \t]\\|$\\)"))
 183           "\\)\\)")
 184   "Regexp to separate paragraphs in an Org buffer.
 185 In the case of lines starting with \"#\" and \":\", this regexp
 186 is not sufficient to know if point is at a paragraph ending.  See
 187 `org-element-paragraph-parser' for more information.")
 188
 189 (defconst org-element-all-elements
 190   '(babel-call center-block clock comment comment-block diary-sexp drawer
 191                dynamic-block example-block export-block fixed-width
 192                footnote-definition headline horizontal-rule inlinetask item
 193                keyword latex-environment node-property paragraph plain-list
 194                planning property-drawer quote-block quote-section section
 195                special-block src-block table table-row verse-block)
 196   "Complete list of element types.")
 197
 198 (defconst org-element-greater-elements
 199   '(center-block drawer dynamic-block footnote-definition headline inlinetask
 200                  item plain-list property-drawer quote-block section
 201                  special-block table)
 202   "List of recursive element types aka Greater Elements.")
 203
 204 (defconst org-element-all-successors
 205   '(export-snippet footnote-reference inline-babel-call inline-src-block
 206                    latex-or-entity line-break link macro plain-link radio-target
 207                    statistics-cookie sub/superscript table-cell target
 208                    text-markup timestamp)
 209   "Complete list of successors.")
 210
 211 (defconst org-element-object-successor-alist
 212   '((subscript . sub/superscript) (superscript . sub/superscript)
 213     (bold . text-markup) (code . text-markup) (italic . text-markup)
 214     (strike-through . text-markup) (underline . text-markup)
 215     (verbatim . text-markup) (entity . latex-or-entity)
 216     (latex-fragment . latex-or-entity))
 217   "Alist of translations between object type and successor name.
 218 Sharing the same successor comes handy when, for example, the
 219 regexp matching one object can also match the other object.")
 220
 221 (defconst org-element-all-objects
 222   '(bold code entity export-snippet footnote-reference inline-babel-call
 223          inline-src-block italic line-break latex-fragment link macro
 224          radio-target statistics-cookie strike-through subscript superscript
 225          table-cell target timestamp underline verbatim)
 226   "Complete list of object types.")
 227
 228 (defconst org-element-recursive-objects
 229   '(bold italic link subscript radio-target strike-through superscript
 230          table-cell underline)
 231   "List of recursive object types.")
 232
 233 (defvar org-element-block-name-alist
 234   '(("CENTER" . org-element-center-block-parser)
 235     ("COMMENT" . org-element-comment-block-parser)
 236     ("EXAMPLE" . org-element-example-block-parser)
 237     ("QUOTE" . org-element-quote-block-parser)
 238     ("SRC" . org-element-src-block-parser)
 239     ("VERSE" . org-element-verse-block-parser))
 240   "Alist between block names and the associated parsing function.
 241 Names must be uppercase.  Any block whose name has no association
 242 is parsed with `org-element-special-block-parser'.")
 243
 244 (defconst org-element-link-type-is-file
 245   '("file" "file+emacs" "file+sys" "docview")
 246   "List of link types equivalent to \"file\".
 247 Only these types can accept search options and an explicit
 248 application to open them.")
 249
 250 (defconst org-element-affiliated-keywords
 251   '("CAPTION" "DATA" "HEADER" "HEADERS" "LABEL" "NAME" "PLOT" "RESNAME" "RESULT"
 252     "RESULTS" "SOURCE" "SRCNAME" "TBLNAME")
 253   "List of affiliated keywords as strings.
 254 By default, all keywords setting attributes (i.e. \"ATTR_LATEX\")
 255 are affiliated keywords and need not to be in this list.")
 256
 257 (defconst org-element--affiliated-re
 258   (format "[ \t]*#\\+%s:"
 259           ;; Regular affiliated keywords.
 260           (format "\\(%s\\|ATTR_[-_A-Za-z0-9]+\\)\\(?:\\[\\(.*\\)\\]\\)?"
 261                   (regexp-opt org-element-affiliated-keywords)))
 262   "Regexp matching any affiliated keyword.
 263
 264 Keyword name is put in match group 1.  Moreover, if keyword
 265 belongs to `org-element-dual-keywords', put the dual value in
 266 match group 2.
 267
 268 Don't modify it, set `org-element-affiliated-keywords' instead.")
 269
 270 (defconst org-element-keyword-translation-alist
 271   '(("DATA" . "NAME")  ("LABEL" . "NAME") ("RESNAME" . "NAME")
 272     ("SOURCE" . "NAME") ("SRCNAME" . "NAME") ("TBLNAME" . "NAME")
 273     ("RESULT" . "RESULTS") ("HEADERS" . "HEADER"))
 274   "Alist of usual translations for keywords.
 275 The key is the old name and the value the new one.  The property
 276 holding their value will be named after the translated name.")
 277
 278 (defconst org-element-multiple-keywords '("CAPTION" "HEADER")
 279   "List of affiliated keywords that can occur more than once in an element.
 280
 281 Their value will be consed into a list of strings, which will be
 282 returned as the value of the property.
 283
 284 This list is checked after translations have been applied.  See
 285 `org-element-keyword-translation-alist'.
 286
 287 By default, all keywords setting attributes (i.e. \"ATTR_LATEX\")
 288 allow multiple occurrences and need not to be in this list.")
 289
 290 (defconst org-element-parsed-keywords '("CAPTION")
 291   "List of affiliated keywords whose value can be parsed.
 292
 293 Their value will be stored as a secondary string: a list of
 294 strings and objects.
 295
 296 This list is checked after translations have been applied.  See
 297 `org-element-keyword-translation-alist'.")
 298
 299 (defconst org-element-dual-keywords '("CAPTION" "RESULTS")
 300   "List of affiliated keywords which can have a secondary value.
 301
 302 In Org syntax, they can be written with optional square brackets
 303 before the colons.  For example, RESULTS keyword can be
 304 associated to a hash value with the following:
 305
 306   #+RESULTS[hash-string]: some-source
 307
 308 This list is checked after translations have been applied.  See
 309 `org-element-keyword-translation-alist'.")
 310
 311 (defconst org-element-document-properties '("AUTHOR" "DATE" "TITLE")
 312   "List of properties associated to the whole document.
 313 Any keyword in this list will have its value parsed and stored as
 314 a secondary string.")
 315
 316 (defconst org-element-object-restrictions
 317   (let* ((standard-set
 318           (remq 'plain-link (remq 'table-cell org-element-all-successors)))
 319          (standard-set-no-line-break (remq 'line-break standard-set)))
 320     `((bold ,@standard-set)
 321       (footnote-reference ,@standard-set)
 322       (headline ,@standard-set-no-line-break)
 323       (inlinetask ,@standard-set-no-line-break)
 324       (italic ,@standard-set)
 325       (item ,@standard-set-no-line-break)
 326       (keyword ,@standard-set)
 327       ;; Ignore all links excepted plain links in a link description.
 328       ;; Also ignore radio-targets and line breaks.
 329       (link export-snippet inline-babel-call inline-src-block latex-or-entity
 330             macro plain-link statistics-cookie sub/superscript text-markup)
 331       (paragraph ,@standard-set)
 332       ;; Remove any variable object from radio target as it would
 333       ;; prevent it from being properly recognized.
 334       (radio-target latex-or-entity sub/superscript)
 335       (strike-through ,@standard-set)
 336       (subscript ,@standard-set)
 337       (superscript ,@standard-set)
 338       ;; Ignore inline babel call and inline src block as formulas are
 339       ;; possible.  Also ignore line breaks and statistics cookies.
 340       (table-cell export-snippet footnote-reference latex-or-entity link macro
 341                   radio-target sub/superscript target text-markup timestamp)
 342       (table-row table-cell)
 343       (underline ,@standard-set)
 344       (verse-block ,@standard-set)))
 345   "Alist of objects restrictions.
 346
 347 CAR is an element or object type containing objects and CDR is
 348 a list of successors that will be called within an element or
 349 object of such type.
 350
 351 For example, in a `radio-target' object, one can only find
 352 entities, latex-fragments, subscript and superscript.
 353
 354 This alist also applies to secondary string.  For example, an
 355 `headline' type element doesn't directly contain objects, but
 356 still has an entry since one of its properties (`:title') does.")
 357
 358 (defconst org-element-secondary-value-alist
 359   '((headline . :title)
 360     (inlinetask . :title)
 361     (item . :tag)
 362     (footnote-reference . :inline-definition))
 363   "Alist between element types and location of secondary value.")
 364
 365 (defconst org-element-object-variables '(org-link-abbrev-alist-local)
 366   "List of buffer-local variables used when parsing objects.
 367 These variables are copied to the temporary buffer created by
 368 `org-export-secondary-string'.")
 369
 370
 371 #+end_src
 372
 373 * Accessors and Setters
 374
 375 Provide four accessors: `org-element-type', `org-element-property'
 376 `org-element-contents' and `org-element-restriction'.
 377
 378 Setter functions allow to modify elements by side effect.  There is
 379 `org-element-put-property', `org-element-set-contents',
 380 `org-element-set-element' and `org-element-adopt-element'.  Note
 381 that `org-element-set-element' and `org-element-adopt-elements' are
 382 higher level functions since also update `:parent' property.
 383
 384 #+begin_src emacs-lisp
 385 (defsubst org-element-type (element)
 386   "Return type of ELEMENT.
 387
 388 The function returns the type of the element or object provided.
 389 It can also return the following special value:
 390   `plain-text'       for a string
 391   `org-data'         for a complete document
 392   nil                in any other case.")
 393
 394 (defsubst org-element-property (property element)
 395   "Extract the value from the PROPERTY of an ELEMENT.")
 396
 397 (defsubst org-element-contents (element)
 398   "Extract contents from an ELEMENT.")
 399
 400 (defsubst org-element-restriction (element)
 401   "Return restriction associated to ELEMENT.
 402 ELEMENT can be an element, an object or a symbol representing an
 403 element or object type.")
 404
 405 (defsubst org-element-put-property (element property value)
 406   "In ELEMENT set PROPERTY to VALUE.
 407 Return modified element.")
 408
 409 (defsubst org-element-set-contents (element &rest contents)
 410   "Set ELEMENT contents to CONTENTS.
 411 Return modified element.")
 412
 413 (defsubst org-element-set-element (old new)
 414   "Replace element or object OLD with element or object NEW.
 415 The function takes care of setting `:parent' property for NEW.")
 416
 417 (defsubst org-element-adopt-elements (parent &rest children)
 418   "Append elements to the contents of another element.
 419
 420 PARENT is an element or object.  CHILDREN can be elements,
 421 objects, or a strings.
 422
 423 The function takes care of setting `:parent' property for CHILD.
 424 Return parent element.")
 425
 426
 427 #+end_src
 428
 429 * Greater elements
 430
 431 For each greater element type, we define a parser and an
 432 interpreter.
 433
 434 A parser returns the element or object as the list described above.
 435 Most of them accepts no argument.  Though, exceptions exist.  Hence
 436 every element containing a secondary string (see
 437 `org-element-secondary-value-alist') will accept an optional
 438 argument to toggle parsing of that secondary string.  Moreover,
 439 `item' parser requires current list's structure as its first
 440 element.
 441
 442 An interpreter accepts two arguments: the list representation of
 443 the element or object, and its contents.  The latter may be nil,
 444 depending on the element or object considered.  It returns the
 445 appropriate Org syntax, as a string.
 446
 447 Parsing functions must follow the naming convention:
 448 org-element-TYPE-parser, where TYPE is greater element's type, as
 449 defined in `org-element-greater-elements'.
 450
 451 Similarly, interpreting functions must follow the naming
 452 convention: org-element-TYPE-interpreter.
 453
 454 With the exception of `headline' and `item' types, greater elements
 455 cannot contain other greater elements of their own type.
 456
 457 Beside implementing a parser and an interpreter, adding a new
 458 greater element requires to tweak `org-element--current-element'.
 459 Moreover, the newly defined type must be added to both
 460 `org-element-all-elements' and `org-element-greater-elements'.
 461
 462
 463 ** Center Block
 464
 465 #+begin_src emacs-lisp
 466 (defun org-element-center-block-parser (limit affiliated)
 467   "Parse a center block.
 468
 469 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 470 the buffer position at the beginning of the first affiliated
 471 keyword and CDR is a plist of affiliated keywords along with
 472 their value.
 473
 474 Return a list whose CAR is `center-block' and CDR is a plist
 475 containing `:begin', `:end', `:hiddenp', `:contents-begin',
 476 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
 477
 478 Assume point is at the beginning of the block.")
 479
 480 (defun org-element-center-block-interpreter (center-block contents)
 481   "Interpret CENTER-BLOCK element as Org syntax.
 482 CONTENTS is the contents of the element.")
 483
 484 #+end_src
 485
 486 ** Drawer
 487
 488 #+begin_src emacs-lisp
 489 (defun org-element-drawer-parser (limit affiliated)
 490   "Parse a drawer.
 491
 492 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 493 the buffer position at the beginning of the first affiliated
 494 keyword and CDR is a plist of affiliated keywords along with
 495 their value.
 496
 497 Return a list whose CAR is `drawer' and CDR is a plist containing
 498 `:drawer-name', `:begin', `:end', `:hiddenp', `:contents-begin',
 499 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
 500
 501 Assume point is at beginning of drawer.")
 502
 503 (defun org-element-drawer-interpreter (drawer contents)
 504   "Interpret DRAWER element as Org syntax.
 505 CONTENTS is the contents of the element.")
 506
 507 #+end_src
 508
 509 ** Dynamic Block
 510
 511 #+begin_src emacs-lisp
 512 (defun org-element-dynamic-block-parser (limit affiliated)
 513   "Parse a dynamic block.
 514
 515 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 516 the buffer position at the beginning of the first affiliated
 517 keyword and CDR is a plist of affiliated keywords along with
 518 their value.
 519
 520 Return a list whose CAR is `dynamic-block' and CDR is a plist
 521 containing `:block-name', `:begin', `:end', `:hiddenp',
 522 `:contents-begin', `:contents-end', `:arguments', `:post-blank'
 523 and `:post-affiliated' keywords.
 524
 525 Assume point is at beginning of dynamic block.")
 526
 527 (defun org-element-dynamic-block-interpreter (dynamic-block contents)
 528   "Interpret DYNAMIC-BLOCK element as Org syntax.
 529 CONTENTS is the contents of the element.")
 530
 531 #+end_src
 532
 533 ** Footnote Definition
 534
 535 #+begin_src emacs-lisp
 536 (defun org-element-footnote-definition-parser (limit affiliated)
 537   "Parse a footnote definition.
 538
 539 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 540 the buffer position at the beginning of the first affiliated
 541 keyword and CDR is a plist of affiliated keywords along with
 542 their value.
 543
 544 Return a list whose CAR is `footnote-definition' and CDR is
 545 a plist containing `:label', `:begin' `:end', `:contents-begin',
 546 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
 547
 548 Assume point is at the beginning of the footnote definition.")
 549
 550 (defun org-element-footnote-definition-interpreter (footnote-definition contents)
 551   "Interpret FOOTNOTE-DEFINITION element as Org syntax.
 552 CONTENTS is the contents of the footnote-definition.")
 553
 554 #+end_src
 555
 556 ** Headline
 557
 558 #+begin_src emacs-lisp
 559 (defun org-element-headline-parser (limit &optional raw-secondary-p)
 560   "Parse a headline.
 561
 562 Return a list whose CAR is `headline' and CDR is a plist
 563 containing `:raw-value', `:title', `:alt-title', `:begin',
 564 `:end', `:pre-blank', `:hiddenp', `:contents-begin' and
 565 `:contents-end', `:level', `:priority', `:tags',
 566 `:todo-keyword',`:todo-type', `:scheduled', `:deadline',
 567 `:closed', `:quotedp', `:archivedp', `:commentedp' and
 568 `:footnote-section-p' keywords.
 569
 570 The plist also contains any property set in the property drawer,
 571 with its name in upper cases and colons added at the
 572 beginning (i.e. `:CUSTOM_ID').
 573
 574 When RAW-SECONDARY-P is non-nil, headline's title will not be
 575 parsed as a secondary string, but as a plain string instead.
 576
 577 Assume point is at beginning of the headline.")
 578
 579 (defun org-element-headline-interpreter (headline contents)
 580   "Interpret HEADLINE element as Org syntax.
 581 CONTENTS is the contents of the element.")
 582
 583 #+end_src
 584
 585 ** Inlinetask
 586
 587 #+begin_src emacs-lisp
 588 (defun org-element-inlinetask-parser (limit &optional raw-secondary-p)
 589   "Parse an inline task.
 590
 591 Return a list whose CAR is `inlinetask' and CDR is a plist
 592 containing `:title', `:begin', `:end', `:hiddenp',
 593 `:contents-begin' and `:contents-end', `:level', `:priority',
 594 `:raw-value', `:tags', `:todo-keyword', `:todo-type',
 595 `:scheduled', `:deadline', `:closed' and `:post-blank' keywords.
 596
 597 The plist also contains any property set in the property drawer,
 598 with its name in upper cases and colons added at the
 599 beginning (i.e. `:CUSTOM_ID').
 600
 601 When optional argument RAW-SECONDARY-P is non-nil, inline-task's
 602 title will not be parsed as a secondary string, but as a plain
 603 string instead.
 604
 605 Assume point is at beginning of the inline task.")
 606
 607 (defun org-element-inlinetask-interpreter (inlinetask contents)
 608   "Interpret INLINETASK element as Org syntax.
 609 CONTENTS is the contents of inlinetask.")
 610
 611 #+end_src
 612
 613 ** Item
 614
 615 #+begin_src emacs-lisp
 616 (defun org-element-item-parser (limit struct &optional raw-secondary-p)
 617   "Parse an item.
 618
 619 STRUCT is the structure of the plain list.
 620
 621 Return a list whose CAR is `item' and CDR is a plist containing
 622 `:bullet', `:begin', `:end', `:contents-begin', `:contents-end',
 623 `:checkbox', `:counter', `:tag', `:structure', `:hiddenp' and
 624 `:post-blank' keywords.
 625
 626 When optional argument RAW-SECONDARY-P is non-nil, item's tag, if
 627 any, will not be parsed as a secondary string, but as a plain
 628 string instead.
 629
 630 Assume point is at the beginning of the item.")
 631
 632 (defun org-element-item-interpreter (item contents)
 633   "Interpret ITEM element as Org syntax.
 634 CONTENTS is the contents of the element.")
 635
 636 #+end_src
 637
 638 ** Plain List
 639
 640 #+begin_src emacs-lisp
 641 (defun org-element-plain-list-parser (limit affiliated structure)
 642   "Parse a plain list.
 643
 644 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 645 the buffer position at the beginning of the first affiliated
 646 keyword and CDR is a plist of affiliated keywords along with
 647 their value.  STRUCTURE is the structure of the plain list being
 648 parsed.
 649
 650 Return a list whose CAR is `plain-list' and CDR is a plist
 651 containing `:type', `:begin', `:end', `:contents-begin' and
 652 `:contents-end', `:structure', `:post-blank' and
 653 `:post-affiliated' keywords.
 654
 655 Assume point is at the beginning of the list.")
 656
 657 (defun org-element-plain-list-interpreter (plain-list contents)
 658   "Interpret PLAIN-LIST element as Org syntax.
 659 CONTENTS is the contents of the element.")
 660
 661 #+end_src
 662
 663 ** Property Drawer
 664
 665 #+begin_src emacs-lisp
 666 (defun org-element-property-drawer-parser (limit affiliated)
 667   "Parse a property drawer.
 668
 669 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 670 the buffer position at the beginning of the first affiliated
 671 keyword and CDR is a plist of affiliated keywords along with
 672 their value.
 673
 674 Return a list whose CAR is `property-drawer' and CDR is a plist
 675 containing `:begin', `:end', `:hiddenp', `:contents-begin',
 676 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
 677
 678 Assume point is at the beginning of the property drawer.")
 679
 680 (defun org-element-property-drawer-interpreter (property-drawer contents)
 681   "Interpret PROPERTY-DRAWER element as Org syntax.
 682 CONTENTS is the properties within the drawer.")
 683
 684 #+end_src
 685
 686 ** Quote Block
 687
 688 #+begin_src emacs-lisp
 689 (defun org-element-quote-block-parser (limit affiliated)
 690   "Parse a quote block.
 691
 692 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 693 the buffer position at the beginning of the first affiliated
 694 keyword and CDR is a plist of affiliated keywords along with
 695 their value.
 696
 697 Return a list whose CAR is `quote-block' and CDR is a plist
 698 containing `:begin', `:end', `:hiddenp', `:contents-begin',
 699 `:contents-end', `:post-blank' and `:post-affiliated' keywords.
 700
 701 Assume point is at the beginning of the block.")
 702
 703 (defun org-element-quote-block-interpreter (quote-block contents)
 704   "Interpret QUOTE-BLOCK element as Org syntax.
 705 CONTENTS is the contents of the element.")
 706
 707 #+end_src
 708
 709 ** Section
 710
 711 #+begin_src emacs-lisp
 712 (defun org-element-section-parser (limit)
 713   "Parse a section.
 714
 715 LIMIT bounds the search.
 716
 717 Return a list whose CAR is `section' and CDR is a plist
 718 containing `:begin', `:end', `:contents-begin', `contents-end'
 719 and `:post-blank' keywords.")
 720
 721 (defun org-element-section-interpreter (section contents)
 722   "Interpret SECTION element as Org syntax.
 723 CONTENTS is the contents of the element."
 724  )
 725
 726 #+end_src
 727
 728 ** Special Block
 729
 730 #+begin_src emacs-lisp
 731 (defun org-element-special-block-parser (limit affiliated)
 732   "Parse a special block.
 733
 734 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 735 the buffer position at the beginning of the first affiliated
 736 keyword and CDR is a plist of affiliated keywords along with
 737 their value.
 738
 739 Return a list whose CAR is `special-block' and CDR is a plist
 740 containing `:type', `:begin', `:end', `:hiddenp',
 741 `:contents-begin', `:contents-end', `:post-blank' and
 742 `:post-affiliated' keywords.
 743
 744 Assume point is at the beginning of the block.")
 745
 746 (defun org-element-special-block-interpreter (special-block contents)
 747   "Interpret SPECIAL-BLOCK element as Org syntax.
 748 CONTENTS is the contents of the element.")
 749
 750
 751 #+end_src
 752
 753 * Elements
 754
 755 For each element, a parser and an interpreter are also defined.
 756 Both follow the same naming convention used for greater elements.
 757
 758 Also, as for greater elements, adding a new element type is done
 759 through the following steps: implement a parser and an interpreter,
 760 tweak `org-element--current-element' so that it recognizes the new
 761 type and add that new type to `org-element-all-elements'.
 762
 763 As a special case, when the newly defined type is a block type,
 764 `org-element-block-name-alist' has to be modified accordingly.
 765
 766
 767 ** Babel Call
 768
 769 #+begin_src emacs-lisp
 770 (defun org-element-babel-call-parser (limit affiliated)
 771   "Parse a babel call.
 772
 773 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 774 the buffer position at the beginning of the first affiliated
 775 keyword and CDR is a plist of affiliated keywords along with
 776 their value.
 777
 778 Return a list whose CAR is `babel-call' and CDR is a plist
 779 containing `:begin', `:end', `:info', `:post-blank' and
 780 `:post-affiliated' as keywords.")
 781
 782 (defun org-element-babel-call-interpreter (babel-call contents)
 783   "Interpret BABEL-CALL element as Org syntax.
 784 CONTENTS is nil.")
 785
 786 #+end_src
 787
 788 ** Clock
 789
 790 #+begin_src emacs-lisp
 791 (defun org-element-clock-parser (limit)
 792   "Parse a clock.
 793
 794 LIMIT bounds the search.
 795
 796 Return a list whose CAR is `clock' and CDR is a plist containing
 797 `:status', `:value', `:time', `:begin', `:end' and `:post-blank'
 798 as keywords.")
 799
 800 (defun org-element-clock-interpreter (clock contents)
 801   "Interpret CLOCK element as Org syntax.
 802 CONTENTS is nil.")
 803
 804 #+end_src
 805
 806 ** Comment
 807
 808 #+begin_src emacs-lisp
 809 (defun org-element-comment-parser (limit affiliated)
 810   "Parse a comment.
 811
 812 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 813 the buffer position at the beginning of the first affiliated
 814 keyword and CDR is a plist of affiliated keywords along with
 815 their value.
 816
 817 Return a list whose CAR is `comment' and CDR is a plist
 818 containing `:begin', `:end', `:value', `:post-blank',
 819 `:post-affiliated' keywords.
 820
 821 Assume point is at comment beginning.")
 822
 823 (defun org-element-comment-interpreter (comment contents)
 824   "Interpret COMMENT element as Org syntax.
 825 CONTENTS is nil.")
 826
 827 #+end_src
 828
 829 ** Comment Block
 830
 831 #+begin_src emacs-lisp
 832 (defun org-element-comment-block-parser (limit affiliated)
 833   "Parse an export block.
 834
 835 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 836 the buffer position at the beginning of the first affiliated
 837 keyword and CDR is a plist of affiliated keywords along with
 838 their value.
 839
 840 Return a list whose CAR is `comment-block' and CDR is a plist
 841 containing `:begin', `:end', `:hiddenp', `:value', `:post-blank'
 842 and `:post-affiliated' keywords.
 843
 844 Assume point is at comment block beginning.")
 845
 846 (defun org-element-comment-block-interpreter (comment-block contents)
 847   "Interpret COMMENT-BLOCK element as Org syntax.
 848 CONTENTS is nil.")
 849
 850 #+end_src
 851
 852 ** Diary Sexp
 853
 854 #+begin_src emacs-lisp
 855 (defun org-element-diary-sexp-parser (limit affiliated)
 856   "Parse a diary sexp.
 857
 858 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 859 the buffer position at the beginning of the first affiliated
 860 keyword and CDR is a plist of affiliated keywords along with
 861 their value.
 862
 863 Return a list whose CAR is `diary-sexp' and CDR is a plist
 864 containing `:begin', `:end', `:value', `:post-blank' and
 865 `:post-affiliated' keywords.")
 866
 867 (defun org-element-diary-sexp-interpreter (diary-sexp contents)
 868   "Interpret DIARY-SEXP as Org syntax.
 869 CONTENTS is nil.")
 870
 871 #+end_src
 872
 873 ** Example Block
 874
 875 #+begin_src emacs-lisp
 876 (defun org-element--remove-indentation (s &optional n)
 877   "Remove maximum common indentation in string S and return it.
 878 When optional argument N is a positive integer, remove exactly
 879 that much characters from indentation, if possible, or return
 880 S as-is otherwise.  Unlike to `org-remove-indentation', this
 881 function doesn't call `untabify' on S.")
 882
 883 (defun org-element-example-block-parser (limit affiliated)
 884   "Parse an example block.
 885
 886 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 887 the buffer position at the beginning of the first affiliated
 888 keyword and CDR is a plist of affiliated keywords along with
 889 their value.
 890
 891 Return a list whose CAR is `example-block' and CDR is a plist
 892 containing `:begin', `:end', `:number-lines', `:preserve-indent',
 893 `:retain-labels', `:use-labels', `:label-fmt', `:hiddenp',
 894 `:switches', `:value', `:post-blank' and `:post-affiliated'
 895 keywords.")
 896
 897 (defun org-element-src-block-interpreter (src-block contents)
 898   "Interpret SRC-BLOCK element as Org syntax.
 899 CONTENTS is nil.")
 900
 901 #+end_src
 902
 903 ** Table
 904
 905 #+begin_src emacs-lisp
 906 (defun org-element-table-parser (limit affiliated)
 907   "Parse a table at point.
 908
 909 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 910 the buffer position at the beginning of the first affiliated
 911 keyword and CDR is a plist of affiliated keywords along with
 912 their value.
 913
 914 Return a list whose CAR is `table' and CDR is a plist containing
 915 `:begin', `:end', `:tblfm', `:type', `:contents-begin',
 916 `:contents-end', `:value', `:post-blank' and `:post-affiliated'
 917 keywords.
 918
 919 Assume point is at the beginning of the table.")
 920
 921 (defun org-element-table-interpreter (table contents)
 922   "Interpret TABLE element as Org syntax.
 923 CONTENTS is nil.")
 924
 925 #+end_src
 926
 927 ** Table Row
 928
 929 #+begin_src emacs-lisp
 930 (defun org-element-table-row-parser (limit)
 931   "Parse table row at point.
 932
 933 LIMIT bounds the search.
 934
 935 Return a list whose CAR is `table-row' and CDR is a plist
 936 containing `:begin', `:end', `:contents-begin', `:contents-end',
 937 `:type' and `:post-blank' keywords.")
 938
 939 (defun org-element-table-row-interpreter (table-row contents)
 940   "Interpret TABLE-ROW element as Org syntax.
 941 CONTENTS is the contents of the table row.")
 942
 943 #+end_src
 944
 945 ** Verse Block
 946
 947 #+begin_src emacs-lisp
 948 (defun org-element-verse-block-parser (limit affiliated)
 949   "Parse a verse block.
 950
 951 LIMIT bounds the search.  AFFILIATED is a list of which CAR is
 952 the buffer position at the beginning of the first affiliated
 953 keyword and CDR is a plist of affiliated keywords along with
 954 their value.
 955
 956 Return a list whose CAR is `verse-block' and CDR is a plist
 957 containing `:begin', `:end', `:contents-begin', `:contents-end',
 958 `:hiddenp', `:post-blank' and `:post-affiliated' keywords.
 959
 960 Assume point is at beginning of the block.")
 961
 962 (defun org-element-verse-block-interpreter (verse-block contents)
 963   "Interpret VERSE-BLOCK element as Org syntax.
 964 CONTENTS is verse block contents.")
 965
 966
 967 #+end_src
 968
 969 * Objects
 970
 971 Unlike to elements, interstices can be found between objects.
 972 That's why, along with the parser, successor functions are provided
 973 for each object.  Some objects share the same successor (i.e. `code'
 974 and `verbatim' objects).
 975
 976 A successor must accept a single argument bounding the search.  It
 977 will return either a cons cell whose CAR is the object's type, as
 978 a symbol, and CDR the position of its next occurrence, or nil.
 979
 980 Successors follow the naming convention:
 981 org-element-NAME-successor, where NAME is the name of the
 982 successor, as defined in `org-element-all-successors'.
 983
 984 Some object types (i.e. `italic') are recursive.  Restrictions on
 985 object types they can contain will be specified in
 986 `org-element-object-restrictions'.
 987
 988 Adding a new type of object is simple.  Implement a successor,
 989 a parser, and an interpreter for it, all following the naming
 990 convention.  Register type in `org-element-all-objects' and
 991 successor in `org-element-all-successors'.  Maybe tweak
 992 restrictions about it, and that's it.
 993
 994
 995 ** Bold
 996
 997 #+begin_src emacs-lisp
 998 (defun org-element-bold-parser ()
 999   "Parse bold object at point.
1000
1001 Return a list whose CAR is `bold' and CDR is a plist with
1002 `:begin', `:end', `:contents-begin' and `:contents-end' and
1003 `:post-blank' keywords.
1004
1005 Assume point is at the first star marker.")
1006
1007 (defun org-element-bold-interpreter (bold contents)
1008   "Interpret BOLD object as Org syntax.
1009 CONTENTS is the contents of the object.")
1010
1011 (defun org-element-text-markup-successor (limit)
1012   "Search for the next text-markup object.
1013
1014 LIMIT bounds the search.
1015
1016 Return value is a cons cell whose CAR is a symbol among `bold',
1017 `italic', `underline', `strike-through', `code' and `verbatim'
1018 and CDR is beginning position.")
1019
1020 #+end_src
1021
1022 ** Code
1023
1024 #+begin_src emacs-lisp
1025 (defun org-element-code-parser ()
1026   "Parse code object at point.
1027
1028 Return a list whose CAR is `code' and CDR is a plist with
1029 `:value', `:begin', `:end' and `:post-blank' keywords.
1030
1031 Assume point is at the first tilde marker.")
1032
1033 (defun org-element-code-interpreter (code contents)
1034   "Interpret CODE object as Org syntax.
1035 CONTENTS is nil.")
1036
1037 #+end_src
1038
1039 ** Entity
1040
1041 #+begin_src emacs-lisp
1042 (defun org-element-entity-parser ()
1043   "Parse entity at point.
1044
1045 Return a list whose CAR is `entity' and CDR a plist with
1046 `:begin', `:end', `:latex', `:latex-math-p', `:html', `:latin1',
1047 `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as
1048 keywords.
1049
1050 Assume point is at the beginning of the entity.")
1051
1052 (defun org-element-entity-interpreter (entity contents)
1053   "Interpret ENTITY object as Org syntax.
1054 CONTENTS is nil.")
1055
1056 (defun org-element-latex-or-entity-successor (limit)
1057   "Search for the next latex-fragment or entity object.
1058
1059 LIMIT bounds the search.
1060
1061 Return value is a cons cell whose CAR is `entity' or
1062 `latex-fragment' and CDR is beginning position.")
1063
1064 #+end_src
1065
1066 ** Export Snippet
1067
1068 #+begin_src emacs-lisp
1069 (defun org-element-export-snippet-parser ()
1070   "Parse export snippet at point.
1071
1072 Return a list whose CAR is `export-snippet' and CDR a plist with
1073 `:begin', `:end', `:back-end', `:value' and `:post-blank' as
1074 keywords.
1075
1076 Assume point is at the beginning of the snippet.")
1077
1078 (defun org-element-export-snippet-interpreter (export-snippet contents)
1079   "Interpret EXPORT-SNIPPET object as Org syntax.
1080 CONTENTS is nil.")
1081
1082 (defun org-element-export-snippet-successor (limit)
1083   "Search for the next export-snippet object.
1084
1085 LIMIT bounds the search.
1086
1087 Return value is a cons cell whose CAR is `export-snippet' and CDR
1088 its beginning position.")
1089
1090 #+end_src
1091
1092 ** Footnote Reference
1093
1094 #+begin_src emacs-lisp
1095 (defun org-element-footnote-reference-parser ()
1096   "Parse footnote reference at point.
1097
1098 Return a list whose CAR is `footnote-reference' and CDR a plist
1099 with `:label', `:type', `:inline-definition', `:begin', `:end'
1100 and `:post-blank' as keywords.")
1101
1102 (defun org-element-footnote-reference-interpreter (footnote-reference contents)
1103   "Interpret FOOTNOTE-REFERENCE object as Org syntax.
1104 CONTENTS is nil.")
1105
1106 (defun org-element-footnote-reference-successor (limit)
1107   "Search for the next footnote-reference object.
1108
1109 LIMIT bounds the search.
1110
1111 Return value is a cons cell whose CAR is `footnote-reference' and
1112 CDR is beginning position.")
1113
1114 #+end_src
1115
1116 ** Inline Babel Call
1117
1118 #+begin_src emacs-lisp
1119 (defun org-element-inline-babel-call-parser ()
1120   "Parse inline babel call at point.
1121
1122 Return a list whose CAR is `inline-babel-call' and CDR a plist
1123 with `:begin', `:end', `:info' and `:post-blank' as keywords.
1124
1125 Assume point is at the beginning of the babel call.")
1126
1127 (defun org-element-inline-babel-call-interpreter (inline-babel-call contents)
1128   "Interpret INLINE-BABEL-CALL object as Org syntax.
1129 CONTENTS is nil.")
1130
1131 (defun org-element-inline-babel-call-successor (limit)
1132   "Search for the next inline-babel-call object.
1133
1134 LIMIT bounds the search.
1135
1136 Return value is a cons cell whose CAR is `inline-babel-call' and
1137 CDR is beginning position.")
1138
1139 #+end_src
1140
1141 ** Inline Src Block
1142
1143 #+begin_src emacs-lisp
1144 (defun org-element-inline-src-block-parser ()
1145   "Parse inline source block at point.
1146
1147 LIMIT bounds the search.
1148
1149 Return a list whose CAR is `inline-src-block' and CDR a plist
1150 with `:begin', `:end', `:language', `:value', `:parameters' and
1151 `:post-blank' as keywords.
1152
1153 Assume point is at the beginning of the inline src block.")
1154
1155 (defun org-element-inline-src-block-interpreter (inline-src-block contents)
1156   "Interpret INLINE-SRC-BLOCK object as Org syntax.
1157 CONTENTS is nil.")
1158
1159 (defun org-element-inline-src-block-successor (limit)
1160   "Search for the next inline-babel-call element.
1161
1162 LIMIT bounds the search.
1163
1164 Return value is a cons cell whose CAR is `inline-babel-call' and
1165 CDR is beginning position.")
1166 #+end_src
1167
1168 ** Italic
1169
1170 #+begin_src emacs-lisp
1171 (defun org-element-italic-parser ()
1172   "Parse italic object at point.
1173
1174 Return a list whose CAR is `italic' and CDR is a plist with
1175 `:begin', `:end', `:contents-begin' and `:contents-end' and
1176 `:post-blank' keywords.
1177
1178 Assume point is at the first slash marker.")
1179
1180 (defun org-element-italic-interpreter (italic contents)
1181   "Interpret ITALIC object as Org syntax.
1182 CONTENTS is the contents of the object.")
1183
1184 #+end_src
1185
1186 ** Latex Fragment
1187
1188 #+begin_src emacs-lisp
1189 (defun org-element-latex-fragment-parser ()
1190   "Parse latex fragment at point.
1191
1192 Return a list whose CAR is `latex-fragment' and CDR a plist with
1193 `:value', `:begin', `:end', and `:post-blank' as keywords.
1194
1195 Assume point is at the beginning of the latex fragment.")
1196
1197 (defun org-element-latex-fragment-interpreter (latex-fragment contents)
1198   "Interpret LATEX-FRAGMENT object as Org syntax.
1199 CONTENTS is nil.")
1200 #+end_src
1201
1202 ** Line Break
1203
1204 #+begin_src emacs-lisp
1205 (defun org-element-line-break-parser ()
1206   "Parse line break at point.
1207
1208 Return a list whose CAR is `line-break', and CDR a plist with
1209 `:begin', `:end' and `:post-blank' keywords.
1210
1211 Assume point is at the beginning of the line break.")
1212
1213 (defun org-element-line-break-interpreter (line-break contents)
1214   "Interpret LINE-BREAK object as Org syntax.
1215 CONTENTS is nil.")
1216
1217 (defun org-element-line-break-successor (limit)
1218   "Search for the next line-break object.
1219
1220 LIMIT bounds the search.
1221
1222 Return value is a cons cell whose CAR is `line-break' and CDR is
1223 beginning position.")
1224
1225 #+end_src
1226
1227 ** Link
1228
1229 #+begin_src emacs-lisp
1230 (defun org-element-link-parser ()
1231   "Parse link at point.
1232
1233 Return a list whose CAR is `link' and CDR a plist with `:type',
1234 `:path', `:raw-link', `:application', `:search-option', `:begin',
1235 `:end', `:contents-begin', `:contents-end' and `:post-blank' as
1236 keywords.
1237
1238 Assume point is at the beginning of the link.")
1239
1240 (defun org-element-link-interpreter (link contents)
1241   "Interpret LINK object as Org syntax.
1242 CONTENTS is the contents of the object, or nil.")
1243
1244 (defun org-element-link-successor (limit)
1245   "Search for the next link object.
1246
1247 LIMIT bounds the search.
1248
1249 Return value is a cons cell whose CAR is `link' and CDR is
1250 beginning position.")
1251
1252 (defun org-element-plain-link-successor (limit)
1253   "Search for the next plain link object.
1254
1255 LIMIT bounds the search.
1256
1257 Return value is a cons cell whose CAR is `link' and CDR is
1258 beginning position.")
1259
1260 #+end_src
1261
1262 ** Macro
1263
1264 #+begin_src emacs-lisp
1265 (defun org-element-macro-parser ()
1266   "Parse macro at point.
1267
1268 Return a list whose CAR is `macro' and CDR a plist with `:key',
1269 `:args', `:begin', `:end', `:value' and `:post-blank' as
1270 keywords.
1271
1272 Assume point is at the macro.")
1273
1274 (defun org-element-macro-interpreter (macro contents)
1275   "Interpret MACRO object as Org syntax.
1276 CONTENTS is nil.")
1277
1278 (defun org-element-macro-successor (limit)
1279   "Search for the next macro object.
1280
1281 LIMIT bounds the search.
1282
1283 Return value is cons cell whose CAR is `macro' and CDR is
1284 beginning position.")
1285
1286 #+end_src
1287
1288 ** Radio-target
1289
1290 #+begin_src emacs-lisp
1291 (defun org-element-radio-target-parser ()
1292   "Parse radio target at point.
1293
1294 Return a list whose CAR is `radio-target' and CDR a plist with
1295 `:begin', `:end', `:contents-begin', `:contents-end', `:value'
1296 and `:post-blank' as keywords.
1297
1298 Assume point is at the radio target.")
1299
1300 (defun org-element-radio-target-interpreter (target contents)
1301   "Interpret TARGET object as Org syntax.
1302 CONTENTS is the contents of the object.")
1303
1304 (defun org-element-radio-target-successor (limit)
1305   "Search for the next radio-target object.
1306
1307 LIMIT bounds the search.
1308
1309 Return value is a cons cell whose CAR is `radio-target' and CDR
1310 is beginning position.")
1311
1312 #+end_src
1313
1314 ** Statistics Cookie
1315
1316 #+begin_src emacs-lisp
1317 (defun org-element-statistics-cookie-parser ()
1318   "Parse statistics cookie at point.
1319
1320 Return a list whose CAR is `statistics-cookie', and CDR a plist
1321 with `:begin', `:end', `:value' and `:post-blank' keywords.
1322
1323 Assume point is at the beginning of the statistics-cookie.")
1324
1325 (defun org-element-statistics-cookie-interpreter (statistics-cookie contents)
1326   "Interpret STATISTICS-COOKIE object as Org syntax.
1327 CONTENTS is nil.")
1328
1329 (defun org-element-statistics-cookie-successor (limit)
1330   "Search for the next statistics cookie object.
1331
1332 LIMIT bounds the search.
1333
1334 Return value is a cons cell whose CAR is `statistics-cookie' and
1335 CDR is beginning position.")
1336
1337 #+end_src
1338
1339 ** Strike-Through
1340
1341 #+begin_src emacs-lisp
1342 (defun org-element-strike-through-parser ()
1343   "Parse strike-through object at point.
1344
1345 Return a list whose CAR is `strike-through' and CDR is a plist
1346 with `:begin', `:end', `:contents-begin' and `:contents-end' and
1347 `:post-blank' keywords.
1348
1349 Assume point is at the first plus sign marker.")
1350
1351 (defun org-element-strike-through-interpreter (strike-through contents)
1352   "Interpret STRIKE-THROUGH object as Org syntax.
1353 CONTENTS is the contents of the object.")
1354
1355 #+end_src
1356
1357 ** Subscript
1358
1359 #+begin_src emacs-lisp
1360 (defun org-element-subscript-parser ()
1361   "Parse subscript at point.
1362
1363 Return a list whose CAR is `subscript' and CDR a plist with
1364 `:begin', `:end', `:contents-begin', `:contents-end',
1365 `:use-brackets-p' and `:post-blank' as keywords.
1366
1367 Assume point is at the underscore.")
1368
1369 (defun org-element-subscript-interpreter (subscript contents)
1370   "Interpret SUBSCRIPT object as Org syntax.
1371 CONTENTS is the contents of the object.")
1372
1373 (defun org-element-sub/superscript-successor  (limit)
1374   "Search for the next sub/superscript object.
1375
1376 LIMIT bounds the search.
1377
1378 Return value is a cons cell whose CAR is either `subscript' or
1379 `superscript' and CDR is beginning position.")
1380
1381 #+end_src
1382
1383 ** Superscript
1384
1385 #+begin_src emacs-lisp
1386 (defun org-element-superscript-parser ()
1387   "Parse superscript at point.
1388
1389 Return a list whose CAR is `superscript' and CDR a plist with
1390 `:begin', `:end', `:contents-begin', `:contents-end',
1391 `:use-brackets-p' and `:post-blank' as keywords.
1392
1393 Assume point is at the caret.")
1394
1395 (defun org-element-superscript-interpreter (superscript contents)
1396   "Interpret SUPERSCRIPT object as Org syntax.
1397 CONTENTS is the contents of the object.")
1398
1399 #+end_src
1400
1401 ** Table Cell
1402
1403 #+begin_src emacs-lisp
1404 (defun org-element-table-cell-parser ()
1405   "Parse table cell at point.
1406
1407 Return a list whose CAR is `table-cell' and CDR is a plist
1408 containing `:begin', `:end', `:contents-begin', `:contents-end'
1409 and `:post-blank' keywords.")
1410
1411 (defun org-element-table-cell-interpreter (table-cell contents)
1412   "Interpret TABLE-CELL element as Org syntax.
1413 CONTENTS is the contents of the cell, or nil.")
1414
1415 (defun org-element-table-cell-successor (limit)
1416   "Search for the next table-cell object.
1417
1418 LIMIT bounds the search.
1419
1420 Return value is a cons cell whose CAR is `table-cell' and CDR is
1421 beginning position.")
1422
1423 #+end_src
1424
1425 ** Target
1426
1427 #+begin_src emacs-lisp
1428 (defun org-element-target-parser ()
1429   "Parse target at point.
1430
1431 Return a list whose CAR is `target' and CDR a plist with
1432 `:begin', `:end', `:value' and `:post-blank' as keywords.
1433
1434 Assume point is at the target.")
1435
1436 (defun org-element-target-interpreter (target contents)
1437   "Interpret TARGET object as Org syntax.
1438 CONTENTS is nil.")
1439
1440 (defun org-element-target-successor (limit)
1441   "Search for the next target object.
1442
1443 LIMIT bounds the search.
1444
1445 Return value is a cons cell whose CAR is `target' and CDR is
1446 beginning position.")
1447
1448 #+end_src
1449
1450 ** Timestamp
1451
1452 #+begin_src emacs-lisp
1453 (defun org-element-timestamp-parser ()
1454   "Parse time stamp at point.
1455
1456 Return a list whose CAR is `timestamp', and CDR a plist with
1457 `:type', `:begin', `:end', `:value' and `:post-blank' keywords.
1458
1459 Assume point is at the beginning of the timestamp.")
1460
1461 (defun org-element-timestamp-interpreter (timestamp contents)
1462   "Interpret TIMESTAMP object as Org syntax.
1463 CONTENTS is nil.")
1464
1465 (defun org-element-timestamp-successor (limit)
1466   "Search for the next timestamp object.
1467
1468 LIMIT bounds the search.
1469
1470 Return value is a cons cell whose CAR is `timestamp' and CDR is
1471 beginning position.")
1472
1473 #+end_src
1474
1475 ** Underline
1476
1477 #+begin_src emacs-lisp
1478 (defun org-element-underline-parser ()
1479   "Parse underline object at point.
1480
1481 Return a list whose CAR is `underline' and CDR is a plist with
1482 `:begin', `:end', `:contents-begin' and `:contents-end' and
1483 `:post-blank' keywords.
1484
1485 Assume point is at the first underscore marker.")
1486
1487 (defun org-element-underline-interpreter (underline contents)
1488   "Interpret UNDERLINE object as Org syntax.
1489 CONTENTS is the contents of the object.")
1490
1491 #+end_src
1492
1493 ** Verbatim
1494
1495 #+begin_src emacs-lisp
1496 (defun org-element-verbatim-parser ()
1497   "Parse verbatim object at point.
1498
1499 Return a list whose CAR is `verbatim' and CDR is a plist with
1500 `:value', `:begin', `:end' and `:post-blank' keywords.
1501
1502 Assume point is at the first equal sign marker.")
1503
1504 (defun org-element-verbatim-interpreter (verbatim contents)
1505   "Interpret VERBATIM object as Org syntax.
1506 CONTENTS is nil.")
1507
1508
1509 #+end_src
1510
1511 * Parsing Element Starting At Point
1512
1513 `org-element--current-element' is the core function of this section.
1514 It returns the Lisp representation of the element starting at
1515 point.
1516
1517 `org-element--current-element' makes use of special modes.  They
1518 are activated for fixed element chaining (i.e. `plain-list' >
1519 `item') or fixed conditional element chaining (i.e. `headline' >
1520 `section').  Special modes are: `first-section', `item',
1521 `node-property', `quote-section', `section' and `table-row'.
1522
1523 #+begin_src emacs-lisp
1524 (defun org-element--current-element
1525   (limit &optional granularity special structure)
1526   "Parse the element starting at point.
1527
1528 LIMIT bounds the search.
1529
1530 Return value is a list like (TYPE PROPS) where TYPE is the type
1531 of the element and PROPS a plist of properties associated to the
1532 element.
1533
1534 Possible types are defined in `org-element-all-elements'.
1535
1536 Optional argument GRANULARITY determines the depth of the
1537 recursion.  Allowed values are `headline', `greater-element',
1538 `element', `object' or nil.  When it is broader than `object' (or
1539 nil), secondary values will not be parsed, since they only
1540 contain objects.
1541
1542 Optional argument SPECIAL, when non-nil, can be either
1543 `first-section', `item', `node-property', `quote-section',
1544 `section', and `table-row'.
1545
1546 If STRUCTURE isn't provided but SPECIAL is set to `item', it will
1547 be computed.
1548
1549 This function assumes point is always at the beginning of the
1550 element it has to parse.")
1551
1552 #+end_src
1553
1554 Most elements can have affiliated keywords.  When looking for an
1555 element beginning, we want to move before them, as they belong to
1556 that element, and, in the meantime, collect information they give
1557 into appropriate properties.  Hence the following function.
1558
1559 #+begin_src emacs-lisp
1560 (defun org-element--collect-affiliated-keywords (limit)
1561   "Collect affiliated keywords from point down to LIMIT.
1562
1563 Return a list whose CAR is the position at the first of them and
1564 CDR a plist of keywords and values and move point to the
1565 beginning of the first line after them.
1566
1567 As a special case, if element doesn't start at the beginning of
1568 the line (i.e. a paragraph starting an item), CAR is current
1569 position of point and CDR is nil.")
1570
1571
1572 #+end_src
1573
1574 * The Org Parser
1575
1576 The two major functions here are `org-element-parse-buffer', which
1577 parses Org syntax inside the current buffer, taking into account
1578 region, narrowing, or even visibility if specified, and
1579 `org-element-parse-secondary-string', which parses objects within
1580 a given string.
1581
1582 The (almost) almighty `org-element-map' allows to apply a function
1583 on elements or objects matching some type, and accumulate the
1584 resulting values.  In an export situation, it also skips unneeded
1585 parts of the parse tree.
1586
1587 #+begin_src emacs-lisp
1588 (defun org-element-parse-buffer (&optional granularity visible-only)
1589   "Recursively parse the buffer and return structure.
1590 If narrowing is in effect, only parse the visible part of the
1591 buffer.
1592
1593 Optional argument GRANULARITY determines the depth of the
1594 recursion.  It can be set to the following symbols:
1595
1596 `headline'          Only parse headlines.
1597 `greater-element'   Don't recurse into greater elements excepted
1598                     headlines and sections.  Thus, elements
1599                     parsed are the top-level ones.
1600 `element'           Parse everything but objects and plain text.
1601 `object'            Parse the complete buffer (default).
1602
1603 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
1604 elements.
1605
1606 An element or an objects is represented as a list with the
1607 pattern (TYPE PROPERTIES CONTENTS), where :
1608
1609   TYPE is a symbol describing the element or object.  See
1610   `org-element-all-elements' and `org-element-all-objects' for an
1611   exhaustive list of such symbols.  One can retrieve it with
1612   `org-element-type' function.
1613
1614   PROPERTIES is the list of attributes attached to the element or
1615   object, as a plist.  Although most of them are specific to the
1616   element or object type, all types share `:begin', `:end',
1617   `:post-blank' and `:parent' properties, which respectively
1618   refer to buffer position where the element or object starts,
1619   ends, the number of white spaces or blank lines after it, and
1620   the element or object containing it.  Properties values can be
1621   obtained by using `org-element-property' function.
1622
1623   CONTENTS is a list of elements, objects or raw strings
1624   contained in the current element or object, when applicable.
1625   One can access them with `org-element-contents' function.
1626
1627 The Org buffer has `org-data' as type and nil as properties.
1628 `org-element-map' function can be used to find specific elements
1629 or objects within the parse tree.
1630
1631 This function assumes that current major mode is `org-mode'.")
1632
1633 (defun org-element-parse-secondary-string (string restriction &optional parent)
1634   "Recursively parse objects in STRING and return structure.
1635
1636 RESTRICTION is a symbol limiting the object types that will be
1637 looked after.
1638
1639 Optional argument PARENT, when non-nil, is the element or object
1640 containing the secondary string.  It is used to set correctly
1641 `:parent' property within the string."
1642   ;; Copy buffer-local variables listed in
1643   ;; `org-element-object-variables' into temporary buffer.  This is
1644   ;; required since object parsing is dependent on these variables.)
1645
1646 (defun org-element-map
1647   (data types fun &optional info first-match no-recursion with-affiliated)
1648   "Map a function on selected elements or objects.
1649
1650 DATA is a parse tree, an element, an object, a string, or a list
1651 of such constructs.  TYPES is a symbol or list of symbols of
1652 elements or objects types (see `org-element-all-elements' and
1653 `org-element-all-objects' for a complete list of types).  FUN is
1654 the function called on the matching element or object.  It has to
1655 accept one argument: the element or object itself.
1656
1657 When optional argument INFO is non-nil, it should be a plist
1658 holding export options.  In that case, parts of the parse tree
1659 not exportable according to that property list will be skipped.
1660
1661 When optional argument FIRST-MATCH is non-nil, stop at the first
1662 match for which FUN doesn't return nil, and return that value.
1663
1664 Optional argument NO-RECURSION is a symbol or a list of symbols
1665 representing elements or objects types.  `org-element-map' won't
1666 enter any recursive element or object whose type belongs to that
1667 list.  Though, FUN can still be applied on them.
1668
1669 When optional argument WITH-AFFILIATED is non-nil, FUN will also
1670 apply to matching objects within parsed affiliated keywords (see
1671 `org-element-parsed-keywords').
1672
1673 Nil values returned from FUN do not appear in the results.
1674
1675
1676 Examples:
1677 ---------
1678
1679 Assuming TREE is a variable containing an Org buffer parse tree,
1680 the following example will return a flat list of all `src-block'
1681 and `example-block' elements in it:
1682
1683   \(org-element-map tree '(example-block src-block) 'identity)
1684
1685 The following snippet will find the first headline with a level
1686 of 1 and a \"phone\" tag, and will return its beginning position:
1687
1688   \(org-element-map tree 'headline
1689    \(lambda (hl)
1690      \(and (= (org-element-property :level hl) 1)
1691           \(member \"phone\" (org-element-property :tags hl))
1692           \(org-element-property :begin hl)))
1693    nil t)
1694
1695 The next example will return a flat list of all `plain-list' type
1696 elements in TREE that are not a sub-list themselves:
1697
1698   \(org-element-map tree 'plain-list 'identity nil nil 'plain-list)
1699
1700 Eventually, this example will return a flat list of all `bold'
1701 type objects containing a `latex-snippet' type object, even
1702 looking into captions:
1703
1704   \(org-element-map tree 'bold
1705    \(lambda (b)
1706      \(and (org-element-map b 'latex-snippet 'identity nil t) b))
1707    nil nil nil t)"
1708   ;; Ensure TYPES and NO-RECURSION are a list, even of one element.
1709   (unless (listp types) (setq types (list types)))
1710   (unless (listp no-recursion) (setq no-recursion (list no-recursion)))
1711   ;; Recursion depth is determined by --CATEGORY.
1712   (let* ((--category
1713           (catch 'found
1714             (let ((category 'greater-elements))
1715               (mapc (lambda (type)
1716                       (cond ((or (memq type org-element-all-objects)
1717                                  (eq type 'plain-text))
1718                              ;; If one object is found, the function
1719                              ;; has to recurse into every object.
1720                              (throw 'found 'objects))
1721                             ((not (memq type org-element-greater-elements))
1722                              ;; If one regular element is found, the
1723                              ;; function has to recurse, at least,
1724                              ;; into every element it encounters.
1725                              (and (not (eq category 'elements))
1726                                   (setq category 'elements)))))
1727                     types)
1728               category)))
1729          ;; Compute properties for affiliated keywords if necessary.
1730          (--affiliated-alist
1731           (and with-affiliated
1732                (mapcar (lambda (kwd)
1733                          (cons kwd (intern (concat ":" (downcase kwd)))))
1734                        org-element-affiliated-keywords)))
1735          --acc
1736          --walk-tree
1737          (--walk-tree
1738           (function
1739            (lambda (--data)
1740              ;; Recursively walk DATA.  INFO, if non-nil, is a plist
1741              ;; holding contextual information.
1742              (let ((--type (org-element-type --data)))
1743                (cond
1744                 ((not --data))
1745                 ;; Ignored element in an export context.
1746                 ((and info (memq --data (plist-get info :ignore-list))))
1747                 ;; List of elements or objects.
1748                 ((not --type) (mapc --walk-tree --data))
1749                 ;; Unconditionally enter parse trees.
1750                 ((eq --type 'org-data)
1751                  (mapc --walk-tree (org-element-contents --data)))
1752                 (t
1753                  ;; Check if TYPE is matching among TYPES.  If so,
1754                  ;; apply FUN to --DATA and accumulate return value
1755                  ;; into --ACC (or exit if FIRST-MATCH is non-nil).
1756                  (when (memq --type types)
1757                    (let ((result (funcall fun --data)))
1758                      (cond ((not result))
1759                            (first-match (throw '--map-first-match result))
1760                            (t (push result --acc)))))
1761                  ;; If --DATA has a secondary string that can contain
1762                  ;; objects with their type among TYPES, look into it.
1763                  (when (and (eq --category 'objects) (not (stringp --data)))
1764                    (let ((sec-prop
1765                           (assq --type org-element-secondary-value-alist)))
1766                      (when sec-prop
1767                        (funcall --walk-tree
1768                                 (org-element-property (cdr sec-prop) --data)))))
1769                  ;; If --DATA has any affiliated keywords and
1770                  ;; WITH-AFFILIATED is non-nil, look for objects in
1771                  ;; them.
1772                  (when (and with-affiliated
1773                             (eq --category 'objects)
1774                             (memq --type org-element-all-elements))
1775                    (mapc (lambda (kwd-pair)
1776                            (let ((kwd (car kwd-pair))
1777                                  (value (org-element-property
1778                                          (cdr kwd-pair) --data)))
1779                              ;; Pay attention to the type of value.
1780                              ;; Preserve order for multiple keywords.
1781                              (cond
1782                               ((not value))
1783                               ((and (member kwd org-element-multiple-keywords)
1784                                     (member kwd org-element-dual-keywords))
1785                                (mapc (lambda (line)
1786                                        (funcall --walk-tree (cdr line))
1787                                        (funcall --walk-tree (car line)))
1788                                      (reverse value)))
1789                               ((member kwd org-element-multiple-keywords)
1790                                (mapc (lambda (line) (funcall --walk-tree line))
1791                                      (reverse value)))
1792                               ((member kwd org-element-dual-keywords)
1793                                (funcall --walk-tree (cdr value))
1794                                (funcall --walk-tree (car value)))
1795                               (t (funcall --walk-tree value)))))
1796                          --affiliated-alist))
1797                  ;; Determine if a recursion into --DATA is possible.
1798                  (cond
1799                   ;; --TYPE is explicitly removed from recursion.
1800                   ((memq --type no-recursion))
1801                   ;; --DATA has no contents.
1802                   ((not (org-element-contents --data)))
1803                   ;; Looking for greater elements but --DATA is simply
1804                   ;; an element or an object.
1805                   ((and (eq --category 'greater-elements)
1806                         (not (memq --type org-element-greater-elements))))
1807                   ;; Looking for elements but --DATA is an object.
1808                   ((and (eq --category 'elements)
1809                         (memq --type org-element-all-objects)))
1810                   ;; In any other case, map contents.
1811                   (t (mapc --walk-tree (org-element-contents --data)))))))))))
1812     (catch '--map-first-match
1813       (funcall --walk-tree data)
1814       ;; Return value in a proper order.
1815       (nreverse --acc))))
1816 (put 'org-element-map 'lisp-indent-function 2)
1817 #+end_src
1818
1819 The following functions are internal parts of the parser.
1820
1821 The first one, `org-element--parse-elements' acts at the element's
1822 level.
1823
1824 The second one, `org-element--parse-objects' applies on all objects
1825 of a paragraph or a secondary string.  It uses
1826 `org-element--get-next-object-candidates' to optimize the search of
1827 the next object in the buffer.
1828
1829 More precisely, that function looks for every allowed object type
1830 first.  Then, it discards failed searches, keeps further matches,
1831 and searches again types matched behind point, for subsequent
1832 calls.  Thus, searching for a given type fails only once, and every
1833 object is searched only once at top level (but sometimes more for
1834 nested types).
1835
1836 #+begin_src emacs-lisp
1837 (defun org-element--parse-elements
1838   (beg end special structure granularity visible-only acc)
1839   "Parse elements between BEG and END positions.
1840
1841 SPECIAL prioritize some elements over the others.  It can be set
1842 to `first-section', `quote-section', `section' `item' or
1843 `table-row'.
1844
1845 When value is `item', STRUCTURE will be used as the current list
1846 structure.
1847
1848 GRANULARITY determines the depth of the recursion.  See
1849 `org-element-parse-buffer' for more information.
1850
1851 When VISIBLE-ONLY is non-nil, don't parse contents of hidden
1852 elements.
1853
1854 Elements are accumulated into ACC.")
1855
1856 (defun org-element--parse-objects (beg end acc restriction)
1857   "Parse objects between BEG and END and return recursive structure.
1858
1859 Objects are accumulated in ACC.
1860
1861 RESTRICTION is a list of object successors which are allowed in
1862 the current object.")
1863
1864 (defun org-element--get-next-object-candidates (limit restriction objects)
1865   "Return an alist of candidates for the next object.
1866
1867 LIMIT bounds the search, and RESTRICTION narrows candidates to
1868 some object successors.
1869
1870 OBJECTS is the previous candidates alist.  If it is set to
1871 `initial', no search has been done before, and all symbols in
1872 RESTRICTION should be looked after.
1873
1874 Return value is an alist whose CAR is the object type and CDR its
1875 beginning position.")
1876
1877
1878 #+end_src
1879
1880 * Towards A Bijective Process
1881
1882 The parse tree obtained with `org-element-parse-buffer' is really
1883 a snapshot of the corresponding Org buffer.  Therefore, it can be
1884 interpreted and expanded into a string with canonical Org syntax.
1885 Hence `org-element-interpret-data'.
1886
1887 The function relies internally on
1888 `org-element--interpret-affiliated-keywords'.
1889
1890 ###autoload
1891 #+begin_src emacs-lisp
1892 (defun org-element-interpret-data (data &optional parent)
1893   "Interpret DATA as Org syntax.
1894
1895 DATA is a parse tree, an element, an object or a secondary string
1896 to interpret.
1897
1898 Optional argument PARENT is used for recursive calls.  It contains
1899 the element or object containing data, or nil.
1900
1901 Return Org syntax as a string.")
1902
1903 (defun org-element--interpret-affiliated-keywords (element)
1904   "Return ELEMENT's affiliated keywords as Org syntax.
1905 If there is no affiliated keyword, return the empty string.")
1906 #+end_src
1907
1908 Because interpretation of the parse tree must return the same
1909 number of blank lines between elements and the same number of white
1910 space after objects, some special care must be given to white
1911 spaces.
1912
1913 The first function, `org-element-normalize-string', ensures any
1914 string different from the empty string will end with a single
1915 newline character.
1916
1917 The second function, `org-element-normalize-contents', removes
1918 global indentation from the contents of the current element.
1919
1920 #+begin_src emacs-lisp
1921 (defun org-element-normalize-string (s)
1922   "Ensure string S ends with a single newline character.
1923
1924 If S isn't a string return it unchanged.  If S is the empty
1925 string, return it.  Otherwise, return a new string with a single
1926 newline character at its end.")
1927
1928 (defun org-element-normalize-contents (element &optional ignore-first)
1929   "Normalize plain text in ELEMENT's contents.
1930
1931 ELEMENT must only contain plain text and objects.
1932
1933 If optional argument IGNORE-FIRST is non-nil, ignore first line's
1934 indentation to compute maximal common indentation.
1935
1936 Return the normalized element that is element with global
1937 indentation removed from its contents.  The function assumes that
1938 indentation is not done with TAB characters.")
1939
1940
1941 #+end_src
1942
1943 * The Toolbox
1944
1945 The first move is to implement a way to obtain the smallest element
1946 containing point.  This is the job of `org-element-at-point'.  It
1947 basically jumps back to the beginning of section containing point
1948 and moves, element after element, with
1949 `org-element--current-element' until the container is found.  Note:
1950 When using `org-element-at-point', secondary values are never
1951 parsed since the function focuses on elements, not on objects.
1952
1953 At a deeper level, `org-element-context' lists all elements and
1954 objects containing point.
1955
1956 `org-element-nested-p' and `org-element-swap-A-B' may be used
1957 internally by navigation and manipulation tools.
1958
1959 ###autoload
1960 #+begin_src emacs-lisp
1961 (defun org-element-at-point (&optional keep-trail)
1962   "Determine closest element around point.
1963
1964 Return value is a list like (TYPE PROPS) where TYPE is the type
1965 of the element and PROPS a plist of properties associated to the
1966 element.
1967
1968 Possible types are defined in `org-element-all-elements'.
1969 Properties depend on element or object type, but always include
1970 `:begin', `:end', `:parent' and `:post-blank' properties.
1971
1972 As a special case, if point is at the very beginning of a list or
1973 sub-list, returned element will be that list instead of the first
1974 item.  In the same way, if point is at the beginning of the first
1975 row of a table, returned element will be the table instead of the
1976 first row.
1977
1978 If optional argument KEEP-TRAIL is non-nil, the function returns
1979 a list of elements leading to element at point.  The list's CAR
1980 is always the element at point.  The following positions contain
1981 element's siblings, then parents, siblings of parents, until the
1982 first element of current section.")
1983 #+end_src
1984
1985 ###autoload
1986 #+begin_src emacs-lisp
1987 (defun org-element-context (&optional element)
1988   "Return closest element or object around point.
1989
1990 Return value is a list like (TYPE PROPS) where TYPE is the type
1991 of the element or object and PROPS a plist of properties
1992 associated to it.
1993
1994 Possible types are defined in `org-element-all-elements' and
1995 `org-element-all-objects'.  Properties depend on element or
1996 object type, but always include `:begin', `:end', `:parent' and
1997 `:post-blank'.
1998
1999 Optional argument ELEMENT, when non-nil, is the closest element
2000 containing point, as returned by `org-element-at-point'.
2001 Providing it allows for quicker computation.")
2002
2003 (defun org-element-nested-p (elem-A elem-B)
2004   "Non-nil when elements ELEM-A and ELEM-B are nested.")
2005
2006 (defun org-element-swap-A-B (elem-A elem-B)
2007   "Swap elements ELEM-A and ELEM-B.
2008 Assume ELEM-B is after ELEM-A in the buffer.  Leave point at the
2009 end of ELEM-A.")
2010
2011 (provide 'org-element)
2012 #+end_src
2013
2014 Local variables:
2015 generated-autoload-file: "org-loaddefs.el"
2016 End:
2017
2018 * org-element.el ends here