o-b-worg.org: added LoB imae and removed LoB link (it's not up to much yet)
[org-mode.git] / org-babel.org
blobbe9d38d8c40536e3f194d2ebe50a35c37ff68cb8
1 #+TITLE: org-babel --- facilitating communication between programming languages and people
2 #+SEQ_TODO: PROPOSED TODO STARTED | DONE DEFERRED REJECTED
3 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
4 #+STARTUP: oddeven hideblocks
6 #+begin_html 
7   <div id="subtitle">
8     <p>executable source code blocks in org-mode</p>
9   </div>
10   <div id="logo">
11     <p>
12       <img src="images/tower-of-babel.png"  alt="images/tower-of-babel.png" />
13       <div id="attr">from <a href="http://www.flickr.com/photos/23379658@N05/" title=""><b>Martijn Streefkerk</b></a></div>
14     </p>  
15   </div>
16 #+end_html
18 Org-Babel makes source-code blocks in Org-Mode executable and allows
19 data to pass seamlessly between different programming languages,
20 Org-Mode constructs (tables, file links, example text) and interactive
21 comint buffers.
23 In this document:
24 - The [[* Introduction][Introduction]] :: provides a brief overview of the design and use
25      of Org-Babel including tutorials and examples.
26 - In [[* Getting started][Getting Started]] :: find instructions for installing org-babel
27      into your emacs configuration.
28 - The [[* Tasks][Tasks]] :: section contains current and past tasks roughly ordered
29      by TODO state, then importance or date-completed.  This would be
30      a good place to suggest ideas for development.
31 - The [[* Bugs][Bugs]] :: section contains bug reports.
32 - The [[* Tests][Tests]] :: section consists of a large table which can be
33      evaluated to run Org-Babel's functional test suite.  This
34      provides a good overview of the current functionality with
35      pointers to example source blocks.
36 - The [[* Sandbox][Sandbox]] :: demonstrates much of the early/basic functionality
37      through commented source-code blocks.
39 Also see the [[file:library-of-babel.org][Library of Babel]], an extensible collection of ready-made
40 and easily-shortcut-callable source-code blocks for handling common
41 tasks.
43 * Introduction
45 Org-Babel enables *communication* between programming languages and
46 between people.
48 Org-Babel provides:
49 - communication between programs :: Data passes seamlessly between
50      different programming languages, Org-Mode constructs (tables,
51      file links, example text) and interactive comint buffers.
52 - communication between people :: Data and calculations are embedded
53      in the same document as notes explanations and reports.
55 ** communication between programs
57 Org-Mode supports embedded blocks of source code (in any language)
58 inside of Org documents.  Org-Babel allows these blocks of code to be
59 executed from within Org-Mode with natural handling of their inputs
60 and outputs.
62 *** simple execution
63 with both scalar, file, and table output
65 *** reading information from tables
67 *** reading information from other source blocks (disk usage in your home directory)
69 This will work for Linux and Mac users, not so sure about shell
70 commands for windows users.
72 To run place the cursor on the =#+begin_src= line of the source block
73 labeled directory-pie and press =\C-c\C-c=.
75 #+srcname: directories
76 #+begin_src bash :results replace
77 cd ~ && du -sc * |grep -v total
78 #+end_src
80 #+resname: directories
81 |       64 | "Desktop"   |
82 | 11882808 | "Documents" |
83 |  8210024 | "Downloads" |
84 |   879800 | "Library"   |
85 |    57344 | "Movies"    |
86 |  7590248 | "Music"     |
87 |  5307664 | "Pictures"  |
88 |        0 | "Public"    |
89 |      152 | "Sites"     |
90 |        8 | "System"    |
91 |       56 | "bin"       |
92 |  3274848 | "mail"      |
93 |  5282032 | "src"       |
94 |     1264 | "tools"     |
96 #+srcname: directory-pie
97 #+begin_src R :var dirs = directories :session R-pie-example
98 pie(dirs[,1], labels = dirs[,2])
99 #+end_src
106 *** operations in/on tables
108 #+tblname: grades-table
109 | student | grade | letter |
110 |---------+-------+--------|
111 |       1 |    99 | A      |
112 |       2 |    59 | F      |
113 |       3 |    75 | C      |
114 |       4 |    15 | F      |
115 |       5 |     7 | F      |
116 |       6 |    13 | F      |
117 #+TBLFM: $2='(sbe random-score-generator)::$3='(sbe assign-grade (score $2))
119 #+srcname: assign-grade
120 #+begin_src ruby :var score=99
121 case score
122    when 0..59: "F"
123    when 60..69: "D"
124    when 70..79: "C"
125    when 80..89: "B"
126    when 90..100: "A"
127    else "Invalid Score"
129 #+end_src
131 #+srcname: random-score-generator
132 #+begin_src ruby 
133 rand(100)
134 #+end_src
136 #+srcname: show-distribution
137 #+begin_src R :var grades=grades-table :session *R*
138 hist(grades$grade)
139 #+end_src
145 ** communication between people
146 Quick overview of Org-Mode's exportation abilities, with links to the
147 online Org-Mode documentation, a focus on source-code blocks, and the
148 exportation options provided by Org-Babel.
150 *** Interactive tutorial
151 This would demonstrate applicability to Reproducible Research, and
152 Literate Programming.
154 *** Tests embedded in documentation
155 org-babels own functional tests are contained in a large org-mode
156 table, allowing the test suite to be run be evaluation of the table
157 and the results to be collected in the same table.
159 *** Emacs initialization files stored in Org-Mode buffers
160 Using `org-babel-tangle' it is possible to embed your Emacs
161 initialization into org-mode files.  This allows for folding,
162 note-taking, todo's etc... embedded with the source-code of your Emacs
163 initialization, and through org-mode's publishing features aids in
164 sharing your customizations with others.
166 It may be worthwhile to create a fork of Phil Hagelberg's
167 [[http://github.com/technomancy/emacs-starter-kit/tree/master][emacs-starter-kit]] which uses literate org-mode files for all of the
168 actual elisp customization.  These org-mode files could then be
169 exported to html and used to populate the repositories wiki on [[http://github.com/][github]].
172 ** features
174 *** code evaluation (comint buffer sessions and external processes)
175 There are two main ways to evaluate source blocks with org-babel.
177 - external :: By default (if the =:session= header argument is not
178               present) all source code blocks are evaluated in
179               external processes.  In these cases an external process
180               is used to evaluate the source-code blocks.
181 - session :: Session based evaluation uses persistent sessions in
182              comint buffers.  Sessions can be used across multiple
183              source blocks setting and accessing variables in the
184              global environment.
186              Evaluating source blocks in sessions also allows for
187              interaction with the code.  To jump to the session of a
188              source block use the `org-babel-pop-to-session' command
189              or press =M-[down]= while inside of a source code block.
190              When called with a prefix argument
191              `org-babel-pop-to-session' will evaluate all header
192              arguments before jumping to the source-code block.
194 *** results (values and outputs)
195 Either the *value* or the *output* of source code blocks can be
196 collected after evaluation.
198 - value :: The default way to collect results from a source-code block
199            is to return the value of the last statement in the block.
200            This can be thought of as the return value of the block.
201            In this case any printed output of the block is ignored.
202            This can be though of a similar to a "functional" value of
203            evaluation.
204 - output :: Another way of generating results from a source-code block
205             is to collect the output generated by the execution of the
206             block.  In this case all printed output is collected
207             throughout the execution of the block.  This can be
208             thought of as similar to a "script" style of evaluation.
211 * Getting started
212 Add the following lines to your .emacs, replacing the path as
213 appropriate. A good place to check that things are up and running
214 would then be [[#sandbox][the sandbox]].
215 #+begin_src emacs-lisp
216   (add-to-list 'load-path "/path/to/org-babel/lisp")
217   (require 'org-babel-init)
218 #+end_src
220   
221 * Tasks [47/65]
222 ** STARTED share org-babel [1/7]
223 how should we share org-babel?
224 *** DONE post to org-mode
225 *** TODO post to ess mailing list
226     I'd like to not rush in to this, get some feedback from the org
227     list first and let my R usage of org-babel settle down. [DD]
228 *** STARTED create a org-babel page on worg
229 **** TODO Getting hold of it instructions
230      - What about non-git users?
231      - Are we moving/copying to contrib/?
232 **** TODO Fixed width HTML output created by =...= is ugly!
233 *** TODO create a short screencast demonstrating org-babel in action
234 *** PROPOSED a peer-reviewed publication?
236     The following notes are biased towards statistics-oriented
237     journals because ESS and Sweave are written by people associated
238     with / in statistics departments. But I am sure there are suitable
239     journals out there for an article on using org mode for
240     reproducible research (and literate programming etc).
242     Clearly, we would invite Carsten to be involved with this.
244      ESS is described in a peer-reviewed journal article:
245      Emacs Speaks Statistics: A Multiplatform, Multipackage Development Environment for Statistical Analysis  [Abstract]
246      Journal of Computational & Graphical Statistics 13(1), 247-261
247      Rossini, A.J, Heiberger, R.M., Sparapani, R.A., Maechler, M., Hornik, K. (2004) 
248      [[http://www.amstat.org/publications/jcgs.cfm][Journal of Computational and Graphical Statistics]]
250      Also [[http://www.amstat.org/publications/jss.cfm][Journal of Statistical Software]] Established in 1996, the
251      Journal of Statistical Software publishes articles, book reviews,
252      code snippets, and software reviews. The contents are freely
253      available online. For both articles and code snippets, the source
254      code is published along with the paper.
256     Sweave has a paper: 
258     Friedrich Leisch and Anthony J. Rossini. Reproducible statistical
259     research. Chance, 16(2):46-50, 2003. [ bib ]
261     also
263     Friedrich Leisch. Sweave: Dynamic generation of statistical reports
264     using literate data analysis. In Wolfgang Härdle and Bernd Rönz,
265     editors, Compstat 2002 - Proceedings in Computational Statistics,
266     pages 575-580. Physica Verlag, Heidelberg, 2002. ISBN 3-7908-1517-9.
268     also
270     We could also look at the Journals publishing these [[http://www.reproducibleresearch.net/index.php/RR_links#Articles_about_RR_.28chronologically.29][Reproducible
271     Research articles]].
272     
273 *** PROPOSED an article in [[http://journal.r-project.org/][The R Journal]]
274 This looks good.  It seems that their main topic to software tools for
275 use by R programmers, and Org-babel is certainly that.
277 *** existing similar tools
278 try to collect pointers to similar tools 
280 Reproducible Research
281 - [[http://en.wikipedia.org/wiki/Sweave][Sweave]]
283 Literate Programming
284 - [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]]
285 - [[http://www-cs-faculty.stanford.edu/~knuth/cweb.html][Cweb]]
286 - [[http://www.lri.fr/~filliatr/ocamlweb/][OCamlWeb]]
288 Meta Functional Programming
289 - ?
291 Programmable Spreadsheet
292 - ?
294 *** examples
295 we need to think up some good examples
297 **** interactive tutorials
298 This could be a place to use [[* org-babel assertions][org-babel assertions]].
300 for example the first step of a tutorial could assert that the version
301 of the software-package (or whatever) is equal to some value, then
302 source-code blocks could be used with confidence (and executed
303 directly from) the rest of the tutorial.
305 **** answering a text-book question w/code example
306 org-babel is an ideal environment enabling both the development and
307 demonstrationg of the code snippets required as answers to many
308 text-book questions.
310 **** something using tables
311 maybe something along the lines of calculations from collected grades
313 **** file sizes
314 Maybe something like the following which outputs sizes of directories
315 under the home directory, and then instead of the trivial =emacs-lisp=
316 block we could use an R block to create a nice pie chart of the
317 results.
319 #+srcname: sizes
320 #+begin_src bash :results replace
321 du -sc ~/*
322 #+end_src
324 #+begin_src emacs-lisp :var sizes=sizes :results replace
325 (mapcar #'car sizes)
326 #+end_src
327 *** Answer to question on list
328 From: Hector Villafuerte <hectorvd@gmail.com>
329 Subject: [Orgmode] Merge tables
330 Date: Wed, 19 Aug 2009 10:08:40 -0600
331 To: emacs-orgmode@gnu.org
334 I've just discovered Org and are truly impressed with it; using it for
335 more and more tasks.
337 Here's what I want to do: I have 2 tables with the same number of rows
338 (one row per subject). I would like to make just one big table by
339 copying the second table to the right of the first one. This is a
340 no-brainer in a spreadsheet but my attempts in Org have failed. Any
341 ideas?
343 By the way, thanks for this great piece of software!
344 -- 
345  hector
347 **** Suppose the tables are as follows
348 #+tblname: tab1
349 | a | b | c |
350 |---+---+---|
351 | 1 | 2 | 3 |
352 | 7 | 8 | 9 |
354 #+tblname: tab2
355 |  d |  e |  f |
356 |----+----+----|
357 |  4 |  5 |  6 |
358 | 10 | 11 | 12 |
360 **** Here is an answer using R in org-babel
362 #+srcname: column-bind(a=tab1, b=tab2)
363 #+begin_src R :colnames t
364 cbind(a, b)
365 #+end_src
367 #+resname: column-bind
368 | "a" | "b" | "c" | "d" | "e" | "f" |
369 |-----+-----+-----+-----+-----+-----|
370 |   1 |   2 |   3 |   4 |   5 |   6 |
371 |   7 |   8 |   9 |  10 |  11 |  12 |
374 **** Alternatively
375      Use org-table-export, do it in external spreadsheet software,
376      then org-table-import
377 ** TODO sha1 hash based caching
378    :PROPERTIES:
379    :CUSTOM_ID: sha1-caching
380    :END:
382 #+begin_quote 
383 I wonder if we should consider some cashing of images, also for
384 export.  I think we could have an alist with sha1 hashes as keys and
385 image files as values.  The sha1 hash could be made from the entire
386 code and the command that is used to create the image..
388 -- Carsten
389 #+end_quote
392 #+begin_quote 
393 (sha1 stuff) seems to work.
395 org-feed.el has a (require 'sha1) and org-publish.el uses it too.
397 -- Bernt
398 #+end_quote
400 ** TODO support for working with =*Org Edit Src Example*= buffers [4/7]
401 *** STARTED Patch against org source. 
402     I've worked on several related changes to source code edit buffer
403     behaviour in the org core.  My current patch (below) does the
404     following. Detailed explanation / working notes are below.
405     - C-x s offers to save edit buffers
406     - C-x C-c offers to save edit buffers
407     - C-x k warns that you're killing an edit buffer
408     - If you do kill an edit buffer, the overlay in the parent buffer is removed
409     - Edit buffers are named *Org Src <orgbuf>[<lang>]*, where
410       <orgbuf> is the name of the org-mode buffer containing this
411       source code block, and lang is the language major mode. The
412       latter might be unnecessary?
414     These changes were added to the main org repository in commit
415     4b6988bf36cb458c9d113ee4332e016990c1eb04
416     
417 **** Detailed working notes to go with that patch
418 ***** Recap of current org-src-mode
419       
420       If you use C-c ' to work on code in a begin_source block, the code
421       buffer is put in minor mode org-src-mode, which features the
422       following two useful key-bindings:
424       | C-x s | org-edit-src-save | save the code in the source code block in the parent org file |
425       | C-c ' | org-edit-src-exit | return to the parent org file with new code                   |
427       Furthermore, while the edit buffer is alive, the originating code
428       block is subject to a special overlay which links to the edit
429       buffer when you click on it.
431       This is all excellent, and I use it daily, but I think there's
432       still a couple of improvements that we should make.
434 ***** Proposed bug I
435       C-x k kills the buffer without questions; the overlay remains, but
436       now links to a deleted buffer.
437 ***** Proposed bug II
438       C-x C-c kills a modified edit buffer silently, without offering to
439       save your work. I have lost work like that a number of times
440       recently.
441 ***** Proposed bug III
442       C-x s does not offer to save a modified edit buffer
443 ***** Notes on solution
444 ****** write-contents-functions
445        A good start seems to be to use org-src-mode-hook to add
446        org-edit-src-save to the write-contents-functions list. This
447        means that when it comes to saving, org-edit-src-save will be
448        called and no subsequent attempt will be made to save the buffer
449        in the normal way. (This should obviate the remapping of C-x C-s
450        to org-edit-src-save in org-src.el)
451 ****** buffer-offer-save
452        We also want to set this to t.
454 ****** Where does this get us?
456        - C-x s still does *not* offer to save the edit buffer. That's
457          because buffer-file-name is nil.
458        
459        - C-x C-c does ask us whether we want to save the
460          edit buffer. However, since buffer-file-name is nil it asks us
461          for a file name. The check in org-edit-src-exit throws an error
462          unless the buffer is named '* Org Edit '...
464        - C-x k kills the buffer silently, leaving a broken overlay
465          link. If buffer-file-name were set, it would have warned that
466          the buffer was modified.
468 ****** buffer-file-name
469        So, that all suggests that we need to set buffer-file-name, even
470        though we don't really want to associate this buffer with a file
471        in the normal way. As for the file name, my current suggestion
472        is parent-org-filename[edit-buffer-name].
473        
474        [I had to move the (org-src-mode) call to the end of
475        org-edit-src-code to make sure that the required variables were
476        defined when the hook was called.]
477        
478 ****** And so where are we now?
479        - C-x s *does* offer to save the edit buffer, but in saving
480          produces a warning that the edit buffer is modified.
481        - C-x k now gives a warning that the edit buffer is modified
482          (even if it's not).
483        - C-x C-c is working as desired, except that again we get
484          warnings that the edit buffer is modified, once when we save,
485          and again just before exiting emacs.
486        - And C-c ' now issues a warning that the edit buffer is
487          modified when we leave it, which we don't want.
488 ****** So, we need to get rid of the buffer modification warnings.
489        I've made buffer-file-name nil inside the let binding in
490        org-edit-src-exit.
491 ****** And?
492        - C-x s behaves as desired, except that as was already the case,
493          the edit buffer is always considered modified, and so repeated
494          invocations keep saving it.
495        - As was already the case, C-x k always gives a warning that the
496          edit buffer has been modified.
497        - C-x C-c is as desired (offers to save the edit buffer) except
498          that it warns of the modified buffer just before exiting.
499        - C-c ' is as it should be (silent)
500 ***** Conclusion
501       We've got the desired behaviour, at the cost of being forced to
502       assign a buffer-file-name to the edit buffer. The consequence is
503       that the edit buffer is considered to always be modified, since
504       a file of that name is never actually written to (doesn't even
505       exist). I couldn't see a way to trick emacs into believing that
506       the buffer was unmodified since last save. But in any case, I
507       think there's an argument that these modifications warnings are
508       a good thing, because one should not leave active edit buffers
509       around: you should always have exited with C-c ' first.
511 **** TODO Doesn't currently work with ess-load-file
512      ess-load-file contains these two lines
513 #+begin_src emacs-lisp
514   (let ((source-buffer (get-file-buffer filename)))
515     (if (ess-check-source filename)
516         (error "Buffer %s has not been saved" (buffer-name source-buffer)))
517 #+end_src
519 which have the effect of, in the course of saving, deleting the buffer
520 `source-buffer', and then attempting to use it subsequently. The only
521 solution I have thought of so far is submitting a patch to ess which
522 would, e.g. reverse the order of those two lines (perform the error
523 check outside the let binding).
525 In fact, even after doing that there are further problems generated by
526 the fact that the edit buffer has an associated filename for which the
527 file doesn't exist. I think this worked OK in the past when the edit
528 buffer had no associated filename. So this is a problem which needs
529 addressing. Maybe defadvice could be used on ess functions where
530 necessary to make org/org-babel play nicely with ess?
532 **** TODO C-x s steals focus
533      With two modified edit buffers open, make one of them the current
534      buffer and issue C-x s. It will offer to save both of them, but
535      the second one to be saved will become the current buffer at the
536      end.
537 *** DONE name edit buffer according to #+srcname (and language?)
538     See above patch agains org.
539 *** DONE optionally evaluate header references when we switch to =*Org Edit Src*= buffer
540 That seems to imply that the header references need to be evaluated
541 and transformed into the target language object when we hit C-c ' to
542 enter the *Org Edit Src* buffer [DED]
544 Good point, I heartily agree that this should be supported [Eric]
546 (or at least before the first time we attempt to evaluate code in that
547 buffer -- I suppose there might be an argument for lazy evaluation, in
548 case someone hits C-c ' but is "just looking" and not actually
549 evaluating anything.) Of course if evaluating the reference is
550 computationally intensive then the user might have to wait before they
551 get the *Org Edit Src* buffer. [DED]
553 I fear that it may be hard to anticipate when the references will be
554 needed, some major-modes do on-the-fly evaluation while the buffer is
555 being edited.  I think that we should either do this before the buffer
556 is opened or not at all, specifically I think we should resolve
557 references if the user calls C-c ' with a prefix argument.  Does that
558 sound reasonable? [Eric]
560 Yes [Dan]
562 [Dan] So now that we have org-src-mode and org-src-mode-hook, I guess
563 org-babel should do this by using the hook to make sure that, when C-c
564 C-' is issued on a source block, any references are resolved and
565 assignments are made in the appropriate session.
567 #+tblname: my-little-table
568 | 1 | 2 |
569 | 3 | 4 |
571 #+srcname: resolve-vars-on-edit
572 #+begin_src ruby :var table=my-little-table :results silent :session test
573   table.size.times.do |n|
574     puts n
575   end
576 #+end_src
578 *** TODO set buffer-local-process variables appropriately [DED]
579     I think something like this would be great. You've probably
580 already thought of this, but just to note it down: it would be really
581 nice if org-babel's notion of a buffer's 'session/process' played
582 nicely with ESS's notion of the buffer's session/process. ESS keeps
583 the current process name for a buffer in a buffer-local variable
584 ess-local-process-name. So one thing we will probably want to do is
585 make sure that the *Org Edit Src Example* buffer sets that variable
586 appropriately. [DED]
588 I had not thought of that, but I agree whole heartedly. [Eric]
590 Once this is done every variable should be able to dump regions into
591 their inferior-process buffer using major-mode functions.
592 *** REJECTED send code to inferior process
593 Another thought on this topic: I think we will want users to send
594 chunks of code to the interpreter from within the *Org Edit Src*
595 buffer, and I think that's what you have in mind already. In ESS that
596 is done using the ess-eval-* functions. [DED]
598 I think we can leave this up to the major-mode in the source code
599 buffer, as almost every source-code major mode will have functions for
600 doing things like sending regions to the inferior process.  If
601 anything we might need to set the value of the buffer local inferior
602 process variable. [Eric]
604 *** DONE some possible requests/proposed changes for Carsten [4/4]
605     While I remember, some possible requests/proposed changes for Carsten
606     come to mind in that regard:
608 **** DONE Remap C-x C-s to save the source to the org buffer?
609      I've done this personally and I find it essential. I'm using 
610 #+begin_src emacs-lisp
611 (defun org-edit-src-save ()
612   "Update the parent org buffer with the edited source code, save
613 the parent org-buffer, and return to the source code edit
614 buffer."
615   (interactive)
616   (let ((p (point)))
617     (org-edit-src-exit)
618     (save-buffer)
619     (org-edit-src-code)
620     (goto-char p)))
622 (define-key org-exit-edit-mode-map "\C-x\C-s" 'org-edit-src-save)
623 #+end_src     
624     which seems to work.
626 I think this is great, but I think it should be implemented in the
627 org-mode core
629 **** DEFERRED Rename buffer and minor mode?
630      Something shorter than *Org Edit Src Example* for the buffer
631      name. org-babel is bringing org's source code interaction to a
632      level of maturity where the 'example' is no longer
633      appropriate. And if further keybindings are going to be added to
634      the minor mode then maybe org-edit-src-mode is a better name than
635      org-exit-edit-mode.
637      Maybe we should name the buffer with a combination of the source
638      code and the session.  I think that makes sense.
640      [ES] Are you also suggesting a new org-edit-src minor mode?
641      [DED] org-exit-edit-mode is a minor mode that already exists:
643      Minor mode installing a single key binding, "C-c '" to exit special edit.
645      org-edit-src-save now has a binding in that mode, so I guess all
646      I'm saying at this stage is that it's a bit of a misnomer. But
647      perhaps we will also have more functionality to add to that minor
648      mode, making it even more of a misnomer. Perhaps something like
649      org-src-mode would be better.
650 **** DONE Changed minor mode name and added hooks
651      
652 **** DONE a hook called when the src edit buffer is created
653      This should be implemented in the org-mode core
654 ** TODO resolve references to other org buffers/files
655    This would allow source blocks to call upon tables, source-blocks,
656    and results in other org buffers/files.
657    
658    See...
659    - [[file:lisp/org-babel-ref.el::TODO%20allow%20searching%20for%20names%20in%20other%20buffers][org-babel-ref.el:searching-in-other-buffers]]
660    - [[file:lisp/org-babel.el::defun%20org-babel%20find%20named%20result%20name][org-babel.el#org-babel-find-named-result]]
661 ** TODO resolve references to other non-org files
662    - tabular data in .csv, .tsv etc format
663    - files of interpreted code: anything stopping us giving such files
664      similar status to a source code block?
665    - Would be nice to allow org and non-org files to be remote
666 ** TODO Finalise behaviour regarding vector/scalar output
667 *** DONE Stop spaces causing vector output
668 This simple example of multilingual chaining produces vector output if
669 there are spaces in the message and scalar otherwise.
671 [Not any more]
673 #+srcname: msg-from-R(msg=msg-from-python)
674 #+begin_src R
675 paste(msg, "und R", sep=" ")
676 #+end_src
678 #+resname:
679 : org-babel speaks elisp y python und R
681 #+srcname: msg-from-python(msg=msg-from-elisp)
682 #+begin_src python
683 msg + " y python"
684 #+end_src
686 #+srcname: msg-from-elisp(msg="org-babel speaks")
687 #+begin_src emacs-lisp
688 (concat msg " elisp")
689 #+end_src
690 ** TODO command line execution
691 Allow source code blocks to be called form the command line.  This
692 will be easy using the =sbe= function in [[file:lisp/org-babel-table.el][org-babel-table.el]].
694 This will rely upon [[* resolve references to other buffers][resolve references to other buffers]].
696 ** TODO inline source code blocks [3/5]
697    Like the =\R{ code }= blocks
699    not sure what the format should be, maybe just something simple
700    like =src_lang[]{}= where lang is the name of the source code
701    language to be evaluated, =[]= is optional and contains any header
702    arguments and ={}= contains the code.
704    (see [[* (sandbox) inline source blocks][the-sandbox]])
706 *** DONE evaluation with \C-c\C-c
707 Putting aside the header argument issue for now we can just run these
708 with the following default header arguments
709 - =:results= :: silent
710 - =:exports= :: results
712 *** DONE inline exportation
713 Need to add an interblock hook (or some such) through org-exp-blocks
714 *** DONE header arguments
715 We should make it possible to use header arguments.
717 *** TODO fontification
718 we should color these blocks differently
720 *** TODO refine html exportation
721 should use a span class, and should show original source in tool-tip
722 ** TODO LoB: re-implement plotting and analysis functions from org-R
723    I'll do this soon, now that we things are a bit more settled and we
724    have column names in R.
725 ** PROPOSED allow `anonymous' function block with function call args?
726    My question here is simply whether we're going to allow
727 #+begin_src python(arg=ref)
728 # whatever
729 #+end_src
731 but with preference given to
732 #+srcname blockname(arg=ref)
733 ** PROPOSED allow :result as synonym for :results?
734 ** PROPOSED allow 'output mode to return stdout as value?
735    Maybe we should allow this. In fact, if block x is called
736    with :results output, and it references blocks y and z, then
737    shouldn't the output of x contain a concatenation of the outputs of
738    y and z, together with x's own output? That would raise the
739    question of what happens if y is defined with :results output and z
740    with :results value. I guess z's (possibly vector/tabular) output
741    would be inside a literal example block containing the whole lot.
742 ** PROPOSED make tangle files read-only?
743    With a file-local variable setting, yea that makes sense.  Maybe
744    the header should reference the related org-mode file.
745 ** PROPOSED Creating presentations
746    The [[mairix:t:@@9854.1246500519@gamaville.dokosmarshall.org][recent thread]] containing posts by Nick Dokos and Sebastian
747    Vaubán on exporting to beamer looked very interesting, but I
748    haven't had time to try it out yet. I would really like it if,
749    eventually, we can generate a presentation (with graphics generated
750    by code blocks) from the same org file that contains all the notes
751    and code etc. I just wanted that to be on record in this document;
752    I don't have anything more profound to say about it at the moment,
753    and I'm not sure to what extent it is an org-babel issue.
754 ** PROPOSED conversion between org-babel and noweb (e.g. .Rnw) format
755    I haven't thought about this properly. Just noting it down. What
756    Sweave uses is called "R noweb" (.Rnw).
757    
758    I found a good description of noweb in the following article (see
759    the [[http://www.cs.tufts.edu/~nr/pubs/lpsimp.pdf][pdf]]).
760    
761    I think there are two parts to noweb, the construction of
762    documentation and the extraction of source-code (with notangle).
764    *documentation*: org-mode handles all of our documentation needs in
765    a manner that I believe is superior to noweb.
766    
767    *source extraction* At this point I don't see anyone writing large
768    applications with 100% of the source code contained in org-babel
769    files, rather I see org-babel files containing things like
770    - notes with active code chunks
771    - interactive tutorials
772    - requirements documents with code running test suites
773    - and of course experimental reports with the code to run the
774      experiment, and perform analysis
776    Basically I think the scope of the programs written in org-babel
777    (at least initially) will be small enough that it wont require the
778    addition of a tangle type program to extract all of the source code
779    into a running application.
781    On the other hand, since we already have named blocks of source
782    code which reference other blocks on which they rely, this
783    shouldn't be too hard to implement either on our own, or possibly
784    relying on something like noweb/notangle.
786 ** PROPOSED support for passing paths to files between source blocks
787 Maybe this should be it's own result type (in addition to scalars and
788 vectors).  The reason being that some source-code blocks (for example
789 ditaa or anything that results in the creation of a file) may want to
790 pass a file path back to org-mode which could then be inserted into
791 the org-mode buffer as a link to the file...
793 This would allow for display of images upon export providing
794 functionality similar to =org-exp-blocks= only in a more general
795 manner.
796 ** DEFERRED optional timestamp for output
797    *DEFERRED*: I'm deferring this in deference to the better caching
798    system proposed by Carsten. (see [[sha1-caching]])
800    Add option to place an (inactive) timestamp at the #+resname, to
801    record when that output was generated.
803 *** source code block timestamps (optional addition)
804     [Eric] If we did this would we then want to place a timestamp on the
805     source-code block, so that we would know if the results are
806     current or out of date?  This would have the effect of caching the
807     results of calculations and then only re-running if the
808     source-code has changed.  For the caching to work we would need to
809     check not only the timestamp on a source-code block, but also the
810     timestamps of any tables or source-code blocks referenced by the
811     original source-code block.
813     [Dan] I do remember getting frustrated by Sweave always having to
814     re-do everything, so this could be desirable, as long as it's easy
815     to over-ride of course. I'm not sure it should be the default
816     behaviour unless we are very confident that it works well.
818 **** maintaining source-code block timestamps
819      It may make sense to add a hook to `org-edit-special' which could
820      update the source-code blocks timestamp.  If the user edits the
821      contents of a source-code block directly I can think of no
822      efficient way of maintaining the timestamp.
823 ** DEFERRED figure out how to handle errors during evaluation
824    I expect it will be hard to do this properly, but ultimately it
825    would be nice to be able to specify somewhere to receive STDERR,
826    and to be warned if it is non-empty.
828    Probably simpler in non-session evaluation than session? At least
829    the mechanism will be different I guess.
831    R has a try function, with error handling, along the lines of
832    python. I bet ruby does too. Maybe more of an issue for functional
833    style; in my proposed scripting style the error just gets dumped to
834    the org buffer and the user is thus alerted.
836    For now I think the current behavior of returning any error
837    messages generated by the source language is sufficient.
838 ** DEFERRED source-name visible in LaTeX and html exports
839 Maybe this should be done in backend specific manners.
841 The listings package may provide for naming a source-code block...
843 Actually there is no obvious simple and attractive way to implement
844 this.  Closing this issue for now.
845 ** DEFERRED Support rownames and other org babel table features?
847    The full org table features are detailed in the manual [[http://orgmode.org/manual/Advanced-features.html#Advanced-features][here]].
849 *** rownames
850    Perhaps add a :rownames header arg. This would be an integer
851     (usually 1) which would have the effect of post-processing all the
852     variables created in the R session in the following way: if the
853     integer is j, set the row names to the contents of column j and
854     delete column j. Perhaps it is artificial to allow this integer to
855     take any value other than 1. The default would be nil which would
856     mean no such behaviour.
858     Actually I don't know about that. If multiple variables are passed
859     in, it's not appropriate to alter them all in the same way. The
860     rownames specification would normally refer to just one of the
861     variables. For now maybe just say this has to be done in R. E.g.
863 #+TBLNAME: sample-sizes
864   | collection      | size | exclude | include | exclude2 | include2 |
865   |-----------------+------+---------+---------+----------+----------|
866   | 58C             | 2936 |       8 |    2928 |      256 |     2680 |
867   | MS              | 5852 |     771 |    5081 |      771 |     5081 |
868   | NBS             | 2929 |      64 |    2865 |      402 |     2527 |
869   | POBI            | 2717 |       1 |    2716 |        1 |     2716 |
870   | 58C+MS+NBS+POBI |      |         |   13590 |          |    13004 |
871 #+TBLFM: @2$4=@2$2 - @2$3::@2$6=@2$2 - @2$5::@3$4=@3$2-@3$3::@3$6=@3$2 - @3$5::@4$4=@4$2 - @4$3::@4$6=@4$2 - @4$5::@5$4=@5$2-@5$3::@5$6=@5$2 - @5$5::@6$4=vsum(@2$4..@5$4)::@6$6=vsum(@2$6..@5$6)
873 #+srcname: make-size-table(size=sample-sizes)
874 #+begin_src R 
875   rownames(size) <- size[,1]
876   size <- size[,-1]
877 #+end_src
880 *** Old notes
881     [I don't think it's as problematic as this makes out]
882     This is non-trivial, but may be worth doing, in particular to
883     develop a nice framework for sending data to/from R.
884 **** Notes
885     In R, indexing vector elements, and rows and columns, using
886     strings rather than integers is an important part of the
887     language.
888  - elements of a vector may have names
889  - matrices and data.frames may have "column names" and "row names"
890    which can be used for indexing
891  - In a data frame, row names *must* be unique
892 Examples
893 #+begin_example
894 > # a named vector
895 > vec <- c(a=1, b=2)
896 > vec["b"]
899 > mat <- matrix(1:4, nrow=2, ncol=2, dimnames=list(c("r1","r2"), c("c1","c2")))
900 > mat
901    c1 c2
902 r1  1  3
903 r2  2  4
904 > # The names are separate from the data: they do not interfere with operations on the data
905 > mat * 3
906    c1 c2
907 r1  3  9
908 r2  6 12
909 > mat["r1","c2"]
910 [1] 3
911 > df <- data.frame(var1=1:26, var2=26:1, row.names=letters)
912 > df$var2
913  [1] 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1
914 > df["g",]
915   var1 var2
916 g    7   20
917 #+end_example
919  So it's tempting to try to provide support for this in org-babel. For example
920  - allow R to refer to columns of a :var reference by their names
921  - When appropriate, results from R appear in the org buffer with "named
922    columns (and rows)"
924    However none (?) of the other languages we are currently supporting
925    really have a native matrix type, let alone "column names" or "row
926    names". Names are used in e.g. python and perl to refer to entries
927    in dicts / hashes.
929    It currently seems to me that support for this in org-babel would
930    require setting rules about when org tables are considered to have
931    named columns/fields, and ensuring that (a) languages with a notion
932    of named columns/fields use them appropriately and (b) languages
933    with no such notion do not treat then as data.
935  - Org allows something that *looks* like column names to be separated
936    by a hline
937  - Org also allows a row to *function* as column names when special
938    markers are placed in the first column. An hline is unnecessary
939    (indeed hlines are purely cosmetic in org [correct?]
940  - Org does not have a notion of "row names" [correct?]
941     
942    The full org table functionality exeplified [[http://orgmode.org/manual/Advanced-features.html#Advanced-features][here]] has features that
943    we would not support in e.g. R (like names for the row below).
944    
945 **** Initial statement: allow tables with hline to be passed as args into R
946    This doesn't seem to work at the moment (example below). It would
947    also be nice to have a natural way for the column names of the org
948    table to become the column names of the R data frame, and to have
949    the option to specify that the first column is to be used as row
950    names in R (these must be unique). But this might require a bit of
951    thinking about.
954 #+TBLNAME: egtable
955 | col1 | col2    | col3 |
956 |------+---------+------|
957 |    1 | 2       |    3 |
958 |    4 | schulte |    6 |
960 #+TBLNAME: egtable2
961 | 1 |         2 | 3 |
962 | 4 | schulte   | 6 |
964 #+begin_src R :var tabel=egtable :colnames t
965 tabel
966 #+end_src
968 #+resname:
969 | "col1" | "col2"    | "col3" |
970 |--------+-----------+--------|
971 |      1 | 2         |      3 |
972 |      4 | "schulte" |      6 |
975 Another example is in the [[*operations%20in%20on%20tables][grades example]].
976 ** DEFERRED use textConnection to pass tsv to R?
977    When passing args from the org buffer to R, the following route is
978    used: arg in buffer -> elisp -> tsv on file -> data frame in R. I
979    think it would be possible to avoid having to write to file by
980    constructing an R expression in org-babel-R-assign-elisp, something
981    like this
983 #+begin_src emacs-lisp
984 (org-babel-R-input-command
985  (format  "%s <- read.table(textConnection(\"%s\"), sep=\"\\t\", as.is=TRUE)"
986           name (orgtbl-to-tsv value '(:sep "\t" :fmt org-babel-R-quote-tsv-field))))
987 #+end_src
989    I haven't tried to implement this yet as it's basically just
990    fiddling with something that works. The only reason for it I can
991    think of would be efficiency and I haven't tested that.
993    This Didn't work after an initial test.  I still think this is a
994    good idea (I also think we should try to do something similar when
995    writing out results frmo R to elisp) however as it wouldn't result
996    in any functional changes I'm bumping it down to deferred for
997    now. [Eric]
999 for quick tests
1001 #+tblname: quick-test
1002 | 1 | 2 | 3 |
1004 #+srcname: quick-test-src-blk
1005 #+begin_src R :var vec=quick-test
1006 mean(mean(vec))
1007 #+end_src
1009 #+resname:
1010 : 2
1013 : 2
1015 ** DEFERRED Rework Interaction with Running Processes [2/5]
1016 *** DONE robust to errors interrupting execution
1018 #+srcname: long-runner-ruby
1019 #+begin_src ruby :results silent
1020   sleep(10)
1021   :patton_is_an_grumpy
1022 #+end_src
1024 *** DEFERRED use =C-g= keyboard-quit to push processing into the background
1025 This may be possible using the `run-with-timer' command.
1027 I have no idea how this could work...
1029 #+srcname: long-runner-ruby
1030 #+begin_src ruby :results silent
1031   sleep(10)
1032   :patton_is_an_grumpy
1033 #+end_src
1035 *** TODO ability to select which of multiple sessions is being used
1036     Increasingly it is looking like we're going to want to run all
1037     source code blocks in comint buffer (sessions).  Which will have
1038     the benefits of
1039     1) allowing background execution
1040     2) maintaining state between source-blocks
1041        - allowing inline blocks w/o header arguments 
1043 **** R sessions
1044      (like ess-switch-process in .R buffers)
1045      
1046      Maybe this could be packaged into a header argument, something
1047      like =:R_session= which could accept either the name of the
1048      session to use, or the string =prompt=, in which case we could use
1049      the =ess-switch-process= command to select a new process.
1050      
1051 *** TODO evaluation of shell code as background process? 
1052     After C-c C-c on an R code block, the process may appear to
1053     block, but C-g can be used to reclaim control of the .org buffer,
1054     without interrupting the R evalution. However I believe this is not
1055     true of bash/sh evaluation. [Haven't tried other languages] Perhaps
1056     a solution is just to background the individual shell commands.
1058     The other languages (aside from emacs lisp) are run through the
1059     shell, so if we find a shell solution it should work for them as
1060     well.
1061     
1062     Adding an ampersand seems to be a supported way to run commands in
1063     the background (see [[http://www.emacswiki.org/emacs/ExecuteExternalCommand#toc4][external-commands]]).  Although a more extensible
1064     solution may involve the use of the [[elisp:(progn (describe-function 'call-process-region) nil)][call-process-region]] function.
1065     
1066     Going to try this out in a new file [[file:lisp/org-babel-proc.el][org-babel-proc.el]].  This should
1067     contain functions for asynchronously running generic shell commands
1068     in the background, and then returning their input.
1070 **** partial update of org-mode buffer
1071     The sleekest solution to this may be using a comint buffer, and
1072     then defining a filter function which would incrementally interpret
1073     the results as they are returned, including insertion into the
1074     org-mode buffer.  This may actually cause more problems than it is
1075     worth, what with the complexities of identifying the types of
1076     incrementally returned results, and the need for maintenance of a
1077     process marker in the org buffer.
1079 **** 'working' spinner
1080      It may be nice and not too difficult to place a spinner on/near the
1081      evaluating source code block
1083 *** TODO conversion of output from interactive shell, R (and python) sessions to org-babel buffers
1084     [DED] This would be a nice feature I think. Although an org-babel
1085     purist would say that it's working the wrong way round... After
1086     some interactive work in a *R* buffer, you save the buffer, maybe
1087     edit out some lines, and then convert it to org-babel format for
1088     posterity. Same for a shell session either in a *shell* buffer, or
1089     pasted from another terminal emulator. And python of course.
1090 ** DEFERRED improve the source-block snippet
1091 any real improvement seems somewhat beyond the ability of yasnippet
1092 for now.
1094 [[file:~/src/emacs-starter-kit/src/snippets/text-mode/rst-mode/chap::name%20Chapter%20title][file:~/src/emacs-starter-kit/src/snippets/text-mode/rst-mode/chap::name Chapter title]]
1095 #+begin_example
1096 ,#name : Chapter title
1097 ,# --
1098 ${1:Chapter}
1099 ${1:$(make-string (string-width text) ?\=)}
1102 #+end_example
1104 [[file:snippets/org-mode/sb][sb -- snippet]]
1106 waiting for guidance from those more familiar with yasnippets
1108 ** REJECTED re-implement R evaluation using ess-command or ess-execute
1109    I don't have any complaints with the current R evaluation code or
1110    behaviour, but I think it would be good to use the ESS functions
1111    from a political point of view. Plus of course it has the normal
1112    benefits of an API (insulates us from any underlying changes etc). [DED]
1114    I'll look into this.  I believe that I looked at and rejected these
1115    functions initially but now I can't remember why.  I agree with
1116    your overall point about using API's where available.  I will take
1117    a look back at these and either switch to using the ess commands,
1118    or at least articulate under this TODO the reasons for using our
1119    custom R-interaction commands. [Eric]
1121    ess-execute
1123    Lets just replace =org-babel-R-input-command= with =ess-execute=.
1125    I tried this, and although it works in some situations, I find that
1126    =ess-command= will often just hang indefinitely without returning
1127    results.  Also =ess-execute= will occasionally hang, and pops up
1128    the buffer containing the results of the command's execution, which
1129    is undesirable.  For now these functions can not be used.  Maybe
1130    someone more familiar with the ESS code can recommend proper usage
1131    of =ess-command= or some other lower-level function which could be
1132    used in place of [[file:lisp/org-babel-R.el::defun%20org-babel%20R%20input%20command%20command][org-babel-R-input-command]].
1134 *** ess functions
1135    
1136 #+begin_quote ess-command
1137 (ess-command COM &optional BUF SLEEP NO-PROMPT-CHECK)
1139 Send the ESS process command COM and delete the output
1140 from the ESS process buffer.  If an optional second argument BUF exists
1141 save the output in that buffer. BUF is erased before use.
1142 COM should have a terminating newline.
1143 Guarantees that the value of .Last.value will be preserved.
1144 When optional third arg SLEEP is non-nil, `(sleep-for (* a SLEEP))'
1145 will be used in a few places where `a' is proportional to `ess-cmd-delay'.
1146 #+end_quote
1148 #+begin_quote ess-execute
1149 (ess-execute COMMAND &optional INVERT BUFF MESSAGE)
1151 Send a command to the ESS process.
1152 A newline is automatically added to COMMAND.  Prefix arg (or second arg
1153 INVERT) means invert the meaning of
1154 `ess-execute-in-process-buffer'.  If INVERT is 'buffer, output is
1155 forced to go to the process buffer.  If the output is going to a
1156 buffer, name it *BUFF*.  This buffer is erased before use.  Optional
1157 fourth arg MESSAGE is text to print at the top of the buffer (defaults
1158 to the command if BUFF is not given.)
1159 #+end_quote
1161 *** out current setup
1163     1) The body of the R source code block is wrapped in a function
1164     2) The function is called inside of a =write.table= function call
1165        writing the results to a table
1166     3) The table is read using =org-table-import=
1167 ** DONE figure out how to handle graphic output
1168    
1169 This is listed under [[* graphical output][graphical output]] in out objectives.
1171 This should take advantage of the =:results file= option, and
1172 languages which almost always produce graphical output should set
1173 =:results file= to true by default (this is currently done for the
1174 gnuplot and ditaa languages).  That would handle placing these results
1175 in the buffer.  Then if there is a combination of =silent= and =file=
1176 =:results= headers we could drop the results to a temp buffer and pop
1177 open that buffer...
1179 Display of file results is addressed in the [[* =\C-c \C-o= to open results of source block][open-results-task]].
1181 I think this is done for now.  With the ability of the file option it
1182 is now possible to save images directly to a file.  Then calling
1183 =\C-c\C-o= with point on the source block will open the related
1184 results.
1186 *** R graphics to screen means session evaluation
1187     If R graphical output is going to screen then evaluation must be
1188     in a session, otherwise the graphics will disappear as soon as the
1189     R process dies.
1191 *** Adding to a discussion started in email
1192     I'm not deeply wedded to these ideas, just noting them down. I'm
1193     probably just thinking of R and haven't really thought about how
1194     this fits with the other graphics-generating languages.
1195 Dan:
1196 > I used the approach below to get graphical file output
1197 > today, which is one idea at least. Maybe it could be linked up with
1198 > your :results file variable. (Or do we need a :results image for R?)
1200 Eric:
1201 I don't think we need a special image results variable, but I may be
1202 missing what the code below accomplishes.  Would the task I added about
1203 adding org-open-at-point functionality to source code blocks take care
1204 of this need?
1206 Dan: I'm not sure. I think the ability for a script to generate both
1207 text and graphical output might be a natural expectation, at least for
1208 R users.
1211 > Dan
1213 > #+srcname: cohort-scatter-plots-2d(org_babel_graphical_output_file="cohort-scatter-plots-2d.png")
1214 > #+begin_src R 
1215 >   if(exists("org_babel_output_file"))
1216 >       png(filename=org_babel_graphical_output_file, width=1000, height=1000)
1217 >   ## plotting code in here
1218 >   if(exists("org_babel_graphical_output_file")) dev.off()
1219 > #+end_src
1221 Dan: Yes, the results :file option is nice for dealing with graphical
1222 output, and that could well be enough. Something based on the scheme
1223 above would have a couple of points in its favour:
1224 1. It's easy to switch between output going to on-screen graphics and
1225    output going to file: Output will go to screen unless a string variable
1226    with a standard name (e.g. ""org_babel_graphical_output_file"")
1227    exists in which case it will go to the file indicated by the value
1228    of that variable.
1229 2. The block can return a result / script output, as well as produce
1230    graphical output.
1232 In interactive use we might want to allow the user to choose between
1233 screen and file output. In non-interactive use such as export, it
1234 would be file output (subject to the :exports directives).
1235 ** DONE new results types (org, html, latex)
1236    Thanks to Tom Short for this recommendation.
1238    - raw or org :: in which case the results are implemented raw, unquoted
1239                    into the org-mode file.  This would also handle links as
1240                    source block output.
1241    - html :: the results are inserted inside of a #+BEGIN_HTML block
1242    - latex :: the results are inserted inside of a #+BEGIN_LATEX block
1244    It might look like:
1245 : #+begin_src R :session *R* :results org
1246 : cat("***** This is a table\n")
1247 : cat("| 1 | 2 | 3 |\n")
1248 : cat("[[http://google.com][Google it here]]\n"
1249 : #+end_src
1250 :        
1251 : #+resname:
1252 : ***** This is a table
1253 : | 1 | 2 | 3 |
1254 [[http://google.com][: Google it here]]
1256 We actually might want to remove the =#+resname= line if the results
1257 type is org-mode, not sure...  Either way I don't think there is a
1258 good way to capture/remove org type results.
1260 *** LaTeX
1261 #+srcname: latex-results
1262 #+begin_src emacs-lisp :results latex
1263 "this should be inside of a LaTeX block"
1264 #+end_src
1266 #+resname:
1267 #+BEGIN_LaTeX
1268 this should be inside of a LaTeX block
1269 #+END_LaTeX
1271 *** Html
1272 #+srcname: html-results
1273 #+begin_src emacs-lisp :results html
1274 "this should be inside of a HTML block
1278 and more
1282 is long"
1283 #+end_src
1285 #+resname:
1286 #+BEGIN_HTML
1287 this should be inside of a HTML block
1291 and more
1295 is long
1296 #+END_HTML
1298 *** raw
1300 Added a =raw= results header argument, which will insert the results
1301 of a source-code block into an org buffer un-escaped.  Also, if the
1302 results look like a table, then the table will be aligned.
1304 #+srcname: raw-table-demonstration
1305 #+begin_src ruby :results output raw
1306   puts "| root | square |"
1307   puts "|---"
1308   10.times do |n|
1309     puts "| #{n} | #{n*n} |"
1310   end
1311 #+end_src
1313 #+resname:
1314 | root | square |
1315 |------+--------|
1316 |    0 |      0 |
1317 |    1 |      1 |
1318 |    2 |      4 |
1319 |    3 |      9 |
1320 |    4 |     16 |
1321 |    5 |     25 |
1322 |    6 |     36 |
1323 |    7 |     49 |
1324 |    8 |     64 |
1325 |    9 |     81 |
1327 Not sure how/if this would work, but it may be desirable.
1328 ** DONE org-bable-tangle: no default extension if one already exists
1329 ** DONE take default values for header args from properties
1330    Use file-wide and subtree wide properties to set default values for
1331    header args.
1332    
1333    [DED] One thing I'm finding when working with R is that an org file
1334    may contain many source blocks, but that I just want to evaluate a
1335    subset of them. Typically this is in order to take up where I left
1336    off: I need to recreate a bunch of variables in the session
1337    environment. I'm thinking maybe we want to use a tag-based
1338    mechanism similar to :export: and :noexport: to control evaluation
1339    on a per-subtree basis.
1341 *** test-header with properties
1342     :PROPERTIES:
1343     :tangle:   yes
1344     :var:      def=8
1345     :END:
1347 Ahh... as is so often the case, just had to wrap
1348 `org-babel-params-from-properties' in a `save-match-data' form.
1350 #+tblname: why-def-props-cause-probs
1351 | 1 | 2 | 3 | 4 |
1353 #+srcname: default-props-implementation
1354 #+begin_src emacs-lisp :tangle no :var my-lis=why-def-props-cause-probs :results silent
1355 (+ (length my-lis) def)
1356 #+end_src
1358 ** DONE new reference syntax *inside* source code blocks
1359 This is from an email discussion on the org-mode mailing list with
1360 Sébastien.  The goal here is to mimic the source-block reference style
1361 of Noweb.  Upon export and/or tangle these references could be
1362 replaced with the actual body of the referenced source-code block.
1364 See the following for an example.
1366 #+srcname: ems-ruby-print-header
1367 #+begin_src ruby 
1368 puts "---------------------------header---------------------------"
1369 #+end_src
1371 #+srcname: emacs-ruby-print-footer
1372 #+begin_src ruby 
1373 puts "---------------------------footer---------------------------"
1374 #+end_src
1376 #+srcname: ems-ruby-print-message
1377 #+begin_src ruby :file ruby-noweb.rb
1378   # <<ems-ruby-print-header>>
1379   puts "                            Ruby                            "
1380   # <<ems-ruby-print-footer>>
1381 #+end_src
1383 Upon export the previous source-code block would result in a file
1384 being generated at =ruby-noweb.rb= with the following contents
1386 : puts "---------------------------header---------------------------"
1387 : puts "                            Ruby                            "
1388 : puts "---------------------------footer---------------------------"
1390 the body of a source-code block with all =<<src-name>>= references
1391 expanded can now be returned by `org-babel-expand-noweb-references'.
1392 This function is now called by default on all source-code blocks on
1393 export.
1395 ** DONE re-work tangling system
1396 Sometimes when tangling a file (e.g. when extracting elisp from a
1397 org-mode file) we want to get nearly every source-code block.
1399 Sometimes we want to only extract those source-code blocks which
1400 reference a indicate that they should be extracted (e.g. traditional
1401 literate programming along the Noweb model)
1403 I'm not sure how we can devise a single simple tangling system that
1404 naturally fits both of these use cases.
1406 *** new setup
1407 the =tangle= header argument will default to =no= meaning source-code
1408 blocks will *not* be exported by default.  In order for a source-code
1409 block to be tangled it needs to have an output file specified.  This
1410 can happen in two ways...
1412 1) a file-wide default output file can be passed to `org-babel-tangle'
1413    which will then be used for all blocks
1414 2) if the value of the =tangle= header argument is anything other than
1415    =no= or =yes= then it is used as the file name
1417 #+srcname: test-new-tangling
1418 #+begin_src emacs-lisp 
1419   (org-babel-load-file "test-tangle.org")
1420   (if (string= test-tangle-advert "use org-babel-tangle for all your emacs initialization files!!")
1421       "succeed"
1422     "fail")
1423 #+end_src
1425 #+resname:
1426 : succeed
1428 ** DONE =\C-c \C-o= to open results of source block
1429 by adding a =defadvice= to =org-open-at-point= we can use the common
1430 =\C-c \C-o= keybinding to open the results of a source-code block.
1431 This would be especially useful for source-code blocks which generate
1432 graphical results and insert a file link as the results in the
1433 org-mode buffer.  (see [[* figure out how to handle graphic output][TODO figure out how to handle graphic output]]).
1434 This could also act reasonably with other results types...
1436 - file :: use org-open-at-point to open the file
1437 - scalar :: open results unquoted in a new buffer
1438 - tabular :: export the table to a new buffer and open that buffer
1440 when called with a prefix argument the block is re-run
1442 #+srcname: task-opening-results-of-blocks
1443 #+begin_src ditaa :results replace :file blue.png :cmdline -r
1444 +---------+
1445 | cBLU    |
1446 |         |
1447 |    +----+
1448 |    |cPNK|
1449 |    |    |
1450 +----+----+
1451 #+end_src
1453 #+resname:
1454 [[file:blue.png][blue.png]]
1456 #+srcname: task-open-vector
1457 #+begin_src emacs-lisp
1458 '((1 2) (3 4))
1459 #+end_src
1461 #+resname:
1462 | 1 | 2 |
1463 | 3 | 4 |
1465 #+srcname: task-open-scalar
1466 #+begin_src ruby :results output
1467   8.times do |n|
1468     puts "row #{n}"
1469   end
1470 #+end_src
1472 #+resname:
1473 : row 0
1474 : row 1
1475 : row 2
1476 : row 3
1477 : row 4
1478 : row 5
1479 : row 6
1480 : row 7
1482 ** DONE Stop spaces causing vector output
1483 This simple example of multilingual chaining produces vector output if
1484 there are spaces in the message and scalar otherwise.
1486 [Not any more]
1488 #+srcname: msg-from-R(msg=msg-from-python)
1489 #+begin_src R
1490 paste(msg, "und R", sep=" ")
1491 #+end_src
1493 #+resname:
1494 : org-babel speaks elisp y python und R
1496 #+srcname: msg-from-python(msg=msg-from-elisp)
1497 #+begin_src python
1498 msg + " y python"
1499 #+end_src
1501 #+srcname: msg-from-elisp(msg="org-babel speaks")
1502 #+begin_src emacs-lisp
1503 (concat msg " elisp")
1504 #+end_src
1506 ** DONE add =:tangle= family of header arguments
1507 values are
1508 - no :: don't include source-code block when tangling
1509 - yes :: do include source-code block when tangling
1511 this is tested in [[file:test-tangle.org::*Emacs%20Lisp%20initialization%20stuff][test-tangle.org]]
1513 ** DONE extensible library of callable source blocks
1514 *** Current design
1515     This is covered by the [[file:library-of-babel.org][Library of Babel]], which will contain
1516     ready-made source blocks designed to carry out useful common tasks.
1517 *** Initial statement [Eric]
1518     Much of the power of org-R seems to be in it's helper functions for
1519     the quick graphing of tables.  Should we try to re-implement these
1520     functions on top of org-babel?
1522     I'm thinking this may be useful both to add features to org-babel-R and
1523     also to potentially suggest extensions of the framework.  For example
1524     one that comes to mind is the ability to treat a source-code block
1525     like a function which accepts arguments and returns results. Actually
1526     this can be it's own TODO (see [[* source blocks as functions][source blocks as functions]]).
1527 *** Objectives [Dan]
1528     - We want to provide convenient off-the-shelf actions
1529       (e.g. plotting data) that make use of our new code evaluation
1530       environment but do not require any actual coding.
1531 *** Initial Design proposal [Dan]
1532     - *Input data* will be specified using the same mechanism as :var
1533       references, thus the input data may come from a table, or
1534       another source block, and it is initially available as an elisp
1535       data structure.
1536     - We introduce a new #+ line, e.g.  #+BABELDO. C-c C-c on that
1537       line will apply an *action* to the referenced data.
1538     - *Actions correspond to source blocks*: our library of available
1539       actions will be a library of org-babel source blocks. Thus the
1540       code for executing an action, and the code for dealing with the
1541       output of the action will be the same code as for executing
1542       source blocks in general
1543     - Optionally, the user can have the relevant source block inserted
1544       into the org buffer after the (say) #+BABELDO line. This will
1545       allow the user to fine tune the action by modifying the code
1546       (especially useful for plots).
1547     - So maybe a #+BABELDO line will have header args
1548       - :data (a reference to a table or source code block)
1549       - :action (or should that be :srcname?) which will be something
1550         like :action pie-chart, referring to a source block which will
1551         be executed with the :data referent passed in using a :var arg.
1552       - :showcode or something controlling whether to show the code
1553       
1554 *** Modification to design
1555     I'm implementing this, at least initially, as a new interpreter
1556     named 'babel', which has an empty body. 'babel' blocks take
1557     a :srcname header arg, and look for the source-code block with
1558     that name. They then execute the referenced block, after first
1559     appending their own header args on to the target block's header
1560     args.
1562     If the target block is in the library of babel (a.o.t. e.g. the
1563     current buffer), then the code in the block will refer to the
1564     input data with a name dictated by convention (e.g. __data__
1565     (something which is syntactically legal in all languages...). Thus
1566     the babel block will use a :var __data__ = whatever header arg to
1567     reference the data to be plotted.
1569 ** DONE Column names in R input/output
1570    This has been implemented: Automatic on input to R; optional in
1571    output. Note that this equates column names with the header row in
1572    an org table; whereas org actually has a mechanism whereby a row
1573    with a '!' in the first field defines column names. I have not
1574    attempted to support these org table mechanisms yet. See [[*Support%20rownames%20and%20other%20org%20babel%20table%20features][this
1575    DEFERRED todo item]].
1576 ** DONE use example block for large amounts of stdout output?
1577    We're currently `examplizing' with : at the beginning of the line,
1578    but should larger amounts of output be in a
1579    \#+begin_example...\#+end_example block? What's the cutoff? > 1
1580    line?  This would be nice as it would allow folding of lengthy
1581    output. Sometimes one will want to see stdout just to check
1582    everything looks OK, and then fold it away.
1584    I'm addressing this in branch 'examplizing-output'.
1585    Yea, that makes sense.  (either that or allow folding of large
1586    blocks escaped with =:=).
1588    Proposed cutoff of 10 lines, we can save this value in a user
1589    customizable variable.
1590 *** DONE add ability to remove such results
1591 ** DONE exclusive =exports= params
1592    
1593 #+srcname: implement-export-exclusivity
1594 #+begin_src ruby 
1595 :this_is_a_test
1596 #+end_src
1598 #+resname:
1599 : :this_is_a_test
1600 ** DONE LoB: allow output in buffer
1601 ** DONE allow default header arguments by language
1602 org-babel-default-header-args:lang-name
1604 An example of when this is useful is for languages which always return
1605 files as their results (e.g. [[*** ditaa][ditaa]], and [[*** gnuplot][gnuplot]]).
1606 ** DONE singe-function tangling and loading elisp from literate org-mode file [3/3]
1608 This function should tangle the org-mode file for elisp, and then call
1609 `load-file' on the resulting tangled file.
1611 #+srcname: test-loading-embedded-emacs-lisp
1612 #+begin_src emacs-lisp :results replace
1613   (setq test-tangle-advert nil)
1614   (setq test-tangle-loading nil)
1615   (setq results (list :before test-tangle-loading test-tangle-advert))
1616   (org-babel-load-file "test-tangle.org")
1617   (setq results (list (list :after test-tangle-loading test-tangle-advert) results))
1618   (delete-file "test-tangle.el")
1619   (reverse results)
1620 #+end_src
1622 #+resname: test-loading-embedded-emacs-lisp
1623 | :before | nil                 | nil                                                              |
1624 | :after  | "org-babel tangles" | "use org-babel-tangle for all your emacs initialization files!!" |
1626 *** DONE add optional language limiter to org-babel-tangle
1627 This should check to see if there is any need to re-export
1629 *** DONE ensure that org-babel-tangle returns the path to the tangled file(s)
1631 #+srcname: test-return-value-of-org-babel-tangle
1632 #+begin_src emacs-lisp :results replace
1633   (mapcar #'file-name-nondirectory (org-babel-tangle-file "test-tangle.org" "emacs-lisp"))
1634 #+end_src
1636 #+resname:
1637 | "test-tangle.el" |
1639 *** DONE only tangle the file if it's actually necessary
1640 ** DONE add a function to jump to a source-block by name
1641    I've had an initial stab at that in org-babel-find-named-block
1642    (library-of-babel branch).
1644    At the same time I introduced org-babel-named-src-block-regexp, to
1645    match src-blocks with srcname.
1647    This is now working with the command
1648    `org-babel-goto-named-source-block', all we need is a good key
1649    binding.
1651 ** DONE add =:none= session argument (for purely functional execution) [4/4]
1652 This would allow source blocks to be run in their own new process
1654 - These blocks could then also be run in the background (since we can
1655   detach and just wait for the process to signal that it has terminated)
1656 - We wouldn't be drowning in session buffers after running the tests
1657 - we can re-use much of the session code to run in a more /functional/
1658   mode
1660 While session provide a lot of cool features, like persistent
1661 environments, [[* DONE function to bring up inferior-process buffer][pop-to-session]], and hints at exportation for
1662 org-babel-tangle, they also have some down sides and I'm thinking that
1663 session-based execution maybe shouldn't be the default behavior.
1665 Down-sides to sessions
1666 - *much* more complicated than functional evaluation
1667   - maintaining the state of the session has weird issues
1668   - waiting for evaluation to finish
1669   - prompt issues like [[* TODO weird escaped characters in shell prompt break shell evaluation][shell-prompt-escapes-bug]]
1670 - can't run in background
1671 - litter emacs with session buffers
1673 *** DONE ruby
1675 #+srcname: ruby-task-no-session
1676 #+begin_src ruby :results replace output
1677 puts :eric
1678 puts :schulte
1679 [1, 2, 3]
1680 #+end_src
1682 #+resname: ruby-task-no-session
1683 | "eric"    |
1684 | "schulte" |
1685 *** DONE python
1687 #+srcname: task-python-none-session
1688 #+begin_src python :session none :results replace value
1689 print 'something'
1690 print 'output'
1691 [1, 2, 3]
1692 #+end_src
1694 #+resname: task-python-none-session
1695 | 1 | 2 | 3 |
1697 *** DONE sh
1699 #+srcname: task-session-none-sh
1700 #+begin_src sh :results replace
1701 echo "first"
1702 echo "second"
1703 #+end_src
1705 #+resname: task-session-none-sh
1706 | "first"  |
1707 | "second" |
1709 *** DONE R
1711 #+srcname: task-no-session-R
1712 #+begin_src R :results replace output
1713 a <- 8
1714 b <- 9
1715 a + b
1716 b - a
1717 #+end_src
1719 #+resname: task-no-session-R
1720 | "[1]" | 17 |
1721 | "[1]" |  1 |
1723 ** DONE fully purge org-babel-R of direct comint interaction
1724 try to remove all code under the [[file:lisp/org-babel-R.el::functions%20for%20evaluation%20of%20R%20code][;; functions for evaluation of R code]] line
1726 ** DONE Create objects in top level (global) environment [5/5]
1727 *sessions*
1729 *** initial requirement statement [DED]
1730    At the moment, objects created by computations performed in the
1731    code block are evaluated in the scope of the
1732    code-block-function-body and therefore disappear when the code
1733    block is evaluated {unless you employ some extra trickery like
1734    assign('name', object, env=globalenv()) }. I think it will be
1735    desirable to also allow for a style wherein objects that are
1736    created in one code block persist in the R global environment and
1737    can be re-used in a separate block.
1739    This is what Sweave does, and while I'm not saying we have to be
1740    the same as Sweave, it wouldn't be hard for us to provide the same
1741    behaviour in this case; if we don't, we risk undeservedly being
1742    written off as an oddity by some.
1744    IOW one aspect of org-babel is that of a sort of functional
1745    meta-programming language. This is crazy, in a very good
1746    way. Nevertheless, wrt R I think there's going to be a lot of value
1747    in providing for a working style in which the objects are stored in
1748    the R session, rather than elisp/org buffer. This will be a very
1749    familiar working style to lots of people.
1751    There are no doubt a number of different ways of accomplishing
1752    this, the simplest being a hack like adding
1754 #+begin_src R
1755 for(objname in ls())
1756     assign(objname, get(objname), envir=globalenv())
1757 #+end_src
1759 to the source code block function body. (Maybe wrap it in an on.exit() call).
1761 However this may deserve to be thought about more carefully, perhaps
1762 with a view to having a uniform approach across languages. E.g. shell
1763 code blocks have the same semantics at the moment (no persistence of
1764 variables across code blocks), because the body is evaluated in a new
1765 bash shell process rather than a running shell. And I guess the same
1766 is true for python. However, in both these cases, you could imagine
1767 implementing the alternative in which the body is evaluated in a
1768 persistent interactive session. It's just that it's particularly
1769 natural for R, seeing as both ESS and org-babel evaluate commands in a
1770 single persistent R session.
1772 *** sessions [Eric]
1774 Thanks for bringing this up.  I think you are absolutely correct that we
1775 should provide support for a persistent environment (maybe called a
1776 *session*) in which to evaluate code blocks.  I think the current setup
1777 demonstrates my personal bias for a functional style of programming
1778 which is certainly not ideal in all contexts.
1780 While the R function you mention does look like an elegant solution, I
1781 think we should choose an implementation that would be the same across
1782 all source code types.  Specifically I think we should allow the user to
1783 specify an optional *session* as a header variable (when not present we
1784 assume a default session for each language).  The session name could be
1785 used to name a comint buffer (like the *R* buffer) in which all
1786 evaluation would take place (within which variables would retain their
1787 values --at least once I remove some of the functional method wrappings
1788 currently in place-- ).
1790 This would allow multiple environments to be used in the same buffer,
1791 and once this setup was implemented we should be able to fairly easily
1792 implement commands for jumping between source code blocks and the
1793 related session buffers, as well as for dumping the last N commands from
1794 a session into a new or existing source code block.
1796 Please let me know if you foresee any problems with this proposed setup,
1797 or if you think any parts might be confusing for people coming from
1798 Sweave.  I'll hopefully find some time to work on this later in the
1799 week.
1801 *** can functional and interpreted/interactive models coexist?
1803 Even though both of these use the same =*R*= buffer the value of =a=
1804 is not preserved because it is assigned inside of a functional
1805 wrapper.
1807 #+srcname: task-R-sessions
1808 #+begin_src R 
1809 a <- 9
1810 b <- 21
1811 a + b
1812 #+end_src
1814 #+srcname: task-R-same-session
1815 #+begin_src R 
1817 #+end_src
1819 This functional wrapper was implemented in order to efficiently return
1820 the results of the execution of the entire source code block.  However
1821 it inhibits the evaluation of source code blocks in the top level,
1822 which would allow for persistence of variable assignment across
1823 evaluations.  How can we allow *both* evaluation in the top level, and
1824 efficient capture of the return value of an entire source code block
1825 in a language independent manner?
1827 Possible solutions...
1828 1) we can't so we will have to implement two types of evaluation
1829    depending on which is appropriate (functional or imperative)
1830 2) we remove the functional wrapper and parse the source code block
1831    into it's top level statements (most often but not always on line
1832    breaks) so that we can isolate the final segment which is our
1833    return value.
1834 3) we add some sort of "#+return" line to the code block
1835 4) we take advantage of each languages support for meta-programming
1836    through =eval= type functions, and use said to evaluate the entire
1837    blocks in such a way that their environment can be combined with the
1838    global environment, and their results are still captured.
1839 5) I believe that most modern languages which support interactive
1840    sessions have support for a =last_result= type function, which
1841    returns the result of the last input without re-calculation.  If
1842    widely enough present this would be the ideal solution to a
1843    combination of functional and imperative styles.
1845 None of these solutions seem very desirable, but for now I don't see
1846 what else would be possible.
1848 Of these options I was leaning towards (1) and (4) but now believe
1849 that if it is possible option (5) will be ideal.
1851 **** (1) both functional and imperative evaluation
1852 Pros
1853 - can take advantage of built in functions for sending regions to the
1854   inferior process
1855 - retains the proven tested and working functional wrappers
1857 Cons
1858 - introduces the complication of keeping track of which type of
1859   evaluation is best suited to a particular context
1860 - the current functional wrappers may require some changes in order to
1861   include the existing global context
1863 **** (4) exploit language meta-programming constructs to explicitly evaluate code
1864 Pros
1865 - only one type of evaluation
1867 Cons
1868 - some languages may not have sufficient meta-programming constructs
1870 **** (5) exploit some =last_value= functionality if present
1872 Need to ensure that most languages have such a function, those without
1873 will simply have to implement their own similar solution...
1875 | language   | =last_value= function       |
1876 |------------+-----------------------------|
1877 | R          | .Last.value                 |
1878 | ruby       | _                           |
1879 | python     | _                           |
1880 | shell      | see [[* last command for shells][last command for shells]] |
1881 | emacs-lisp | see [[* emacs-lisp will be a special case][special-case]]            |
1883 #+srcname: task-last-value
1884 #+begin_src ruby
1885 82 + 18
1886 #+end_src
1888 ***** last command for shells
1889 Do this using the =tee= shell command, and continually pipe the output
1890 to a file.
1892 Got this idea from the following [[http://linux.derkeiler.com/Mailing-Lists/Fedora/2004-01/0898.html][email-thread]].
1894 suggested from mailing list
1896 #+srcname: bash-save-last-output-to-file
1897 #+begin_src sh 
1898 while read line 
1899 do 
1900   bash -c "$line" | tee /tmp/last.out1 
1901   mv /tmp/last.out1 /tmp/last.out 
1902 done
1903 #+end_src
1905 another proposed solution from the above thread
1907 #+srcname: bash-save-in-variable
1908 #+begin_src sh 
1909 #!/bin/bash 
1910 # so - Save Output. Saves output of command in OUT shell variable. 
1911 OUT=`$*` 
1912 echo $OUT 
1913 #+end_src
1915 and another
1917 #+begin_quote
1918 .inputrc: 
1919 "^[k": accept-line 
1920 "^M": " | tee /tmp/h_lastcmd.out ^[k" 
1922 .bash_profile: 
1923 export __=/tmp/h_lastcmd.out 
1925 If you try it, Alt-k will stand for the old Enter; use "command $__" to 
1926 access the last output. 
1928 Best, 
1932 Herculano de Lima Einloft Neto
1933 #+end_quote
1935 ***** emacs-lisp will be a special case
1936 While it is possible for emacs-lisp to be run in a console type
1937 environment (see the =elim= function) it is *not* possible to run
1938 emacs-lisp in a different *session*.  Meaning any variable set top
1939 level of the console environment will be set *everywhere* inside
1940 emacs.  For this reason I think that it doesn't make any sense to
1941 worry about session support for emacs-lisp.
1943 *** Further thoughts on 'scripting' vs. functional approaches
1945     These are just thoughts, I don't know how sure I am about this.
1946     And again, perhaps I'm not saying anything very radical, just that
1947     it would be nice to have some options supporting things like
1948     receiving text output in the org buffer.
1950     I can see that you've already gone some way down the road towards
1951     the 'last value' approach, so sorry if my comments come rather
1952     late. I am concerned that we are not giving sufficient attention
1953     to stdout / the text that is returned by the interpreters. In
1954     contrast, many of our potential users will be accustomed to a
1955     'scripting' approach, where they are outputting text at various
1956     points in the code block, not just at the end. I am leaning
1957     towards thinking that we should have 2 modes of evaluation:
1958     'script' mode, and 'functional' mode.
1960     In script mode, evaluation of a code block would result in *all*
1961     text output from that code block appearing as output in the org
1962     buffer, presumably as an #+begin_example...#+end_example. There
1963     could be an :echo option controlling whether the input commands
1964     also appear in the output. [This is like Sweave].
1966     In functional mode, the *result* of the code block is available as
1967     an elisp object, and may appear in the org buffer as an org
1968     table/string, via the mechanisms you have developed already.
1970     One thing I'm wondering about is whether, in script mode, there
1971     simply should not be a return value. Perhaps this is not so
1972     different from what exists: script mode would be new, and what
1973     exists currently would be functional mode.
1975     I think it's likely that, while code evaluation will be exciting
1976     to people, a large majority of our users in a large majority of
1977     their usage will not attempt to actually use the return value from
1978     a source code block in any meaningful way. In that case, it seems
1979     rather restrictive to only allow them to see output from the end
1980     of the code block.
1982     Instead I think the most accessible way to introduce org-babel to
1983     people, at least while they are learning it, is as an immensely
1984     powerful environment in which to embed their 'scripts', which now
1985     also allows them to 'run' their 'scripts'. Especially as such
1986     people are likely to be the least capable of the user-base, a
1987     possible design-rule would be to make the scripting style of usage
1988     easy (default?), perhaps requiring a special option to enable a
1989     functional style. Those who will use the functional style won't
1990     have a problem understanding what's going on, whereas the 'skript
1991     kiddies' might not even know the syntax for defining a function in
1992     their language of choice. And of course we can allow the user to
1993     set a variable in their .emacs controlling the preference, so that
1994     functional users are not inconveniennced by having to provide
1995     header args the whole time.
1997     Please don't get the impression that I am down-valuing the
1998     functional style of org-babel. I am constantly horrified at the
1999     messy 'scripts' that my colleagues produce in perl or R or
2000     whatever! Nevertheless that seems to be how a lot of people work.
2001     
2002     I think you were leaning towards the last-value approach because
2003     it offered the possibility of unified code supporting both the
2004     single evaluation environment and the functional style. If you
2005     agree with any of the above then perhaps it will impact upon this
2006     and mean that the code in the two branches has to differ a bit. In
2007     that case, functional mode could perhaps after all evaluate each
2008     code block in its own environment, thus (re)approaching 'true'
2009     functional programming (side-effects are hard to achieve).
2011 #+begin_src sh
2012 ls > files
2013 echo "There are `wc -l files` files in this directory"
2015 #+end_src
2017 *** even more thoughts on evaluation, results, models and options
2019 Thanks Dan, These comments are invaluable.
2021 What do you think about this as a new list of priorities/requirements
2022 for the execution of source-code blocks.
2024 - Sessions
2025    1)  we want the evaluation of the source code block to take place in a
2026        session which can persist state (variables, current directory,
2027        etc...).
2028    2)  source code blocks can specify their session with a header argument
2029    3)  each session should correspond to an Emacs comint buffer so that the
2030        user can drop into the session and experiment with live code
2031        evaluation.
2032 - Results
2033   1) each source-code block generates some form of results which (as
2034      we have already implemented) is transfered into emacs-lisp
2035      after which it can be inserted into the org-mode buffer, or
2036      used by other source-code blocks
2037   2) when the results are translated into emacs-lisp, forced to be
2038      interpreted as a scalar (dumping their raw values into the
2039      org-mode buffer), as a vector (which is often desirable with R
2040      code blocks), or interpreted on the fly (the default option).
2041      Note that this is very nearly currently implemented through the
2042      [[* DONE results-type header (vector/file)][results-type-header]].
2043   3) there should be *two* means of collecting results from the
2044      execution of a source code block.  *Either* the value of the
2045      last statement of the source code block, or the collection of
2046      all that has been passed to STDOUT during the evaluation.
2048 **** header argument or return line (*header argument*)
2050    Rather than using a header argument to specify how the return value
2051    should be passed back, I'm leaning towards the use of a =#+RETURN=
2052    line inside the block.  If such a line *is not present* then we
2053    default to using STDOUT to collect results, but if such a line *is
2054    present* then we use it's value as the results of the block.  I
2055    think this will allow for the most elegant specification between
2056    functional and script execution.  This also cleans up some issues
2057    of implementation and finding which statement is the last
2058    statement.
2060    Having given this more thought, I think a header argument is
2061    preferable.  The =#+return:= line adds new complicating syntax for
2062    something that does little more than we would accomplish through
2063    the addition of a header argument.  The only benefit being that we
2064    know where the final statement starts, which is not an issue in
2065    those languages which contain 'last value' operators.
2067    new header =:results= arguments
2068    - script :: explicitly states that we want to use STDOUT to
2069                initialize our results
2070    - return_last :: stdout is ignored instead the *value* of the final
2071                     statement in the block is returned
2072    - echo :: means echo the contents of the source-code block along
2073              with the results (this implies the *script* =:results=
2074              argument as well)
2076 *** DONE rework evaluation lang-by-lang [4/4]
2078 This should include...
2079 - functional results working with the comint buffer
2080 - results headers
2081   - script :: return the output of STDOUT
2082     - write a macro which runs the first redirection, executes the
2083       body, then runs the second redirection
2084   - last :: return the value of the last statement
2085     - 
2087 - sessions in comint buffers
2089 **** DONE Ruby [4/4]
2090 - [X] functional results working with comint
2091 - [X] script results
2092 - [X] ensure scalar/vector results args are taken into consideration
2093 - [X] ensure callable by other source block
2095 #+srcname: ruby-use-last-output
2096 #+begin_src ruby :results replace
2097 a = 2
2098 b = 4
2099 c = a + b
2100 [a, b, c, 78]
2101 #+end_src
2103 #+resname: ruby-use-last-output
2104 | 2 | 4 | 6 | 78 |
2106 #+srcname: task-call-use-last-output
2107 #+begin_src ruby :var last=ruby-use-last-output :results replace
2108 last.flatten.size + 1
2109 #+end_src
2111 #+resname: task-call-use-last-output
2112 : 5
2114 ***** ruby sessions
2116 #+srcname: first-ruby-session-task
2117 #+begin_src ruby :session schulte :results silent
2118 schulte = 27
2119 #+end_src
2121 #+srcname: second-ruby-session-task
2122 #+begin_src ruby :session schulte :results silent
2123 schulte + 3
2124 #+end_src
2126 #+srcname: without-the-right-session
2127 #+begin_src ruby :results silent
2128 schulte
2129 #+end_src
2131 **** DONE R [4/4]
2133 - [X] functional results working with comint
2134 - [X] script results
2135 - [X] ensure scalar/vector results args are taken into consideration
2136 - [X] ensure callable by other source block
2138 To redirect output to a file, you can use the =sink()= command.
2140 #+srcname: task_R_B
2141 #+begin_src R :results value vector silent
2142 a <- 9
2143 b <- 10
2144 b - a
2145 a + b
2146 #+end_src
2148 #+srcname: task-R-use-other-output
2149 #+begin_src R :var twoentyseven=task_R_B() :results replace value
2151 twoentyseven + 9
2152 #+end_src
2154 #+resname: task-R-use-other-output
2155 : 28
2157 **** DONE Python [4/4]
2158 - [X] functional results working with comint
2159 - [X] script results
2160 - [X] ensure scalar/vector results args are taken into consideration
2161 - [X] ensure callable by other source block
2163 #+srcname: task-new-eval-for-python
2164 #+begin_src python :results silent output scalar
2168 #+end_src
2170 #+srcname: task-use-new-eval
2171 #+begin_src python :var tasking=task-new-eval-for-python() :results replace
2172 tasking + 2
2173 #+end_src
2175 #+resname: task-use-new-eval
2176 : 12
2178 **** DONE Shells [4/4]
2179 - [X] functional results working with comint
2180 - [X] script results
2181 - [X] ensure scalar/vector results args are taken into consideration
2182 - [X] ensure callable by other source block
2184 #+srcname: task-shell-new-evaluation
2185 #+begin_src sh :results silent value scalar
2186 echo 'eric'
2187 date
2188 #+end_src
2190 #+srcname: task-call-other-shell
2191 #+begin_src sh :var other=task-shell-new-evaluation() :results replace  scalar
2192 echo $other ' is the old date'
2193 #+end_src
2195 #+resname: task-call-other-shell
2196 : $ Fri Jun 12 13:08:37 PDT 2009  is the old date
2198 *** DONE implement a *session* header argument [4/4]
2199 =:session= header argument to override the default *session* buffer
2201 **** DONE ruby
2203 #+srcname: task-ruby-named-session
2204 #+begin_src ruby :session schulte :results replace
2205 schulte = :in_schulte
2206 #+end_src
2208 #+resname: task-ruby-named-session
2209 : :in_schulte
2211 #+srcname: another-in-schulte
2212 #+begin_src ruby :session schulte 
2213 schulte
2214 #+end_src
2216 #+resname: another-in-schulte
2217 : :in_schulte
2218 : :in_schulte
2219 : :in_schulte
2221 **** DONE python
2223 #+srcname: python-session-task
2224 #+begin_src python :session what :results silent
2225 what = 98
2226 #+end_src
2228 #+srcname: python-get-from-session
2229 #+begin_src python :session what :results replace
2230 what
2231 #+end_src
2233 #+resname: python-get-from-session
2234 : 98
2236 **** DONE shell
2238 #+srcname: task-shell-sessions
2239 #+begin_src sh :session what
2240 WHAT='patton'
2241 #+end_src
2243 #+srcname: task-shell-sessions-what
2244 #+begin_src sh :session what :results replace
2245 echo $WHAT
2246 #+end_src
2248 #+resname: task-shell-sessions-what
2249 : patton
2251 **** DONE R
2253 #+srcname: task-R-session
2254 #+begin_src R :session what :results replace
2255 a <- 9
2256 b <- 8
2257 a + b
2258 #+end_src
2260 #+resname: task-R-session
2261 : 17
2263 #+srcname: another-task-R-session
2264 #+begin_src R :session what :results replace
2265 a + b
2266 #+end_src
2268 *** DONE function to bring up inferior-process buffer [4/4]
2270 This should be callable from inside of a source-code block in an
2271 org-mode buffer.  It should evaluate the header arguments, then bring
2272 up the inf-proc buffer using =pop-to-buffer=.
2274 For lack of a better place, lets add this to the `org-metadown-hook'
2275 hook.
2277 To give this a try, place the cursor on a source block with variables,
2278 (optionally git a prefix argument) then hold meta and press down.
2280 **** DONE ruby
2282 #+srcname: task-ruby-pop-to-session
2283 #+begin_src ruby :var num=9 :var another="something else"
2284 num.times{|n| puts another}
2285 #+end_src
2287 **** DONE python
2289 #+srcname: task-python-pop-to-session
2290 #+begin_src python :var num=9 :var another="something else"
2291 another * num
2292 #+end_src
2293 **** DONE R
2295 #+srcname: task-R-pop-to-session
2296 #+begin_src R :var a=9 :var b=8
2297 a * b
2298 #+end_src
2300 **** DONE shell
2302 #+srcname: task-shell-pop-sessions
2303 #+begin_src sh :var NAME="eric"
2304 echo $NAME
2305 #+end_src
2307 *** DEFERRED function to dump last N lines from inf-proc buffer into the current source block
2309 Callable with a prefix argument to specify how many lines should be
2310 dumped into the source-code buffer.
2312 *** REJECTED comint notes
2314 Implementing comint integration in [[file:lisp/org-babel-comint.el][org-babel-comint.el]].
2316 Need to have...
2317 - handling of outputs
2318   - split raw output from process by prompts
2319   - a ring of the outputs, buffer-local, `org-babel-comint-output-ring'
2320   - a switch for dumping all outputs to a buffer
2321 - inputting commands
2323 Lets drop all this language specific stuff, and just use
2324 org-babel-comint to split up our outputs, and return either the last
2325 value of an execution or the combination of values from the
2326 executions.
2328 **** comint filter functions
2329 : ;;  comint-input-filter-functions     hook    process-in-a-buffer
2330 : ;;  comint-output-filter-functions    hook    function modes.
2331 : ;;  comint-preoutput-filter-functions   hook
2332 : ;;  comint-input-filter                       function ...
2334 #+srcname: obc-filter-ruby
2335 #+begin_src ruby :results last
2341 #+end_src
2343 ** DONE Remove protective commas from # comments before evaluating
2344    org inserts protective commas in front of ## comments in language
2345    modes that use them. We need to remove them prior to sending code
2346    to the interpreter.
2348 #+srcname: testing-removal-of-protective-comas
2349 #+begin_src ruby
2350 ,# this one might break it??
2351 :comma_protection
2352 #+end_src
2354 ** DONE pass multiple reference arguments into R
2355    Can we do this? I wasn't sure how to supply multiple 'var' header
2356    args. Just delete this if I'm being dense.
2358    This should be working, see the following example...
2360 #+srcname: two-arg-example
2361 #+begin_src R :var n=2 :var m=8
2362 n + m
2363 #+end_src
2365 #+resname: two-arg-example
2366 : 10
2368 ** DONE ensure that table ranges work
2369 when a table range is passed to org-babel as an argument, it should be
2370 interpreted as a vector.
2372 | 1 | 2 | simple       |
2373 | 2 | 3 | Fixnum:1     |
2374 | 3 | 4 | Array:123456 |
2375 | 4 | 5 |              |
2376 | 5 | 6 |              |
2377 | 6 | 7 |              |
2378 #+TBLFM: @1$3='(sbe simple-sbe-example (n 4))::@2$3='(sbe task-table-range (n @1$1..@6$1))::@3$3='(sbe task-table-range (n (@1$1..@6$1)))
2380 #+srcname: simple-sbe-example
2381 #+begin_src emacs-lisp 
2382 "simple"
2383 #+end_src
2385 #+srcname: task-table-range
2386 #+begin_src ruby :var n=simple-sbe-example
2387 "#{n.class}:#{n}"
2388 #+end_src
2390 #+srcname: simple-results
2391 #+begin_src emacs-lisp :var n=task-table-range(n=(1 2 3))
2393 #+end_src
2395 #+resname: simple-results
2396 : Array:123
2398 #+srcname: task-arr-referent
2399 #+begin_src ruby :var ar=(1 2 3)
2400 ar.size
2401 #+end_src
2403 #+resname: task-arr-referent
2404 : 3
2406 ** DONE global variable indicating default to vector output
2407 how about an alist... =org-babel-default-header-args= this may already
2408 exist... just execute the following and all source blocks will default
2409 to vector output
2411 #+begin_src emacs-lisp 
2412 (setq org-babel-default-header-args '((:results . "vector")))
2413 #+end_src
2415 ** DONE name named results if source block is named
2416 currently this isn't happening although it should be
2418 #+srcname: test-naming-named-source-blocks
2419 #+begin_src emacs-lisp 
2420 :namer
2421 #+end_src
2423 #+resname: test-naming-named-source-blocks
2424 : :namer
2425 ** DONE (simple caching) check for named results before source blocks
2426 see the TODO comment in [[file:lisp/org-babel-ref.el::TODO%20This%20should%20explicitly%20look%20for%20resname%20lines%20before][org-babel-ref.el#org-babel-ref-resolve-reference]]
2427 ** DONE set =:results silent= when eval with prefix argument
2429 #+begin_src emacs-lisp
2430 'silentp
2431 #+end_src
2432 ** DONE results-type header (vector/file) [3/3]
2433    In response to a point in Dan's email.  We should allow the user to
2434    force scalar or vector results.  This could be done with a header
2435    argument, and the default behavior could be controlled through a
2436    configuration variable.
2437    
2438 #+srcname: task-trivial-vector
2439 #+begin_src ruby :results replace vector
2440 :scalar
2441 #+end_src
2443 #+resname:
2444 | ":scalar" |
2446    since it doesn't make sense to turn a vector into a scalar, lets
2447    just add a two values...
2448    
2449    - vector :: forces the results to be a vector (potentially 1 dimensional)
2450    - file :: this throws an error if the result isn't a string, and
2451              tries to treat it as a path to a file.
2453    I'm just going to cram all of these into the =:results= header
2454    argument.  Then if we allow multiple header arguments it should
2455    work out, for example one possible header argument string could be
2456    =:results replace vector file=, which would *replace* any existing
2457    results forcing the results into an org-mode table, and
2458    interpreting any strings as file paths.
2460 *** DONE multiple =:results= headers
2462 #+srcname: multiple-result-headers
2463 #+begin_src ruby :results replace silent
2464 :schulte
2465 #+end_src
2467 #+resname:
2469 *** DONE file result types
2470 When inserting into an org-mode buffer create a link with the path
2471 being the value, and optionally the display being the
2472 =file-name-nondirectory= if it exists.
2474 #+srcname: task-file-result
2475 #+begin_src python :results replace file
2476 "something"
2477 #+end_src
2479 #+resname:
2480 [[something][something]]
2483 This will be useful because blocks like =ditaa= and =dot= can return
2484 the string path of their files, and can add =file= to their results
2485 header.
2487 *** DONE vector result types
2489 #+srcname: task-force-results
2490 #+begin_src emacs-lisp :results vector
2492 #+end_src
2494 #+resname:
2495 | 8 |
2497 ** DONE results name
2498     In order to do this we will need to start naming our results.
2499     Since the source blocks are named with =#+srcname:= lines we can
2500     name results with =#+resname:= lines (if the source block has no
2501     name then no name is given to the =#+resname:= line on creation,
2502     otherwise the name of the source block is used).
2504     This will have the additional benefit of allowing results and
2505     source blocks to be located in different places in a buffer (and
2506     eventually in different buffers entirely).
2508 #+srcname: developing-resnames
2509 #+begin_src emacs-lisp  :results silent
2510 'schulte
2511 #+end_src
2513     Once source blocks are able to find their own =#+resname:= lines
2514     we then need to...
2516 #+srcname: sbe-w-new-results
2517 #+begin_src emacs-lisp :results replace
2518 (sbe "developing-resnames")
2519 #+end_src
2521 #+resname:
2522 : schulte
2524 *** TODO change the results insertion functions to use these lines
2526 *** TODO teach references to resolve =#+resname= lines.
2528 ** DONE org-babel tests org-babel [1/1]
2529 since we are accumulating this nice collection of source-code blocks
2530 in the sandbox section we should make use of them as unit tests.
2531 What's more, we should be able to actually use org-babel to run these
2532 tests.
2534 We would just need to cycle over every source code block under the
2535 sandbox, run it, and assert that the return value is equal to what we
2536 expect.
2538 I have the feeling that this should be possible using only org-babel
2539 functions with minimal or no additional elisp.  It would be very cool
2540 for org-babel to be able to test itself.
2542 This is now done, see [[* Tests]].
2544 *** DEFERRED org-babel assertions (may not be necessary)
2545 These could be used to make assertions about the results of a
2546 source-code block.  If the assertion fails then the point could be
2547 moved to the block, and error messages and highlighting etc... could
2548 ensue
2550 ** DONE make C-c C-c work anywhere within source code block?
2551    This seems like it would be nice to me, but perhaps it would be
2552    inefficient or ugly in implementation? I suppose you could search
2553    forward, and if you find #+end_src before you find #+begin_src,
2554    then you're inside one. [DED]
2556    Agreed, I think inside of the =#+srcname: line= would be useful as
2557    well.
2559 #+srcname: testing-out-cc
2560 #+begin_src emacs-lisp
2561 'schulte
2562 #+end_src
2564 ** DONE integration with org tables
2565 We should make it easy to call org-babel source blocks from org-mode
2566 table formulas.  This is practical now that it is possible to pass
2567 arguments to org-babel source blocks.
2569 See the related [[* (sandbox) integration w/org tables][sandbox]] header for tests/examples.
2571 *** digging in org-table.el
2572 In the past [[file:~/src/org/lisp/org-table.el::org%20table%20el%20The%20table%20editor%20for%20Org%20mode][org-table.el]] has proven difficult to work with.
2574 Should be a hook in [[file:~/src/org/lisp/org-table.el::defun%20org%20table%20eval%20formula%20optional%20arg%20equation][org-table-eval-formula]].
2576 Looks like I need to change this [[file:~/src/org/lisp/org-table.el::if%20lispp][if statement]] (line 2239) into a cond
2577 expression.
2579 ** DONE source blocks as functions
2581 Allow source code blocks to be called like functions, with arguments
2582 specified.  We are already able to call a source-code block and assign
2583 it's return result to a variable.  This would just add the ability to
2584 specify the values of the arguments to the source code block assuming
2585 any exist.  For an example see 
2587 When a variable appears in a header argument, how do we differentiate
2588 between it's value being a reference or a literal value?  I guess this
2589 could work just like a programming language.  If it's escaped or in
2590 quotes, then we count it as a literal, otherwise we try to look it up
2591 and evaluate it.
2593 ** DONE folding of code blocks? [2/2]
2594    [DED] In similar way to using outline-minor-mode for folding function
2595    bodies, can we fold code blocks?  #+begin whatever statements are
2596    pretty ugly, and in any case when you're thinking about the overall
2597    game plan you don't necessarily want to see the code for each Step.
2599 *** DONE folding of source code block
2600     Sounds good, and wasn't too hard to implement.  Code blocks should
2601     now be fold-able in the same manner as headlines (by pressing TAB
2602     on the first line).
2604 *** REJECTED folding of results
2605     So, lets do a three-stage tab cycle... First fold the src block,
2606     then fold the results, then unfold.
2607     
2608     There's no way to tell if the results are a table or not w/o
2609     actually executing the block which would be too expensive of an
2610     operation.
2612 ** DONE selective export of text, code, figures
2613    [DED] The org-babel buffer contains everything (code, headings and
2614    notes/prose describing what you're up to, textual/numeric/graphical
2615    code output, etc). However on export to html / LaTeX one might want
2616    to include only a subset of that content. For example you might
2617    want to create a presentation of what you've done which omits the
2618    code.
2620    [EMS] So I think this should be implemented as a property which can
2621    be set globally or on the outline header level (I need to review
2622    the mechanics of org-mode properties).  And then as a source block
2623    header argument which will apply only to a specific source code
2624    block.  A header argument of =:export= with values of
2625    
2626    - =code= :: just show the code in the source code block
2627    - =none= :: don't show the code or the results of the evaluation
2628    - =results= :: just show the results of the code evaluation (don't
2629                   show the actual code)
2630    - =both= :: show both the source code, and the results
2632 this will be done in [[* (sandbox) selective export][(sandbox) selective export]].
2634 ** DONE a header argument specifying silent evaluation (no output)
2635 This would be useful across all types of source block.  Currently
2636 there is a =:replace t= option to control output, this could be
2637 generalized to an =:output= option which could take the following
2638 options (maybe more)
2640 - =t= :: this would be the default, and would simply insert the
2641          results after the source block
2642 - =replace= :: to replace any results which may already be there
2643 - =silent= :: this would inhibit any insertion of the results
2645 This is now implemented see the example in the [[* silent evaluation][sandbox]]
2647 ** DONE assign variables from tables in R
2648 This is now working (see [[* (sandbox table) R][(sandbox-table)-R]]).  Although it's not that
2649 impressive until we are able to print table results from R.
2651 ** DONE insert 2-D R results as tables
2652 everything is working but R and shell
2654 *** DONE shells
2656 *** DONE R
2658 This has already been tackled by Dan in [[file:existing_tools/org-R.el::defconst%20org%20R%20write%20org%20table%20def][org-R:check-dimensions]].  The
2659 functions there should be useful in combination with [[http://cran.r-project.org/doc/manuals/R-data.html#Export-to-text-files][R-export-to-csv]]
2660 as a means of converting multidimensional R objects to emacs lisp.
2662 It may be as simple as first checking if the data is multidimensional,
2663 and then, if so using =write= to write the data out to a temporary
2664 file from which emacs can read the data in using =org-table-import=.
2666 Looking into this further, is seems that there is no such thing as a
2667 scalar in R [[http://tolstoy.newcastle.edu.au/R/help/03a/3733.html][R-scalar-vs-vector]]  In that light I am not sure how to
2668 deal with trivial vectors (scalars) in R.  I'm tempted to just treat
2669 them as vectors, but then that would lead to a proliferation of
2670 trivial 1-cell tables...
2672 ** DONE allow variable initialization from source blocks
2673 Currently it is possible to initialize a variable from an org-mode
2674 table with a block argument like =table=sandbox= (note that the
2675 variable doesn't have to named =table=) as in the following example
2677 #+TBLNAME: sandbox
2678 | 1 |       2 | 3 |
2679 | 4 | schulte | 6 |
2681 #+begin_src emacs-lisp :var table=sandbox :results replace
2682 (message (format "table = %S" table))
2683 #+end_src
2685 : "table = ((1 2 3) (4 \"schulte\" 6))"
2687 It would be good to allow initialization of variables from the results
2688 of other source blocks in the same manner.  This would probably
2689 require the addition of =#+SRCNAME: example= lines for the naming of
2690 source blocks, also the =table=sandbox= syntax may have to be expanded
2691 to specify whether the target is a source code block or a table
2692 (alternately we could just match the first one with the given name
2693 whether it's a table or a source code block).
2695 At least initially I'll try to implement this so that there is no need
2696 to specify whether the reference is to a table or a source-code block.
2697 That seems to be simpler both in terms of use and implementation.
2699 This is now working for emacs-lisp, ruby and python (and mixtures of
2700 the three) source blocks.  See the examples in the [[* (sandbox) referencing other source blocks][sandbox]].
2702 This is currently working only with emacs lisp as in the following
2703 example in the [[* emacs lisp source reference][emacs lisp source reference]].
2706 ** TODO Add languages [11/16]
2707 I'm sure there are many more that aren't listed here.  Please add
2708 them, and bubble any that you particularly care about up to the top.
2710 Any new language should be implemented in a org-babel-lang.el file.
2711 Follow the pattern set by [[file:lisp/org-babel-script.el][org-babel-script.el]], [[file:lisp/org-babel-shell.el][org-babel-shell.el]] and
2712 [[file:lisp/org-babel-R.el][org-babel-R.el]].
2714 *** STARTED Haskell
2715 #+begin_src haskell
2716 "hello Haskell"
2717 #+end_src
2719 #+resname:
2720 : hello Haskell
2722 #+begin_src haskell
2723   let fac n = if n == 0 then 1 else n * fac (n - 1)
2724   fac 4
2725 #+end_src
2727 #+resname:
2728 : 24
2730 #+begin_src haskell
2731 [1, 2, 3, 4, 5]
2732 #+end_src
2734 #+resname:
2735 | 1 | 2 | 3 | 4 | 5 |
2737 **** allow non-interactive evaluation
2739 *** STARTED ocaml [2/3]
2741 - [X] Working for the simple case (no arguments, simple output)
2742 - [X] correct handling of vector/list output
2743 - [ ] ability to import arguments
2745 #+begin_src ocaml
2746 let rec fib x =
2747   match x with
2748     | 0 -> 1
2749     | 1 -> 1
2750     | n -> fib(n - 1) + fib(n - 2) in
2751   fib 12
2752 #+end_src
2754 #+resname:
2755 : 233
2757 #+begin_src ocaml
2758 "string"
2759 #+end_src
2761 #+resname:
2762 : "string"
2764 #+begin_src ocaml
2765 [1; 2; 3; 4]
2766 #+end_src
2768 #+resname:
2769 | 1 | 2 | 3 | 4 |
2771 #+begin_src ocaml
2772 [|"ocaml"; "array"|]
2773 #+end_src
2775 #+resname:
2776 | "ocaml" | "array" |
2778 *** TODO perl
2779 This could probably be added to [[file:lisp/org-babel-script.el][org-babel-script.el]]
2780 *** TODO java
2781 *** STARTED SQL
2782 Things left to do
2783 - support for sessions
2784 - add more useful header arguments (user, passwd, database, etc...)
2785 - support for more engines (currently only supports mysql)
2786 - what's a reasonable way to drop table data into SQL?
2788 #+srcname: sql-example
2789 #+begin_src sql :engine mysql
2790   show databases
2791 #+end_src
2793 #+resname:
2794 | "Database"           |
2795 | "information_schema" |
2796 | "test"               |
2798 *** DONE SASS
2799 Sass is a very nice extension of CSS, which is much nicer to read and
2800 write (see [[http://sass-lang.com/][sass-lang]]).
2802 #+srcname: sass-example
2803 #+begin_src sass :file stylesheet.css :results file
2804   #me
2805     position: absolute
2806     top: 1em
2807     left: 1em
2808     .head
2809       text-align: center
2810 #+end_src
2812 #+resname:
2813 [[file:stylesheet.css][stylesheet.css]]
2815 *** DONE CSS
2816 trivial [[file:lisp/langs/org-babel-css.el][org-babel-css.el]]
2818 *** DONE ditaa
2819 (see [[* file result types][file result types]])
2821 #+srcname: implementing-ditaa
2822 #+begin_src ditaa :results replace :file blue.png :cmdline -r
2823 +---------+
2824 | cBLU    |
2825 |         |
2826 |    +----+
2827 |    |cPNK|
2828 |    |    |
2829 +----+----+
2830 #+end_src
2832 #+resname: implementing-ditaa
2833 [[file:blue.png][blue.png]]
2835 *** DONE gnuplot [7/7]
2836 (see [[* file result types][file result types]])
2838 #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
2839 #+TBLNAME: gnuplot-data
2840 | independent var | first dependent var | second dependent var |
2841 |-----------------+---------------------+----------------------|
2842 |             0.1 |               0.425 |                0.375 |
2843 |             0.2 |              0.3125 |               0.3375 |
2844 |             0.3 |          0.24999993 |           0.28333338 |
2845 |             0.4 |               0.275 |              0.28125 |
2846 |             0.5 |                0.26 |                 0.27 |
2847 |             0.6 |          0.25833338 |           0.24999993 |
2848 |             0.7 |          0.24642845 |           0.23928553 |
2849 |             0.8 |             0.23125 |               0.2375 |
2850 |             0.9 |          0.23333323 |            0.2333332 |
2851 |               1 |              0.2225 |                 0.22 |
2852 |             1.1 |          0.20909075 |           0.22272708 |
2853 |             1.2 |          0.19999998 |           0.21458333 |
2854 |             1.3 |          0.19615368 |           0.21730748 |
2856 #+srcname: implementing-gnuplot
2857 #+begin_src gnuplot :var data=gnuplot-data :results silent
2858 set title "Implementing Gnuplot"
2859 plot data using 1:2 with lines
2860 #+end_src
2862 **** DONE add variables
2863      gnuplot 4.2 and up support user defined variables.  This is how
2864      we will handle variables with org-babel (meaning we will need to
2865      require gnuplot 4.2 and up for variable support, which can be
2866      install using [[http://www.macports.org/install.php][macports]] on Mac OSX).
2868      - scalar variables should be replaced in the body of the gnuplot code
2869      - vector variables should be exported to tab-separated files, and
2870        the variable names should be replaced with the path to the files
2872 **** DONE direct plotting w/o session
2873 **** DEFERRED gnuplot support for column/row names
2874 This should be implemented along the lines of the [[* STARTED Column (and row) names of tables in R input/output][R-colname-support]].
2876 We can do something similar to the :labels param in org-plot, we just
2877 have to be careful to ensure that each label is aligned with the
2878 related data file.
2880 This may be walking too close to an entirely prebuilt plotting tool
2881 rather than straight gnuplot code evaluation.  For now I think this
2882 can wait.
2884 **** DONE a =file= header argument
2885 to specify a file holding the results
2887 #+srcname: gnuplot-to-file-implementation
2888 #+begin_src gnuplot :file plot.png :var data=gnuplot-data
2889 plot data using 1:2, data using 1:3 with lines
2890 #+end_src
2892 #+resname:
2893 [[file:plot.png][plot.png]]
2895 **** DONE helpers from org-plot.el
2896 There are a variety of helpers in org-plot which can be fit nicely
2897 into custom gnuplot header arguments.
2899 These should all be in place by now.
2901 **** DEFERRED header argument specifying 3D data
2903 #+tblname: org-grid
2904 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
2905 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
2906 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
2907 | 0 | 0 | 1 | 1 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 1 | 0 | 0 |
2908 | 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 1 | 0 |
2909 | 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 1 | 0 |
2910 | 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 1 | 1 | 1 | 0 |
2911 | 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 |
2912 | 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 |
2913 | 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 1 | 0 |
2914 | 0 | 1 | 0 | 0 | 1 | 0 | 1 | 1 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 1 | 0 |
2915 | 0 | 0 | 1 | 1 | 0 | 0 | 1 | 0 | 1 | 1 | 0 | 0 | 1 | 1 | 1 | 0 | 0 |
2916 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
2917 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
2919 #+srcname: implementing-gnuplot-grid-plots
2920 #+begin_src gnuplot :vars data=org-grid
2922 #+end_src
2924 **** DONE gnuplot sessions
2925 Working on this, we won't support multiple sessions as `gnuplot-mode'
2926 isn't setup for such things.
2928 Also we can't display results with the default :none session, so for
2929 gnuplot we really want the default behavior to be :default, and to
2930 only run a :none session when explicitly specified.
2932 #+srcname: implementing-gnuplot-sessions
2933 #+begin_src gnuplot :var data=gnuplot-data :session none :file session.png
2934 set title "Implementing Gnuplot Sessions"
2935 plot data using 1:2 with lines
2936 #+end_src
2938 #+resname:
2939 [[file:session.png][session.png]]
2941 *** DONE dot
2942 (see [[* file result types][file result types]])
2944 #+srcname: implementing-dot-support
2945 #+begin_src dot :file test-dot.png :cmdline -Tpng
2946 digraph data_relationships {
2947   "data_requirement" [shape=Mrecord, label="{DataRequirement|description\lformat\l}"]
2948   "data_product" [shape=Mrecord, label="{DataProduct|name\lversion\lpoc\lformat\l}"]
2949   "data_requirement" -> "data_product"
2951 #+end_src
2953 #+resname:
2954 [[file:test-dot.png][test-dot.png]]
2956 *** DONE asymptote
2957 (see [[* file result types][file result types]])
2959 for information on asymptote see http://asymptote.sourceforge.net
2961 #+begin_src asymptote :file asymptote-test.png
2962 import graph;
2964 size(0,4cm);
2966 real f(real t) {return 1+cos(t);}
2968 path g=polargraph(f,0,2pi,operator ..)--cycle;
2969 filldraw(g,pink);
2971 xaxis("$x$",above=true);
2972 yaxis("$y$",above=true);
2974 dot("$(a,0)$",(1,0),N);
2975 dot("$(2a,0)$",(2,0),N+E);
2976 #+end_src
2978 #+resname:
2979 [[file:asymptote-test.png][asymptote-test.png]]
2981 *** DONE ruby
2982 *** DONE python
2983 *** DONE R
2984 *** DONE emacs-lisp
2985 *** DONE sh
2988 * Bugs [39/43]
2989 ** DONE stripping indentation from source-code blocks
2990 This is a problem in [[file:lisp/org-babel-exp.el][org-babel-exp.el]].
2992 ** DONE failing to write srcname to resname when evaluating a named block
2994 #+srcname: please-name-my-result
2995 #+begin_src emacs-lisp 
2996 "I'm the result"
2997 #+end_src
2999 #+resname: please-name-my-result
3000 : I'm the result
3002 ** DONE Python session evaluation bug
3003    The following block evaluates correctly with :session none
3004    (set :results to output), but fails with session-based evaluation
3005    (with :results value, as below, you see the error message)
3007    I edebug'ed it and it seems fine until [[file:lisp/langs/org-babel-python.el::comint%20session%20evaluation%20org%20babel%20comint%20in%20buffer%20buffer%20let%20full%20body][we go to comint]].
3009 #+begin_src python :session pysession :results value
3010   import os
3011   from subprocess import *
3012   
3013   chunk = 10000
3014   format = '.gen.gz'
3015   
3016   cc = [('58C','NBS'),
3017         ('58C','POBI'),
3018         ('NBS','POBI')]
3019   
3020   for outdir in ['none', 'noscots', 'lax', 'strict']:
3021       outdir = os.path.join('exclusion-study', outdir)
3022       for case, control in cc:
3023           outfile = os.path.join(outdir, '%s-vs-%s-direct' % (case, control))
3024           cmd = 'snptest %s -frequentist 1 -hwe ' % ('-gen_gz' if format == '.gen.gz' else '')
3025           cmd += '-cases %s %s ' % (case + format, case + '.sample')
3027           cmd += '-controls %s %s ' % (control + format, control + '.sample')
3028           cmd += '-exclude_samples %s ' % os.path.join(outdir, 'exclusions')
3029           cmd += '-o %s ' % outfile
3030           cmd += '-chunk %d ' % chunk
3031           cmd += '> %s' % outfile + '.log'
3032           # os.system(cmd)
3033           print(cmd)
3034 #+end_src
3036 #+resname:
3037 #+begin_example
3038 snptest -gen_gz -frequentist 1 -hwe -cases 58C.gen.gz 58C.sample -controls NBS.gen.gz NBS.sample -exclude_samples exclusion-study/none/exclusions -o exclusion-study/none/58C-vs-NBS-direct -chunk 10000 > exclusion-study/none/58C-vs-NBS-direct.log
3039 snptest -gen_gz -frequentist 1 -hwe -cases 58C.gen.gz 58C.sample -controls POBI.gen.gz POBI.sample -exclude_samples exclusion-study/none/exclusions -o exclusion-study/none/58C-vs-POBI-direct -chunk 10000 > exclusion-study/none/58C-vs-POBI-direct.log
3040 snptest -gen_gz -frequentist 1 -hwe -cases NBS.gen.gz NBS.sample -controls POBI.gen.gz POBI.sample -exclude_samples exclusion-study/none/exclusions -o exclusion-study/none/NBS-vs-POBI-direct -chunk 10000 > exclusion-study/none/NBS-vs-POBI-direct.log
3041 snptest -gen_gz -frequentist 1 -hwe -cases 58C.gen.gz 58C.sample -controls NBS.gen.gz NBS.sample -exclude_samples exclusion-study/noscots/exclusions -o exclusion-study/noscots/58C-vs-NBS-direct -chunk 10000 > exclusion-study/noscots/58C-vs-NBS-direct.log
3042 snptest -gen_gz -frequentist 1 -hwe -cases 58C.gen.gz 58C.sample -controls POBI.gen.gz POBI.sample -exclude_samples exclusion-study/noscots/exclusions -o exclusion-study/noscots/58C-vs-POBI-direct -chunk 10000 > exclusion-study/noscots/58C-vs-POBI-direct.log
3043 snptest -gen_gz -frequentist 1 -hwe -cases NBS.gen.gz NBS.sample -controls POBI.gen.gz POBI.sample -exclude_samples exclusion-study/noscots/exclusions -o exclusion-study/noscots/NBS-vs-POBI-direct -chunk 10000 > exclusion-study/noscots/NBS-vs-POBI-direct.log
3044 snptest -gen_gz -frequentist 1 -hwe -cases 58C.gen.gz 58C.sample -controls NBS.gen.gz NBS.sample -exclude_samples exclusion-study/lax/exclusions -o exclusion-study/lax/58C-vs-NBS-direct -chunk 10000 > exclusion-study/lax/58C-vs-NBS-direct.log
3045 snptest -gen_gz -frequentist 1 -hwe -cases 58C.gen.gz 58C.sample -controls POBI.gen.gz POBI.sample -exclude_samples exclusion-study/lax/exclusions -o exclusion-study/lax/58C-vs-POBI-direct -chunk 10000 > exclusion-study/lax/58C-vs-POBI-direct.log
3046 snptest -gen_gz -frequentist 1 -hwe -cases NBS.gen.gz NBS.sample -controls POBI.gen.gz POBI.sample -exclude_samples exclusion-study/lax/exclusions -o exclusion-study/lax/NBS-vs-POBI-direct -chunk 10000 > exclusion-study/lax/NBS-vs-POBI-direct.log
3047 snptest -gen_gz -frequentist 1 -hwe -cases 58C.gen.gz 58C.sample -controls NBS.gen.gz NBS.sample -exclude_samples exclusion-study/strict/exclusions -o exclusion-study/strict/58C-vs-NBS-direct -chunk 10000 > exclusion-study/strict/58C-vs-NBS-direct.log
3048 snptest -gen_gz -frequentist 1 -hwe -cases 58C.gen.gz 58C.sample -controls POBI.gen.gz POBI.sample -exclude_samples exclusion-study/strict/exclusions -o exclusion-study/strict/58C-vs-POBI-direct -chunk 10000 > exclusion-study/strict/58C-vs-POBI-direct.log
3049 snptest -gen_gz -frequentist 1 -hwe -cases NBS.gen.gz NBS.sample -controls POBI.gen.gz POBI.sample -exclude_samples exclusion-study/strict/exclusions -o exclusion-study/strict/NBS-vs-POBI-direct -chunk 10000 > exclusion-study/strict/NBS-vs-POBI-direct.log
3050 #+end_example
3052 ** DONE require users to explicitly turn on each language
3053 As we continue to add more languages to org-babel, many of which will
3054 require new major-modes we need to re-think how languages are added to
3055 org-babel.
3057 Currently we are requiring all available languages in the
3058 [[file:lisp/org-babel-init.el][org-babel-init.el]] file.  I think we need to change this to a user
3059 setting so that only the language which have their requirements met
3060 (in terms of system executables and emacs major modes) are loaded.  It
3061 is one more step for install, but it seems to me to be the only
3062 solution.  Thoughts?
3064 *** proposed
3066 we add something like the following to the instillation instructions  
3068 #+begin_src emacs-lisp
3069 ;; Uncomment each of the following require lines if you want org-babel
3070 ;; to support that language.  Each language has a comment explaining
3071 ;; it's dependencies.  See the related files in lisp/langs for more
3072 ;; detailed explanations of requirements.
3073 ;; 
3074 ;; (require 'org-babel-R)         ;; ess-mode
3075 ;; (require 'org-babel-asymptote) ;; asymptote be installed on your system
3076 ;; (require 'org-babel-css)       ;; none
3077 ;; (require 'org-babel-ditaa)     ;; ditaa be installed on your system
3078 ;; (require 'org-babel-dot)       ;; dot be installed on your system
3079 ;; (require 'org-babel-gnuplot)   ;; gnuplot-mode
3080 ;; (require 'org-babel-python)    ;; python-mode
3081 ;; (require 'org-babel-ruby)      ;; inf-ruby mode, ruby and irb must be installed on your system
3082 ;; (require 'org-babel-sql)       ;; none
3083 #+end_src
3085 note that =org-babel-sh=, =org-babel-emacs-lisp= are not included in
3086 the list as they can safely be assumed to work on any system.
3088 *** impetus
3089 we should come up with a way to gracefully degrade when support for a
3090 specific language is missing
3092 > To demonstrate creation of documents, open the "test-export.org" file in
3093 > the base of the org-babel directory, and export it as you would any
3094 > other org-mode file.  The "exports" header argument controls how
3095 > source-code blocks are exported, with the following options
3097 > - none :: no part of the source-code block is exported in the document
3098 > - results :: only the output of the evaluated block is exported
3099 > - code :: the code itself is exported
3100 > - both :: both the code and results are exported
3102 I have this error showing up:
3104 executing Ruby source code block
3105 apply: Searching for program: no such file or directory, irb
3107 ** DONE problem with newlines in output when :results value
3109 #+begin_src python :results value
3110 '\n'.join(map(str, range(4)))
3111 #+end_src
3113 #+resname:
3114 : 0
3115 : 1
3116 : 2
3117 : 3
3119 Whereas I was hoping for
3121 | 0 |
3122 | 1 |
3123 | 2 |
3124 | 3 |
3126 *Note*: to generate the above you can try using the new =raw= results
3127 header.
3129 #+begin_src python :results value raw
3130 '|'+'|\n|'.join(map(str, range(4)))+'|'
3131 #+end_src
3133 #+resname:
3134 | 0 |
3135 | 1 |
3136 | 2 |
3137 | 3 |
3139 This is now working, it doesn't return as a table because the value
3140 returned is technically a string.  To return the table mentioned above
3141 try something like the following.
3143 #+begin_src python
3144 [[0], [1], [2], [3]]
3145 #+end_src
3147 #+resname:
3148 | 0 |
3149 | 1 |
3150 | 2 |
3151 | 3 |
3153 This is some sort of non-printing char / quoting issue I think. Note
3154 that
3156 #+begin_src python :results value
3157 '\\n'.join(map(str, range(4)))
3158 #+end_src
3160 #+resname:
3161 : 0\n1\n2\n3
3163 Also, note that
3164 #+begin_src python :results output
3165 print('\n'.join(map(str, range(4))))
3166 #+end_src
3168 #+resname:
3169 : 0
3170 : 1
3171 : 2
3172 : 3
3174 *** collapsing consecutive newlines in string output
3175     
3176     This is an example of the same bug
3178 #+srcname: multi-line-string-output
3179 #+begin_src ruby :results output
3180 "the first line ends here
3183      and this is the second one
3185 even a third"
3186 #+end_src
3188 This doesn't produce anything at all now. I believe that's because
3189 I've changed things so that :results output really does *not* get the
3190 value of the block, only the STDOUT. So if we add a print statement
3191 this works OK.
3193 #+srcname: multi-line-string-output
3194 #+begin_src ruby :results output
3195 print "the first line ends here
3198      and this is the second one
3200 even a third"
3201 #+end_src
3203 #+resname:
3204 : the first line ends here
3207 :      and this is the second one
3209 : even a third
3211 However, the behaviour with :results value is wrong
3213 #+srcname: multi-line-string-value
3214 #+begin_src ruby
3215 "the first line ends here
3218      and this is the second one
3220 even a third"
3221 #+end_src
3223 #+resname:
3224 : 0
3226 ** TODO prompt characters appearing in output with R
3227 #+begin_src R :session *R* :results output
3228   x <- 6
3229   y <- 8
3230   3
3231 #+end_src      
3233 #+resname:
3234 : > [1] 3
3236 ** TODO o-b-execute-subtree overwrites heading when subtree is folded
3237 *** Example
3238     Try M-x org-babel-execute-subtree with the subtree folded and
3239     point at the beginning of the heading line.
3240 #+begin_src sh
3241 size=5
3242 #+end_src
3243 ** DONE non-orgtbl formatted lists
3244 for example
3246 #+srcname: this-doesn't-match-orgtbl
3247 #+begin_src emacs-lisp :results replace
3248 '((:results . "replace"))
3249 #+end_src
3251 #+resname:
3252 | (:results . "replace") |
3254 #+srcname: this-probably-also-wont-work
3255 #+begin_src emacs-lisp :results replace
3256 '(eric schulte)
3257 #+end_src
3259 #+resname:
3260 | eric | schulte |
3262 ** PROPOSED allow un-named arguments
3264 #+srcname: f(x)
3265 #+begin_src python 
3267 #+end_src
3269 #+lob: f(5)
3271 ## produces no output
3273  It's not essential but would be nice for this to work. To do it
3274 properly, would mean that we'd have to specify rules for how a string
3275 of supplied arguments (some possibly named) interact with the
3276 arguments in the definition (some possibly with defaults) to give
3277 values to the variables in the funbction body.
3278 ** PROPOSED external shell execution can't isolate return values
3279 I have no idea how to do this as of yet.  The result is that when
3280 shell functions are run w/o a session there is no difference between
3281 the =output= and =value= result arguments.
3283 Yea, I don't know how to do this either.  I searched extensively on
3284 how to isolate the *last* output of a series of shell commands (see
3285 [[* last command for
3286  shells][last command for shells]]).  The results of the search were basically
3287 that it was not possible (or at least not accomplish-able with a
3288 reasonable amount of effort).
3290 That fact combined with the tenancy to all ways use standard out in
3291 shell scripts led me to treat these two options (=output= and =value=)
3292 as identical in shell evaluation.  Not ideal but maybe good enough for
3293 the moment.
3295 In the `results' branch I've changed this so that they're not quite
3296 identical: output results in raw stdout contents, whereas value
3297 converts it to elisp, perhaps to a table if it looks tabular. This is
3298 the same for the other languages. [Dan]
3299    
3300 ** DONE adding blank line when source-block produces no output
3302 #+srcname: show-org-babel-trim
3303 #+begin_src sh
3304 find . \( -path \*/SCCS -o -path \*/RCS -o -path \*/CVS -o -path \*/MCVS -o -path \*/.svn -o -path \*/.git -o -path \*/.hg -o -path \*/.bzr -o -path \*/_MTN -o -path \*/_darcs -o -path \*/\{arch\} \) -prune -o  -type f \( -iname \*.el \) -exec grep -i -nH -e org-babel-trim {} \;
3305 #+end_src
3307 ** DONE Allow source blocks to be recognised when #+ are not first characters on the line
3308    I think Carsten has recently altered the core so that #+ can have
3309    preceding whitespace, at least for literal/code examples. org-babel
3310    should support this.
3312 #+srcname: testing-indentation
3313    #+begin_src emacs-lisp :results silent
3314    (message "i'm indented")
3315    #+end_src
3317 #+srcname: testing-non-indentation
3318 #+begin_src emacs-lisp :results silent
3319 (message "I'm not indented")
3320 #+end_src
3322 #+srcname: i-resolve-references-to-the-indented
3323 #+begin_src emacs-lisp :var speech=testing-indentation :results silent
3324 (message "I said %s" speech)
3325 #+end_src
3327 ** DONE are the org-babel-trim s necessary?
3328    at the end of e.g. org-babel-R-evaluate, org-babel-python-evaluate, but
3329    not org-babel-ruby-evaluate
3330    
3331    I think it depends on the language, if we find that extra blank
3332    lines are being inserted in a particular language that is a good
3333    indication that the trim or chomp functions may be appropriate.
3335    org-babel-trim and the related org-babel-chomp are use throughout
3336    org-babel...
3338 #+srcname: show-org-babel-trim-usage
3339 #+begin_src sh :results output
3340 find lisp/ \( -path \*/SCCS -o -path \*/RCS -o -path \*/CVS -o -path \*/MCVS -o -path \*/.svn -o -path \*/.git -o -path \*/.hg -o -path \*/.bzr -o -path \*/_MTN -o -path \*/_darcs -o -path \*/\{arch\} \) -prune -o  -type f \( -iname \*.el \) -exec grep -i -nH org-babel-trim {} \;
3341 #+end_src
3343 #+resname:
3344 #+begin_example
3345 lisp//langs/org-babel-python.el:49:                  vars "\n") "\n" (org-babel-trim body) "\n")) ;; then the source block body
3346 lisp//langs/org-babel-python.el:143:                           (org-remove-indentation (org-babel-trim body)) "[\r\n]")))
3347 lisp//langs/org-babel-python.el:158:           #'org-babel-trim
3348 lisp//langs/org-babel-python.el:166:                                           (reverse (mapcar #'org-babel-trim raw)))))))
3349 lisp//langs/org-babel-python.el:169:      (output (org-babel-trim (mapconcat #'identity (reverse (cdr results)) "\n")))
3350 lisp//langs/org-babel-python.el:170:      (value (org-babel-python-table-or-string (org-babel-trim (car results)))))))))
3351 lisp//langs/org-babel-ruby.el:149:                                                  (mapcar #'org-babel-trim raw)))))))
3352 lisp//langs/org-babel-sh.el:148:                                                  (mapcar #'org-babel-trim raw)))))))
3353 lisp//langs/org-babel-sh.el:151:            (output (org-babel-trim (mapconcat #'org-babel-trim (reverse results) "\n")))
3354 lisp//org-babel-ref.el:161:    (mapcar #'org-babel-trim (reverse (cons buffer return)))))
3355 lisp//org-babel.el:198:    (with-temp-buffer (insert (org-babel-trim body)) (copy-region-as-kill (point-min) (point-max)))
3356 lisp//org-babel.el:465:           (org-babel-trim
3357 lisp//org-babel.el:706:(defun org-babel-trim (string &optional regexp)
3358 #+end_example
3360 #+srcname: show-org-babel-chomp-usage
3361 #+begin_src sh :results output
3362 find lisp/ \( -path \*/SCCS -o -path \*/RCS -o -path \*/CVS -o -path \*/MCVS -o -path \*/.svn -o -path \*/.git -o -path \*/.hg -o -path \*/.bzr -o -path \*/_MTN -o -path \*/_darcs -o -path \*/\{arch\} \) -prune -o  -type f \( -iname \*.el \) -exec grep -i -nH org-babel-chomp {} \;
3363 #+end_src
3365 #+resname:
3366 #+begin_example
3367 lisp//langs/org-babel-R.el:122:             (full-body (mapconcat #'org-babel-chomp
3368 lisp//langs/org-babel-R.el:143:       (delete nil (mapcar #'extractor (mapcar #'org-babel-chomp raw))) "\n"))))))))
3369 lisp//langs/org-babel-ruby.el:143:           #'org-babel-chomp
3370 lisp//langs/org-babel-sh.el:142:           (full-body (mapconcat #'org-babel-chomp
3371 lisp//org-babel-tangle.el:163:      (insert (format "\n%s\n" (org-babel-chomp body)))
3372 lisp//org-babel.el:362:                  (org-babel-chomp (match-string 2 arg)))
3373 lisp//org-babel.el:698:(defun org-babel-chomp (string &optional regexp)
3374 lisp//org-babel.el:707:  "Like `org-babel-chomp' only it runs on both the front and back of the string"
3375 lisp//org-babel.el:708:  (org-babel-chomp (org-babel-reverse-string
3376 lisp//org-babel.el:709:                    (org-babel-chomp (org-babel-reverse-string string) regexp)) regexp))
3377 #+end_example
3379 ** DONE LoB is not populated on startup
3380    org-babel-library-of-babel is nil for me on startup. I have to
3381    evaluate the [[file:lisp/org-babel-lob.el::][org-babel-lob-ingest]] line manually.
3383 #+tblname: R-plot-example-data
3384 | 1 |  2 |
3385 | 2 |  4 |
3386 | 3 |  9 |
3387 | 4 | 16 |
3388 | 5 | 25 |
3390 #+lob: R-plot(data=R-plot-example-data)
3394    I've added a section to [[file:lisp/org-babel-init.el][org-babel-init.el]] which will load the
3395    library of babel on startup.
3397    Note that this needs to be done in [[file:lisp/org-babel-init.el][org-babel-init.el]] rather than in
3398    [[file:lisp/org-babel-lob.el][org-babel-lob.el]], not entirely sure why, something about it being
3399    required directly?
3401    Also, I'm now having the file closed if it wasn't being visited by
3402    a buffer before being loaded.
3404 ** DONE use new merge function [[file:lisp/org-babel-ref.el::t%20nil%20org%20combine%20plists%20args%20nil][here]]?
3405    And at other occurrences of org-combine-plists?
3406 ** DONE creeping blank lines
3407    There's still inappropriate addition of blank lines in some circumstances. 
3409    Hmm, it's a bit confusing. It's to do with o-b-remove-result. LoB
3410    removes the entire (#+resname and result) and starts from scratch,
3411    whereas #+begin_src only removes the result. I haven't worked out
3412    what the correct fix is yet. Maybe the right thing to do is to make
3413    sure that those functions (o-b-remove-result et al.) are neutral
3414    with respect to newlines. Sounds easy, but...
3416    E.g.
3418 #+begin_src sh
3420 #+end_src
3424    Compare the results of
3425 #+lob: adder(a=5, b=17)
3427 #+resname: python-add(a=5, b=17)
3428 : 22
3429 --------------------------------
3431 #+begin_src python
3433 #+end_src
3435 #+resname:
3436 : 23
3437 ---------------------
3438 ** DONE #+srcname arg parsing bug
3439 #+srcname: test-zz(arg=adder(a=1, b=1))
3440 #+begin_src python 
3442 #+end_src
3444 #+resname: test-zz
3445 : 2
3448 #+srcname: test-zz-nasty(arg=adder(a=adder(a=19,b=adder(a=5,b=2)),b=adder(a=adder(a=1,b=9),b=adder(a=1,b=3))))
3449 #+begin_src python 
3451 #+end_src
3453 #+resname: test-zz-nasty
3454 : 40
3458 #+srcname: test-zz-hdr-arg
3459 #+begin_src python :var arg=adder(a=adder(a=19,b=adder(a=5,b=2)),b=adder(a=adder(a=1,b=9),b=adder(a=1,b=3)))
3461 #+end_src
3463 #+resname:
3464 : 40
3466 ** DONE Fix nested evaluation and default args
3467    The current parser / evaluator fails with greater levels of nested
3468    function block calls (example below).
3470 *** Initial statement [ded]
3471     If we want to overcome this I think we'd have to redesign some of
3472     the evaluation mechanism. Seeing as we are also facing issues like
3473     dealing with default argument values, and seeing as we now know
3474     how we want the library of babel to behave in addition to the
3475     source blocks, now might be a good time to think about this. It
3476     would be nice to do the full thing at some point, but otoh we may
3477     not consider it a massive priority.
3478     
3479     AIui, there are two stages: (i) construct a parse tree, and (ii)
3480     evaluate it and return the value at the root. In the parse tree
3481     each node represents an unevaluated value (either a literal value
3482     or a reference). Node v may have descendent nodes, which represent
3483     values upon which node v's evaluation depends. Once that tree is
3484     constructed, then we evaluate the nodes from the tips towards the
3485     root (a post-order traversal).
3487     [This would also provide a solution for concatenating the STDOUTs
3488     of called blocks, which is a [[*allow%20output%20mode%20to%20return%20stdout%20as%20value][task below]]; we concatenate them in
3489     whatever order the traversal is done in.]
3491     In addition to the variable references (i.e. daughter nodes), each
3492     node would contain the information needed to evaluate that node
3493     (e.g. lang body). Then we would pass a function postorder over the
3494     tree which would call o-b-execute-src-block at each node, finally
3495     returning the value at the root.
3497     Fwiw I made a very tentative small start at stubbing this out in
3498     org-babel-call.el in the 'evaluation' branch. And I've made a start
3499     at sketching a parsing algorithm below.
3500 **** Parse tree algorithm
3501     Seeing as we're just trying to parse a string like
3502     f(a=1,b=g(c=2,d=3)) it shouldn't be too hard. But of course there
3503     are 'proper' parsers written in elisp out there,
3504     e.g. [[http://cedet.sourceforge.net/semantic.shtml][Semantic]]. Perhaps we can find what we need -- our syntax is
3505     pretty much the same as python and R isn't it?
3507     Or, a complete hack, but maybe it would be we easy to transform it
3508     to XML and then parse that with some existing tool?
3509     
3510     But if we're doing it ourselves, something very vaguely like this?
3511     (I'm sure there're lots of problems with this)
3513 #+srcname: org-babel-call-parse(call)
3514 #+begin_src python 
3515   ## we are currently reading a reference name: the name of the root function
3516   whereami = "refname"
3517   node = root = Node()
3518   for c in call_string:
3519       if c == '(':
3520           varnum = 0
3521           whereami = "varname" # now we're reading a variable name
3522       if c == '=':
3523           new = Node()
3524           node.daughters = [node.daughters, new]
3525           new.parent = node
3526           node = new
3527           whereami = "refname"
3528       if c == ',':
3529           whereami = "varname"
3530           varnum += 1
3531       elif c == ')':
3532           node = node.parent
3533       elif c == ' ':
3534           pass
3535       else:
3536           if whereami = "varname":
3537               node.varnames[varnum] += c
3538           elif whereami = "refname":
3539               node.name += c
3540 #+end_src
3541     
3542 *** discussion / investigation
3543 I believe that this issue should be addressed as a bug rather than as
3544 a point for new development.   The code in [[file:lisp/org-babel-ref.el][org-babel-ref.el]] already
3545 resolves variable references in a recursive manner which *should* work
3546 in the same manner regardless of the depth of the number of nested
3547 function calls.  This recursive evaluation has the effect of
3548 implicitly constructing the parse tree that your are thinking of
3549 constructing explicitly.
3551 Through using some of the commented out debugging statements in
3552 [[file:lisp/org-babel-ref.el][org-babel-ref.el]] I have looked at what may be going wrong in the
3553 current evaluation setup, and it seems that nested variables are being
3554 set using the =:var= header argument, and these variables are being
3555 overridden by the *default* variables which are being entered through
3556 the new functional syntax (see the demonstration header below).
3558 I believe that once this bug is fixed we should be back to fully
3559 resolution of nested arguments.  We should capture this functionality
3560 in a test to ensure that we continue to test it as we move forward.  I
3561 can take a look at implementing this once I get a chance.
3563 Looks like the problem may be in [[file:lisp/org-babel.el::defun%20org%20babel%20merge%20params%20rest%20plists][org-babel-merge-params]], which seems
3564 to be trampling the provided :vars values.
3566 Nope, now it seems that we are actually looking up the results line,
3567 rather than the actual source-code block, which would make sense given
3568 that the results-line will return the same value regardless of the
3569 arguments supplied.  See the output of this [[file:lisp/org-babel-ref.el::message%20type%20S%20type%20debugging][debug-statement]].
3571 We need to be sure that we don't read from a =#+resname:= line when we
3572 have a non-nil set of arguments.
3574 **** demonstration
3575 After uncommenting the debugging statements located [[file:lisp/org-babel-ref.el::message%20format%20first%20second%20S%20S%20new%20refere%20new%20referent%20debugging][here]] and more
3576 importantly [[file:lisp/org-babel-ref.el::message%20nested%20args%20S%20args%20debugging][here]], we can see that the current reference code does
3577 evaluate the references correctly, and it uses the =:var= header
3578 argument to set =a=8=, however the default variables specified using
3579 the functional syntax in =adder(a=3, b=2)= is overriding this
3580 specification.
3582 ***** doesn't work with functional syntax
3584 #+srcname: adder-func(a=3, b=2)
3585 #+begin_src python 
3586 a + b
3587 #+end_src
3589 #+resname: adder-func
3590 : 5
3592 #+srcname: after-adder-func(arg=adder-func(a=8))
3593 #+begin_src python 
3595 #+end_src
3597 #+resname: after-adder-func
3598 : 5
3600 ***** still does work with =:var= syntax
3602 so it looks like regardless of the syntax used we're not overriding
3603 the default argument values.
3605 #+srcname: adder-header
3606 #+begin_src python :var a=3 :var b=2
3607 a + b
3608 #+end_src
3610 #+resname: adder-header
3611 : 5
3613 #+srcname: after-adder-header
3614 #+begin_src python :var arg=adder-header(a=8, b=0)
3616 #+end_src
3618 #+resname: after-adder-header
3619 : 5
3621 *** Set of test cases
3622 **** Both defaults provided in definition
3623 #+srcname: adder1(a=10,b=20)
3624 #+begin_src python
3626 #+end_src
3628 #+resname: adder1
3629 : 30
3630 ****** DONE Rely on defaults
3631 #+lob: adder1()
3633 #+resname: adder1()
3634 : 30
3636 ## should be 30
3637 ## OK, but
3638 ******* DONE empty parens () not recognised as lob call
3639         E.g. remove spaces between parens above
3641         updated [[file:lisp/org-babel-lob.el::defvar%20org%20babel%20lob%20one%20liner%20regexp%20lob%20t%20n%20n%20t%20n][org-babel-lob-one-liner-regexp]]
3643 ****** DONE One supplied, one default
3644 #+lob: adder1(a=0)
3646 #+resname: adder1(a=0)
3647 : 20
3649 ## should be 20
3651 #+lob: adder1(b=0)
3653 #+resname: adder1(b=0)
3654 ## should be 10
3655 : 10
3657 ****** DONE Both supplied
3658 #+lob: adder1(a=1,b=2)
3660 #+resname: adder1(a=1,b=2)
3662 : 3
3663 **** One arg lacks default in definition
3664 #+srcname: adder2(a=10,b)
3665 #+begin_src python
3667 #+end_src
3668 ****** DEFERRED Rely on defaults (one of which is missing)
3669 #+lob: adder2( )
3671 [no output]
3673 ## should be error: b has no default
3675 Maybe we should let the programming language handle this case.  For
3676 example python spits out an error in the =#+lob= line above.  Maybe
3677 rather than catching these errors our-selves we should raise an error
3678 when the source-block returns an error.  I'll propose a [[* PROPOSED raise elisp error when source-blocks return errors][task]] for this
3679 idea, I'm not sure how/if it would work...
3681 ****** DEFERRED Default over-ridden
3682 #+lob: adder2(a=1)
3684 See the above [[* DEFERRED Rely on defaults (one of which is missing)][deferred]] and the new proposed [[* PROPOSED raise elisp error when source-blocks return errors][task]], I think it may be
3685 more flexible to allow the source block language to handle the error.
3687 [no output ]
3688 ## should be error: b has no default
3690 ****** DONE Missing default supplied
3691 #+lob: adder2(b=1)
3693 #+resname: adder2(b=1)
3694 : 11
3697 ## should be 11
3698 ## OK
3700 ****** DONE One over-ridden, one supplied
3701 #+lob: adder2(a=1,b=2)
3703 #+resname: adder2(a=1,b=2)
3704 : 3
3706 ## should be 3
3708 *** Example that fails
3709     
3710 #+srcname: adder(a=0, b=99)
3711 #+begin_src python 
3713 #+end_src
3717 #+srcname: one()
3718 #+begin_src python
3720 #+end_src
3722 **** nesting
3723 #+srcname: level-one-nesting()
3724 #+begin_src python :var arg=adder(a=one(),b=one())
3726 #+end_src
3728 #+resname: level-one-nesting
3730 : nil
3732 #+srcname: level-one-nesting()
3733 #+begin_src python :var arg=adder(a=adder(a=one(),b=one()),b=adder(a=one(),b=one()))
3735 #+end_src
3737 #+resname:
3738 : 12
3740 *** DONE deeply nested arguments still fails
3742 #+srcname: deeply-nested-args-bug
3743 #+begin_src python :var arg=adder(a=adder(a=one(),b=one()),b=adder(a=one(),b=one()))
3745 #+end_src
3747 #+resname:
3748 : 4
3750 **** Used to result in this error
3751 : supplied params=nil
3752 : new-refere="adder", new-referent="a=adder(a=one(),b=one()),b=adder(a=one(),b=one())"
3753 : args=((:var . "a=adder(a=one()") (:var . "b=one())") (:var . "b=adder(a=one()") (:var . "b=one())"))
3754 : type=source-block
3755 : supplied params=((:var . "a=adder(a=one()") (:var . "b=one())") (:var . "b=adder(a=one()") (:var . "b=one())"))
3756 : new-refere="adder", new-referent="a=one("
3757 : args=((:var . "a=one("))
3758 : type=source-block
3759 : supplied params=((:var . "a=one("))
3760 : reference 'one(' not found in this buffer
3762 Need to change the regexp in [[file:lisp/org-babel-ref.el::assign%20any%20arguments%20to%20pass%20to%20source%20block][org-babel-ref-resolve-reference]] so that
3763 it only matches when the parenthesis are balanced.  Maybe look at
3764 [[http://www.gnu.org/software/emacs/elisp/html_node/List-Motion.html][this]].
3766 *** DONE Still some problems with deeply nested arguments and defaults
3767 **** sandbox
3768 **** DONE Parsing / defaults bug
3769      Try inserting a space between 'a=0,' and 'b=0' and comparing results
3770 #+srcname: parsing-defaults-bug()
3771 #+begin_src python :var arg=adder(a=adder(a=0,b=0))
3773 #+end_src
3775 #+resname: parsing-defaults-bug
3777 : 99
3779 #+srcname: deeply-nested-args-bug-orig()
3780 #+begin_src python :var arg=adder(a=adder(a=one(),b=one()),b=adder(a=adder(a=3, b=4),b=one()))
3782 #+end_src
3784 #+resname: deeply-nested-args-bug-orig
3786 : 10
3789 **** DONE Nesting problem II
3790      This generates parsing errors
3792      Fixed: c2bef96b7f644c05be5a38cad6ad1d28723533aa
3794 #+srcname: deeply-nested-args-bug-II-1()
3795 #+begin_src python :var arg=adder(a=adder(a=one(),b=adder(a=2,b=4)))
3797 #+end_src
3799 #+resname: deeply-nested-args-bug-II-1
3801 : 106
3803 #+srcname: deeply-nested-args-bug-II-original()
3804 #+begin_src python :var arg=adder(a=adder(a=one(),b=one()),b=adder(a=one(),b=adder(a=1,b=4)))
3806 #+end_src
3808 #+resname: deeply-nested-args-bug-II-original
3809 : 8
3813 **** DONE Why does this give 8?
3814      It was picking up the wrong definition of adder
3815 #+srcname: deeply-nested-args-bug-2()
3816 #+begin_src python :var arg=adder(a=adder(a=one(),b=one()))
3818 #+end_src
3820 #+resname: deeply-nested-args-bug-2
3822 : 101
3824 **** DONE Problem with empty argument list
3825      This gives empty list with () and 'no output' with ( )
3827      I think this is OK now.
3829 #+srcname: x
3830 #+begin_src python :var arg=adder( )
3832 #+end_src
3834 #+resname:
3835 : 99
3837 #+srcname: deeply-nested-args-bug-orig()
3838 #+begin_src python :var arg=adder(a=adder(a=one(),b=one()),b=adder(a=adder(a=3, b=4),b=one()))
3840 #+end_src
3842 #+resname: deeply-nested-args-bug-orig
3844 : 10
3847 **** DONE Nesting problem II
3848      This generates parsing errors
3850      Fixed: c2bef96b7f644c05be5a38cad6ad1d28723533aa
3852 #+srcname: deeply-nested-args-bug-II-1()
3853 #+begin_src python :var arg=adder(a=adder(a=one(),b=adder(a=2,b=4)))
3855 #+end_src
3857 #+resname: deeply-nested-args-bug-II-1
3859 : 106
3861 #+srcname: deeply-nested-args-bug-II-original()
3862 #+begin_src python :var arg=adder(a=adder(a=one(),b=one()),b=adder(a=one(),b=adder(a=1,b=4)))
3864 #+end_src
3866 #+resname: deeply-nested-args-bug-II-original
3867 : 8
3871 **** DONE Why does this give 8?
3872      It was picking up the wrong definition of adder
3873 #+srcname: deeply-nested-args-bug-2()
3874 #+begin_src python :var arg=adder(a=adder(a=one(),b=one()))
3876 #+end_src
3878 #+resname: deeply-nested-args-bug-2
3880 : 101
3882 **** DONE Problem with empty argument list
3883      This gives empty list with () and 'no output' with ( )
3885      I think this is OK now.
3887 #+srcname: x
3888 #+begin_src python :var arg=adder( )
3890 #+end_src
3892 #+resname:
3893 : 99
3921 #+srcname: test-zz(arg=adder(a=adder(a=19,b=adder(a=5,b=2)),b=adder(a=adder(a=1,b=9),b=adder(a=1,b=3))))
3922 #+begin_src python 
3924 #+end_src
3927 *** DONE Arg lacking default
3928    This would be good thing to address soon. I'm imagining that
3929    e.g. here, the 'caller' block would return the answer 30. I believe
3930    there's a few issues here: i.e. the naked 'a' without a reference
3931    is not understood; the default arg b=6 is not understood.
3933 #+srcname: adder-with-arg-lacking-default(a, b=6)
3934 #+begin_src python 
3936 #+end_src
3940 #+srcname: caller(var=adder-with-arg-lacking-default(a=24))
3941 #+begin_src python :results silent
3943 #+end_src
3945 ** DONE allow srcname to omit function call parentheses
3946    Someone needs to revisit those regexps. Is there an argument for
3947    moving some of the regexps used to match function calls into
3948    defvars? (i.e. in o-b.el and o-b-ref.el)
3950    This seems to work now. It still might be a good idea to separate
3951    out some of the key regexps into defvars at some point.
3953 #+srcname: omit-parens-test
3954 #+begin_src ruby :results output
3955 3.times {puts 'x'}
3956 #+end_src
3958 #+resname:
3959 : x
3960 : x
3961 : x
3963 ** DONE avoid stripping whitespace from output when :results output
3964    This may be partly solved by using o-b-chomp rather than o-b-trim
3965    in the o-b-LANG-evaluate functions.
3966 ** DEFERRED weird escaped characters in shell prompt break shell evaluation
3967    E.g. this doesn't work. Should the shell sessions set a sane prompt
3968    when they start up? Or is it a question of altering
3969    comint-prompt-regexp? Or altering org-babel regexps?
3970    
3971 #+begin_src sh   
3972    black=30 ; red=31 ; green=32 ; yellow=33 ; blue=34 ; magenta=35 ; cyan=36 ; white=37
3973    prompt_col=$red
3974    prompt_char='>'
3975    export PS1="\[\033[${prompt_col}m\]\w${prompt_char} \[\033[0m\]"
3976 #+end_src
3978    I just pushed a good amount of changes, could you see if your shell
3979    problems still exist?
3981    The problem's still there. Specifically, aIui, at [[file:lisp/langs/org-babel-sh.el::raw%20org%20babel%20comint%20with%20output%20buffer%20org%20babel%20sh%20eoe%20output%20nil%20insert%20full%20body%20comint%20send%20input%20nil%20t][this line]] of
3982    org-babel-sh.el, raw gets the value
3984 ("" "\e[0m Sun Jun 14 19:26:24 EDT 2009\n" "\e[0m org_babel_sh_eoe\n" "\e[0m ")
3986    and therefore (member org-babel-sh-eoe-output ...) fails
3988    I think that `comint-prompt-regexp' needs to be altered to match
3989    the shell prompt.  This shouldn't be too difficult to do by hand,
3990    using the `regexp-builder' command and should probably be part of
3991    the user's regular emacs init.  I can't think of a way for us to
3992    set this automatically, and we are SOL without a regexp to match
3993    the prompt.
3994 ** DONE function calls in #+srcname: refs
3995    
3996    My srcname references don't seem to be working for function
3997    calls. This needs fixing.
3998    
3999 #+srcname: called()
4000 #+begin_src python 
4002 #+end_src
4004 srcname function call doesn't work for calling a source block
4005 #+srcname: caller(var1=called())
4006 #+begin_src python
4007 var1
4008 #+end_src
4010 #+resname: caller
4011 : 59
4018 They do work for a simple reference
4019 #+srcname: caller2(var1=56)
4020 #+begin_src python 
4021 var1
4022 #+end_src
4024 #+resname: caller2
4025 : 59
4028 and they do work for :var header arg
4029 #+srcname: caller3
4030 #+begin_src python :var var1=called() 
4031 var1
4032 #+end_src
4034 #+resname:
4035 : 58
4036 ** DONE LoB: with output to buffer, not working in buffers other than library-of-babel.org
4037 *** Initial report
4038    I haven't fixed this yet. org-babel-ref-resolve-reference moves
4039    point around, inside a save-excursion. Somehow when it comes to
4040    inserting the results (after possible further recursive calls to
4041    org-babel-ref-resolve-reference), point hasn't gone back to the
4042    lob line.
4044 #+tblname: test-data
4045 | 1 |    1 |
4046 | 2 |   .5 |
4047 | 3 | .333 |
4049 #+lob: R-plot(data=test-data)
4051 #+lob: python-add(a=2, b=9)
4053 #+resname: python-add(a=2, b=9)
4054 : 11
4056 *** Now
4057     I think this got fixed in the bugfixes before merging results into master.
4059 ** DONE cursor movement when evaluating source blocks
4060    E.g. the pie chart example. Despite the save-window-excursion in
4061    org-babel-execute:R. (I never learned how to do this properly: org-R
4062    jumps all over the place...)
4064    I don't see this now [ded]
4066 ** DONE LoB: calls fail if reference has single character name
4067    commit 21d058869df1ff23f4f8cc26f63045ac9c0190e2
4068 **** This doesn't work
4069 #+lob: R-plot(data=X)
4071 #+tblname: X
4072 | 1 |     1 |
4073 | 2 |    .5 |
4074 | 3 | .3333 |
4075 | 4 |   .25 |
4076 | 5 |    .2 |
4077 | 6 | .1666 |
4079 **** But this is OK
4080 #+tblname: XX
4081 | 1 |     1 |
4082 | 2 |    .5 |
4083 | 3 | .3333 |
4084 | 4 |   .25 |
4085 | 5 |    .2 |
4086 | 6 | .1666 |
4088 #+lob: R-plot(data=XX)
4090 ** DONE make :results replace the default?
4091    I'm tending to think that appending results to pre-existing results
4092    creates mess, and that the cleaner `replace' option should be the
4093    default. E.g. when a source block creates an image, we would want
4094    that to be updated, rather than have a new one be added.
4095    
4096    I agree.
4098 ** DONE ruby evaluation not working under ubuntu emacs 23
4099    With emacs 23.0.91.1 on ubuntu, for C-h f run-ruby I have the
4100    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.
4102 #+begin_example
4103 run-ruby is an interactive compiled Lisp function.
4105 (run-ruby cmd)
4107 Run an inferior Ruby process, input and output via buffer *ruby*.
4108 If there is a process already running in `*ruby*', switch to that buffer.
4109 With argument, allows you to edit the command line (default is value
4110 of `ruby-program-name').  Runs the hooks `inferior-ruby-mode-hook'
4111 (after the `comint-mode-hook' is run).
4112 (Type C-h m in the process buffer for a list of commands.)
4113 #+end_example
4115    So, I may have a non-standard inf-ruby.el.  Here's my version of
4116    run-ruby.
4118 #+begin_example 
4119 run-ruby is an interactive Lisp function in `inf-ruby.el'.
4121 (run-ruby &optional COMMAND NAME)
4123 Run an inferior Ruby process, input and output via buffer *ruby*.
4124 If there is a process already running in `*ruby*', switch to that buffer.
4125 With argument, allows you to edit the command line (default is value
4126 of `ruby-program-name').  Runs the hooks `inferior-ruby-mode-hook'
4127 (after the `comint-mode-hook' is run).
4128 (Type C-h m in the process buffer for a list of commands.)
4129 #+end_example
4131    It seems we could either bundle my version of inf-ruby.el (as it's
4132    the newest).  Or we could change the use of `run-ruby' so that it
4133    is robust across multiple distributions.  I think I'd prefer the
4134    former, unless the older version of inf-ruby is actually bundled
4135    with emacs, in which case maybe we should go out of our way to
4136    support it.  Thoughts?
4138    I think for now I'll just include the latest [[file:util/inf-ruby.el][inf-ruby.el]] in the
4139    newly created utility directory.  I doubt anyone would have a
4140    problem using the latest version of this file.
4141 ** DONE test failing forcing vector results with =test-forced-vector-results= ruby code block
4142 Note that this only seems to happen the *second* time the test table
4143 is evaluated
4145 #+srcname: bug-trivial-vector
4146 #+begin_src emacs-lisp :results vector silent
4148 #+end_src
4150 #+srcname: bug-forced-vector-results
4151 #+begin_src ruby :var triv=test-trivial-vector :results silent
4152 triv.class.name
4153 #+end_src
4155 mysteriously this seems to be fixed...
4156 ** DONE defunct R sessions
4157 Sometimes an old R session will turn defunct, and newly inserted code
4158 will not be evaluated (leading to a hang).
4160 This seems to be fixed by using `inferior-ess-send-input' rather than `comint-send-input'.
4161 ** DONE ruby fails on first call to non-default session
4163 #+srcname: bug-new-session
4164 #+begin_src ruby :session is-new
4165 :patton
4166 #+end_src
4168 ** DONE when reading results from =#+resname= line
4170 Errors when trying to read from resname lines.
4172 #+resname: bug-in-resname
4173 : 8
4175 #+srcname: bug-in-resname-reader
4176 #+begin_src emacs-lisp :var buggy=bug-in-resname() :results silent
4177 buggy
4178 #+end_src
4180 ** DONE R-code broke on "org-babel" rename
4182 #+srcname: bug-R-babels
4183 #+begin_src R 
4184 8 * 2
4185 #+end_src
4187 ** DONE error on trivial R results
4189 So I know it's generally not a good idea to squash error without
4190 handling them, but in this case the error almost always means that
4191 there was no file contents to be read by =org-table-import=, so I
4192 think it's ok.
4194 #+srcname: bug-trivial-r1
4195 #+begin_src R :results replace
4196 pie(c(1, 2, 3), labels = c(1, 2, 3))
4197 #+end_src
4199 #+srcname: bug-trivial-r2
4200 #+begin_src R :results replace
4202 #+end_src
4204 #+resname: bug-trivial-r2
4205 : 8
4207 #+srcname: bug-trivial-r3
4208 #+begin_src R :results replace
4209 c(1,2,3)
4210 #+end_src
4212 #+resname: bug-trivial-r3
4213 | 1 |
4214 | 2 |
4215 | 3 |
4217 ** DONE ruby new variable creation (multi-line ruby blocks)
4218 Actually it looks like we were dropping all but the last line.
4220 #+srcname: multi-line-ruby-test
4221 #+begin_src ruby :var table=bug-numerical-table :results replace
4222 total = 0
4223 table.each{|n| total += n}
4224 total/table.size
4225 #+end_src
4227 #+resname:
4228 : 2
4230 ** DONE R code execution seems to choke on certain inputs
4231 Currently the R code seems to work on vertical (but not landscape)
4232 tables
4234 #+srcname: little-fake
4235 #+begin_src emacs-lisp 
4236 "schulte"
4237 #+end_src
4240 #+begin_src R :var num=little-fake
4242 #+end_src
4244 #+resname:
4245 : schulte
4247 #+srcname: set-debug-on-error
4248 #+begin_src emacs-lisp :results silent
4249 (setq debug-on-error t)
4250 #+end_src
4252 #+srcname: bug-numerical-table
4253 #+begin_src emacs-lisp :results silent
4254 '(1 2 3)
4255 #+end_src
4260 #+srcname: bug-R-number-evaluation
4261 #+begin_src R :var table=bug-numerical-table
4262 mean(mean(table))
4263 #+end_src
4265 #+resname:
4266 : 2
4270 #+tblname: bug-vert-table
4271 | 1 |
4272 | 2 |
4273 | 3 |
4275 #+srcname: bug-R-vertical-table
4276 #+begin_src R :var table=bug-vert-table :results silent
4277 mean(table)
4278 #+end_src
4280 ** DONE org bug/request: prevent certain org behaviour within code blocks
4281    E.g. [[]] gets recognised as a link (when there's text inside the
4282    brackets). This is bad for R code at least, and more generally
4283    could be argued to be inappropriate. Is it difficult to get org to
4284    ignore text in code blocks? [DED]
4285    
4286    I believe Carsten addressed this recently on the mailing list with
4287    the comment that it was indeed a difficult issue.  I believe this
4288    may be one area where we could wait for an upstream (org-mode) fix.
4290    [Dan] Carsten has fixed this now in the core.
4292 ** DONE with :results replace, non-table output doesn't replace table output
4293    And vice versa. E.g. Try this first with table and then with len(table) [DED]
4294 #+begin_src python :var table=sandbox :results replace
4295 table
4296 #+end_src
4298 | 1 |         2 | 3 |
4299 | 4 | "schulte" | 6 |
4300 : 2
4302 Yes, this is certainly a problem.  I fear that if we begin replacing
4303 anything immediately following a source block (regardless of whether
4304 it matches the type of our current results) we may accidentally delete
4305 hand written portions of the user's org-mode buffer.
4307 I think that the best solution here would be to actually start
4308 labeling results with a line that looks something like...
4310 #+results: name
4312 This would have a couple of benefits...
4313 1) we wouldn't have to worry about possibly deleting non-results
4314    (which is currently an issue)
4315 2) we could reliably replace results even if there are different types
4316 3) we could reference the results of a source-code block in variable
4317    definitions, which would be useful if for example we don't wish to
4318    re-run a source-block every time because it is long-running.
4320 Thoughts?  If no-one objects, I believe I will implement the labeling
4321 of results.
4323 ** DONE extra quotes for nested string
4324 Well R appears to be reading the tables without issue...
4326 these *should* be quoted
4327 #+srcname: ls
4328 #+begin_src sh :results replace
4330 #+end_src
4332 | "COPYING"          |
4333 | "README.markdown"  |
4334 | "block"            |
4335 | "examples.org"     |
4336 | "existing_tools"   |
4337 | "intro.org"        |
4338 | "org-babel"          |
4339 | "rorg.org"         |
4340 | "test-export.html" |
4341 | "test-export.org"  |
4343 #+srcname: test-quotes
4344 #+begin_src ruby :var tab=ls
4345 tab[1][0]
4346 #+end_src
4348 : README.markdown
4350 #+srcname: test-quotes
4351 #+begin_src R :var tab=ls
4352 as.matrix(tab[2,])
4353 #+end_src
4355 : README.markdown
4357 ** DONE simple ruby arrays not working
4359 As an example eval the following.  Adding a line to test
4361 #+tblname: simple-ruby-array
4362 | 3 | 4 | 5 |
4364 #+srcname: ruby-array-test
4365 #+begin_src ruby :var ar = simple-ruby-array :results silent
4366 ar.first.first
4367 #+end_src
4369 ** DONE space trailing language name
4370 fix regexp so it works when there's a space trailing the language name
4372 #+srcname: test-trailing-space
4373 #+begin_src ruby 
4374 :schulte
4375 #+end_src
4377 ** DONE Args out of range error
4378    
4379 The following block resulted in the error below [DED]. It ran without
4380 error directly in the shell.
4381 #+begin_src sh
4382 cd ~/work/genopca
4383 for platf in ill aff ; do
4384     for pop in CEU YRI ASI ; do
4385         rm -f $platf/hapmap-genos-$pop-all $platf/hapmap-rs-all
4386         cat $platf/hapmap-genos-$pop-* > $platf/hapmap-genos-$pop-all
4387         cat $platf/hapmap-rs-* > $platf/hapmap-rs-all
4388     done
4389 done
4390 #+end_src
4391   
4392  executing source block with sh...
4393 finished executing source block
4394 string-equal: Args out of range: "", -1, 0
4396 the error =string-equal: Args out of range: "", -1, 0= looks like what
4397 used to be output when the block returned an empty results string.
4398 This should be fixed in the current version, you should now see the
4399 following message =no result returned by source block=.
4401 ** DONE ruby arrays not recognized as such
4403 Something is wrong in [[file:lisp/org-babel-script.el]] related to the
4404 recognition of ruby arrays as such.
4406 #+begin_src ruby :results replace
4407 [1, 2, 3, 4]
4408 #+end_src
4410 | 1 | 2 | 3 | 4 |
4412 #+begin_src python :results replace
4413 [1, 2, 3, 4]
4414 #+end_src
4416 | 1 | 2 | 3 | 4 |
4417 ** REJECTED elisp reference fails for literal number
4418    That's a bug in Dan's elisp, not in org-babel.
4419 #+srcname: elisp-test(a=4)
4420 #+begin_src emacs-lisp 
4421 (message a)
4422 #+end_src
4428 : 30
4431 * Tests
4432 Evaluate all the cells in this table for a comprehensive test of the
4433 org-babel functionality.
4435 *Note*: if you have customized =org-babel-default-header-args= then some
4436 of these tests may fail.
4438 #+TBLNAME: org-babel-tests
4439 | functionality           | block                      | arg |    expected |     results | pass |
4440 |-------------------------+----------------------------+-----+-------------+-------------+------|
4441 | basic evaluation        |                            |     |             |             | pass |
4442 |-------------------------+----------------------------+-----+-------------+-------------+------|
4443 | emacs lisp              | basic-elisp                |     |           5 |           5 | pass |
4444 | shell                   | basic-shell                |     |           6 |           6 | pass |
4445 | ruby                    | basic-ruby                 |     |   org-babel |   org-babel | pass |
4446 | python                  | basic-python               |     | hello world | hello world | pass |
4447 | R                       | basic-R                    |     |          13 |          13 | pass |
4448 |-------------------------+----------------------------+-----+-------------+-------------+------|
4449 | tables                  |                            |     |             |             | pass |
4450 |-------------------------+----------------------------+-----+-------------+-------------+------|
4451 | emacs lisp              | table-elisp                |     |           3 |           3 | pass |
4452 | ruby                    | table-ruby                 |     |       1-2-3 |       1-2-3 | pass |
4453 | python                  | table-python               |     |           5 |           5 | pass |
4454 | R                       | table-R                    |     |         3.5 |         3.5 | pass |
4455 | R: col names in R       | table-R-colnames           |     |          -3 |          -3 | pass |
4456 | R: col names in org     | table-R-colnames-org       |     |         169 |         169 | pass |
4457 |-------------------------+----------------------------+-----+-------------+-------------+------|
4458 | source block references |                            |     |             |             | pass |
4459 |-------------------------+----------------------------+-----+-------------+-------------+------|
4460 | all languages           | chained-ref-last           |     |       Array |       Array | pass |
4461 |-------------------------+----------------------------+-----+-------------+-------------+------|
4462 | source block functions  |                            |     |             |             | pass |
4463 |-------------------------+----------------------------+-----+-------------+-------------+------|
4464 | emacs lisp              | defun-fibb                 |     |       fibbd |       fibbd | pass |
4465 | run over                | Fibonacci                  |   0 |           1 |           1 | pass |
4466 | a                       | Fibonacci                  |   1 |           1 |           1 | pass |
4467 | variety                 | Fibonacci                  |   2 |           2 |           2 | pass |
4468 | of                      | Fibonacci                  |   3 |           3 |           3 | pass |
4469 | different               | Fibonacci                  |   4 |           5 |           5 | pass |
4470 | arguments               | Fibonacci                  |   5 |           8 |           8 | pass |
4471 |-------------------------+----------------------------+-----+-------------+-------------+------|
4472 | bugs and tasks          |                            |     |             |             | pass |
4473 |-------------------------+----------------------------+-----+-------------+-------------+------|
4474 | simple ruby arrays      | ruby-array-test            |     |           3 |           3 | pass |
4475 | R number evaluation     | bug-R-number-evaluation    |     |           2 |           2 | pass |
4476 | multi-line ruby blocks  | multi-line-ruby-test       |     |           2 |           2 | pass |
4477 | forcing vector results  | test-forced-vector-results |     |       Array |       Array | pass |
4478 | deeply nested arguments | deeply-nested-args-bug     |     |           4 |           4 | pass |
4479 |-------------------------+----------------------------+-----+-------------+-------------+------|
4480 | sessions                |                            |     |             |             | pass |
4481 |-------------------------+----------------------------+-----+-------------+-------------+------|
4482 | set ruby session        | set-ruby-session-var       |     |        :set |        :set | pass |
4483 | get from ruby session   | get-ruby-session-var       |     |           3 |           3 | pass |
4484 | set python session      | set-python-session-var     |     |         set |         set | pass |
4485 | get from python session | get-python-session-var     |     |           4 |           4 | pass |
4486 | set R session           | set-R-session-var          |     |         set |         set | pass |
4487 | get from R session      | get-R-session-var          |     |           5 |           5 | pass |
4488 #+TBLFM: $5='(if (= (length $3) 1) (progn (message (format "running %S" '(sbe $2 (n $3)))) (sbe $2 (n $3))) (sbe $2))::$6='(if (string= $4 $5) "pass" (format "expected %S but was %S" $4 $5))
4489 #+TBLFM: $5=""::$6=""
4492 The second TBLFM line (followed by replacing '[]' with '') can be used
4493 to blank out the table results, in the absence of a better method.
4495 ** basic tests
4497 #+srcname: basic-elisp
4498 #+begin_src emacs-lisp :results silent
4499 (+ 1 4)
4500 #+end_src
4503 #+srcname: basic-shell
4504 #+begin_src sh :results silent
4505 expr 1 + 5
4506 #+end_src
4509 #+srcname: date-simple
4510 #+begin_src sh :results silent
4511 date
4512 #+end_src
4514 #+srcname: basic-ruby
4515 #+begin_src ruby :results silent
4516 "org-babel"
4517 #+end_src
4520 #+srcname: basic-python
4521 #+begin_src python :results silent
4522 'hello world'
4523 #+end_src
4526 #+srcname: basic-R
4527 #+begin_src R :results silent
4528 b <- 9
4529 b + 4
4530 #+end_src
4533 ** read tables
4535 #+tblname: test-table
4536 | 1 | 2 | 3 |
4537 | 4 | 5 | 6 |
4539 #+tblname: test-table-colnames
4540 | var1 | var2 | var3 |
4541 |------+------+------|
4542 |    1 |   22 |   13 |
4543 |   41 |   55 |   67 |
4545 #+srcname: table-elisp
4546 #+begin_src emacs-lisp :results silent :var table=test-table
4547 (length (car table))
4548 #+end_src
4551 #+srcname: table-ruby
4552 #+begin_src ruby :results silent :var table=test-table
4553 table.first.join("-")
4554 #+end_src
4557 #+srcname: table-python
4558 #+begin_src python :var table=test-table
4559 table[1][1]
4560 #+end_src
4562 #+srcname: table-R(table=test-table)
4563 #+begin_src R
4564 mean(mean(table))
4565 #+end_src
4567 #+srcname: table-R-colnames(table=test-table-colnames)
4568 #+begin_src R :results silent
4569 sum(table$var2 - table$var3)
4570 #+end_src
4572 #+srcname: R-square(x=default-name-doesnt-exist)
4573 #+begin_src R :colnames t
4575 #+end_src
4577 This should return 169. The fact that R is able to use the column name
4578 to index the data frame (x$var3) proves that a table with column names
4579 (a header row) has been recognised as input for the R-square function
4580 block, and that the R-square block has output an elisp table with
4581 column names, and that the colnames have again been recognised when
4582 creating the R variables in this block.
4583 #+srcname: table-R-colnames-org(x = R-square(x=test-table-colnames))
4584 #+begin_src R
4585 x$var3[1]
4586 #+end_src
4591 ** references
4593 Lets pass a references through all of our languages...
4595 Lets start by reversing the table from the previous examples
4597 #+srcname: chained-ref-first
4598 #+begin_src python :var table = test-table
4599 table.reverse()
4600 table
4601 #+end_src
4603 #+resname: chained-ref-first
4604 | 4 | 5 | 6 |
4605 | 1 | 2 | 3 |
4607 Take the first part of the list
4609 #+srcname: chained-ref-second
4610 #+begin_src R :var table = chained-ref-first
4611 table[1]
4612 #+end_src
4614 #+resname: chained-ref-second
4615 | 4 |
4616 | 1 |
4618 Turn the numbers into string
4620 #+srcname: chained-ref-third
4621 #+begin_src emacs-lisp :var table = chained-ref-second
4622 (mapcar (lambda (el) (format "%S" el)) table)
4623 #+end_src
4625 #+resname: chained-ref-third
4626 | "(4)" | "(1)" |
4628 and Check that it is still a list
4630 #+srcname: chained-ref-last
4631 #+begin_src ruby :var table=chained-ref-third
4632 table.class.name
4633 #+end_src
4636 ** source blocks as functions
4638 #+srcname: defun-fibb
4639 #+begin_src emacs-lisp :results silent
4640 (defun fibbd (n) (if (< n 2) 1 (+ (fibbd (- n 1)) (fibbd (- n 2)))))
4641 #+end_src
4644 #+srcname: fibonacci
4645 #+begin_src emacs-lisp :results silent :var n=7
4646 (fibbd n)
4647 #+end_src
4655 ** sbe tests (these don't seem to be working...)
4656 Testing the insertion of results into org-mode tables.
4658 #+srcname: multi-line-output
4659 #+begin_src ruby :results replace
4660 "the first line ends here
4663      and this is the second one
4665 even a third"
4666 #+end_src
4668 #+resname:
4669 : the first line ends here\n\n\n     and this is the second one\n\neven a third
4671 #+srcname: multi-line-error
4672 #+begin_src ruby :results replace
4673 raise "oh nooooooooooo"
4674 #+end_src
4676 #+resname:
4677 : oh nooooooooooo
4679 | the first line ends here... | -:5: warning: parenthesize argument(s) for future version... |
4680 #+TBLFM: $1='(sbe "multi-line-output")::$2='(sbe "multi-line-error")
4682 ** forcing results types tests
4684 #+srcname: test-trivial-vector
4685 #+begin_src emacs-lisp :results vector silent
4687 #+end_src
4689 #+srcname: test-forced-vector-results
4690 #+begin_src ruby :var triv=test-trivial-vector :results silent
4691 triv.class.name
4692 #+end_src
4694 ** sessions
4696 #+srcname: set-ruby-session-var
4697 #+begin_src ruby :session :results silent
4698 var = [1, 2, 3]
4699 :set
4700 #+end_src
4702 #+srcname: get-ruby-session-var
4703 #+begin_src ruby :session :results silent
4704 var.size
4705 #+end_src
4707 #+srcname: set-python-session-var
4708 #+begin_src python :session
4709 var=4
4710 'set'
4711 #+end_src
4713 #+srcname: get-python-session-var
4714 #+begin_src python :session
4716 #+end_src
4718 #+srcname: set-R-session-var
4719 #+begin_src R :session
4720 a <- 5
4721 'set'
4722 #+end_src
4724 #+srcname: get-R-session-var
4725 #+begin_src R :session
4727 #+end_src
4730 * Sandbox
4731   :PROPERTIES:
4732   :CUSTOM_ID: sandbox
4733   :END:
4734 To run these examples evaluate [[file:lisp/org-babel-init.el][org-babel-init.el]]
4736 ** org-babel.el beginning functionality
4738 #+begin_src sh  :results replace
4739 date
4740 #+end_src
4742 #+resname:
4743 : Sun Jul  5 18:54:39 EDT 2009
4745 #+begin_src ruby
4746 Time.now
4747 #+end_src
4749 #+resname:
4750 : Sun Jul 05 18:54:35 -0400 2009
4752 #+begin_src python
4753 "Hello World"
4754 #+end_src
4756 #+resname:
4757 : Hello World
4760 ** org-babel-R
4762 #+begin_src R :results replace
4763 a <- 9
4764 b <- 16
4765 a + b
4766 #+end_src
4768 #+resname:
4769 : 25
4771 #+begin_src R
4772 hist(rgamma(20,3,3))
4773 #+end_src
4777 ** org-babel plays with tables
4778 Alright, this should demonstrate both the ability of org-babel to read
4779 tables into a lisp source code block, and to then convert the results
4780 of the source code block into an org table.  It's using the classic
4781 "lisp is elegant" demonstration transpose function.  To try this
4782 out...
4784 1. evaluate [[file:lisp/org-babel-init.el]] to load org-babel and friends
4785 2. evaluate the transpose definition =\C-c\\C-c= on the beginning of
4786    the source block
4787 3. evaluate the next source code block, this should read in the table
4788    because of the =:var table=previous=, then transpose the table, and
4789    finally it should insert the transposed table into the buffer
4790    immediately following the block
4792 *** Emacs lisp
4794 #+begin_src emacs-lisp :results silent
4795 (defun transpose (table)
4796   (apply #'mapcar* #'list table))
4797 #+end_src
4800 #+TBLNAME: sandbox
4801 | 1 |       2 | 3 |
4802 | 4 | schulte | 6 |
4804 #+begin_src emacs-lisp :var table=sandbox :results replace
4805 (transpose table)
4806 #+end_src
4809 #+begin_src emacs-lisp
4810 '(1 2 3 4 5)
4811 #+end_src
4813 #+resname:
4814 | 1 | 2 | 3 | 4 | 5 |
4816 *** Ruby and Python
4818 #+begin_src ruby :var table=sandbox :results replace
4819 table.first.join(" - ")
4820 #+end_src
4822 #+resname:
4823 : 1 - 2 - 3
4825 #+begin_src python :var table=sandbox
4826 table[0]
4827 #+end_src
4830 #+begin_src ruby :var table=sandbox :results replace
4831 table
4832 #+end_src
4834 #+resname:
4835 : [[1, 2, 3], [4, "schulte", 6]]
4838 | 1 |         2 | 3 |
4839 | 4 | "schulte" | 6 |
4841 #+begin_src python :var table=sandbox :results replace
4842 len(table)
4843 #+end_src
4845 : 2
4847 | "__add__" | "__class__" | "__contains__" | "__delattr__" | "__delitem__" | "__delslice__" | "__doc__" | "__eq__" | "__format__" | "__ge__" | "__getattribute__" | "__getitem__" | "__getslice__" | "__gt__" | "__hash__" | "__iadd__" | "__imul__" | "__init__" | "__iter__" | "__le__" | "__len__" | "__lt__" | "__mul__" | "__ne__" | "__new__" | "__reduce__" | "__reduce_ex__" | "__repr__" | "__reversed__" | "__rmul__" | "__setattr__" | "__setitem__" | "__setslice__" | "__sizeof__" | "__str__" | "__subclasshook__" | "append" | "count" | "extend" | "index" | "insert" | "pop" | "remove" | "reverse" | "sort" |
4849 *** (sandbox table) R
4851 #+TBLNAME: sandbox_r
4852 | 1 |       2 | 3 |
4853 | 4 | schulte | 6 |
4855 #+begin_src R :results replace
4856 x <- c(rnorm(10, mean=-3, sd=1), rnorm(10, mean=3, sd=1))
4858 #+end_src
4860 | -3.35473133869346 |
4861 |    -2.45714878661 |
4862 | -3.32819924928633 |
4863 | -2.97310212756194 |
4864 | -2.09640758369576 |
4865 | -5.06054014378736 |
4866 | -2.20713700711221 |
4867 | -1.37618039712037 |
4868 | -1.95839385821742 |
4869 | -3.90407396475502 |
4870 |  2.51168071590226 |
4871 |  3.96753011570494 |
4872 |  3.31793212627865 |
4873 |  1.99829753972341 |
4874 |  4.00403686419829 |
4875 |  4.63723764452927 |
4876 |  3.94636744261313 |
4877 |  3.58355906547775 |
4878 |  3.01563442274226 |
4879 |   1.7634976849927 |
4881 #+begin_src R var tabel=sandbox_r :results replace
4882 tabel
4883 #+end_src
4885 | 1 |         2 | 3 |
4886 | 4 | "schulte" | 6 |
4888 *** shell
4889 Now shell commands are converted to tables using =org-table-import=
4890 and if these tables are non-trivial (i.e. have multiple elements) then
4891 they are imported as org-mode tables...
4893 #+begin_src sh :results replace
4894 ls -l
4895 #+end_src
4897 | "total"      | 208 | ""    | ""    |    "" |   "" | "" | ""                |
4898 | "-rw-r--r--" |   1 | "dan" | "dan" |    57 | 2009 | 15 | "block"           |
4899 | "-rw-r--r--" |   1 | "dan" | "dan" | 35147 | 2009 | 15 | "COPYING"         |
4900 | "-rw-r--r--" |   1 | "dan" | "dan" |   722 | 2009 | 18 | "examples.org"    |
4901 | "drwxr-xr-x" |   4 | "dan" | "dan" |  4096 | 2009 | 19 | "existing_tools"  |
4902 | "-rw-r--r--" |   1 | "dan" | "dan" |  2207 | 2009 | 14 | "intro.org"       |
4903 | "drwxr-xr-x" |   2 | "dan" | "dan" |  4096 | 2009 | 18 | "org-babel"         |
4904 | "-rw-r--r--" |   1 | "dan" | "dan" |   277 | 2009 | 20 | "README.markdown" |
4905 | "-rw-r--r--" |   1 | "dan" | "dan" | 11837 | 2009 | 18 | "rorg.html"       |
4906 | "-rw-r--r--" |   1 | "dan" | "dan" | 61829 | 2009 | 19 | "#rorg.org#"      |
4907 | "-rw-r--r--" |   1 | "dan" | "dan" | 60190 | 2009 | 19 | "rorg.org"        |
4908 | "-rw-r--r--" |   1 | "dan" | "dan" |   972 | 2009 | 11 | "test-export.org" |
4911 ** silent evaluation
4913 #+begin_src ruby
4914 :im_the_results
4915 #+end_src
4917 : :im_the_results
4919 #+begin_src ruby :results silent
4920 :im_the_results
4921 #+end_src
4923 #+begin_src ruby :results replace
4924 :im_the_results_
4925 #+end_src
4927 : :im_the_results_
4930 ** (sandbox) referencing other source blocks
4931 Doing this in emacs-lisp first because it's trivial to convert
4932 emacs-lisp results to and from emacs-lisp.
4934 *** emacs lisp source reference
4935 This first example performs a calculation in the first source block
4936 named =top=, the results of this calculation are then saved into the
4937 variable =first= by the header argument =:var first=top=, and it is
4938 used in the calculations of the second source block.
4940 #+SRCNAME: top
4941 #+begin_src emacs-lisp
4942 (+ 4 2)
4943 #+end_src
4945 #+begin_src emacs-lisp :var first=top :results replace
4946 (* first 3)
4947 #+end_src
4949 : 18
4951 This example is the same as the previous only the variable being
4952 passed through is a table rather than a number.
4954 #+begin_src emacs-lisp :results silent
4955 (defun transpose (table)
4956   (apply #'mapcar* #'list table))
4957 #+end_src
4959 #+TBLNAME: top_table
4960 | 1 |       2 | 3 |
4961 | 4 | schulte | 6 |
4963 #+SRCNAME: second_src_example
4964 #+begin_src emacs-lisp :var table=top_table
4965 (transpose table)
4966 #+end_src
4968 #+begin_src emacs-lisp :var table=second_src_example :results replace
4969 (transpose table)
4970 #+end_src
4972 | 1 |         2 | 3 |
4973 | 4 | "schulte" | 6 |
4974 *** ruby python
4975 Now working for ruby
4977 #+srcname: start
4978 #+begin_src ruby
4980 #+end_src
4982 #+begin_src ruby :var other=start :results replace
4983 2 * other
4984 #+end_src
4986 and for python
4988 #+SRCNAME: start_two
4989 #+begin_src python
4991 #+end_src
4993 #+begin_src python :var another=start_two :results replace
4994 another*3
4995 #+end_src
4997 *** mixed languages
4998 Since all variables are converted into Emacs Lisp it is no problem to
4999 reference variables specified in another language.
5001 #+SRCNAME: ruby-block
5002 #+begin_src ruby
5004 #+end_src
5006 #+SRCNAME: lisp_block
5007 #+begin_src emacs-lisp :var ruby-variable=ruby-block
5008 (* ruby-variable 8)
5009 #+end_src
5011 #+begin_src python :var lisp_var=lisp_block
5012 lisp_var + 4
5013 #+end_src
5015 : 20
5017 *** R
5019 #+srcname: first_r
5020 #+begin_src R :results replace
5021 a <- 9
5023 #+end_src
5025 : 9
5027 #+begin_src R :var other=first_r :results replace
5028 other + 2
5029 #+end_src
5031 : 11
5034 ** (sandbox) selective export
5036 For exportation tests and examples see (including exportation of
5037 inline source code blocks) [[file:test-export.org]]
5040 ** (sandbox) source blocks as functions
5042 #+srcname: default
5043 #+begin_src emacs-lisp :results silent
5045 #+end_src
5047 #+srcname: triple
5048 #+begin_src emacs-lisp :var n=default :results replace
5049 (* 3 n)
5050 #+end_src
5052 : 15
5054 #+begin_src emacs-lisp :var result=triple(n=3, m=98) :results replace
5055 result
5056 #+end_src
5058 : 294
5060 The following just demonstrates the ability to assign variables to
5061 literal values, which was not implemented until recently.
5063 #+begin_src ruby :var num="eric" :results replace
5064 num+" schulte "
5065 #+end_src
5067 : "eric schulte "
5070 ** (sandbox) inline source blocks
5072 This is an inline source code block src_ruby{1 + 6}.  And another
5073 source block with text output src_emacs-lisp{"eric"}.
5075 This is an inline source code block with header
5076 arguments.  src_ruby[:var n=fibbd( n = 0 )]{n}
5079 ** (sandbox) integration w/org tables
5081 #+begin_src emacs-lisp :results silent
5082 (defun fibbd (n) (if (< n 2) 1 (+ (fibbd (- n 1)) (fibbd (- n 2)))))
5083 #+end_src
5085 #+srcname: fibbd
5086 #+begin_src emacs-lisp :var n=4 :results silent
5087 (fibbd n)
5088 #+end_src
5090 #+begin_src emacs-lisp :results silent
5091 (mapcar #'fibbd '(0 1 2 3 4 5 6 7 8))
5092 #+end_src
5094 Something is not working here.  The function `sbe ' works fine when
5095 called from outside of the table (see the source block below), but
5096 produces an error when called from inside the table.  I think there
5097 must be some narrowing going on during intra-table emacs-lisp
5098 evaluation.
5100 | original | fibbd |
5101 |----------+-------|
5102 |        0 |     1 |
5103 |        1 |     1 |
5104 |        2 |     2 |
5105 |        3 |     3 |
5106 |        4 |     5 |
5107 |        5 |     8 |
5108 |        6 |    13 |
5109 |        7 |    21 |
5110 |        8 |    34 |
5111 |        9 |    55 |
5112 #+TBLFM: $2='(sbe "fibbd" (n $1))
5114 silent-result
5116 #+begin_src emacs-lisp :results silent
5117 (sbe 'fibbd (n "8"))
5118 #+end_src
5121 * Buffer Dictionary
5122  LocalWords:  DBlocks dblocks org-babel el eric fontification