Re: [O] Usage of org-element api

[Dieter Van Eessen]

Hello Rasmus,

Thank you for the fast reply, the link you've given on interpreting is very useful ! Also didn't know there existed such thing as the org-dp library to manipulate org-elements, I'll sure check it out.

More about question number 3:
>> 3) How can the output of (org-element-parse-secondary-string ...) be used.
>> When I give a heading and bit of text as input (output of
>> buffer-substring), it looks like it returns the 'content' of the region.
>> Though I can't seem to use it anyway as 'CONTENT' for the functions
>> requiring this.

The reason I've tried this (and the internal org-element--parse-elements) is because I'd prefer not having to parse the whole buffer and still get the contents. The local parsing functions (org-element-at-point) and (org-element-context) don't contain content (stated in the org-element api, also tried it ).

Now I'm not sure IF I really NEED it? I could actually get the contents using the  :content-begin and :content-end and other properties from (org-elemen-at-point)  BUT I don't know the exact syntax the content should have and how to merge it with the element-list I get from (org-element-at-point) before feeding it to the org-element-interpret-data.

I don't actually know how 'content' looks like...  When applying a small function
" (defun test ()                                                                                                                                
    (interactive)
    (debug)                                                                                                                                     
    (setq content (org-element-contents (org-element-parse-buffer))))"

on a simple headline with some text,

" * woot

     And a bit of text "

I can see in debugger (returned values) that 'content' is actually (org-data nil ('content'). See output below. Thus concluding that content is also just an <element>. Then why do all the org-element-<element>-interpreters require both the <element>  AND 'content', since to me, it seems logical that all this information is already inside <element>.

At first I thought that the things behind #  were 'content' (for example in the output below. These don't show up in (org-element-at-point), thus explaining why they returned nil when asked for content. The org-element-parse-secondary-string also returns all things behind #. If this is NOT content, then how to manipulate this data (behind the #) whilst assuring that syntax and position remains valid for org-element-interpret-data to understand?

OUTPUT:
 (org-data nil (headline (:raw-value "woot" :begin 1 :end 29 :pre-blank 0 :contents-begin 8 ...) (section (:begin 8 :end 29 :contents-begin
  8 :contents-end 26 :post-blank 2 ...) (paragraph (:begin 8 :end 26 :contents-begin 8 :contents-end 26 :post-blank 0 ...) #("And a bit of
  text  " 0 18 (:parent #3))))))
   
  ((headline (:raw-value "woot" :begin 1 :end 29 :pre-blank 0 :contents-begin 8 ...) (section (:begin 8 :end 29 :contents-begin 8
  :contents-end 26 :post-blank 2 ...) (paragraph (:begin 8 :end 26 :contents-begin 8 :contents-end 26 :post-blank 0 ...) #("And a bit of text
  " 0 18 (:parent #3))))))

Perhaps my view is completely wrong, so please correct me if possible.

Thanks for the time,

Dieter

On Fri, Jan 16, 2015 at 8:35 PM, Rasmus <address@hidden> wrote:

Hi Dieter,

Nicolas will probably reply at some point and he has much greater (∞ more)
insight in this topics.  None the less, I hope the below message will
help a bit.

Dieter Van Eessen <address@hidden> writes:

> 1) How to use org-element-content? Returns nil when used on elements parsed
> by org-element-<element>-parser (because they operate locally)  When used
> globally, it only seems to remove the car of the list (org-data ....)

Don't use org-element-<element>-parser directly.

Use org-element-at-point or org-element-contents.  The former is for
elements, the latter is for contents, such as scripts, bold, etc.  See the
head of org-element.el.

> 2) What is actually a normal workflow if you wish to interactive manipulate
> only some of the elements? Is it something like:
>  a)  Define the region in which you wish to manipulate things (using :begin
> and :extract from  org-element-at-point)

Org-element is a parser and manipulation might not be super efficient with
org-element, but it can be done.

OTOH Org-syntax is great for manipulation.  E.g. to insert a heading you
can do (insert (format "* %s" "my-heading")).

>  b) Parse the region: Get TREE and CONTENT
>      (Are they always separated for manipulation?)

See org-element-map for operating on a subset of the consents.  You could
also use narrowing to operate only on a subset of the buffer.

>  c) Manipulate tree AND/OR manipulate content


Manipulate whatever you have as you want.  Org-elements are plists.  Check
org-element-type, org-element-property, org-element-contents,
org-element-put-property, org-element-set-contents.  See also
";;; Accessors and Setters" in org-element.el.

org-element-interpret-data is the way to go from an element to
org-syntax.  Here's an example:

             http://emacs.stackexchange.com/questions/2869/turn-a-list-or-data-structure-into-an-org-document/

>  d) Interpret (the org-element-<element>interpreters seem to require
> <element> and content whilst the org-element-interpret-data only requires a
> single 'data'. Why?)

Don't use org-element-<element>interpreters.  Use
org-element-interpret-data for transforming org-element→org-syntax.

>  e) See the manipulated stuff appear in the buffer.

There's insert for that.

> 3) How can the output of (org-element-parse-secondary-string ...) be used.
> When I give a heading and bit of text as input (output of
> buffer-substring), it looks like it returns the 'content' of the region.
> Though I can't seem to use it anyway as 'CONTENT' for the functions
> requiring this.

I don't get this.

> 4) How to use org-element--parse-elements? Whilst it is running i notice
> that it uses (org-element--current-element) and some of the
> (org-element-<element>-parser) functions. Thought it could be nice to use
> this one, but no matter how use it, all I get is nil. For example:

In Emacs-lisp typically "--" indicates that it's a private function.
Don't use it.

> 5) What is org-element--current-element for? It also seems to be called by
> org-element--parse-element.The properties :begin, :end and :title  seem
> different than when parsing with org-element-at-point. Org-element-contents
> also nill when applied on the output. Why can't I use
>     this function (org-element--current-element) on plainlists/items
> (returns error with point within a plain-list/item)?

See above.

> I know the basic answer to most of these question is: Why don't you use
> (org-element-parse-buffer). Well simply because I don't need everything. in
> first implementation I only need:
> OR HEADLINE under point and it's subtree
>   (HEADLINE (plainlist (item,item,item)),(subheadline),...)
> OR the headline of an ITEM under point and subtree
>  (headline (plainlist (item, ITEM,item)),(subheadline),...).

So use org-element-map and org-element-parse-buffer.

Hope it helps,
Rasmus

--
The second rule of Fight Club is: You do not talk about Fight Club

--

gtz,
Dieter VE