exporters/org-element-docstrings.org

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