From mboxrd@z Thu Jan 1 00:00:00 1970 From: Dieter Van Eessen Subject: Usage of org-element api Date: Fri, 16 Jan 2015 19:35:53 +0100 Message-ID: Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=001a11390a8e174f4a050cc93e37 Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:56300) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YCBkS-0000dG-Cn for emacs-orgmode@gnu.org; Fri, 16 Jan 2015 13:35:58 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YCBkQ-0002eu-Bg for emacs-orgmode@gnu.org; Fri, 16 Jan 2015 13:35:56 -0500 Received: from mail-yk0-x22a.google.com ([2607:f8b0:4002:c07::22a]:52231) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YCBkQ-0002eq-5a for emacs-orgmode@gnu.org; Fri, 16 Jan 2015 13:35:54 -0500 Received: by mail-yk0-f170.google.com with SMTP id 200so10216895ykr.1 for ; Fri, 16 Jan 2015 10:35:53 -0800 (PST) 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 --001a11390a8e174f4a050cc93e37 Content-Type: text/plain; charset=UTF-8 Hello, New to the list. Got some questions regarding the use of the org-element api. I've already learned alot by reading the emacs help and org-developers section. and the online org-element-docstrings have been very helpful. I'm not a highly skilled lisp-programmer, but got good grip on the basics and I learn fast :) Still a few questions remain: 1) How to use org-element-content? Returns nil when used on elements parsed by org-element--parser (because they operate locally) When used globally, it only seems to remove the car of the list (org-data ....) 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) b) Parse the region: Get TREE and CONTENT (Are they always separated for manipulation?) c) Manipulate tree AND/OR manipulate content d) Interpret (the org-element-interpreters seem to require and content whilst the org-element-interpret-data only requires a single 'data'. Why?) e) See the manipulated stuff appear in the buffer. 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. 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--parser) functions. Thought it could be nice to use this one, but no matter how use it, all I get is nil. For example: (setq element-parse (org-element--parse-elements (org-element-property ':begin (org-element-at-point)) (org-element-property ':end (org-element-at-point)) 'section nil 'headline nil nil)) When I try such this ANYWHERE in the following text, i get nil. * boe * argh ** lol Something funny ** woot 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)? 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),...). Manipulating these trees won't be too hard. I don't neccesarily need the contents, I can (buffer-substring) them using the :contents-begin and :contents-end properties. BUT I think I will need them to write back to the buffer after having manipulated some things in the tree. Haven't investigated (org-element-interpret-data) yet, nor all the (org-element--interpreters) it calls. It's a long mail, please don't yell at me if I overlooked stuff on the web, it's quite a huge pool of information... Dieter Van Eessen --001a11390a8e174f4a050cc93e37 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
Hello,

New to the list. Got some qu= estions regarding the use of the org-element api. I've already learned = alot by reading the emacs help and org-developers section. and the online o= rg-element-docstrings have been very helpful. I'm not a highly skilled = lisp-programmer, but got good grip on the basics and I learn fast :)
Still a few questions remain:

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

2) What is actually a normal workflow if you wish to = interactive manipulate only some of the elements? Is it something like:
=
=C2=A0a)=C2=A0 Define the region in which you wish to manipulate= things (using :begin and :extract from=C2=A0 org-element-at-point)
=C2=A0b) Parse the region: Get TREE and CONTENT
=C2=A0= =C2=A0=C2=A0=C2=A0 (Are they always separated for manipulation?)
<= div>=C2=A0c) Manipulate tree AND/OR manipulate content
=C2=A0= d) Interpret (the org-element-<element>interpreters seem to require &= lt;element> and content whilst the org-element-interpret-data only requi= res a single 'data'. Why?)
=C2=A0e) See the manipulat= ed stuff appear in the buffer.

3) How can the = output of (org-element-parse-secondary-string ...) be used. When I give a h= eading 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=C2=A0 requiring this.=

4) How to use org-element--parse-elements? Whilst it is running i n= otice that it uses (org-element--current-element) and some of the=C2=A0 (or= g-element-<element>-parser) functions. Thought it could be nice to us= e this one, but no matter how use it, all I get is nil. For example:
=C2= =A0=C2=A0=C2=A0=C2=A0
=C2=A0(setq element-parse (org-element--parse-ele= ments (org-element-property ':begin (org-element-at-point)) (org-elemen= t-property ':end (org-element-at-point)) 'section nil 'headline= nil nil))
=C2=A0=C2=A0=C2=A0
When I try such this ANYWHERE in the f= ollowing text, i get nil.
* boe
* argh
** lol
=C2=A0=C2=A0=C2= =A0 Something funny
** woot
=C2=A0=C2=A0=C2=A0
5) What is org-ele= ment--current-element for? It also seems to be called by org-element--parse= -element.The properties :begin, :end and :title=C2=A0 seem different than w= hen parsing with org-element-at-point. Org-element-contents also nill when = applied on the output. Why can't I use=C2=A0=C2=A0=C2=A0=C2=A0
=C2= =A0=C2=A0=C2=A0 this function (org-element--current-element) on plainlists/= items (returns error with point within a plain-list/item)?


I know the basic answer to most of these question is: Why don't y= ou use (org-element-parse-buffer). Well simply because I don't need eve= rything. in first implementation I only need:
OR HEADLINE under point an= d it's subtree
=C2=A0 (HEADLINE (plainlist (item,item,ite= m)),(subheadline),...)
OR the headline of an ITEM under point= and subtree
=C2=A0(headline (plainlist (item, ITEM,item)),(s= ubheadline),...).

Manipulating = these trees won't be too hard. I don't neccesarily need the content= s, I can (buffer-substring) them using the :contents-begin and :contents-en= d properties.
BUT I think I will need them to write back to the buffer = after having manipulated some things in the tree. Haven't investigated = (org-element-interpret-data) yet, nor all the (org-element-<element>-= interpreters) it calls.


It= 's a long mail, please don't yell at me if I overlooked stuff on th= e web, it's quite a huge pool of information...

Dieter Van Eessen
--001a11390a8e174f4a050cc93e37--