From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thorsten Jolitz Subject: Re: Org-element once again Date: Wed, 08 Oct 2014 09:20:33 +0200 Message-ID: <8738azrpry.fsf@gmail.com> References: <87k34blbly.fsf@wmi.amu.edu.pl> <8761fvz3ew.fsf@ericabrahamsen.net> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:38751) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XblYL-00039w-RZ for emacs-orgmode@gnu.org; Wed, 08 Oct 2014 03:20:59 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XblYG-0005O4-Iz for emacs-orgmode@gnu.org; Wed, 08 Oct 2014 03:20:53 -0400 Received: from plane.gmane.org ([80.91.229.3]:37598) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XblYG-0005Ny-B1 for emacs-orgmode@gnu.org; Wed, 08 Oct 2014 03:20:48 -0400 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1XblYE-0003Ko-Td for emacs-orgmode@gnu.org; Wed, 08 Oct 2014 09:20:46 +0200 Received: from g231108194.adsl.alicedsl.de ([92.231.108.194]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 08 Oct 2014 09:20:46 +0200 Received: from tjolitz by g231108194.adsl.alicedsl.de with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 08 Oct 2014 09:20:46 +0200 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 Eric Abrahamsen writes: > Marcin Borkowski writes: > >> Hi list, >> >> does there exist any place I could find the specs of the org-element >> data structure? From what I can see, it is a list whose car is the type >> of the element, then a (somewhat mysterious or me) plist follows, and >> then the children. Where could I find more info? If the answer is >> "read the source, Luke" ;-) , which functions should I start with? >> >> Best, > > Have you looked at this page? > > http://orgmode.org/worg/dev/org-element-api.html > > That and the pages linked from it seem to cover most of what's going on. > > The mysterious plist holds all the properties for a given element. Most > are generated by the parsing process (eg :contents-begin and > :contents-end, see the link above for all the different properties the > various elements/objects might get), while headlines will also have > their actual property-drawer properties put into the list. > > The only thing that remains a little opaque to me is the "section" > element, which apparently gets wrapped around a heading's subtree. I > don't know what it does, but it's never gotten in my way so I haven't > worried about it. in simple terms, the data structure is just: ,---- | (element-typ (plist) (section)) `---- i.e. the plist describes the element itself, the section is its content. * TODO Test :@home: DEADLINE: <2014-10-09 Do> :PROPERTIES: :ARCHIVE: foo :END: org-element-at-point does not parse the contents of an element, it thus simply returns ,---- | (element-typ (plist)) `---- #+NAME: foo #+BEGIN_SRC emacs-lisp (save-excursion (outline-previous-heading) (org-element-at-point)) #+END_SRC # [:results pp] #+results: : (headline : (:raw-value "Test" :begin 1432 :end 2214 :pre-blank 0 :contents-begin 1452 :contents-end 2214 :level 1 :priority nil :tags : ("@home") : :todo-keyword "TODO" :todo-type todo :post-blank 0 :footnote-section-p nil :archivedp nil :commentedp nil :post-affiliated 1432 :deadline : (timestamp : (:type active :raw-value "<2014-10-09 Do>" :year-start 2014 :month-start 10 :day-start 9 :hour-start nil :minute-start nil :year-end 2014 :month-end 10 :day-end 9 :hour-end nil :minute-end nil :begin 1464 :end 1479 :post-blank 0)) : :ARCHIVE "foo" :title "Test")) #+NAME: bar #+BEGIN_SRC emacs-lisp :var x=foo (org-element-interpret-data x) #+END_SRC #+results: bar : * TODO Test :@home: so this is (just) the element (headline) as specified by its plist. You can get the contents e.g. with #+BEGIN_SRC emacs-lisp :results wrap (require 'org-dp-lib) (save-excursion (outline-previous-heading) (org-dp-contents nil t))) #+END_SRC #+results: :RESULTS: DEADLINE: <2014-10-09 Do> :PROPERTIES: :ARCHIVE: foo :END: [...] :END: but the default org-element-parse-buffer parses everything (when specified), the contents too, so it would give you ,---- | (element-typ (plist) (section)) `---- with section recursively containing other elements with the same structure -> a nested list. -- cheers, Thorsten