From de09a9813e239a6d67bae5c1080182371510d36e Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 1 Jul 2009 16:16:30 -0700 Subject: [PATCH 01/13] just getting started --- org-babel.org | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/org-babel.org b/org-babel.org index f9db4e864..f0c5a87d0 100644 --- a/org-babel.org +++ b/org-babel.org @@ -139,7 +139,13 @@ table, allowing the test suite to be run be evaluation of the table and the results to be collected in the same table. *** Emacs initialization files stored in Org-Mode buffers -Once org-babel-tangle is completed this could be a very compelling use case. +Using `org-babel-tangle' it is possible to embed your Emacs +initialization into org-mode files. This allows for folding, +note-taking, todo's etc... embedded with the source-code of your Emacs +initialization, and through org-mode's publishing features aids in +sharing your customizations with others. + +**** my customization ** features From bd5b9dd32f0e3bfdbe57860d75c5118413dc3954 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 5 Jul 2009 12:55:03 -0400 Subject: [PATCH 02/13] another todo: ^[ \t]*#+ --- org-babel.org | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/org-babel.org b/org-babel.org index 743019610..965f8393c 100644 --- a/org-babel.org +++ b/org-babel.org @@ -25,11 +25,10 @@ In this document: - The [[* Sandbox][Sandbox]] :: demonstrates much of the early/basic functionality through commented source-code blocks. -Also see the [[file:library-of-babel.org][Library of Babel]] an extensible collection of ready-made +Also see the [[file:library-of-babel.org][Library of Babel]], an extensible collection of ready-made and easily-shortcut-callable source-code blocks for handling common tasks. - * Introduction Org-Babel enables *communication* between programming languages and @@ -1913,7 +1912,7 @@ This could probably be added to [[file:lisp/org-babel-script.el][org-babel-scrip (see [[* file result types][file result types]]) -* Bugs [17/23] +* Bugs [17/24] ** TODO Allow source blocks to be recognised when #+ are not first characters on the line I think Carsten has recently altered the core so that #+ can have preceding whitespace, at least for literal/code examples. org-babel From 6ade5446745820f957b1d6160fccfea72a6aa6d0 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 5 Jul 2009 19:40:31 -0400 Subject: [PATCH 03/13] Unimportant: output changes in org-babel.org --- org-babel.org | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/org-babel.org b/org-babel.org index 965f8393c..869fb587e 100644 --- a/org-babel.org +++ b/org-babel.org @@ -2645,12 +2645,14 @@ out... table.first.join(" - ") #+end_src -: "1 - 2 - 3" +#+resname: +: 1 - 2 - 3 -#+begin_src python :var table=sandbox :results replace +#+begin_src python :var table=sandbox table[0] #+end_src +#+resname: | 1 | 2 | 3 | #+begin_src ruby :var table=sandbox :results replace From 37569346f82afa31edccc7a8bbbe69a6fcce0dee Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Mon, 6 Jul 2009 19:36:44 -0700 Subject: [PATCH 04/13] stole a couple of moments to add discussion and a new TODO --- org-babel.org | 42 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/org-babel.org b/org-babel.org index 869fb587e..56a6d1b52 100644 --- a/org-babel.org +++ b/org-babel.org @@ -1,5 +1,5 @@ #+TITLE: org-babel --- facilitating communication between programming languages and people -#+SEQ_TODO: TODO PROPOSED STARTED | DONE DEFERRED REJECTED +#+SEQ_TODO: PROPOSED TODO STARTED | DONE DEFERRED REJECTED #+OPTIONS: H:3 num:nil toc:t #+STARTUP: oddeven hideblocks @@ -190,7 +190,7 @@ would then be [[#sandbox][the sandbox]]. #+end_src -* Tasks [27/42] +* Tasks [27/43] ** TODO support for working with =*Org Edit Src Example*= buffers [2/4] *** TODO optionally evaluate header references when we switch to =*Org Edit Src*= buffer That seems to imply that the header references need to be evaluated @@ -322,6 +322,17 @@ languages which almost always produce graphical output should set results in the buffer. Then if there is a combination of =silent= and =file= =:results= headers we could drop the results to a temp buffer and pop open that buffer... +** TODO =\C-c \C-o= to open results of source block +by adding a =defadvice= to =org-open-at-point= we can use the common +=\C-c \C-o= keybinding to open the results of a source-code block. +This would be especially useful for source-code blocks which generate +graphical results and insert a file link as the results in the +org-mode buffer. (see [[* figure out how to handle graphic output][TODO figure out how to handle graphic output]]). +This could also act reasonably with other results types... + +- file :: use org-open-at-point to open the file +- scalar :: open results unquoted in a new buffer +- tabular :: export the table to a new buffer and open that buffer ** TODO Finalise behaviour regarding vector/scalar output *** DONE Stop spaces causing vector output @@ -1912,20 +1923,18 @@ This could probably be added to [[file:lisp/org-babel-script.el][org-babel-scrip (see [[* file result types][file result types]]) -* Bugs [17/24] +* Bugs [17/23] ** TODO Allow source blocks to be recognised when #+ are not first characters on the line I think Carsten has recently altered the core so that #+ can have preceding whitespace, at least for literal/code examples. org-babel should support this. -** PROPOSED make :results replace the default? +** TODO make :results replace the default? I'm tending to think that appending results to pre-existing results creates mess, and that the cleaner `replace' option should be the default. E.g. when a source block creates an image, we would want that to be updated, rather than have a new one be added. -** PROPOSED external shell execution can't isolate return values -I have no idea how to do this as of yet. The result is that when -shell functions are run w/o a session there is no difference between -the =output= and =value= result arguments. + + I agree. ** TODO non-orgtbl formatted lists for example @@ -1958,6 +1967,23 @@ even a third" E.g. the pie chart example. Despite the save-window-excursion in org-babel-execute:R. (I never learned how to do this properly: org-R jumps all over the place...) + +** PROPOSED external shell execution can't isolate return values +I have no idea how to do this as of yet. The result is that when +shell functions are run w/o a session there is no difference between +the =output= and =value= result arguments. + +Yea, I don't know how to do this either. I searched extensively on +how to isolate the *last* output of a series of shell commands (see +[[* last command for + shells][last command for shells]]). The results of the search were basically +that it was not possible (or at least not accomplish-able with a +reasonable amount of effort). + +That fact combined with the tenancy to all ways use standard out in +shell scripts led me to treat these two options (=output= and =value=) +as identical in shell evaluation. Not ideal but maybe good enough for +the moment. ** DEFERRED weird escaped characters in shell prompt break shell evaluation E.g. this doesn't work. Should the shell sessions set a sane prompt From 4137ceb426d48625a284b17669598705c13ef2c7 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Wed, 8 Jul 2009 00:28:45 -0400 Subject: [PATCH 05/13] A few notes and a completed TODO --- org-babel.org | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/org-babel.org b/org-babel.org index 56a6d1b52..98917767e 100644 --- a/org-babel.org +++ b/org-babel.org @@ -1923,18 +1923,11 @@ This could probably be added to [[file:lisp/org-babel-script.el][org-babel-scrip (see [[* file result types][file result types]]) -* Bugs [17/23] +* Bugs [18/23] ** TODO Allow source blocks to be recognised when #+ are not first characters on the line I think Carsten has recently altered the core so that #+ can have preceding whitespace, at least for literal/code examples. org-babel should support this. -** TODO make :results replace the default? - I'm tending to think that appending results to pre-existing results - creates mess, and that the cleaner `replace' option should be the - default. E.g. when a source block creates an image, we would want - that to be updated, rather than have a new one be added. - - I agree. ** TODO non-orgtbl formatted lists for example @@ -1946,10 +1939,11 @@ for example #+resname: this-doesn't-match-orgtbl + ** TODO collapsing consecutive newlines in string output #+srcname: multi-line-string-output -#+begin_src ruby :results replace +#+begin_src ruby :results output "the first line ends here @@ -1958,10 +1952,8 @@ for example even a third" #+end_src -#+resname: -: the first line ends here -: and this is the second one -: return even a third +#+resname: multi-line-string-output + ** TODO cursor movement when evaluating source blocks E.g. the pie chart example. Despite the save-window-excursion in @@ -1985,6 +1977,11 @@ shell scripts led me to treat these two options (=output= and =value=) as identical in shell evaluation. Not ideal but maybe good enough for the moment. +In the `results' branch I've changed this so that they're not quite +identical: output results in raw stdout contents, whereas value +converts it to elisp, perhaps to a table if it looks tabular. This is +the same for the other languages. [Dan] + ** DEFERRED weird escaped characters in shell prompt break shell evaluation E.g. this doesn't work. Should the shell sessions set a sane prompt when they start up? Or is it a question of altering @@ -2013,6 +2010,13 @@ the moment. the user's regular emacs init. I can't think of a way for us to set this automatically, and we are SOL without a regexp to match the prompt. +** DONE make :results replace the default? + I'm tending to think that appending results to pre-existing results + creates mess, and that the cleaner `replace' option should be the + default. E.g. when a source block creates an image, we would want + that to be updated, rather than have a new one be added. + + I agree. ** DONE ruby evaluation not working under ubuntu emacs 23 With emacs 23.0.91.1 on ubuntu, for C-h f run-ruby I have the following, which seems to conflict with [[file:lisp/langs/org-babel-ruby.el::let%20session%20buffer%20save%20window%20excursion%20run%20ruby%20nil%20session%20current%20buffer][this line]] in org-babel-ruby.el. From 8694253c9fd44586ad2308d2ef6ac63bc4d8cf5b Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Wed, 1 Jul 2009 16:16:30 -0700 Subject: [PATCH 06/13] getting started on automatic loading of elisp from org-mode files --- lisp/org-babel-tangle.el | 8 +- org-babel.org | 228 ++++++++++++++++++++++++--------------- 2 files changed, 146 insertions(+), 90 deletions(-) diff --git a/lisp/org-babel-tangle.el b/lisp/org-babel-tangle.el index 58a98a4d7..a33849594 100644 --- a/lisp/org-babel-tangle.el +++ b/lisp/org-babel-tangle.el @@ -39,7 +39,7 @@ and shebang(#!) line to use when writing out the language to file.") (defun org-babel-tangle () - "Extract the bodies of all source code blocks form the current + "Extract the bodies of all source code blocks from the current file into their own source-specific files." (interactive) (save-excursion @@ -57,13 +57,15 @@ file into their own source-specific files." (with-temp-file filename (funcall lang-f) (when she-bang (insert (concat she-bang "\n"))) - (comment-region (point) (progn (insert "generated by org-babel-tangle") (point))) + (comment-region + (point) (progn (insert "generated by org-babel-tangle") (point))) (mapc #'org-babel-spec-to-string (reverse specs))))) ;; if there are multiple sessions then break out by session (if (> (length by-session) 1) (mapc (lambda (session-pair) (setq block-counter (+ block-counter (length (cdr session-pair)))) - (to-file (format "%s-%s.%s" base-name (car session-pair) ext) (cdr session-pair))) + (to-file (format + "%s-%s.%s" base-name (car session-pair) ext) (cdr session-pair))) by-session) (setq block-counter (+ block-counter (length (cdr (car by-session))))) (to-file (format "%s.%s" base-name ext) (cdr (car by-session))))))) diff --git a/org-babel.org b/org-babel.org index f9db4e864..d93b15512 100644 --- a/org-babel.org +++ b/org-babel.org @@ -1,5 +1,5 @@ #+TITLE: org-babel --- facilitating communication between programming languages and people -#+SEQ_TODO: TODO PROPOSED | DONE DEFERRED REJECTED +#+SEQ_TODO: PROPOSED TODO STARTED | DONE DEFERRED REJECTED #+OPTIONS: H:3 num:nil toc:t #+STARTUP: oddeven hideblocks @@ -25,11 +25,10 @@ In this document: - The [[* Sandbox][Sandbox]] :: demonstrates much of the early/basic functionality through commented source-code blocks. -Also see the [[file:library-of-babel.org][Library of Babel]] an extensible collection of ready-made +Also see the [[file:library-of-babel.org][Library of Babel]], an extensible collection of ready-made and easily-shortcut-callable source-code blocks for handling common tasks. - * Introduction Org-Babel enables *communication* between programming languages and @@ -139,7 +138,13 @@ table, allowing the test suite to be run be evaluation of the table and the results to be collected in the same table. *** Emacs initialization files stored in Org-Mode buffers -Once org-babel-tangle is completed this could be a very compelling use case. +Using `org-babel-tangle' it is possible to embed your Emacs +initialization into org-mode files. This allows for folding, +note-taking, todo's etc... embedded with the source-code of your Emacs +initialization, and through org-mode's publishing features aids in +sharing your customizations with others. + +**** my customization ** features @@ -191,8 +196,35 @@ would then be [[#sandbox][the sandbox]]. #+end_src -* Tasks [27/42] -** TODO support for working with =*Org Edit Src Example*= buffers [1/4] +* Tasks [27/43] +** TODO support for working with =*Org Edit Src Example*= buffers [2/4] +*** TODO optionally evaluate header references when we switch to =*Org Edit Src*= buffer +That seems to imply that the header references need to be evaluated +and transformed into the target language object when we hit C-c ' to +enter the *Org Edit Src* buffer [DED] + +Good point, I heartily agree that this should be supported [Eric] + +(or at least before the first time we attempt to evaluate code in that +buffer -- I suppose there might be an argument for lazy evaluation, in +case someone hits C-c ' but is "just looking" and not actually +evaluating anything.) Of course if evaluating the reference is +computationally intensive then the user might have to wait before they +get the *Org Edit Src* buffer. [DED] + +I fear that it may be hard to anticipate when the references will be +needed, some major-modes do on-the-fly evaluation while the buffer is +being edited. I think that we should either do this before the buffer +is opened or not at all, specifically I think we should resolve +references if the user calls C-c ' with a prefix argument. Does that +sound reasonable? [Eric] + +Yes [Dan] + +[Dan] So now that we have org-src-mode and org-src-mode-hook, I guess +org-babel should do this by using the hook to make sure that, when C-c +C-' is issued on a source block, any references are resolved and +assignments are made in the appropriate session. *** TODO set buffer-local-process variables appropriately [DED] I think something like this would be great. You've probably already thought of this, but just to note it down: it would be really @@ -207,8 +239,19 @@ I had not thought of that, but I agree whole heartedly. [Eric] Once this is done every variable should be able to dump regions into their inferior-process buffer using major-mode functions. +*** DEFERRED send code to inferior process +Another thought on this topic: I think we will want users to send +chunks of code to the interpreter from within the *Org Edit Src* +buffer, and I think that's what you have in mind already. In ESS that +is done using the ess-eval-* functions. [DED] -*** TODO some possible requests/proposed changes for Carsten [2/3] +I think we can leave this up to the major-mode in the source code +buffer, as almost every source-code major mode will have functions for +doing things like sending regions to the inferior process. If +anything we might need to set the value of the buffer local inferior +process variable. [Eric] + +*** DONE some possible requests/proposed changes for Carsten [4/4] While I remember, some possible requests/proposed changes for Carsten come to mind in that regard: @@ -232,7 +275,8 @@ buffer." I think this is great, but I think it should be implemented in the org-mode core -**** TODO Rename buffer and minor mode? + +**** DEFERRED Rename buffer and minor mode? Something shorter than *Org Edit Src Example* for the buffer name. org-babel is bringing org's source code interaction to a level of maturity where the 'example' is no longer @@ -253,45 +297,10 @@ org-mode core perhaps we will also have more functionality to add to that minor mode, making it even more of a misnomer. Perhaps something like org-src-mode would be better. - -**** DEFERRED a hook called when the src edit buffer is created -This should be implemented in the org-mode core +**** DONE Changed minor mode name and added hooks - -*** DEFERRED send code to inferior process -Another thought on this topic: I think we will want users to send -chunks of code to the interpreter from within the *Org Edit Src* -buffer, and I think that's what you have in mind already. In ESS that -is done using the ess-eval-* functions. [DED] - -I think we can leave this up to the major-mode in the source code -buffer, as almost every source-code major mode will have functions for -doing things like sending regions to the inferior process. If -anything we might need to set the value of the buffer local inferior -process variable. [Eric] - -*** TODO optionally evaluate header references when we switch to =*Org Edit Src*= buffer -That seems to imply that the header references need to be evaluated -and transformed into the target language object when we hit C-c ' to -enter the *Org Edit Src* buffer [DED] - -Good point, I heartily agree that this should be supported [Eric] - -(or at least before the first time we attempt to evaluate code in that -buffer -- I suppose there might be an argument for lazy evaluation, in -case someone hits C-c ' but is "just looking" and not actually -evaluating anything.) Of course if evaluating the reference is -computationally intensive then the user might have to wait before they -get the *Org Edit Src* buffer. [DED] - -I fear that it may be hard to anticipate when the references will be -needed, some major-modes do on-the-fly evaluation while the buffer is -being edited. I think that we should either do this before the buffer -is opened or not at all, specifically I think we should resolve -references if the user calls C-c ' with a prefix argument. Does that -sound reasonable? [Eric] - -Yes [Dan] +**** DEFERRED a hook called when the src edit buffer is created + This should be implemented in the org-mode core ** TODO resolve references to other org buffers/files This would allow source blocks to call upon tables, source-blocks, @@ -319,6 +328,17 @@ languages which almost always produce graphical output should set results in the buffer. Then if there is a combination of =silent= and =file= =:results= headers we could drop the results to a temp buffer and pop open that buffer... +** TODO =\C-c \C-o= to open results of source block +by adding a =defadvice= to =org-open-at-point= we can use the common +=\C-c \C-o= keybinding to open the results of a source-code block. +This would be especially useful for source-code blocks which generate +graphical results and insert a file link as the results in the +org-mode buffer. (see [[* figure out how to handle graphic output][TODO figure out how to handle graphic output]]). +This could also act reasonably with other results types... + +- file :: use org-open-at-point to open the file +- scalar :: open results unquoted in a new buffer +- tabular :: export the table to a new buffer and open that buffer ** TODO Finalise behaviour regarding vector/scalar output *** DONE Stop spaces causing vector output @@ -343,12 +363,13 @@ msg + " y python" #+begin_src emacs-lisp :var msg="org-babel speaks" (concat msg " elisp") #+end_src -** TODO share org-babel +** STARTED share org-babel [1/4] how should we share org-babel? -- post to org-mode and ess mailing lists -- create a org-babel page on worg -- create a short screencast demonstrating org-babel in action +*** DONE post to org-mode +*** TODO post to ess mailing list +*** TODO create a org-babel page on worg +*** TODO create a short screencast demonstrating org-babel in action *** examples we need to think up some good examples @@ -1908,13 +1929,66 @@ This could probably be added to [[file:lisp/org-babel-script.el][org-babel-scrip (see [[* file result types][file result types]]) -* Bugs [16/21] +* Bugs [18/23] +** TODO Allow source blocks to be recognised when #+ are not first characters on the line + I think Carsten has recently altered the core so that #+ can have + preceding whitespace, at least for literal/code examples. org-babel + should support this. + +** TODO non-orgtbl formatted lists +for example + +#+srcname: this-doesn't-match-orgtbl +#+begin_src emacs-lisp :results replace +'((:results . "replace")) +#+end_src + +#+resname: this-doesn't-match-orgtbl + + +** TODO collapsing consecutive newlines in string output + +#+srcname: multi-line-string-output +#+begin_src ruby :results output +"the first line ends here + + + and this is the second one + +even a third" +#+end_src + +#+resname: multi-line-string-output + + +** TODO cursor movement when evaluating source blocks + E.g. the pie chart example. Despite the save-window-excursion in + org-babel-execute:R. (I never learned how to do this properly: org-R + jumps all over the place...) + ** PROPOSED external shell execution can't isolate return values I have no idea how to do this as of yet. The result is that when shell functions are run w/o a session there is no difference between the =output= and =value= result arguments. -** TODO weird escaped characters in shell prompt break shell evaluation +Yea, I don't know how to do this either. I searched extensively on +how to isolate the *last* output of a series of shell commands (see +[[* last command for + shells][last command for shells]]). The results of the search were basically +that it was not possible (or at least not accomplish-able with a +reasonable amount of effort). + +That fact combined with the tenancy to all ways use standard out in +shell scripts led me to treat these two options (=output= and =value=) +as identical in shell evaluation. Not ideal but maybe good enough for +the moment. + +In the `results' branch I've changed this so that they're not quite +identical: output results in raw stdout contents, whereas value +converts it to elisp, perhaps to a table if it looks tabular. This is +the same for the other languages. [Dan] + +** DEFERRED weird escaped characters in shell prompt break shell evaluation E.g. this doesn't work. Should the shell sessions set a sane prompt when they start up? Or is it a question of altering comint-prompt-regexp? Or altering org-babel regexps? @@ -1942,38 +2016,13 @@ the =output= and =value= result arguments. the user's regular emacs init. I can't think of a way for us to set this automatically, and we are SOL without a regexp to match the prompt. - -** TODO non-orgtbl formatted lists -for example - -#+srcname: this-doesn't-match-orgtbl -#+begin_src emacs-lisp :results replace -'((:results . "replace")) -#+end_src - -#+resname: this-doesn't-match-orgtbl - -** TODO collapsing consecutive newlines in string output - -#+srcname: multi-line-string-output -#+begin_src ruby :results replace -"the first line ends here - - - and this is the second one - -even a third" -#+end_src - -#+resname: -: the first line ends here -: and this is the second one -: return even a third - -** TODO cursor movement when evaluating source blocks - E.g. the pie chart example. Despite the save-window-excursion in - org-babel-execute:R. (I never learned how to do this properly: org-R - jumps all over the place...) +** DONE make :results replace the default? + I'm tending to think that appending results to pre-existing results + creates mess, and that the cleaner `replace' option should be the + default. E.g. when a source block creates an image, we would want + that to be updated, rather than have a new one be added. + + I agree. ** DONE ruby evaluation not working under ubuntu emacs 23 With emacs 23.0.91.1 on ubuntu, for C-h f run-ruby I have the following, which seems to conflict with [[file:lisp/langs/org-babel-ruby.el::let%20session%20buffer%20save%20window%20excursion%20run%20ruby%20nil%20session%20current%20buffer][this line]] in org-babel-ruby.el. @@ -2157,7 +2206,7 @@ mean(mean(table)) mean(table) #+end_src -** DEFERRED org bug/request: prevent certain org behaviour within code blocks +** DONE org bug/request: prevent certain org behaviour within code blocks E.g. [[]] gets recognised as a link (when there's text inside the brackets). This is bad for R code at least, and more generally could be argued to be inappropriate. Is it difficult to get org to @@ -2166,6 +2215,9 @@ mean(table) I believe Carsten addressed this recently on the mailing list with the comment that it was indeed a difficult issue. I believe this may be one area where we could wait for an upstream (org-mode) fix. + + [Dan] Carsten has fixed this now in the core. + ** DONE with :results replace, non-table output doesn't replace table output And vice versa. E.g. Try this first with table and then with len(table) [DED] #+begin_src python :var table=sandbox :results replace @@ -2629,12 +2681,14 @@ out... table.first.join(" - ") #+end_src -: "1 - 2 - 3" +#+resname: +: 1 - 2 - 3 -#+begin_src python :var table=sandbox :results replace +#+begin_src python :var table=sandbox table[0] #+end_src +#+resname: | 1 | 2 | 3 | #+begin_src ruby :var table=sandbox :results replace From 92f979cc88efa90b1f1036dbe291616cab4151f1 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Tue, 14 Jul 2009 18:08:04 -0700 Subject: [PATCH 07/13] fleshing out documentation for automatic tangling and loading of elisp --- org-babel.org | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/org-babel.org b/org-babel.org index d93b15512..e6a01b978 100644 --- a/org-babel.org +++ b/org-babel.org @@ -144,7 +144,10 @@ note-taking, todo's etc... embedded with the source-code of your Emacs initialization, and through org-mode's publishing features aids in sharing your customizations with others. -**** my customization +It may be worthwhile to create a fork of Phil Hagelberg's +[[http://github.com/technomancy/emacs-starter-kit/tree/master][emacs-starter-kit]] which uses literate org-mode files for all of the +actual elisp customization. These org-mode files could then be +exported to html and used to populate the repositories wiki on [[http://github.com/][github]]. ** features @@ -196,7 +199,17 @@ would then be [[#sandbox][the sandbox]]. #+end_src -* Tasks [27/43] +* Tasks [27/44] +** TODO singe-function tangling and loading elisp from literate org-mode file [0/2] + +This function should tangle the org-mode file for elisp, and then call +`load-file' on the resulting tangled file. + +*** TODO add optional language limiter to org-babel-tangle +This should check to see if there is any need to re-export + +*** TODO ensure that org-babel-tangle returns the path to the tangled file(s) + ** TODO support for working with =*Org Edit Src Example*= buffers [2/4] *** TODO optionally evaluate header references when we switch to =*Org Edit Src*= buffer That seems to imply that the header references need to be evaluated From c3166dc09335d4c9b4ea87ad53f7a32a01bc80c4 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Tue, 14 Jul 2009 18:26:15 -0700 Subject: [PATCH 08/13] now able to tangle files by language --- lisp/org-babel-tangle.el | 41 +++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/lisp/org-babel-tangle.el b/lisp/org-babel-tangle.el index a33849594..b1777d1c5 100644 --- a/lisp/org-babel-tangle.el +++ b/lisp/org-babel-tangle.el @@ -38,9 +38,17 @@ language, and the cdr should be a list containing the extension and shebang(#!) line to use when writing out the language to file.") -(defun org-babel-tangle () +(defun org-babel-tangle-file (file &optional lang) + "Extract the bodies of all source code blocks in FILE with +`org-babel-tangle'. Optional argument LANG can be used to limit +the exported source code blocks by language." + (save-window-excursion (find-file file) (org-babel-tangle lang))) + +(defun org-babel-tangle (&optional lang) "Extract the bodies of all source code blocks from the current -file into their own source-specific files." +file into their own source-specific files. Optional argument +LANG can be used to limit the exported source code blocks by +language." (interactive) (save-excursion (let ((base-name (file-name-sans-extension (buffer-file-name))) @@ -69,14 +77,16 @@ file into their own source-specific files." by-session) (setq block-counter (+ block-counter (length (cdr (car by-session))))) (to-file (format "%s.%s" base-name ext) (cdr (car by-session))))))) - (org-babel-collect-blocks)) + (org-babel-collect-blocks lang)) (message "tangled %d source-code blocks" block-counter)))) -(defun org-babel-collect-blocks () +(defun org-babel-collect-blocks (&optional lang) "Collect all source blocks in the current org-mode file. Return two nested association lists, first grouped by language, then by session, the contents will be source-code block -specifications of the form used by `org-babel-spec-to-string'." +specifications of the form used by `org-babel-spec-to-string'. +Optional argument LANG can be used to limit the collected source +code blocks by language." (let ((block-counter 0) blocks) (org-babel-map-source-blocks (buffer-file-name) (setq block-counter (+ 1 block-counter)) @@ -85,21 +95,22 @@ specifications of the form used by `org-babel-spec-to-string'." (source-name (intern (or (org-babel-get-src-block-name) (format "block-%d" block-counter)))) (info (org-babel-get-src-block-info)) - (lang (first info)) + (src-lang (first info)) (body (second info)) (params (third info)) (spec (list link source-name params body)) (session (cdr (assoc :session params))) by-lang by-session) - ;; add the spec for this block to blocks under it's lang and session - (setq by-lang (cdr (assoc lang blocks))) - (setq blocks (delq (assoc lang blocks) blocks)) - (setq by-session (cdr (assoc session by-lang))) - (setq by-lang (delq (assoc session by-lang) by-lang)) - (setq blocks (cons ;; by-language - (cons lang (cons ;; by-session - (cons session (cons spec by-session)) by-lang)) - blocks)))) + (unless (and lang (not (string= lang src-lang))) ;; maybe limit by language + ;; add the spec for this block to blocks under it's language and session + (setq by-lang (cdr (assoc src-lang blocks))) + (setq blocks (delq (assoc src-lang blocks) blocks)) + (setq by-session (cdr (assoc session by-lang))) + (setq by-lang (delq (assoc session by-lang) by-lang)) + (setq blocks (cons ;; by-language + (cons src-lang (cons ;; by-session + (cons session (cons spec by-session)) by-lang)) + blocks))))) ;; blocks should contain all source-blocks organized by language and session ;; (message "blocks=%S" blocks) ;; debugging blocks)) From 07c919cb31f6d5e0a67176de6720309594f14da9 Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Tue, 14 Jul 2009 18:29:28 -0700 Subject: [PATCH 09/13] fleshing out actual loading of tangled files --- lisp/org-babel-tangle.el | 7 +++++++ org-babel.org | 4 ++-- test-tangle.org | 10 ++++++++++ 3 files changed, 19 insertions(+), 2 deletions(-) diff --git a/lisp/org-babel-tangle.el b/lisp/org-babel-tangle.el index b1777d1c5..f627e7e10 100644 --- a/lisp/org-babel-tangle.el +++ b/lisp/org-babel-tangle.el @@ -38,6 +38,13 @@ language, and the cdr should be a list containing the extension and shebang(#!) line to use when writing out the language to file.") +(defun org-babel-load-file (file) + "Load the contents of the Emacs Lisp source code blocks in +FILE. This function will first export the source code using +`org-babel-tangle' and then load the resulting file using +`load-file'." + (load-file (org-babel-tangle-file "emacs-lisp"))) + (defun org-babel-tangle-file (file &optional lang) "Extract the bodies of all source code blocks in FILE with `org-babel-tangle'. Optional argument LANG can be used to limit diff --git a/org-babel.org b/org-babel.org index e6a01b978..c06335081 100644 --- a/org-babel.org +++ b/org-babel.org @@ -200,12 +200,12 @@ would then be [[#sandbox][the sandbox]]. * Tasks [27/44] -** TODO singe-function tangling and loading elisp from literate org-mode file [0/2] +** TODO singe-function tangling and loading elisp from literate org-mode file [1/2] This function should tangle the org-mode file for elisp, and then call `load-file' on the resulting tangled file. -*** TODO add optional language limiter to org-babel-tangle +*** DONE add optional language limiter to org-babel-tangle This should check to see if there is any need to re-export *** TODO ensure that org-babel-tangle returns the path to the tangled file(s) diff --git a/test-tangle.org b/test-tangle.org index b8e965996..7f7ee2795 100644 --- a/test-tangle.org +++ b/test-tangle.org @@ -76,3 +76,13 @@ end #+begin_src ruby :session special plus_two(holder) #+end_src + + +** Emacs Lisp initialization stuff + +#+srcname: lets-set-some-variables +#+begin_src emacs-lisp + (setq test-tangle-loading "org-babel tangles") + (setq test-tangle-advert "use org-babel-tangle for all your emacs initialization files!!") + (setq test-tangle-file-path (expand-file-name (buffer-file-name))) +#+end_src From cdd73500d6b65db484ac663719afaded030fd17f Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Tue, 14 Jul 2009 18:37:47 -0700 Subject: [PATCH 10/13] DONE ensure that org-babel-tangle returns the path to the tangled file(s) --- lisp/org-babel-tangle.el | 17 ++++++++++------- org-babel.org | 13 +++++++++++-- 2 files changed, 21 insertions(+), 9 deletions(-) diff --git a/lisp/org-babel-tangle.el b/lisp/org-babel-tangle.el index f627e7e10..ff212a10d 100644 --- a/lisp/org-babel-tangle.el +++ b/lisp/org-babel-tangle.el @@ -39,11 +39,11 @@ and shebang(#!) line to use when writing out the language to file.") (defun org-babel-load-file (file) - "Load the contents of the Emacs Lisp source code blocks in -FILE. This function will first export the source code using -`org-babel-tangle' and then load the resulting file using -`load-file'." - (load-file (org-babel-tangle-file "emacs-lisp"))) + "Load the contents of the Emacs Lisp source code blocks in the +org-mode formatted FILE. This function will first export the +source code using `org-babel-tangle' and then load the resulting +file using `load-file'." + (mapc #'load-file (org-babel-tangle-file "emacs-lisp"))) (defun org-babel-tangle-file (file &optional lang) "Extract the bodies of all source code blocks in FILE with @@ -59,7 +59,8 @@ language." (interactive) (save-excursion (let ((base-name (file-name-sans-extension (buffer-file-name))) - (block-counter 0)) + (block-counter 0) + path-collector) (mapc ;; for every language create a file (lambda (by-lang) (let* ((lang (car by-lang)) @@ -69,6 +70,7 @@ language." (she-bang (second lang-specs)) (by-session (cdr by-lang))) (flet ((to-file (filename specs) + (add-to-list 'path-collector filename) (with-temp-file filename (funcall lang-f) (when she-bang (insert (concat she-bang "\n"))) @@ -85,7 +87,8 @@ language." (setq block-counter (+ block-counter (length (cdr (car by-session))))) (to-file (format "%s.%s" base-name ext) (cdr (car by-session))))))) (org-babel-collect-blocks lang)) - (message "tangled %d source-code blocks" block-counter)))) + (message "tangled %d source-code blocks" block-counter) + path-collector))) (defun org-babel-collect-blocks (&optional lang) "Collect all source blocks in the current org-mode file. diff --git a/org-babel.org b/org-babel.org index c06335081..f5097dd6d 100644 --- a/org-babel.org +++ b/org-babel.org @@ -200,7 +200,7 @@ would then be [[#sandbox][the sandbox]]. * Tasks [27/44] -** TODO singe-function tangling and loading elisp from literate org-mode file [1/2] +** TODO singe-function tangling and loading elisp from literate org-mode file [2/2] This function should tangle the org-mode file for elisp, and then call `load-file' on the resulting tangled file. @@ -208,7 +208,16 @@ This function should tangle the org-mode file for elisp, and then call *** DONE add optional language limiter to org-babel-tangle This should check to see if there is any need to re-export -*** TODO ensure that org-babel-tangle returns the path to the tangled file(s) +*** DONE ensure that org-babel-tangle returns the path to the tangled file(s) + +#+srcname: test-return-value-of-org-babel-tangle +#+begin_src emacs-lisp + (mapcar #'file-name-nondirectory (org-babel-tangle-file "test-tangle.org" "emacs-lisp")) +#+end_src + +#+resname: +| "test-tangle.el" | + ** TODO support for working with =*Org Edit Src Example*= buffers [2/4] *** TODO optionally evaluate header references when we switch to =*Org Edit Src*= buffer From 77c7fc81cc8689b82020680fc2cf29fdbb08b07c Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Tue, 14 Jul 2009 18:43:45 -0700 Subject: [PATCH 11/13] flesh out org-babel-load-file task statement --- org-babel.org | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/org-babel.org b/org-babel.org index f5097dd6d..f6c2342e2 100644 --- a/org-babel.org +++ b/org-babel.org @@ -200,24 +200,32 @@ would then be [[#sandbox][the sandbox]]. * Tasks [27/44] -** TODO singe-function tangling and loading elisp from literate org-mode file [2/2] +** TODO singe-function tangling and loading elisp from literate org-mode file [2/3] This function should tangle the org-mode file for elisp, and then call `load-file' on the resulting tangled file. +#+srcname: test-loading-embedded-emacs-lisp +#+begin_src emacs-lisp + (org-babel-load-file "test-tangle.org") + (list test-tangle-loading test-tangle-advert) +#+end_src + *** DONE add optional language limiter to org-babel-tangle This should check to see if there is any need to re-export *** DONE ensure that org-babel-tangle returns the path to the tangled file(s) #+srcname: test-return-value-of-org-babel-tangle -#+begin_src emacs-lisp +#+begin_src emacs-lisp :results replace (mapcar #'file-name-nondirectory (org-babel-tangle-file "test-tangle.org" "emacs-lisp")) #+end_src #+resname: | "test-tangle.el" | +*** TODO only tangle the file if it's actually necessary +compare the ages of the files ** TODO support for working with =*Org Edit Src Example*= buffers [2/4] *** TODO optionally evaluate header references when we switch to =*Org Edit Src*= buffer From d37d148d3f029dcd44c49151e08334b8e18ee22f Mon Sep 17 00:00:00 2001 From: Eric Schulte Date: Tue, 14 Jul 2009 20:16:51 -0700 Subject: [PATCH 12/13] DONE singe-function tangling and loading elisp from literate org-mode file [3/3] --- lisp/org-babel-tangle.el | 17 +++++++++-- org-babel.org | 64 ++++++++++++++++++++++------------------ test-tangle.org | 1 - 3 files changed, 51 insertions(+), 31 deletions(-) diff --git a/lisp/org-babel-tangle.el b/lisp/org-babel-tangle.el index ff212a10d..8115e46e1 100644 --- a/lisp/org-babel-tangle.el +++ b/lisp/org-babel-tangle.el @@ -43,13 +43,26 @@ file.") org-mode formatted FILE. This function will first export the source code using `org-babel-tangle' and then load the resulting file using `load-file'." - (mapc #'load-file (org-babel-tangle-file "emacs-lisp"))) + (let ((loadable-file (first (org-babel-tangle-file file "emacs-lisp")))) + (message "loading %s" loadable-file) + (unless (file-exists-p loadable-file) + (error "can't load file that doesn't exist")) + (load-file loadable-file) + (message "loaded %s" loadable-file))) (defun org-babel-tangle-file (file &optional lang) "Extract the bodies of all source code blocks in FILE with `org-babel-tangle'. Optional argument LANG can be used to limit the exported source code blocks by language." - (save-window-excursion (find-file file) (org-babel-tangle lang))) + (flet ((age (file) + (time-to-seconds + (time-subtract (current-time) + (sixth (file-attributes file)))))) + (let ((target-file (concat (file-name-sans-extension file) "." + (second (assoc lang org-babel-tangle-langs))))) + (if (and lang (file-exists-p target-file) (> (age file) (age target-file))) + (list target-file) + (save-window-excursion (find-file file) (org-babel-tangle lang)))))) (defun org-babel-tangle (&optional lang) "Extract the bodies of all source code blocks from the current diff --git a/org-babel.org b/org-babel.org index f6c2342e2..bf6233bf3 100644 --- a/org-babel.org +++ b/org-babel.org @@ -199,34 +199,7 @@ would then be [[#sandbox][the sandbox]]. #+end_src -* Tasks [27/44] -** TODO singe-function tangling and loading elisp from literate org-mode file [2/3] - -This function should tangle the org-mode file for elisp, and then call -`load-file' on the resulting tangled file. - -#+srcname: test-loading-embedded-emacs-lisp -#+begin_src emacs-lisp - (org-babel-load-file "test-tangle.org") - (list test-tangle-loading test-tangle-advert) -#+end_src - -*** DONE add optional language limiter to org-babel-tangle -This should check to see if there is any need to re-export - -*** DONE ensure that org-babel-tangle returns the path to the tangled file(s) - -#+srcname: test-return-value-of-org-babel-tangle -#+begin_src emacs-lisp :results replace - (mapcar #'file-name-nondirectory (org-babel-tangle-file "test-tangle.org" "emacs-lisp")) -#+end_src - -#+resname: -| "test-tangle.el" | - -*** TODO only tangle the file if it's actually necessary -compare the ages of the files - +* Tasks [28/44] ** TODO support for working with =*Org Edit Src Example*= buffers [2/4] *** TODO optionally evaluate header references when we switch to =*Org Edit Src*= buffer That seems to imply that the header references need to be evaluated @@ -870,6 +843,41 @@ $0 [[file:snippets/org-mode/sb][sb -- snippet]] waiting for guidance from those more familiar with yasnippets +** DONE singe-function tangling and loading elisp from literate org-mode file [3/3] + +This function should tangle the org-mode file for elisp, and then call +`load-file' on the resulting tangled file. + +#+srcname: test-loading-embedded-emacs-lisp +#+begin_src emacs-lisp :results replace + (setq test-tangle-advert nil) + (setq test-tangle-loading nil) + (setq results (list :before test-tangle-loading test-tangle-advert)) + (org-babel-load-file "test-tangle.org") + (setq results (list (list :after test-tangle-loading test-tangle-advert) results)) + (delete-file "test-tangle.el") + (reverse results) +#+end_src + +#+resname: test-loading-embedded-emacs-lisp +| :before | nil | nil | +| :after | "org-babel tangles" | "use org-babel-tangle for all your emacs initialization files!!" | + +*** DONE add optional language limiter to org-babel-tangle +This should check to see if there is any need to re-export + +*** DONE ensure that org-babel-tangle returns the path to the tangled file(s) + +#+srcname: test-return-value-of-org-babel-tangle +#+begin_src emacs-lisp :results replace + (mapcar #'file-name-nondirectory (org-babel-tangle-file "test-tangle.org" "emacs-lisp")) +#+end_src + +#+resname: +| "test-tangle.el" | + +*** DONE only tangle the file if it's actually necessary +compare the ages of the files ** DONE add a function to jump to a source-block by name I've had an initial stab at that in org-babel-find-named-block (library-of-babel branch). diff --git a/test-tangle.org b/test-tangle.org index 7f7ee2795..2f08f109b 100644 --- a/test-tangle.org +++ b/test-tangle.org @@ -84,5 +84,4 @@ plus_two(holder) #+begin_src emacs-lisp (setq test-tangle-loading "org-babel tangles") (setq test-tangle-advert "use org-babel-tangle for all your emacs initialization files!!") - (setq test-tangle-file-path (expand-file-name (buffer-file-name))) #+end_src From ad57e15afe3bb448d396a94b7f44f42b6efbee31 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sat, 11 Jul 2009 22:45:57 -0400 Subject: [PATCH 13/13] Bugfix in org-babel-read (relevant to all branches). I haven't managed to see why this is a 2. It breaks if cell is a string of length 1. I'm changing it to a 1 (as it is in org-collector.el), on the assumption that the 2 was erroneous. --- lisp/org-babel.el | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lisp/org-babel.el b/lisp/org-babel.el index dba933112..8b3572909 100644 --- a/lisp/org-babel.el +++ b/lisp/org-babel.el @@ -414,15 +414,15 @@ non-nil." (defun org-babel-read (cell) "Convert the string value of CELL to a number if appropriate. -Otherwise if cell looks like a list (meaning it starts with a -'(') then read it as lisp, otherwise return it unmodified as a -string. +Otherwise if cell looks like lisp (meaning it starts with a +\"(\" or a \"'\") then read it as lisp, otherwise return it +unmodified as a string. This is taken almost directly from `org-read-prop'." (if (and (stringp cell) (not (equal cell ""))) (or (org-babel-number-p cell) (if (or (equal "(" (substring cell 0 1)) - (equal "'" (substring cell 0 2))) + (equal "'" (substring cell 0 1))) (read cell) (progn (set-text-properties 0 (length cell) nil cell) cell))) cell))