programming for org-mode

programming for org-mode

[Ivanov Dmitry]

Hi, can anyone give me a tutorial for org-mode programming and it's API.

I just read Eric Schultes module org-collector.el, but I can't understand the code: how it is organized and how to write the elisp  for org-mode.

Can anyone help?

Re: programming for org-mode

[Eric Schulte]

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

So,

The way that I learned how to program in emacs lisp was mainly using two
commands `elisp-index-search' bound to `C-h e' on my system, and most
importantly `describe-function' bound to `C-h f'.  With
`describe-function' you can look at the source code of functions whose
behavior you are familiar with, you can then copy portions of the code
to your *scratch* buffer where they can be edited and evaluated with
`eval-defun' bound to `C-M-x'.  Now with Babel, instead of doing this in
the scratch buffer you could do this in emacs-lisp code blocks in an org
file, enabling notes and hierarchical organization -- it can be nice to
have your noodling all collected in one file for later reference.

If you are going to do any serious work with lisp, I would emphatically
recommend using paredit-mode, and becoming friends with the Sexp
movement functions

[-- Attachment #2.1: Type: text/plain, Size: 230 bytes --]

| C-M-f | runs the command paredit-forward  |
| C-M-b | runs the command paredit-backward |
| C-M-u | runs the command backward-up-list |
| C-M-k | runs the command kill-sexp        |
| C-y   | runs the command yank             |

[-- Attachment #2.2: Type: text/html, Size: 498 bytes --]

[-- Attachment #3: Type: text/plain, Size: 1471 bytes --]

They allow you to manipulate lisp code on the level of logical
expressions, the utility of which can not be over stated.

As for working with Org-mode in particular, I'd recommend looking at the
documentation and source-code of Org-mode functions with
`describe-function', and then looking for how these functions are
actually used in the Org-mode code base with `rgrep'.

For a more structured learning experience, I've heard very good things
about http://www.gnu.org/software/emacs/emacs-lisp-intro/, although I
haven't used it myself.

Hope this helps.  Happy Hacking -- Eric

Ivanov Dmitry <usr345@gmail.com> writes:

> Hi, can anyone give me a tutorial for org-mode programming and it's API.
>

I'm afraid there is no such thing as an org-mode api, the closest you
could come would be

grep -i defun org/lisp/org.el

for a list of function names and their arguments, or run
`describe-function' then type "org-" into the minibuffer, tab complete,
and then search through the resulting function-names.

>
> I just read Eric Schultes module org-collector.el, but I can't
> understand the code: how it is organized and how to write the elisp
> for org-mode.
>

If you have any org-collector.el specific questions please let me know.

>
> Can anyone help?
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

[-- Attachment #4: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: programming for org-mode

[David Maus]

[-- Attachment #1.1: Type: text/plain, Size: 1516 bytes --]

Eric Schulte wrote:
>[1  <text/plain (7bit)>]
>So,

>The way that I learned how to program in emacs lisp was mainly using two
>commands `elisp-index-search' bound to `C-h e' on my system, and most
>importantly `describe-function' bound to `C-h f'.  With
>`describe-function' you can look at the source code of functions whose
>behavior you are familiar with, you can then copy portions of the code
>to your *scratch* buffer where they can be edited and evaluated with
>`eval-defun' bound to `C-M-x'.  Now with Babel, instead of doing this in
>the scratch buffer you could do this in emacs-lisp code blocks in an org
>file, enabling notes and hierarchical organization -- it can be nice to
>have your noodling all collected in one file for later reference.

>If you are going to do any serious work with lisp, I would emphatically
>recommend using paredit-mode, and becoming friends with the Sexp
>movement functions

+1 and not to forget eldoc (M-x eldoc-mode)[1] that displays the
description of a variable or the arguments of a function in
minibuffer.

For hacking Org mode in particular there is a "Hacking" section in the
manual that explains the mapping and the property API.

For getting in touch with Emacs Lisp there's Xah Lee's Emacs Lisp
Tutorial, too[3].

HTH & happy hacking,

 -- David

[1] http://www.emacswiki.org/emacs/?ElDoc

[2] http://orgmode.org/manual/Hacking.html

[3] http://xahlee.org/emacs/elisp.html

--
OpenPGP... 0x99ADB83B5A4478E6
Jabber.... dmjena@jabber.org
Email..... dmaus@ictsoc.de

[-- Attachment #1.2: Type: application/pgp-signature, Size: 230 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: programming for org-mode

[David Maus]

[-- Attachment #1.1: Type: text/plain, Size: 254 bytes --]

Ah, heck, just forgot:

Casting Spells in Lisp
http://www.lisperati.com/casting.html

Comic book about programming in Lisp, Emacs Lisp Version available.

 -- David
--
OpenPGP... 0x99ADB83B5A4478E6
Jabber.... dmjena@jabber.org
Email..... dmaus@ictsoc.de

[-- Attachment #1.2: Type: application/pgp-signature, Size: 230 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: programming for org-mode

[Nick Dokos]

Eric Schulte <schulte.eric@gmail.com> wrote:

> ... 
> If you are going to do any serious work with lisp, I would emphatically
> recommend using paredit-mode, and becoming friends with the Sexp
> movement functions
> +--------------------------------------------+
> | C-M-f | runs the command paredit-forward   |
> |-------+------------------------------------|
> | C-M-b | runs the command paredit-backward  |
> |-------+------------------------------------|
> | C-M-u | runs the command backward-up-list  |
> |-------+------------------------------------|
> | C-M-k | runs the command kill-sexp         |
> |-------+------------------------------------|
> | C-y   | runs the command yank              |
> +--------------------------------------------+
> 
> They allow you to manipulate lisp code on the level of logical
> expressions, the utility of which can not be over stated.
> 

I presume that paredit is useful because it's a minor mode, so you can
enable it on an org-mode buffer (e.g. using babel). But if you are
editing a .el file, then emacs-lisp mode provides all these facilities
(C-M-f -> forward-sexp, etc.) and you don't need paredit.  Do I have
that right?

Thanks,
Nick

PS. The ultimate *reference* for emacs lisp is the Emacs Lisp Reference
manual

        http://www.gnu.org/software/emacs/manual/html_node/elisp/index.html

At some point in one's emacs-lisp programming life, it will be necessary
to refer to it - but it is very much a reference manual, not a tutorial.

Re: programming for org-mode

[Eric Schulte]

Hi Nick,

Nick Dokos <nicholas.dokos@hp.com> writes:

> Eric Schulte <schulte.eric@gmail.com> wrote:
>
>> ... 
>> If you are going to do any serious work with lisp, I would emphatically
>> recommend using paredit-mode, and becoming friends with the Sexp
>> movement functions
>> +--------------------------------------------+
>> | C-M-f | runs the command paredit-forward   |
>> |-------+------------------------------------|
>> | C-M-b | runs the command paredit-backward  |
>> |-------+------------------------------------|
>> | C-M-u | runs the command backward-up-list  |
>> |-------+------------------------------------|
>> | C-M-k | runs the command kill-sexp         |
>> |-------+------------------------------------|
>> | C-y   | runs the command yank              |
>> +--------------------------------------------+
>> 
>> They allow you to manipulate lisp code on the level of logical
>> expressions, the utility of which can not be over stated.
>> 
>
> I presume that paredit is useful because it's a minor mode, so you can
> enable it on an org-mode buffer (e.g. using babel).

No, even for emacs-lisp code blocks I use C-c ' to edit the code in
emacs-lisp mode.  I do have "[" and "]" globally bound to
`insert-parenthesis' and `move-past-close-and-reindent' respectively,
but that's probably a little too radical for most users.

I only enable paredit minor-mode in lispy modes.

> But if you are editing a .el file, then emacs-lisp mode provides all
> these facilities (C-M-f -> forward-sexp, etc.) and you don't need
> paredit.  Do I have that right?
>

Not quite,

Paredit has a number of nice features aside from sexp movement,
including /electric/ insertion of both open and close parenthesis,
brackets and quotation's which greatly increase the speed with which one
can write lisp code -- all the while ensuring that the code in the
buffer is /valid/ in terms of balanced parenthesis.

Cheers -- Eric

>
> Thanks,
> Nick
>
> PS. The ultimate *reference* for emacs lisp is the Emacs Lisp Reference
> manual
>
>         http://www.gnu.org/software/emacs/manual/html_node/elisp/index.html
>
> At some point in one's emacs-lisp programming life, it will be necessary
> to refer to it - but it is very much a reference manual, not a tutorial.

Re: programming for org-mode

[Nick Dokos]

Eric Schulte <schulte.eric@gmail.com> wrote:

> > I presume that paredit is useful because it's a minor mode, so you can
> > enable it on an org-mode buffer (e.g. using babel).
> 
> No, even for emacs-lisp code blocks I use C-c ' to edit the code in
> emacs-lisp mode.  I do have "[" and "]" globally bound to
> `insert-parenthesis' and `move-past-close-and-reindent' respectively,
> but that's probably a little too radical for most users.
> 
> I only enable paredit minor-mode in lispy modes.
> 

Ah, OK.

> > But if you are editing a .el file, then emacs-lisp mode provides all
> > these facilities (C-M-f -> forward-sexp, etc.) and you don't need
> > paredit.  Do I have that right?
> >
> 
> Not quite,
> 
> Paredit has a number of nice features aside from sexp movement,
> including /electric/ insertion of both open and close parenthesis,
> brackets and quotation's which greatly increase the speed with which one
> can write lisp code -- all the while ensuring that the code in the
> buffer is /valid/ in terms of balanced parenthesis.
> 

Thanks for the explanation!

Nick

Re[2]: programming for org-mode

[Ivanov Dmitry]

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

Hi, Eric. I decided to draw schemes for functions in your module org-collector.el. And started from org-read-prop. Please, check my pdf file - my questions are marked with green. If there are no attachments allowed in the mailing list, you can get it here:

http://live-wtr.ru/org/org-collector.pdf

Can you explain, which function is called, when the user clicks C-c C-c on the line with #+BEGIN: propview? It's almost impossible to understand the complicated code of other programmer without a scheme. Did you see, how many questions emerged after I schematized just one simple function. 

org-dblock-write:propview seems to be really hard.

[-- Attachment #2: org-collector.pdf --]
[-- Type: application/pdf, Size: 5988 bytes --]

[-- Attachment #3: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re[4]: programming for org-mode

[Ivanov Dmitry]

Hi, Marcelo.

I used Visio. Then saved as Postscript and converted to pdf, using ps2pdf.

Re: Re[2]: programming for org-mode

[David Maus]

[-- Attachment #1.1: Type: text/plain, Size: 2547 bytes --]

Hi Ivanov,

Ivanov Dmitry wrote: >Hi, Eric. I decided to draw schemes for
functions in your module org-collector.el. And started from
org-read-prop. Please, check my pdf file - my questions are marked
with green. If there are no attachments allowed in the mailing list,
you can get it here:

>http://live-wtr.ru/org/org-collector.pdf

,----
| 01. (defun org-read-prop (prop)
| 02.   "Convert the string property PROP to a number if appropriate.
| 03. Otherwise if prop looks like a list (meaning it starts with a
| 04. '(') then read it as lisp, otherwise return it unmodified as a
| 05. string."
| 06.   (if (and (stringp prop) (not (equal prop "")))
| 07.       (let ((out (string-to-number prop)))
| 08.         (if (equal out 0)
| 09.             (if (or (equal "(" (substring prop 0 1)) (equal "'" (substring prop 0 1)))
| 10.                 (read prop)
| 11.               (if (string-match "^\\(+0\\|-0\\|0\\)$" prop)
| 12.                   0
| 13.                 (progn (set-text-properties 0 (length prop) nil prop)
| 14.                        prop)))
| 15.           out))
| 16.     prop))
`----

If `prop' is a string and not empty, bind `out' to the result of
calling `string-to-number' with argument `prop'.  `string-to-number'
returns 0 if the string was a zero or if the string didn't contain
convertable characters.  Thus, if `out` ist /not/ zero, we return
`out'.

If it is, check if `prop' looks like a Lisp expression (Line 09).  If
it looks like a Lisp expresion, return this expression.

C-h f read RET:

,----
| read is a built-in function in `C source code'.
|
| (read &optional STREAM)
|
| Read one Lisp expression as text from STREAM, return as Lisp object.
| If STREAM is nil, use the value of `standard-input' (which see).
| STREAM or the value of `standard-input' may be:
|  a buffer (read from point and advance it)
|  a marker (read from where it points and advance it)
|  a function (call it with no arguments for each character,
|      call it with a char as argument to push a char back)
|  a string (takes text from string, starting at the beginning)
|  t (read text line using minibuffer and use it, or read from
|     standard input in batch mode).
|
| [back]
`----

If it didn't look like a Lisp expression, check if `out' is 0 because
`prop' is the string "0", "+0", or "-0".  If this is the case, return
0.  We don't use `unless' because in this case the function
`org-read-prop' would return nil.

HTH,
  -- David
--
OpenPGP... 0x99ADB83B5A4478E6
Jabber.... dmjena@jabber.org
Email..... dmaus@ictsoc.de

[-- Attachment #1.2: Type: application/pgp-signature, Size: 230 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re[4]: programming for org-mode

[Ivanov Dmitry]

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

Thanks, David. I improved the scheme, added 2 question. Please, take a look.

[-- Attachment #2: org-collector.pdf --]
[-- Type: application/pdf, Size: 7133 bytes --]

[-- Attachment #3: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Re[4]: programming for org-mode

[David Maus]

[-- Attachment #1.1: Type: text/plain, Size: 1725 bytes --]

Ivanov Dmitry wrote:
>Thanks, David. I improved the scheme, added 2 question. Please, take a look.

1/

,----
| 09.             (if (or (equal "(" (substring prop 0 1)) (equal "'" (substring prop 0 1)))
|
| vs.
|
| 09.             (if (string-match "^'?(.*)$" prop)
`----

I wouldn't call it a flaw in the original check but a pragmatic
solution for the problem at this point.  Ideally we want to check if
`prop' is a lisp expression so we can call `read' to return the
expression as lisp object.  To achieve this we would need a function
that checks if the string `prop' is a valid s-expression[1]: Balanced
parentheses and valid lisp atoms.  I am not an expert in regular
expressions but I think such a check can't be done with regexps but
requires an implementation of a lisp parser.

Example: (string-match "^'?(.*)$" "((foo baz)")) would return t but
"((foo baz)" is not a valid s-expression.

If we want (read prop) not to fail on an invalid s-exp but to threat
them as strings we can try to catch the error when executing `read':

,----
| (condition-case nil
|     (read prop)
|   (error prop))
`----

This would return the lisp object for `prop' if `prop' is a valid lisp
expression and the string `prop' otherwise (C-h f condition-case RET).

2/

,----
| 13.                 (progn (set-text-properties 0 (length prop) nil prop)
| 14.                        prop)))
`----

Setting the text-properties to nil indeed removes all
... text-properties, including colors.  The `progn' is unnecessary
because the body of the else clause is not limited to one lisp
expression (C-h f if RET).

HTH,
  -- David

[1] Note that the terms "s-expression", "lisp-expression", and "lisp
object" refer to one and the same structure.

[-- Attachment #1.2: Type: application/pgp-signature, Size: 230 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re[6]: programming for org-mode

[Ivanov Dmitry]

[-- Attachment #1.1: Type: text/plain, Size: 1608 bytes --]

I modified the scheme and the function. I think, that these 2 if-s just complicate the code for comprehension: we have 3 cases,
for each of them we should return the appropriate value.

Here is my variant of the function, including the fix, that you suggested:

(defun org-read-prop (prop)
      "Convert the string property PROP to a number if appropriate.
Otherwise if prop looks like a list (meaning it starts with a
'(') then read it as lisp, otherwise return it unmodified as a
string."
      (if (and (stringp prop) (not (equal prop "")))
            (let ((out (string-to-number prop)))
                  (if (equal out 0)
                        (cond
                              ((or
                                     (equal "(" (substring prop 0 1)) 
                                     (equal "'" (substring prop 0 1)))

                                    (condition-case nil
                                          (read prop)
                                          (error prop)))
                              ((string-match "^\\(+0\\|-0\\|0\\)$" prop)
                                    0)
                              (t  
                                    (set-text-properties 0 (length prop) nil prop)
                                    prop))
                        out))
            prop))


All the tests work fine with the new version.
When I tried

(org-read-prop "(1 2 3))") -> (1 2 3)

It gave me (1 2 3), ignoring the last ')'. Seems to be the read function bug.

At last I got rid of these nasty little squares on the scheme :)

[-- Attachment #1.2: Type: text/html, Size: 4603 bytes --]

[-- Attachment #2: org-collector.pdf --]
[-- Type: application/pdf, Size: 6968 bytes --]

[-- Attachment #3: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Re[6]: programming for org-mode

[David Maus]

[-- Attachment #1.1: Type: text/plain, Size: 1262 bytes --]

Ivanov Dmitry wrote:

>I modified the scheme and the function. I think, that these 2 if-s
>just complicate the code for comprehension: we have 3 cases, for each
>of them we should return the appropriate value.

Yes, `cond' is more suitable here.

>All the tests work fine with the new version.
>When I tried

>(org-read-prop "(1 2 3))") -> (1 2 3)

>It gave me (1 2 3), ignoring the last ')'. Seems to be the read
>function bug.

Not sure if it is a bug or the indended behavior.  `read' returns the
first valid lisp expression in finds.  E.g.

(read "(a b c) foo bar") => (a b c)

I think this is good enough at this place.  A complete solutation
would require to parse the entire string.

>At last I got rid of these nasty little squares on the scheme :)

:D

Of course the next step for you would be to tame the beast called git
and prepare a proper patch.  The steps are:

 1. create a topic branch for the fix

 2. change the function, commit to topic branch and provide a proper
    commit message
    (http://orgmode.org/worg/org-contribute.php#sec-4)

 3. create a patch against current master

 4. send the patch manually or using git send-email

Best,
  -- David
--
OpenPGP... 0x99ADB83B5A4478E6
Jabber.... dmjena@jabber.org
Email..... dmaus@ictsoc.de

[-- Attachment #1.2: Type: application/pgp-signature, Size: 230 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode