emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[O] [ANN] org-dp now on MELPA


From: Thorsten Jolitz
Subject: [O] [ANN] org-dp now on MELPA
Date: Sat, 06 Feb 2016 15:47:39 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux)

Hi List,
after not touching it for a year or so I recently rediscovered my org-dp
("Declarative Programming with Org Elements") library and still liked
it, so I decided to clean it up a bit and publish it as version 1.0 on
MELPA. Now you can install it via package manager or clone it from my
github repo (https://github.com/tj64/org-dp).

Here is an excerpt from the readme:

#+BEGIN_QUOTE
Since all Org elements are uniformely represented as nested lists
internally, with their properties stored as key-val pairs in
plists, they can be treated in a much more uniform way when dealing
with the internal representation instead of the highly variable
textual representations. A big advantage of plists is that only
those properties that are actually accessed matter, so when
transforming one Org element into another on the internal level one
does not have to worry about not matching properties as long as
these are not used by the interpreter when building the textual
representation of the transformed element.

Library org-dp is meant for programming at the local level,
i.e. without any (contextual) information except those about the
parsed element at point. It is designed to make using the Org-mode
parser/interpreter framework at local level as convenient as using
it at the global level (with a complete parse-tree produced by
`org-element-parse-buffer` available). It takes care of the
org-element caching mechanism in that it only acts on copies of the
locally parsed elements at point, never on the original parsed (and
cached) object itself.
#+END_QUOTE

There are just 2 core functions (with extensive docstrings) that lets
you do anything you want with the Org element at point:

,----[ C-h f org-dp-create RET ]
| org-dp-create is a compiled Lisp function in `org-dp.el'.
| 
| (org-dp-create ELEM-TYPE &optional CONTENTS INSERT-P AFFILIATED &rest
| ARGS)
| 
| Create Org element of type ELEM-TYPE (headline by default). [...]
`----

,----[ C-h f org-dp-rewire RET ]
| org-dp-rewire is a compiled Lisp function in `org-dp.el'.
| 
| (org-dp-rewire ELEM-TYPE &optional CONTENTS REPLACE AFFILIATED ELEMENT
| &rest ARGS)
| 
| Rewire element-at-point or ELEMENT (if given).
| [...]
`----

and one lightweight but flexible mapping function:

,----[ C-h f org-dp-map RET ]
| org-dp-map is a compiled Lisp function in `org-dp.el'.
| 
| (org-dp-map FUN-WITH-ARGS RGXP &optional MATCH-POS BACKWARD-SEARCH-P
| BEG END SILENT-P)
| 
| Apply quoted FUN-WITH-ARGS at every RGXP match.
| [...]
`----

In org-dp-lib.el you can find a few (lightweight but powerful)
convenience function implemented with the org-dp core functions above,
so they serve as exemples for the org-dp programming style too.

,----[ C-h f org-dp-wrap-in-block RET ]
| org-dp-wrap-in-block is an interactive Lisp function in
| `org-dp-lib.el'.
| 
| (org-dp-wrap-in-block &optional LINES USER-INFO &rest PROMPT-SPEC)
| 
| Wrap sexp-at-point or region in Org block.
| [...]
`----

,----[ C-h f org-dp-toggle-headers RET ]
| org-dp-toggle-headers is an interactive Lisp function in
| `org-dp-lib.el'.
| 
| (org-dp-toggle-headers &optional ACTION)
| 
| Toggle header argument representation.
| [...]
`----

,----[ C-h f org-dp-filter-node-props RET ]
| org-dp-filter-node-props is a Lisp function in `org-dp-lib.el'.
| 
| (org-dp-filter-node-props FILTER &optional NEGATE-P VERBOSE-P)
| 
| Return filtered node-properties.
| [...]
`----

A few functions for creating composite Org elements:

,----[ C-h f org-dp-create-table RET ]
| org-dp-create-table is a Lisp function in `org-dp-lib.el'.
| 
| (org-dp-create-table ROW-LST &optional TBLFM TABLE-EL-P INSERT-P)
| 
| Create table with content ROW-LST.
| [...]
`----

,----[ C-h f org-dp-create-plain-list RET ]
| org-dp-create-plain-list is a Lisp function in `org-dp-lib.el'.
| 
| (org-dp-create-plain-list ITEM-LST &optional INSERT-P)
| 
| Create plain list with content ITEM-LST.
| [...]
`----

,----[ C-h f org-dp-create-property-drawer RET ]
| org-dp-create-property-drawer is a Lisp function in `org-dp-lib.el'.
| 
| (org-dp-create-property-drawer NODE-PROP-LST &optional INSERT-P)
| 
| Create property drawer with content NODE-PROP-LST.
| [...]
`----

And there is the mother of all prompting functions:

,----[ C-h f org-dp-prompt RET ]
| org-dp-prompt is a Lisp function in `org-dp.el'.
| 
| (org-dp-prompt &optional ELEM ELEM-LST PARTIAL-RESULTS-P &key CONT VAL
| REPL AFF SRC ARGS)
| 
| Prompt user for specific properties.
| 
| This function uses `org-dp-prompt-all' to do the real work, but
| follows the opposite strategy: all prompt options are turned off
| by default and must be explicitly activated (while
| `org-dp-prompt-all' prompts for everything that is not explicitly
| deactivated). Called with no argmuents, it simply prompts for an
| element type. 
| 
| See docstring of `org-dp-prompt-all' for more info about
| arguments ELEM and ELEM-LST. 
| 
| If PARTIAL-RESULTS-P is non-nil, delete 'nil' values from
| `org-dp-prompt-all's return-list
| 
|   (elem-type contents replace affiliated args)
| 
| otherwise simply return it 'as-is'.
| 
| Optional keyword arguments CONT, VAL, REPL, AFF, SRC and ARGS, if
| given, should be either `t' (to activate prompting for them) or
| of an adecuate type (see docstring of `org-dp-prompt-all') that
| will be used as default value without prompting.
| 
| [back]
`----

With org-dp, its all about setting or modifying those element properties
that are used by the element's interpreter. These are significantly
fewer than those that are parsed by the element's parser.

It is possible to define a single core workhorse function that prompts
the user for all of these interpreted properties (see docstring above).
>From this workhorse function, countless convenience functions can be
derived simply by restricting/expanding the number of properties
prompted for. 

The workhorse function and its derived functions return a result list,
that can be consumed by

,----[ C-h f org-dp-apply RET ]
| org-dp-apply is a Lisp function in `org-dp.el'.
| 
| (org-dp-apply LST &optional FUN ELEMENT)
| 
| Apply org-dp function to (full) results LST of `org-dp-prompt'.
| If FUN is non-nil, it must be `memq' of variable
| `org-dp-apply-funs'. See docstring of `org-dp-prompt' for
| more info about argument LST and docstring of `org-dp-rewire' for
| more info about argument ELEMENT.
| 
| [back]
`----

So using org-dp, you never have to write your own interactive specs
anymore (within org-dp's context). Just use this construct:

,----[optional]     
| (defun my-custom-org-prompt-cmd ()
|   "Call `org-dp-prompt' with certain parameter combination."
|   (interactive)
|   (org-dp-prompt [argument set]...))
`----

,----[ask user and create org element at point]
| (org-dp-apply (org-dp-prompt)) ; or
| (org-dp-apply (my-custom-org-prompt-cmd))
`----

,----[ask user and rewire(=modify) org element at point]
| (org-dp-apply (org-dp-prompt) t) ; or
| (org-dp-apply (my-custom-org-prompt-cmd) t) ;or
|
| (org-dp-apply (org-dp-prompt) 'rewire) ; or
| (org-dp-apply (my-custom-org-prompt-cmd) 'rewire)
`----

The advantage of this style of programming is that the internal Org element
representation is so uniform (and the number of interpreted properties 
quite limited) that one solution might fit all (elements).

-- 
cheers,
Thorsten




reply via email to

[Prev in Thread] Current Thread [Next in Thread]