From mboxrd@z Thu Jan 1 00:00:00 1970 From: Rasmus Subject: Re: Usage of org-element api Date: Fri, 16 Jan 2015 20:35:49 +0100 Message-ID: <87r3uu34dm.fsf@gmx.us> References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:39905) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YCCgf-0005gc-0f for emacs-orgmode@gnu.org; Fri, 16 Jan 2015 14:36:06 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YCCgY-0005Tc-Mz for emacs-orgmode@gnu.org; Fri, 16 Jan 2015 14:36:03 -0500 Received: from plane.gmane.org ([80.91.229.3]:38964) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YCCgY-0005TQ-C8 for emacs-orgmode@gnu.org; Fri, 16 Jan 2015 14:35:58 -0500 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1YCCgW-0003S9-HJ for emacs-orgmode@gnu.org; Fri, 16 Jan 2015 20:35:56 +0100 Received: from tsn109-201-154-155.dyn.nltelcom.net ([109.201.154.155]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 16 Jan 2015 20:35:56 +0100 Received: from rasmus by tsn109-201-154-155.dyn.nltelcom.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 16 Jan 2015 20:35:56 +0100 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 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 writes: > 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 ....) 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 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-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→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--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