1 #+OPTIONS: H:3 num:nil toc:1 \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate
3 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS: Write(w) Update(u) Fix(f) Check(c)
6 #+AUTHOR: Dan Davison, Eric Schulte
7 #+EMAIL: davison at stats dot ox dot ac dot uk
13 <p>executable source code blocks in org-mode</p>
17 <img src="images/tower-of-babel.png" alt="images/tower-of-babel.png"
18 title="And the Lord said, Behold, the people is one, and they have all one language; and this they begin to do; and now nothing will be restrained from them, which they have imagined to do. Genesis 11:1-9"/>
21 <a href="http://www.flickr.com/photos/23379658@N05/" title=""><b>Martijn Streefkerk</b></a>
28 Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
29 support]] for blocks of source code examples in the org-mode core.
30 1. source code execution
31 2. arguments to source code blocks
32 3. exportation of source code blocks to files (literate programming)
35 Grab the latest code from the git repo at [[http://github.com/eschulte/org-babel/tree/master][github/org-babel]]
37 git clone git://github.com/eschulte/org-babel.git
40 And add the following lines to your .emacs, replacing the path as
41 appropriate. A good place to check that things are up and running
42 would the examples in [[* Basic org-babel functionality][Basic org-babel functionality]].
43 #+begin_src emacs-lisp
44 (add-to-list 'load-path "/path/to/org-babel/lisp")
45 (require 'org-babel-init)
48 * Basic org-babel functionality
49 *** Source code execution
50 For interpreted languages such as shell, python, R, etc, org-babel
51 allows source blocks to be executed: the code is passed to the
52 interpreter and you have control over what is done with the
53 results of excecution. E.g. place point anywhere in the following
54 block and use C-c C-c to run the code:
56 [[http://www.ruby-lang.org/][Ruby]] source code
58 "This file was last evaluated on #{Date.today}"
61 Results of Ruby evaluation
63 : This file was last evaluated on 2009-08-09
65 [[http://www.r-project.org/][R]] source code
66 #+begin_src R :results value
72 Results of R evaluation
77 *** What happens to the results?
78 Org-babel provides two fundamentally different modes for capturing
79 the results of code evaluation, specified by the :results header
82 This means that the 'result' of code evaluation is defined to be
83 the *value* of the last statement in the block. Thus with this
84 setting, one can view the code block as a function with a return
85 value. And not only can one view it that way, but you can
86 actually use the return value of one source block as input for
87 another (see later). This setting is the default.
89 With this setting, org-babel captures all the text output of the
90 code block and places it in the org buffer. One can think of this
91 as a 'scripting' mode: the code block contains a series of
92 commands, and you get the output of all the commands. Unlike in
93 the 'functional' mode specified by =:results value=, the code
94 block has no return value. (This mode will be familiar to Sweave
96 **** Additional :results settings
98 *** Arguments to source code blocks
100 :CUSTOM_ID: arguments-to-source-code-blocks
102 In addition to evaluation of code blocks, org-babel allows them to
103 be parameterised (i.e. have arguments). Thus source code blocks
104 now have the status of *functions*.
106 Inputs for fibonacci-seq
108 #+tblname: fibonacci-inputs
109 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
110 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
112 in the Org-mode buffer this looks like
113 : #+tblname: fibonacci-inputs
114 : | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
115 : | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
117 [[http://www.gnu.org/software/emacs/manual/elisp.html][Emacs Lisp]] source code
118 #+srcname: fibonacci-seq
119 #+begin_src emacs-lisp :var fib-inputs=fibonacci-inputs
121 (if (or (= n 0) (= n 1))
123 (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
125 (mapcar (lambda (row)
126 (mapcar #'fibonacci row)) fib-inputs)
129 in the Org-mode buffer this looks like
130 : #+srcname: fibonacci-seq
131 : #+begin_src emacs-lisp :var fib-inputs=fibonacci-inputs
132 : (defun fibonacci (n)
133 : (if (or (= n 0) (= n 1))
135 : (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
137 : (mapcar (lambda (row)
138 : (mapcar #'fibonacci row)) fib-inputs)
141 Results of Emacs Lisp code evaluation
143 | 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 | 34 | 55 |
144 | 1 | 3 | 8 | 21 | 55 | 144 | 377 | 987 | 2584 | 6765 |
146 * A meta-programming language for org-mode
148 Since information can pass freely between source-code blocks and
149 org-mode tables you can mix and match languages using each language
150 for those tasks to which it is suited. This makes Org-mode files with
151 Org-babel into a kind of meta-functional programming language in which
152 functions from many languages can work together.
154 As an example, lets take some system diagnostics in the shell, and
155 then graph them with R.
158 #+srcname: directories
159 #+begin_src bash :results replace
160 cd ~ && du -sc * |grep -v total
162 2. Results of the shell source code (on my system, grab this org-mode
163 files and try running it on your own)
164 #+resname: directories
166 | 12156104 | "Documents" |
167 | 3482440 | "Downloads" |
168 | 2901720 | "Library" |
170 | 16548024 | "Music" |
172 | 7649472 | "Pictures" |
180 3. R source code (which calls the previous shell source code)
181 #+srcname: directory-pie
182 #+begin_src R :var dirs = directories :session R-pie-example
183 pie(dirs[,1], labels = dirs[,2])
185 4. Results of R code [[file:images/dirs.png]]
187 * Spreadsheet plugins for org-mode in any language
189 *NOTE*: Maybe in-addition-to/in-stead-of this example we should do a
190 more traditional "spreadsheet" example with R [Eric]
192 Not only can Org-babel pass entire tables of data to source code
193 blocks (see [[arguments-to-source-code-blocks]]), Org-babel can also be
194 used to call source code blocks from *within* tables using the
195 Org-mode's [[http://orgmode.org/manual/The-spreadsheet.html#The-spreadsheet][existing spreadsheet functionality]].
197 In fact the functional test suite for Org-babel is implemented as a
198 large Org-mode table. To run the entire test suite you simple
199 evaluate the table =C-u C-c C-c=, and all of the tests are run
200 updating the table with pass/fail statistics.
202 Here's a sample of our test suite.
204 #+TBLNAME: org-babel-tests
205 | functionality | block | arg | expected | results | pass |
206 |------------------+--------------+-----+-------------+-------------+------|
207 | basic evaluation | | | | | pass |
208 |------------------+--------------+-----+-------------+-------------+------|
209 | emacs lisp | basic-elisp | 2 | 4 | 4 | pass |
210 | shell | basic-shell | | 6 | 6 | pass |
211 | ruby | basic-ruby | | org-babel | org-babel | pass |
212 | python | basic-python | | hello world | hello world | pass |
213 | R | basic-R | | 13 | 13 | pass |
214 #+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))
215 #+TBLFM: $5=""::$6=""
217 ** code blocks for tests
219 #+srcname: basic-elisp
220 #+begin_src emacs-lisp :var n=7
224 #+srcname: basic-shell
225 #+begin_src sh :results silent
229 #+srcname: date-simple
230 #+begin_src sh :results silent
234 #+srcname: basic-ruby
235 #+begin_src ruby :results silent
239 #+srcname: basic-python
240 #+begin_src python :results silent
245 #+begin_src R :results silent
251 What about those source code blocks which are so useful you want to
252 have them available in every org-mode buffer?
254 The [[file:library-of-babel.org][Library of Babel]] is an extensible collection of ready-made and
255 easily-shortcut-callable source-code blocks for handling common
256 tasks. Org-babel comes pre-populated with the source-code blocks
257 located in the [[file:library-of-babel.org][library-of-babel.org]] file. It is possible to add
258 source-code blocks from any org-mode file to the library by calling
260 #+srcname: add-file-to-lob
261 #+begin_src emacs-lisp
262 (org-babel-lob-ingest "path/to/file.org")
265 * Reproducible research
266 - output vs. value mode
267 - file & graphical output
269 * Literate programming
271 - org-babel-load-file
272 * Reference / Documentation
274 *** Source Code block syntax
276 The basic syntax of source-code blocks is as follows:
279 : #+begin_src language header-arguments
283 - name :: This name is associated with the source-code block. This is
284 similar to the =#+TBLNAME= lines which can be used to name tables
285 in org-mode files. By referencing the srcname of a source-code
286 block it is possible to evaluate the block for other places,
287 files, or from inside tables.
288 - language :: The language of the code in the source-code block, valid
289 values must be members of `org-babel-interpreters'.
290 - header-arguments :: Header arguments control many facets of the
291 input to, evaluation of, and output of source-code blocks. See
292 the [[* Header Arguments][Header Arguments]] section for a complete review of available
294 - body :: The actual source code which will be evaluated. This can be
295 edited with `org-edit-special'.
297 **** Header Arguments
299 - results :: results arguments specify what should be done with the
300 output of source-code blocks
301 - The following options are mutually exclusive, and specify how the
302 results should be collected from the source-code block
305 - The following options are mutually exclusive and specify what type
306 of results the code block will return
307 - vector :: specifies that the results should be interpreted as a
308 multidimensional vector (even if the vector is
309 trivial), and will be inserted into the org-mode file
311 - scalar :: specifies that the results should be interpreted as a
312 scalar value, and will be inserted into the org-mode
314 - file :: specifies that the results should be interpreted as the
315 path to a file, and will be inserted into the org-mode
317 - The following options specify how the results should be inserted
318 into the org-mode file
319 - replace :: the current results replace any previously inserted
320 results from the code block
321 - silent :: rather than being inserted into the org-mode file the
322 results are echoed into the message bar
323 - exports :: exports arguments specify what should be included in html
324 or latex exports of the org-mode file
325 - code :: the body of code is included into the exported file
326 - results :: the results of evaluating the code is included in the
328 - both :: both the code and results are included in the exported
330 - none :: nothing is included in the exported file
331 - tangle :: tangle arguments specify whether or not the source-code
332 block should be included in tangled extraction of
334 - yes :: the source-code block is exported to a source-code file
335 named after the basename (name w/o extension) of the
337 - no :: (default) the source-code block is not exported to a
339 - other :: any other string passed to the =tangle= header argument
340 is interpreted as a file basename to which the block will