summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNicolas Goaziou <n.goaziou@gmail.com>2013-01-20 09:50:32 +0100
committerNicolas Goaziou <n.goaziou@gmail.com>2013-01-20 09:50:32 +0100
commit3e699dc0327516db5447fbc49101642350e4873a (patch)
tree014fe002e3395fb57019c86d39395e2cd701de88
parent60083a5edb94ec640b1da2a313e1e76403cc6fca (diff)
parent84d2251e57d0922d89640380bac8163bac8e6235 (diff)
downloadorg-mode-3e699dc0327516db5447fbc49101642350e4873a.tar.gz
Merge branch 'maint'
Conflicts: lisp/org-element.el
-rw-r--r--lisp/org-element.el75
1 files changed, 64 insertions, 11 deletions
diff --git a/lisp/org-element.el b/lisp/org-element.el
index 7b8ea28..ad4580f 100644
--- a/lisp/org-element.el
+++ b/lisp/org-element.el
@@ -3916,7 +3916,32 @@ recursion. It can be set to the following symbols:
When VISIBLE-ONLY is non-nil, don't parse contents of hidden
elements.
-Assume buffer is in Org mode."
+An element or an objects is represented as a list with the
+pattern (TYPE PROPERTIES CONTENTS), where :
+
+ TYPE is a symbol describing the element or object. See
+ `org-element-all-elements' and `org-element-all-objects' for an
+ exhaustive list of such symbols. One can retrieve it with
+ `org-element-type' function.
+
+ PROPERTIES is the list of attributes attached to the element or
+ object, as a plist. Although most of them are specific to the
+ element or object type, all types share `:begin', `:end',
+ `:post-blank' and `:parent' properties, which respectively
+ refer to buffer position where the element or object starts,
+ ends, the number of white spaces or blank lines after it, and
+ the element or object containing it. Properties values can be
+ obtained by using `org-element-property' function.
+
+ CONTENTS is a list of elements, objects or raw strings
+ contained in the current element or object, when applicable.
+ One can access them with `org-element-contents' function.
+
+The Org buffer has `org-data' as type and nil as properties.
+`org-element-map' function can be used to find specific elements
+or objects within the parse tree.
+
+This function assumes that current major mode is `org-mode'."
(save-excursion
(goto-char (point-min))
(org-skip-whitespace)
@@ -3956,11 +3981,12 @@ containing the secondary string. It is used to set correctly
(data types fun &optional info first-match no-recursion with-affiliated)
"Map a function on selected elements or objects.
-DATA is the parsed tree, as returned by, i.e,
+DATA is an Org buffer parse tree, as returned by, i.e,
`org-element-parse-buffer'. TYPES is a symbol or list of symbols
-of elements or objects types. FUN is the function called on the
-matching element or object. It must accept one argument: the
-element or object itself.
+of elements or objects types (see `org-element-all-elements' and
+`org-element-all-objects' for a complete list of types). FUN is
+the function called on the matching element or object. It has to
+accept one argument: the element or object itself.
When optional argument INFO is non-nil, it should be a plist
holding export options. In that case, parts of the parse tree
@@ -3974,10 +4000,37 @@ representing elements or objects types. `org-element-map' won't
enter any recursive element or object whose type belongs to that
list. Though, FUN can still be applied on them.
-When optional argument WITH-AFFILIATED is non-nil, also move into
-affiliated keywords to find objects.
+Nil values returned from FUN do not appear in the results.
-Nil values returned from FUN do not appear in the results."
+
+Examples:
+--------
+
+Assuming TREE is a variable containing an Org buffer parse tree,
+the following example will return a flat list of all `src-block'
+and `example-block' elements in it:
+
+ \(org-element-map tree '(example-block src-block) 'identity)
+
+The following snippet will find the first headline with a level
+of 1 and a \"phone\" tag, and will return its beginning position:
+
+ \(org-element-map
+ tree 'headline
+ \(lambda (hl)
+ \(and (= (org-element-property :level hl) 1)
+ \(member \"phone\" (org-element-property :tags hl))
+ \(org-element-property :begin hl)))
+ nil t)
+
+Eventually, this last example will return a flat list of all
+`bold' type objects containing a `latex-snippet' type object:
+
+ \(org-element-map
+ tree 'bold
+ \(lambda (b)
+ \(and (org-element-map b 'latex-snippet 'identity nil t)
+ b)))"
;; Ensure TYPES and NO-RECURSION are a list, even of one element.
(unless (listp types) (setq types (list types)))
(unless (listp no-recursion) (setq no-recursion (list no-recursion)))
@@ -4522,8 +4575,8 @@ of the element and PROPS a plist of properties associated to the
element.
Possible types are defined in `org-element-all-elements'.
-Properties depend on element or object type, but always
-include :begin, :end, :parent and :post-blank properties.
+Properties depend on element or object type, but always include
+`:begin', `:end', `:parent' and `:post-blank' properties.
As a special case, if point is at the very beginning of a list or
sub-list, returned element will be that list instead of the first
@@ -4637,7 +4690,7 @@ of the buffer.
Possible types are defined in `org-element-all-elements' and
`org-element-all-objects'. Properties depend on element or
object type, but always include `:begin', `:end', `:parent' and
-`:post-blank' properties.
+`:post-blank'.
Optional argument ELEMENT, when non-nil, is the closest element
containing point, as returned by `org-element-at-point'.