diff options
author | Nicolas Goaziou <n.goaziou@gmail.com> | 2013-01-20 09:50:32 +0100 |
---|---|---|
committer | Nicolas Goaziou <n.goaziou@gmail.com> | 2013-01-20 09:50:32 +0100 |
commit | 3e699dc0327516db5447fbc49101642350e4873a (patch) | |
tree | 014fe002e3395fb57019c86d39395e2cd701de88 | |
parent | 60083a5edb94ec640b1da2a313e1e76403cc6fca (diff) | |
parent | 84d2251e57d0922d89640380bac8163bac8e6235 (diff) | |
download | org-mode-3e699dc0327516db5447fbc49101642350e4873a.tar.gz |
Merge branch 'maint'
Conflicts:
lisp/org-element.el
-rw-r--r-- | lisp/org-element.el | 75 |
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'. |