* lisp/org-element-ast.el (org-element-ast-map):
* lisp/org-element.el (org-element-map): Treat TYPES t as all possible
types. Add new optional parameter to no resolve deferred while
traversing the AST.
* lisp/org-element-ast.el (org-element-create): Add special case when
CHILDREN contains a single list of Org notes:
(let ((children (list a b c ...)))
(org-element-create 'type nil children))
This will simplify creating new elements when children are stored in a
list.
* lisp/org-element-ast.el (org-element-ast-map): New function
equivalent to `org-element-map', but more low-level. Unlike
`org-element-map', `org-element-ast' does not consider the details of
Org syntax - just syntax tree structure.
* lisp/org-element-ast.el (org-element--properties-mapc): New internal
helper.
(org-element-properties-resolve): New function used to resolve
deferred property values by side effect.
(org-element-properties-mapc):
(org-element-properties-map): New function to map over properties and
their values.
(org-element-resolve-deferred): New alias to resolve all the deferred
values in syntax nodes.
Major changes:
1. Property values can now deferred and computed next time when the
value is requested.
2. Some properties are stored in an array instead of plist. The
functions are inlined to turn the propery queries into direct
`aref' and `aset' calls to the plist, when applicable.
3. Secondary strings are now considered of `anonymous' type, in
backwards-compatible way.
4. New functions to map over and/or resolve deferred values of element
properties.
5. Docstrings and code consistently use "node" for generic syntax tree
elements, to not confuse the element/object terminology we use in
the parser.
* lisp/org-element-ast.el (org-element-deferred): New type user to
store deferred values.
(org-element--deferred-resolve-once):
(org-element--deferred-resolve):
(org-element--deferred-resolve-force):
(org-element--deferred-resolve-list): Helper functions used to resolve
the deferred values.
(org-element--standard-properties):
(org-element--standard-properties-idxs):
(org-element--property-idx):
(org-element--parray):
(org-element--plist-property): Store most commonly used properties in
vector for faster access. Implement inliner helpers to transform
property keywords into array indices.
(org-element-property-1): New function to retrieve property without
resolving deferred value.
(org-element--put-parray):
(org-element-put-property): Refactor, using the new property vector
when applicable.
(org-element--property): New helper function.
(org-element-property): Refactor, using the new property vector and
deferred value resolution. Add new optional arguments DFLT and
FORCE-UNDEFER. Define setters.
(org-element-set-contents): Handle anonymous nodes.
(org-element-set):
(org-element-adopt):
(org-element-extract): Rename from `org-element-set-elements',
`org-element-adopt-elements', and `org-element-extract-elements' and
keep backward-compatible alias. This is to reduce the confusion about
"node" vs. "element" vs. "object".
(org-element-create): Initialize property array correctly.
(org-element-copy): Allow copying secondary strings. Add new optional
argument KEEP-CONTENTS.
(org-element-lineage): Clarify the limitation when cache is disabled.
(org-element-type): New optional argument to identify anonymous nodes
instead of returning nil for both anonymous nodes and everything not
matching other element types.
Clarify some of the undocumented concept assumptions about Org syntax
tree that are used in Org code base. In particular, clarify that
syntax nodes are not necessarily limited by the specific Org syntax -
exporters can define new "pseudo" elements and objects.
Introduce a new concept of deferred values.
Add a new convention to keep secondary property names in a special
:secondary property.
Introduce `anonymous' element type, which was previously
indistinguishable from values that are not Org syntax elements.
Ihor Radchenko