From mboxrd@z Thu Jan 1 00:00:00 1970 From: Dieter Van Eessen Subject: Re: Usage of org-element api Date: Fri, 16 Jan 2015 22:45:05 +0100 Message-ID: References: <87r3uu34dm.fsf@gmx.us> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=001a1133d978c31043050ccbe2be Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:42128) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YCEha-0000PH-AK for emacs-orgmode@gnu.org; Fri, 16 Jan 2015 16:45:12 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YCEhX-0003jN-6g for emacs-orgmode@gnu.org; Fri, 16 Jan 2015 16:45:10 -0500 Received: from mail-yk0-x232.google.com ([2607:f8b0:4002:c07::232]:32806) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YCEhW-0003gx-LV for emacs-orgmode@gnu.org; Fri, 16 Jan 2015 16:45:07 -0500 Received: by mail-yk0-f178.google.com with SMTP id 20so10561235yks.9 for ; Fri, 16 Jan 2015 13:45:06 -0800 (PST) In-Reply-To: <87r3uu34dm.fsf@gmx.us> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org --001a1133d978c31043050ccbe2be Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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 . Then why do all the org-element--interpreters require both the AND 'content', since to me, it seems logical that all this information is already inside . 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 wrote: > Hi Dieter, > > Nicolas will probably reply at some point and he has much greater (=E2=88= =9E more) > insight in this topics. None the less, I hope the below message will > help a bit. > > Dieter Van Eessen writes: > > > 1) How to use org-element-content? Returns nil when used on elements > parsed > > by org-element--parser (because they operate locally) When us= ed > > globally, it only seems to remove the car of the list (org-data ....) > > Don't use org-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 th= e > 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 wit= h > 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. Chec= k > 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-structu= re-into-an-org-document/ > > > d) Interpret (the org-element-interpreters seem to require > > and content whilst the org-element-interpret-data only > requires a > > single 'data'. Why?) > > Don't use org-element-interpreters. Use > org-element-interpret-data for transforming org-element=E2=86=92org-synta= x. > > > 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 notic= e > > that it uses (org-element--current-element) and some of the > > (org-element--parser) functions. Thought it could be nice to u= se > > 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 > > > --=20 gtz, Dieter VE --001a1133d978c31043050ccbe2be Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
Hello Rasmus,

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

More about ques= tion number 3:
>> 3) How can the output of (org-e= lement-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 hav= ing to parse the whole buffer and still get the contents. The local parsing= functions (org-element-at-point) and (org-element-context) don't conta= in content (stated in the org-element api, also tried it ).

=
Now I'm not sure IF I really NEED it? I cou= ld actually get the contents using the=C2=A0 :content-begin and :content-en= d and other properties from (org-elemen-at-point)=C2=A0 BUT I don't kno= w the exact syntax the content should have and how to merge it with the ele= ment-list I get from (org-element-at-point) before feeding it to the org-el= ement-interpret-data.

I don't actually know how 'content= 9; looks like...=C2=A0 When applying a small function
" (defun test= ()=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0
=C2=A0=C2=A0=C2=A0 (interactive)
=C2=A0 =C2=A0= (debug)=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0
=C2=A0 =C2=A0= (setq content (org-element-contents (org-element-parse-buffer))))"
on a simple headline with some text,
" * woot
=C2=A0=C2=A0=C2=A0=C2=A0 And a bit of text "
<= /div>
I can see in debugger (returned values) that = 9;content' is actually (org-data nil ('content'). See output be= low. Thus concluding that content is also just an <element>. Then why= do all the org-element-<element>-interpreters require both the <e= lement>=C2=A0 AND 'content', since to me, it seems logical that = all this information is already inside <element>.

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

OUTPUT:
=C2=A0(org-data nil (headline (:raw-value "woot"= :begin 1 :end 29 :pre-blank 0 :contents-begin 8 ...) (section (:begin 8 :e= nd 29 :contents-begin
=C2=A0 8 :contents-end 26 :post-blank 2 ...) (para= graph (:begin 8 :end 26 :contents-begin 8 :contents-end 26 :post-blank 0 ..= .) #("And a bit of
=C2=A0 text=C2=A0 " 0 18 (:parent #3))))))<= br>=C2=A0 =C2=A0
=C2=A0 ((headline (:raw-value "woot" :begin = 1 :end 29 :pre-blank 0 :contents-begin 8 ...) (section (:begin 8 :end 29 :c= ontents-begin 8
=C2=A0 :contents-end 26 :post-blank 2 ...) (paragraph (:= begin 8 :end 26 :contents-begin 8 :contents-end 26 :post-blank 0 ...) #(&qu= ot;And a bit of text
=C2=A0 " 0 18 (:parent #3))))))

=
Perhaps my view is completely wrong, so please = correct me if possible.
Thanks for th= e time,
Dieter
<= span class=3D"">




On Fri, Jan 16, 2015 at 8:35 PM, Rasmus <rasmus@gmx.= us> wrote:
Hi Dieter,

Nicolas will probably reply at some point and he has much greater (=E2=88= =9E more)
insight in this topics.=C2=A0 None the less, I hope the below message will<= br> help a bit.

Dieter Van Eessen <dieter= .van.eessen@gmail.com> writes:

> 1) How to use org-element-content? Returns nil when used on elements p= arsed
> by org-element-<element>-parser (because they operate locally)= =C2=A0 When used
> globally, it only seems to remove the car of the list (org-data ....)<= br>
Don't use org-element-<element>-parser directly.

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

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

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

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

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

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

>=C2=A0 c) Manipulate tree AND/OR manipulate content


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

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

=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0http://emacs.stackexchange.com/questions/2869/tur= n-a-list-or-data-structure-into-an-org-document/

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

Don't use org-element-<element>interpreters.=C2=A0 Use
org-element-interpret-data for transforming org-element=E2=86=92org-syntax.=

>=C2=A0 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 u= sed.
> When I give a heading and bit of text as input (output of
> buffer-substring), it looks like it returns the 'content' of t= he 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 noti= ce
> that it uses (org-element--current-element) and some of the
> (org-element-<element>-parser) functions. Thought it could be ni= ce 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 pri= vate function.
Don't use it.

> 5) What is org-element--current-element for? It also seems to be calle= d by
> org-element--parse-element.The properties :begin, :end and :title=C2= =A0 seem
> different than when parsing with org-element-at-point. Org-element-con= tents
> also nill when applied on the output. Why can't I use
>=C2=A0 =C2=A0 =C2=A0this function (org-element--current-element) on pla= inlists/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 yo= u use
> (org-element-parse-buffer). Well simply because I don't need every= thing. in
> first implementation I only need:
> OR HEADLINE under point and it's subtree
>=C2=A0 =C2=A0(HEADLINE (plainlist (item,item,item)),(subheadline),...)<= br> > OR the headline of an ITEM under point and subtree
>=C2=A0 (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
--001a1133d978c31043050ccbe2be--