[ANN] org-dp now on MELPA

[ANN] org-dp now on MELPA

[Thorsten Jolitz]

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

Re: [ANN] org-dp now on MELPA

[Xebar Saram]

[-- Attachment #1: Type: text/plain, Size: 7811 bytes --]

Thx Thorsten

i still use it daily :D

best

Z

On Sat, Feb 6, 2016 at 4:47 PM, Thorsten Jolitz <tjolitz@gmail.com> wrote:

>
> 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
>
>
>

[-- Attachment #2: Type: text/html, Size: 9224 bytes --]

Re: [ANN] org-dp now on MELPA

[Thorsten Jolitz]

Xebar Saram <zeltakc@gmail.com> writes:

Hi Xebar,

> Thx Thorsten
>
> i still use it daily :D

I did not know that I have a user actually, because when I announced it
a year ago or so it never drew much attention (a bit to my surprise, I
must admit). So I'm happy about the news ;-)

You just used a few convenience functions based on org-dp - or really
did some Elisp programming in this style? I tested and used these
functions for a while, but it would be nice to hear that they work(ed)
for other programmers too ...
 
-- 
cheers,
Thorsten

Re: [ANN] org-dp now on MELPA

[Rasmus]

Thorsten Jolitz <tjolitz@gmail.com> writes:

> Xebar Saram <zeltakc@gmail.com> writes: 
> 
> Hi Xebar, 
> 
>> Thx Thorsten 
>> 
>> i still use it daily :D 
> 
> I did not know that I have a user actually, because when I 
> announced it a year ago or so it never drew much attention (a 
> bit to my surprise, I must admit). So I'm happy about the news 
> ;-) 

It's also mentioned here, though it may be a unfair 
characterization of org-dp:

     http://emacs.stackexchange.com/a/2885/1974

Rasmus

-- 
Er du tosset for noge' lårt!

Re: [ANN] org-dp now on MELPA

[Thorsten Jolitz]

Rasmus <rasmus@gmx.us> writes:

> Thorsten Jolitz <tjolitz@gmail.com> writes:
>
>> Xebar Saram <zeltakc@gmail.com> writes: 
>>
>> Hi Xebar, 
>>
>>> Thx Thorsten 
>>>
>>> i still use it daily :D 
>>
>> I did not know that I have a user actually, because when I announced
>> it a year ago or so it never drew much attention (a bit to my
>> surprise, I must admit). So I'm happy about the news ;-) 
>
> It's also mentioned here, though it may be a unfair characterization
> of org-dp:
>
>     http://emacs.stackexchange.com/a/2885/1974

Thanks for advertising a bit! 

#+BEGIN_QUOTE
org-dp is a meant to make it easer for to use "lisp representation" to
create new "Org syntax representation" (as this it not a goal of
org-element per se).
#+END_QUOTE
                         
Its not wrong or unfair, but not what I would say either. org-element
does the same thing - parse the given text, work on the internal
representation, write the new text by interpreting the modified internal
representation. Only that it parses the whole (maybe narrowed) buffer
and has all context info, and mostly is not used to write Org syntax
(but rather those of the export backends).

 Maybe this excerpt from the README is a better characteristic:

,----
| 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). 
`----

And the 'd' in 'dp' is important, since this is a different programming
style. Its more declarative (in the sense of "A program that describes
what computation should be performed and not how to compute it") because
the programmer 'declares' he wants a certain element type with certain
parameter values at a certain place. Parsing the existing element and
writing the new/modified element, the HowTo, is mostly left to the
parser framework.

Source code that uses org-dp looks quite different from the usual Elisp
sources in Emacs/Org libraries that work on the textual representation.

-- 
cheers,
Thorsten

Re: [ANN] org-dp now on MELPA

[Rasmus]

Thorsten Jolitz <tjolitz@gmail.com> writes:

> Its not wrong or unfair, but not what I would say 
> either. org-element does the same thing - parse the given text, 
> work on the internal representation, write the new text by 
> interpreting the modified internal representation. Only that it 
> parses the whole (maybe narrowed) buffer and has all context 
> info, and mostly is not used to write Org syntax (but rather 
> those of the export backends). 

I edited it with (almost) the suggested quote, and added a pointer 
back to your post here.  I don’t know how much advertisement it 
generates, though.

Rasmus

-- 
⠠⠵

Re: [ANN] org-dp now on MELPA

[Thorsten Jolitz]

Rasmus <rasmus@gmx.us> writes:

> Thorsten Jolitz <tjolitz@gmail.com> writes:
>
>> Its not wrong or unfair, but not what I would say
>> either. org-element does the same thing - parse the given text, work
>> on the internal representation, write the new text by interpreting
>> the modified internal representation. Only that it parses the whole
>> (maybe narrowed) buffer and has all context info, and mostly is not
>> used to write Org syntax (but rather those of the export backends). 
>
> I edited it with (almost) the suggested quote, and added a pointer
> back to your post here.  I don’t know how much advertisement it
> generates, though.

Ok, thanks!

My sales department told me I should convince/pay some popular open
source hacker to make an enthusiastic note about org-dp on hackers news
(THE NEXT BIG THING!!) 
;-)

JUST kidding, but hackers news really has a big coverage. Last year
apparently someone mentioned outshine on HN, and my number of Github
followers and stars tripled in just a few days, while I had no idea
whats going on and was pretty surprised about so much attention.

-- 
cheers,
Thorsten