dev/org-element-api.org

   1 #+TITLE:      Org Element API
   2 #+AUTHOR:     Nicolas Goaziou
   3 #+EMAIL:      mail@nicolasgoaziou.fr
   4 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   5 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   6 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) NEW(n)
   7 #+LANGUAGE:   en
   8 #+PRIORITIES: A C B
   9 #+CATEGORY:   worg
  10 #+HTML_LINK_UP:    index.html
  11 #+HTML_LINK_HOME:  https://orgmode.org/worg/
  12
  13 # This file is released by its authors and contributors under the GNU
  14 # Free Documentation license v1.3 or later, code examples are released
  15 # under the GNU General Public License v3 or later.
  16
  17 =org-element.el= implements a parser according to Org's [[./org-syntax.org][syntax
  18 specification]].
  19
  20 The library contains tools to generate an abstract syntax tree (AST)
  21 from an Org buffer, to analyze the syntactical object at point.
  22 [[#parsing][Parsing functions]] are detailed in the first part of the document,
  23 along with their relative accessors and setters.
  24
  25 Upon parsing, each token in an Org document gets a type and some
  26 properties attached to it.  This information can be extracted and
  27 modified with provided [[#accessors][accessors]] and [[#setters][setters]].  An exhaustive list of
  28 all types and attributes is given in section [[#attributes]].
  29
  30 Eventually, the library is packed with a few useful functions,
  31 described in the [[#other-tools][last section]] of the document.
  32
  33 * Parsing functions
  34 :PROPERTIES:
  35 :CUSTOM_ID: parsing
  36 :END:
  37
  38 There are two ways to parse a buffer using this library: either
  39 locally or globally.
  40
  41 [[#local][Local parsing]] gives information about the structure at point.
  42 Depending on the level of detail required, ~org-element-at-point~ and
  43 ~org-element-context~ fullfill that role.
  44
  45 [[#global][Global parsing]] is done with ~org-element-parse-buffer~, which returns
  46 the AST representing the document.
  47
  48 ** Analyzing the structure at point
  49 :PROPERTIES:
  50 :CUSTOM_ID: local
  51 :END:
  52
  53 ~org-element-at-point~ offers a glimpse into the local structure of
  54 the document.  However, it stops at the element level.  It doesn't,
  55 for example, analyze the contents of a paragraph.  While this is
  56 sufficient for many use cases, ~org-element-context~ allows to go
  57 deeper, down to the object level.  The following example illustrates
  58 the difference between the two functions.
  59
  60 #+name: context-vs-at-point
  61 #+BEGIN_SRC org
  62 ,*Lorem ipsum dolor* sit amet, consectetur adipisicing elit, sed do
  63 eiusmod tempor incididunt ut labore et dolore magna aliqua.
  64 #+END_SRC
  65
  66 Indeed, calling ~org-element-at-point~ at the beginning of the
  67 paragraph returns a ~paragraph~ structure, whereas calling
  68 ~org-element-context~ returns a ~bold~ object.
  69
  70 Unless point is on a headline, both functions indirectly return all
  71 parents of the value within the current section[fn:1], through
  72 ~:parent~ property.  For example, when point is at =(X)=
  73
  74 #+name: full-hierarchy
  75 #+BEGIN_SRC org
  76 ,* Headline
  77
  78 ,#+BEGIN_CENTER
  79 Paragraph(X)
  80 ,#+END_CENTER
  81 #+END_SRC
  82
  83 ~org-element-at-point~ returns a ~paragraph~ element, whose ~:parent~
  84 property contains a ~center-block~ element, which, in turn, has no
  85 ~:parent~ since the next ancestor is the section itself.
  86
  87 ** Creating a snapshot of the document
  88 :PROPERTIES:
  89 :CUSTOM_ID: global
  90 :END:
  91
  92 ~org-element-parse-buffer~ completely parses a (possibly narrowed)
  93 buffer into an AST.  The virtual root node has type ~org-data~ and no
  94 properties attached to it.
  95
  96 Unlike to local parsing functions, data obtained through
  97 ~org-element-parse-buffer~ can be altered to your heart's content.
  98 See [[#setters]] for a list of related tools.
  99
 100 * Accessors
 101 :PROPERTIES:
 102 :CUSTOM_ID: accessors
 103 :END:
 104
 105 Type and properties of a given element or object are obtained with,
 106 respectively, ~org-element-type~ and ~org-element-property~.
 107
 108 ~org-element-contents~ returns an ordered (by buffer position) list of
 109 all elements or objects within a given element or object.  Since local
 110 parsing ignores contents, it only makes sense to use this function on
 111 a part of an AST.
 112
 113 Eventually, ~org-element-map~ operates on an AST, a part of it, or any
 114 list of elements or objects.  It is a versatile function.
 115
 116 For example, it can be used to collect data from an AST.  Hence the
 117 following snippet returns all paragraphs beginning a section in the
 118 current document.  Note that equality between elements is tested with
 119 ~eq~.
 120
 121 #+name: collect
 122 #+begin_src emacs-lisp
 123 (org-element-map (org-element-parse-buffer) 'paragraph
 124   (lambda (paragraph)
 125     (let ((parent (org-element-property :parent paragraph)))
 126       (and (eq (org-element-type parent) 'section)
 127            (let ((first-child (car (org-element-contents parent))))
 128              (eq first-child paragraph))
 129            ;; Return value.
 130            paragraph))))
 131 #+end_src
 132
 133 It can also be used as a predicate.  Thus, the following snippet
 134 returns a non-~nil~ value when the document contains a checked item.
 135
 136 #+name: checkedp
 137 #+begin_src emacs-lisp
 138 (org-element-map (org-element-parse-buffer) 'item
 139   (lambda (item) (eq (org-element-property :checkbox item) 'on))
 140   nil t)
 141 #+end_src
 142
 143 See ~org-element-map~'s docstring for more examples.
 144
 145 * Setters
 146 :PROPERTIES:
 147 :CUSTOM_ID: setters
 148 :END:
 149
 150 ~org-element-put-property~ modifies any property of a given element or
 151 object.
 152
 153 Note that, even though structures obtained with local parsers are
 154 mutable, it is good practice to consider them immutable.  In
 155 particular, destructively changing properties relative to buffer
 156 positions is likely to break the caching mechanism running in the
 157 background.  If, for example, you need to slightly alter an element
 158 obtained using these functions, first copy it, using
 159 ~org-element-copy~, before modifying it by side effect.  There is no
 160 such restriction for elements grabbed from a complete AST.
 161
 162 The library also provides tools to manipulate the parse tree.  Thus,
 163 ~org-element-extract-element~ removes an element or object from an
 164 AST, ~org-element-set-element~ replaces one with another, whereas
 165 ~org-element-insert-before~ and ~org-element-adopt-element~ insert
 166 elements within the tree, respectively before a precise location or
 167 after all children.
 168
 169 * Types and Attributes
 170 :PROPERTIES:
 171 :CUSTOM_ID: attributes
 172 :END:
 173
 174 Each greater element, element and object has a variable set of
 175 properties attached to it.  Among them, four are shared by all types:
 176 ~:begin~ and ~:end~, which refer to the beginning and ending buffer
 177 positions of the considered element or object, ~:post-blank~, which
 178 holds the number of blank lines, or white spaces, at its end[fn:2] and
 179 ~:parent~, which refers to the element or object containing it.
 180
 181 Greater elements containing objects on the one hand, and elements or
 182 objects containing objects on the other hand also have
 183 ~:contents-begin~ and ~:contents-end~ properties to delimit contents.
 184
 185 In addition to these properties, each element can optionally get some
 186 more from affiliated keywords, namely: ~:caption~, ~:header~, ~:name~,
 187 ~:plot~, ~:results~ or ~:attr_NAME~ where =NAME= stands for the name
 188 of an export back-end.
 189
 190 Also, ~:post-affiliated~ property is attached to all elements.  It
 191 refers to the buffer position after any affiliated keyword, when
 192 applicable, or to the beginning of the element otherwise.
 193
 194 The following example illustrates the relationship between position
 195 properties.
 196
 197 #+name: position-properties
 198 #+BEGIN_SRC org -n -r
 199 ,#+NAME: dont-do-this-at-home (ref:begin)
 200 ,#+BEGIN_SRC emacs-lisp       (ref:post)
 201 (/ 1 0)
 202 ,#+END_SRC
 203
 204 Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do (ref:end)
 205 eiusmod tempor incididunt ut labore et dolore magna aliqua.
 206 #+END_SRC
 207
 208 The first element's type is ~src-block~.  Its ~:begin~ property
 209 (respectively ~:end~ property) is the buffer position at the beginning
 210 of line [[(begin)]] (respectively line [[(end)]]).  ~:post-affiliated~ is the
 211 buffer position at the beginning of line [[(post)]].  Since source blocks
 212 cannot contain other elements or objects, both ~:contents-begin~ and
 213 ~:contents-end~ are ~nil~. ~:post-blank~ is 1.
 214
 215 Other properties, specific to each element or object type, are listed
 216 below.
 217
 218 ** Babel Call
 219
 220 Element.
 221
 222 - ~:call~ :: Name of code block being called (string).
 223 - ~:inside-header~ :: Header arguments applied to the named code block
 224   (string or ~nil~).
 225 - ~:arguments~ :: Arguments passed to the code block (string or ~nil~).
 226 - ~:end-header~ :: Header arguments applied to the calling instance
 227   (string or ~nil~).
 228 - ~:value~ :: Raw call, as Org syntax (string).
 229
 230 ** Bold
 231
 232 Recursive object.
 233
 234 No specific property.
 235
 236 ** Center Block
 237
 238 Greater element.
 239
 240 No specific property.
 241
 242 ** Clock
 243
 244 Element.
 245
 246 - ~:duration~ :: Clock duration for a closed clock, or ~nil~ (string or
 247   ~nil~).
 248 - ~:status~ :: Status of current clock (symbol: ~closed~ or
 249   ~running~).
 250 - ~:value~ :: Timestamp associated to clock keyword (timestamp
 251   object).
 252
 253 ** Code
 254
 255 Object.
 256
 257 - ~:value~ :: Contents (string).
 258
 259 ** Comment
 260
 261 Element.
 262
 263 - ~:value~ :: Comments, with pound signs (string).
 264
 265 ** Comment Block
 266
 267 Element.
 268
 269 - ~:value~ :: Comments, without block's boundaries (string).
 270
 271 ** Diary Sexp
 272
 273 Element.
 274
 275 - ~:value~ :: Full Sexp (string).
 276
 277 ** Drawer
 278
 279 Greater element.
 280
 281 - ~:drawer-name~ :: Drawer's name (string).
 282
 283 ** Dynamic Block
 284
 285 Greater element.
 286
 287 - ~:arguments~ :: Block's parameters (string).
 288 - ~:block-name~ :: Block's name (string).
 289 - ~:drawer-name~ :: Drawer's name (string).
 290
 291 ** Entity
 292
 293 Object.
 294
 295 - ~:ascii~ :: Entity's ASCII representation (string).
 296 - ~:html~ :: Entity's HTML representation (string).
 297 - ~:latex~ :: Entity's LaTeX representation (string).
 298 - ~:latex-math-p~ :: Non-~nil~ if entity's LaTeX representation should
 299   be in math mode (boolean).
 300 - ~:latin1~ :: Entity's Latin-1 encoding representation (string).
 301 - ~:name~ :: Entity's name, without backslash nor brackets (string).
 302 - ~:use-brackets-p~ :: Non-~nil~ if entity is written with optional
 303   brackets in original buffer (boolean).
 304 - ~:utf-8~ :: Entity's UTF-8 encoding representation (string).
 305
 306 ** Example Block
 307
 308 Element.
 309
 310 - ~:label-fmt~ :: Format string used to write labels in current block,
 311   if different from ~org-coderef-label-format~ (string or ~nil~).
 312 - ~:language~ :: Language of the code in the block, if specified
 313   (string or ~nil~).
 314 - ~:number-lines~ :: Non-~nil~ if code lines should be numbered.
 315   A ~new~ value starts numbering from 1 wheareas ~continued~ resume
 316   numbering from previous numbered block (symbol: ~new~, ~continued~
 317   or ~nil~).
 318 - ~:options~ :: Block's options located on the block's opening line
 319   (string).
 320 - ~:parameters~ :: Optional header arguments (string or ~nil~).
 321 - ~:preserve-indent~ :: Non-~nil~ when indentation within the block
 322   mustn't be modified upon export (boolean).
 323 - ~:retain-labels~ :: Non-~nil~ if labels should be kept visible upon
 324   export (boolean).
 325 - ~:switches~ :: Optional switches for code block export (string or
 326   ~nil~).
 327 - ~:use-labels~ :: Non-~nil~ if links to labels contained in the block
 328   should display the label instead of the line number (boolean).
 329 - ~:value~ :: Contents (string).
 330
 331 ** Export Block
 332
 333 Element.
 334
 335 - ~:type~ :: Related back-end's name (string).
 336 - ~:value~ :: Contents (string).
 337
 338 ** Export Snippet
 339
 340 Object.
 341
 342 - ~:back-end~ :: Relative back-end's name (string).
 343 - ~:value~ :: Export code (string).
 344
 345 ** Fixed Width
 346
 347 Element.
 348
 349 - ~:value~ :: Contents, without colons prefix (string).
 350
 351 ** Footnote Definition
 352
 353 Greater element.
 354
 355 - ~:label~ :: Label used for references (string).
 356 - ~:pre-blank~ :: Number of newline characters between the beginning
 357   of the footnoote and the beginning of the contents (0, 1 or 2).
 358
 359 ** Footnote Reference
 360
 361 Recursive object.
 362
 363 - ~:label~ :: Footnote's label, if any (string or ~nil~).
 364 - ~:type~ :: Determine whether reference has its definition inline, or
 365   not (symbol: ~inline~, ~standard~).
 366
 367 ** Headline
 368
 369 Greater element.
 370
 371 In addition to the following list, any property specified in
 372 a property drawer attached to the headline will be accessible as an
 373 attribute (with an uppercase name, e.g., ~:CUSTOM_ID~).
 374
 375 - ~:archivedp~ :: Non-~nil~ if the headline has an archive tag
 376   (boolean).
 377 - ~:closed~ :: Headline's =CLOSED= reference, if any (timestamp object
 378   or ~nil~)
 379 - ~:commentedp~ :: Non-~nil~ if the headline has a comment keyword
 380   (boolean).
 381 - ~:deadline~ :: Headline's =DEADLINE= reference, if any (timestamp
 382   object or ~nil~).
 383 - ~:footnote-section-p~ :: Non-~nil~ if the headline is a footnote
 384   section (boolean).
 385 - ~:level~ :: Reduced level of the headline (integer).
 386 - ~:pre-blank~ :: Number of blank lines between the headline and the
 387   first non-blank line of its contents (integer).
 388 - ~:priority~ :: Headline's priority, as a character (integer).
 389 - ~:quotedp~ :: Non-~nil~ if the headline contains a quote keyword
 390   (boolean).
 391 - ~:raw-value~ :: Raw headline's text, without the stars and the
 392   tags (string).
 393 - ~:scheduled~ :: Headline's =SCHEDULED= reference, if any (timestamp
 394   object or ~nil~).
 395 - ~:tags~ :: Headline's tags, if any, without the archive tag. (list
 396   of strings).
 397 - ~:title~ :: Parsed headline's text, without the stars and the
 398   tags (secondary string).
 399 - ~:todo-keyword~ :: Headline's TODO keyword without quote and comment
 400   strings, if any (string or ~nil~).
 401 - ~:todo-type~ :: Type of headline's TODO keyword, if any (symbol:
 402   ~done~, ~todo~).
 403
 404 ** Horizontal Rule
 405
 406 Element.
 407
 408 No specific property.
 409
 410 ** Inline Babel Call
 411
 412 Object.
 413
 414 - ~:call~ :: Name of code block being called (string).
 415 - ~:inside-header~ :: Header arguments applied to the named code
 416   block (string or ~nil~).
 417 - ~:arguments~ :: Arguments passed to the code block (string or
 418   ~nil~).
 419 - ~:end-header~ :: Header arguments applied to the calling instance
 420   (string or ~nil~).
 421 - ~:value~ :: Raw call, as Org syntax (string).
 422
 423 ** Inline Src Block
 424
 425 Object.
 426
 427 - ~:language~ :: Language of the code in the block (string).
 428 - ~:parameters~ :: Optional header arguments (string or ~nil~).
 429 - ~:value~ :: Source code (string).
 430
 431 ** Inlinetask
 432
 433 Greater element.
 434
 435 In addition to the following list, any property specified in
 436 a property drawer attached to the headline will be accessible as an
 437 attribute (with an uppercase name, e.g. ~:CUSTOM_ID~).
 438
 439 - ~:closed~ :: Inlinetask's =CLOSED= reference, if any (timestamp
 440   object or ~nil~)
 441 - ~:deadline~ :: Inlinetask's =DEADLINE= reference, if any (timestamp
 442   object or ~nil~).
 443 - ~:level~ :: Reduced level of the inlinetask (integer).
 444 - ~:priority~ :: Headline's priority, as a character (integer).
 445 - ~:raw-value~ :: Raw inlinetask's text, without the stars and the
 446   tags (string).
 447 - ~:scheduled~ :: Inlinetask's =SCHEDULED= reference, if any
 448   (timestamp object or ~nil~).
 449 - ~:tags~ :: Inlinetask's tags, if any (list of strings).
 450 - ~:title~ :: Parsed inlinetask's text, without the stars and the
 451   tags (secondary string).
 452 - ~:todo-keyword~ :: Inlinetask's =TODO= keyword, if any (string or
 453   ~nil~).
 454 - ~:todo-type~ :: Type of inlinetask's =TODO= keyword, if any (symbol:
 455   ~done~, ~todo~).
 456
 457 ** Italic
 458
 459 Recursive object.
 460
 461 No specific property.
 462
 463 ** Item
 464
 465 Greater element.
 466
 467 - ~:bullet~ :: Item's bullet (string).
 468 - ~:checkbox~ :: Item's check-box, if any (symbol: ~on~, ~off~,
 469   ~trans~, ~nil~).
 470 - ~:counter~ :: Item's counter, if any.  Literal counters become
 471   ordinals (integer).
 472 - ~:pre-blank~ :: Number of newline characters between the beginning
 473   of the item and the beginning of the contents (0, 1 or 2).
 474 - ~:raw-tag~ :: Uninterpreted item's tag, if any (string or ~nil~).
 475 - ~:tag~ :: Parsed item's tag, if any (secondary string or ~nil~).
 476 - ~:structure~ :: Full list's structure, as returned by
 477   ~org-list-struct~ (alist).
 478
 479 ** Keyword
 480
 481 Element.
 482
 483 - ~:key~ :: Keyword's name (string).
 484 - ~:value~ :: Keyword's value (string).
 485
 486 ** LaTeX Environment
 487
 488 Element.
 489
 490 - ~:begin~ :: Buffer position at first affiliated keyword or at the
 491   beginning of the first line of environment (integer).
 492 - ~:end~ :: Buffer position at the first non-blank line after last
 493   line of the environment, or buffer's end (integer).
 494 - ~:post-blank~ :: Number of blank lines between last environment's
 495   line and next non-blank line or buffer's end
 496   (integer).
 497 - ~:value~ :: LaTeX code (string).
 498
 499 ** LaTeX Fragment
 500
 501 Object.
 502
 503 - ~:value~ :: LaTeX code (string).
 504
 505 ** Line Break
 506
 507 Object.
 508
 509 No specific property.
 510
 511 ** Link
 512
 513 Recursive object.
 514
 515 - ~:application~ :: Name of application requested to open the link in
 516   Emacs (string or ~nil~). It only applies to "file" type links.
 517 - ~:format~ :: Format for link syntax (symbol: ~plain~, ~angle~,
 518   ~bracket~).
 519 - ~:path~ :: Identifier for link's destination.  It is usually the
 520   link part with type, if specified, removed (string).
 521 - ~:raw-link~ :: Uninterpreted link part (string).
 522 - ~:search-option~ :: Additional information for file location
 523   (string or ~nil~). It only applies to "file" type links.
 524 - ~:type~ :: Link's type.  Possible types (string) are:
 525
 526   - ~coderef~ :: Line in some source code,
 527   - ~custom-id~ :: Specific headline's custom-id,
 528   - ~file~ :: External file,
 529   - ~fuzzy~ :: Target, referring to a target object, a named
 530     element or a headline in the current parse tree,
 531   - ~id~ :: Specific headline's id,
 532   - ~radio~ :: Radio-target.
 533
 534   It can also be any type defined in ~org-link-types~.
 535
 536 ** Macro
 537
 538 Object.
 539
 540 - ~:args~ :: Arguments passed to the macro (list of strings).
 541 - ~:key~ :: Macro's name (string).
 542 - ~:value~ :: Replacement text (string).
 543
 544 ** Node Property
 545
 546 Element.
 547
 548 - ~:key~ :: Property's name (string).
 549 - ~:value~ :: Property's value (string).
 550
 551 ** Paragraph
 552
 553 Element containing objects.
 554
 555 No specific property.
 556
 557 ** Plain List
 558
 559 Greater element.
 560
 561 - ~:structure~ :: Full list's structure, as returned by
 562   ~org-list-struct~ (alist).
 563 - ~:type~ :: List's type (symbol: ~descriptive~, ~ordered~,
 564   ~unordered~).
 565
 566 ** Planning
 567
 568 Element.
 569
 570 - ~:closed~ :: Timestamp associated to =CLOSED= keyword, if any
 571   (timestamp object or ~nil~).
 572 - ~:deadline~ :: Timestamp associated to =DEADLINE= keyword, if any
 573   (timestamp object or ~nil~).
 574 - ~:scheduled~ :: Timestamp associated to =SCHEDULED= keyword, if any
 575   (timestamp object or ~nil~).
 576
 577 ** Property Drawer
 578
 579 Greater element.
 580
 581 No specific property.
 582
 583 ** Quote Block
 584
 585 Greater element.
 586
 587 ** Radio Target
 588
 589 Recursive object.
 590
 591 - ~:raw-value~ :: Uninterpreted contents (string).
 592
 593 ** Section
 594
 595 Greater element.
 596
 597 No specific property.
 598
 599 ** Special Block
 600
 601 Greater element.
 602
 603 - ~:type~ :: Block's name (string).
 604 - ~:raw-value~ :: Raw contents in block (string).
 605
 606 ** Src Block
 607
 608 Element.
 609
 610 - ~:label-fmt~ :: Format string used to write labels in current block,
 611   if different from ~org-coderef-label-format~ (string or ~nil~).
 612 - ~:language~ :: Language of the code in the block, if specified
 613   (string or ~nil~).
 614 - ~:number-lines~ :: Non-~nil~ if code lines should be numbered.
 615   A ~new~ value starts numbering from 1 wheareas ~continued~ resume
 616   numbering from previous numbered block (symbol: ~new~, ~continued~
 617   or ~nil~).
 618 - ~:parameters~ :: Optional header arguments (string or ~nil~).
 619 - ~:preserve-indent~ :: Non-~nil~ when indentation within the block
 620   mustn't be modified upon export (boolean).
 621 - ~:retain-labels~ :: Non-~nil~ if labels should be kept visible upon
 622   export (boolean).
 623 - ~:switches~ :: Optional switches for code block export (string or
 624   ~nil~).
 625 - ~:use-labels~ :: Non-~nil~ if links to labels contained in the block
 626   should display the label instead of the line number (boolean).
 627 - ~:value~ :: Source code (string).
 628
 629 ** Statistics Cookie
 630
 631 Object.
 632
 633 - ~:value~ :: Full cookie (string).
 634
 635 ** Strike Through
 636
 637 Recursive object.
 638
 639 No specific property.
 640
 641 ** Subscript
 642
 643 Recursive object.
 644
 645 - ~:use-brackets-p~ :: Non-~nil~ if contents are enclosed in curly
 646   brackets (t, ~nil~).
 647
 648 ** Superscript
 649
 650 Recursive object.
 651
 652 - ~:use-brackets-p~ :: Non-~nil~ if contents are enclosed in curly
 653   brackets (t, ~nil~).
 654
 655 ** Table
 656
 657 Greater element.
 658
 659 - ~:tblfm~ :: Formulas associated to the table, if any (string or
 660   ~nil~).
 661 - ~:type~ :: Table's origin (symbol: ~table.el~, ~org~).
 662 - ~:value~ :: Raw ~table.el~ table or ~nil~ (string or ~nil~).
 663
 664 ** Table Cell
 665
 666 Recursive object.
 667
 668 No specific property.
 669
 670 ** Table Row
 671
 672 Element containing objects.
 673
 674 - ~:type~ :: Row's type (symbol: ~standard~, ~rule~).
 675
 676 ** Target
 677
 678 Object.
 679
 680 - ~:value~ :: Target's ID (string).
 681
 682 ** Timestamp
 683
 684 Object.
 685
 686 - ~:day-end~ :: Day part from timestamp end.  If no ending date is
 687   defined, it defaults to start day part (integer).
 688 - ~:day-start~ :: Day part from timestamp start (integer).
 689 - ~:hour-start~ :: Hour part from timestamp end. If no ending date is
 690   defined, it defaults to start hour part, if any (integer or ~nil~).
 691 - ~:hour-start~ :: Hour part from timestamp start, if specified
 692   (integer or ~nil~).
 693 - ~:minute-start~ :: Minute part from timestamp end. If no ending date
 694   is defined, it defaults to start minute part, if any (integer or
 695   ~nil~).
 696 - ~:minute-start~ :: Minute part from timestamp start, if specified
 697   (integer or ~nil~).
 698 - ~:month-end~ :: Month part from timestamp end.  If no ending date is
 699   defined, it defaults to start month part (integer).
 700 - ~:month-start~ :: Month part from timestamp start (integer).
 701 - ~:raw-value~ :: Raw timestamp (string).
 702 - ~:repeater-type~ :: Type of repeater, if any (symbol: ~catch-up~,
 703   ~restart~, ~cumulate~ or ~nil~)
 704 - ~:repeater-unit~ :: Unit of shift, if a repeater is defined
 705   (symbol: ~year~, ~month~, ~week~, ~day~, ~hour~ or ~nil~).
 706 - ~:repeater-value~ :: Value of shift, if a repeater is defined
 707   (integer or ~nil~).
 708 - ~:type~ :: Type of timestamp (symbol: ~active~, ~active-range~,
 709   ~diary~, ~inactive~, ~inactive-range~).
 710 - ~:warning-type~ :: Type of warning, if any (symbol: ~all~, ~first~
 711   or ~nil~)
 712 - ~:warning-unit~ :: Unit of delay, if one is defined (symbol: ~year~,
 713   ~month~, ~week~, ~day~, ~hour~ or ~nil~).
 714 - ~:warning-value~ :: Value of delay, if one is defined (integer or
 715   ~nil~).
 716 - ~:year-end~ :: Year part from timestamp end.  If no ending date is
 717   defined, it defaults to start year part (integer).
 718 - ~:year-start~ :: Year part from timestamp start (integer).
 719
 720 ** Underline
 721
 722 Recursive object.
 723
 724 No specific property.
 725
 726 ** Verbatim
 727
 728 Object.
 729
 730 - ~:value~ :: Contents (string).
 731
 732 ** Verse Block
 733
 734 Element containing objects.
 735
 736 No specific property.
 737
 738 * Other Tools
 739 :PROPERTIES:
 740 :CUSTOM_ID: other-tools
 741 :END:
 742
 743 ** Turning an AST into an Org document
 744
 745 ~org-element-interpret-data~ is the reciprocal operation of
 746 ~org-element-parse-buffer~.  When provided an element, object, or even
 747 a full parse tree, it generates an equivalent string in Org syntax.
 748
 749 More precisely, output is a normalized document: it preserves
 750 structure and blank spaces but it removes indentation and capitalize
 751 keywords.  As a consequence it is equivalent, but not equal, to the
 752 original document the AST comes from.
 753
 754 When called on an element or object obtained through
 755 ~org-element-at-point~ or ~org-element-context~, its contents will not
 756 appear, since this information is not available.
 757
 758 ** Examining genealogy of an element or object
 759
 760 ~org-element-lineage~ produces a list of all ancestors of a given
 761 element or object.  However, when these come from a [[#local][local parsing
 762 function]], lineage is limited to the section containing them.
 763
 764 With optional arguments, it is also possible to check for a particular
 765 type of ancestor.  See function's docstring for more information.
 766
 767 * Footnotes
 768
 769 [fn:1] Thus, ~org-element-at-point~ cannot return the parent of
 770 a headline.  Nevertheless, headlines are context free elements: it is
 771 efficient to move to parent headline (e.g., with
 772 ~org-up-heading-safe~) before analyzing it.
 773
 774 [fn:2] As a consequence whitespaces or newlines after an element or
 775 object still belong to it.  To put it differently, ~:end~ property of
 776 an element matches ~:begin~ property of the following one at the same
 777 level, if any.