1 #+OPTIONS: H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:nil skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate hideblocks
3 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS: Write(w) Update(u) Fix(f) Check(c) noexport(n)
5 #+TITLE: Org-babel: Introduction
6 #+AUTHOR: Eric Schulte, Dan Davison, Tom Dye
7 #+EMAIL: schulte.eric at gmail dot com, davison at stats dot ox dot ac dot uk, tsd at tsdye dot com
9 #+STYLE: <style type="text/css">#outline-container-introduction{ clear:both; }</style>
11 [[file:index.org][{Back to Babel's index}]]
14 <div id="subtitle" style="float: center; text-align: center;">
15 <p>executable source code blocks in org-mode</p>
17 <div id="logo" style="float: left; text-align: center; max-width: 340px; font-size: 8pt; margin-left: 1em;">
19 <img src="../../images/babel/tower-of-babel.png" alt="Tower of Babel"/>
20 <div id="attr" style="margin: -0.5em;">
22 <a href="http://commons.wikimedia.org/wiki/Pieter_Brueghel_the_Elder" title="">
23 <b>Pieter Brueghel the Elder</b>
27 And the Lord said, Behold, the people is one, and they have all
28 one language; and this they begin to do; and now nothing will be
29 restrained from them, which they have imagined to do. Genesis
36 * Improving this document :noexport:
37 ** DONE Document slice indexing of tables
38 ** DONE Document synonymous alternatives
39 {call,lob}, {source, function, srcname}, {results, resname}
40 ** DONE Describe useful functions
41 - `org-babel-execute-buffer'
42 - `org-babel-execute-subtree'
44 ** TODO Language support
45 Hopefully we will be breaking out a separate section for
46 each language, and expanding the portion which documents the actual
47 usage of header-arguments and noweb references as those sections are
49 ** DONE Document noweb references
50 *** DONE Why is :noweb needed for execution but not for tangling?
52 - org-babel can now cache the results of source block execution to avoid
53 rerunning the same calculation. The cache uses a sha1 hash key of the
54 source code body and the header arguments to determine if
55 recalculation is required. These hash keys are kept mostly hidden in
56 the #+resname line of the results of the block. This behavior is
57 turned off by default. It is controlled through the :cache
58 and :nocache header arguments. To enable caching on a single block
59 add the :cache header argument, to enable global caching change the
60 value of your `org-babel-default-header-args' variable as follows
62 (setq org-babel-default-header-args
64 (assq-delete-all :nocache org-babel-default-header-args)))
66 - It is now possible to fold results by tabbing on the beginning of the
67 #+resname line. This can be done automatically to all results on
68 opening of a file by adding the following to your org-mode hook
70 (add-hook 'org-mode-hook 'org-babel-result-hide-all)
72 - allow header argument values to be lisp forms, for example the
73 following is now valid
75 :file (format "%s/images/pca-scatter.png" dir)
77 ** DONE Useful variables
78 - # -*- org-src-preserve-indentation: t -*-
79 ** TODO Language specific header arguments
80 - org-babel: capture graphical output from R
82 If a [:file filename.ext] header arg is provided, then all graphical
83 output from the source block is captured on disk, and output of the
84 source block is a link to the resulting file, as with the
85 graphics-only languages such as gnuplot, ditaa, dot, asymptote. An
86 attempt is made to find a graphics device corresponding to the file
87 extension (currently .png, .jpg, .jpeg, .tiff, .bmp, .pdf, .ps,
88 .postscript are recognised); if that fails, png format output is
91 Additionally, values for several arguments to the R graphics
92 device can be passed using header args:
94 :width :height :bg :units :pointsize
95 :antialias :quality :compression :res :type
96 :family :title :fonts :version :paper :encoding
97 :pagecentre :colormodel :useDingbats :horizontal
99 Arguments to the R graphics device that are not supported as header
100 args can be passed as a string in R argument syntax, using the header
103 An example block is (although both bg and fg can be passed directly as
106 \#+begin_src R :file z.pdf :width 8 :height 8 :R-dev-args bg="olivedrab", fg="hotpink"
107 plot(matrix(rnorm(100), ncol=2), type="l")
110 - Yes, I think we do want a version of this for python and ruby et al. In
111 your example, the filename is created in python. I suggest doing it
112 slightly differently, something like this.
114 #+srcname: fileoutput
115 #+begin_src python :file outfile.txt
116 def savetofile(result, filename):
117 with open(filename, 'w') as f:
119 savetofile(78, 'outfile.txt')
123 #+resname: fileoutput
126 This functionality is now available for ruby & python in branch
127 ded-babel of git://repo.or.cz/org-mode/babel.git.
129 So here, if you specify :file <filepath> ruby/python blindly outputs a
130 link to <filepath>, regardless of the contents of the
131 code. Responsibility for creating useful contents of <filepath> lies
132 with the code. Notice that with this you have to specify the output file
133 twice: once as an org-babel directive, and once in the python code. This
134 is in contrast to the graphics languages (dot, ditaa, asymptote), where
135 the results *automatically* get sent to the file specified by :file. The
136 same is also true now for graphical output from R.
138 The difference with python, ruby et al is that they might create file
139 output in a variety of ways which we can't anticipate, so we can't
140 automatically send output to the file. In contrast, the graphics
141 language *always* create file output and always do it in the same
142 way. [And in R it is possible to divert all graphical output to file] A
143 possible extension of the above might be to use a "magic variable" so
144 that a python variable is created e.g. __org_babel_output_file__ that
145 always holds a string corresponding to the file specified by :file. Eric
146 may have further ideas / views here.
149 ** DONE What function is bound to C-c '?
150 - this document notes two different functions
153 :CUSTOM_ID: introduction
155 Org-babel extends the very excellent [[http://orgmode.org/][Org-mode]] with the ability to
156 execute source code within Org-mode documents. Org-mode is an [[http://www.gnu.org/software/emacs/][Emacs]]
157 major mode for doing almost anything with plain text. If you are
158 not familiar with Org-mode please take a moment to read [[http://orgmode.org/][the Org-mode
159 homepage]] before continuing.
161 As its name implies, Org-babel will execute code in many different
162 languages. The results of code execution --- text, tables and
163 graphics --- can be used as input to other source code blocks or
164 integrated into the powerful publishing facilities of Org-mode.
166 Org-babel augments [[http://orgmode.org/manual/Literal-examples.html][Org-mode support for source code blocks]]
169 - interactive and on-export execution of source code;
170 - code blocks as functions that can be parameterised, refer to
171 other code blocks, and be called remotely; and
172 - export to files for literate programming.
176 :CUSTOM_ID: getting-started
180 If you have a working Emacs installation, then getting started with
181 Org-babel is a simple five-step process.
183 1) It is strongly recommended that you update to the latest version
184 of Org-mode by [[file:../../org-faq.org::keeping-current-with-Org-mode-development][keeping current with Org-mode development]].
185 Org-babel is included in the contrib directory of Org-mode.
187 2) Make sure that the path to Org-mode's contrib/lisp directory is in
188 your load-path and add the following Emacs Lisp expression to your .emacs.
189 #+begin_src emacs-lisp
190 (require 'org-babel-init)
193 3) Activate the subset of [[#reference-and-documentation][supported Org-babel languages]] that you
194 will be using by adding Emacs Lisp expressions to your
195 .emacs. As an example, the following three Emacs Lisp
196 expressions activate R, Ruby, Python and Clojure. Shell script and
197 Emacs-lisp are enabled by default.
198 #+begin_src emacs-lisp
199 (require 'org-babel-R) ;; requires R and ess-mode
200 (require 'org-babel-ruby) ;; requires ruby, irb, ruby-mode, and inf-ruby
201 (require 'org-babel-python) ;; requires python, and python-mode
202 (require 'org-babel-clojure) ;; requires clojure, clojure-mode, swank-clojure and slime
205 4) Load the Library of Babel by adding the following Emacs Lisp
206 expression to your .emacs. The Library of Babel will make
207 pre-built helper functions available in the languages you will be
209 #+begin_src emacs-lisp
210 (org-babel-load-library-of-babel)
213 5) Evaluate your modified .emacs.
215 * Basic Org-babel Functionality
217 :CUSTOM_ID: basic-functionality
219 *** Source Code Blocks
221 :CUSTOM_ID: source-code-blocks
224 Org-babel is all about [[http://orgmode.org/manual/Literal-examples.html][source code blocks]] in Org-mode. If you are
225 unfamiliar with the notion of a source code block in Org-mode,
226 please have a look at the [[http://orgmode.org/manual/Literal-examples.html][Org-mode manual]] before proceeding.
228 Source code blocks in [[#reference-and-documentation][supported languages]] can occur anywhere in an
229 Org-mode file. Source code blocks can be entered directly into
230 the Org-mode file, but it is often easier to enter code with the
231 function =org-edit-src-code=, which is called with the keyboard
232 shortcut, C-c '. This places the source code block in a new
233 buffer with the appropriate mode activated.
237 For example, a source code block of [[http://www.ruby-lang.org/][ruby]] code looks like this in
242 : "This file was last evaluated on #{Date.today}"
246 We had to take [[http://orgmode.org/manual/Literal-examples.html#Literal-examples][special steps]] to make it look that way in the HTML
247 output. Normally, when exported to HTML, source blocks are
248 fontified according to their language, and the =begin_src=
249 ... =end_src= mark-up is omitted, like this:
253 "This file was last evaluated on #{Date.today}"
257 : This file was last evaluated on 2009-10-03
259 In general, if you are viewing the HTML version, you will see the
260 HTML output only. However, much of this document consists of
261 interactive examples, and therefore in order to get a feeling for the
262 mechanics of Org-babel it might make most sense to grab the Org-mode
264 #+html: <a href="http://eschulte.github.com/org-babel/org-babel.org">org-babel.org</a>
265 and work through it in Emacs. Alternatively the HTMLized version of
266 the plain text of this file at
267 #+html: <a href="http://eschulte.github.com/org-babel/org-babel.org.html">org-babel.org.html</a>
268 allows the plain text version to be viewed (non-interactively) in a
271 If you don't have ruby installed on your system, then you can run this
272 shell script alternative from the Org-mode version of the file:
275 echo "This file was last evaluated on `date`"
278 *** Source Code Execution
280 :CUSTOM_ID: source-code-execution
283 Org-babel executes source code blocks for *interpreted* languages such
284 as shell, python, R, etc. by passing code to the interpreter, which
285 must be installed on your system. You control what is done with the
286 results of execution.
288 Here are examples of code blocks in three different languages,
289 followed by their output. If you are viewing the Org-mode version of
290 this document in Emacs, place point anywhere inside a block and press
291 C-c C-c to run the code[fn:1] (and feel free to alter it!).
294 In the Org-mode file:
296 : "This file was last evaluated on #{Date.today}"
301 "This file was last evaluated on #{Date.today}"
304 HTML export of the resulting string:
306 : This file was last evaluated on 2009-08-09
309 In the Org-mode file:
311 : echo "This file takes up `du -h org-babel.org |sed 's/\([0-9k]*\)[ ]*org-babel.org/\1/'`"
316 echo "This file takes up `du -h org-babel.org |sed 's/\([0-9k]*\)[ ]*org-babel.org/\1/'`"
319 HTML export of the resulting string:
321 : This file takes up 36K
323 **** [[http://www.r-project.org/][R]]
325 In the Org-mode file:
326 : #+begin_src R :colnames t
327 : t(sort(table(tolower(scan("org-babel.org", what="", na.strings="|"))), decreasing=TRUE)[1:10])
331 #+begin_src R :colnames t
332 t(sort(table(tolower(scan("org-babel.org", what="", na.strings="|"))), decreasing=TRUE)[1:10])
335 HTML export of the resulting table:
337 | "the" | "of" | "to" | "in" | "a" | "is" | "and" | "code" | ":" | "be" |
338 |-------+------+------+------+-----+------+-------+--------+-----+------|
339 | 303 | 130 | 100 | 94 | 90 | 84 | 75 | 69 | 60 | 51 |
341 **** [[http://ditaa.sourceforge.net/][ditaa]]
343 In the Org-mode file:
344 : #+begin_src ditaa :file blue.png :cmdline -r
355 #+begin_src ditaa :file blue.png :cmdline -r
365 HTML export of the resulting image:
367 [[file:../../images/babel/blue.png]]
369 *** Source Code Block Syntax
371 The basic syntax of source code blocks in Org-babel is as follows:
373 : #+begin_src language header-arguments
377 - language :: The language of the code in the source-code block. Valid
378 values must be members of =org-babel-interpreters=.
379 - header-arguments :: Header arguments control many facets of the
380 evaluation and output of source-code blocks. See the [[file:reference.org::#header-arguments][Header
381 Arguments]] section for a complete review of available header
383 - body :: The source code to be evaluated. An important key-binding
384 is C-c '. This calls =org-edit-src-code=, a function that brings
385 up an edit buffer containing the code using the Emacs major mode
386 appropriate to the language. You can edit your source code block
387 as you regularly would in Emacs.
389 *** Capturing the Results of Code Evaluation
393 Org-babel provides two fundamentally different modes for capturing
394 the results of code evaluation: functional mode and scripting
395 mode. The choice of mode is specified by the =:results= header
397 **** =:results value= (functional mode)
398 The 'result' of code evaluation is the *value* of the last
399 statement in the source code block. In functional mode, the
400 source code block is a function with a return value. The return
401 value of one source code block can be used as input for another
402 source code block, even one in a different language. In this
403 way, Org-babel becomes a [[meta-programming-language]]. This setting
406 For example, consider the following block of python code and its
409 #+begin_src python :results value
411 print("Hello, today's date is %s" % time.ctime())
412 print('Two plus two is')
419 Notice that, in functional mode, the output consists of the value of
420 the last statement and nothing else.
422 **** =:results output= (scripting mode)
423 In scripting mode, Org-babel captures the text output of the
424 source code block and places it in the Org-mode buffer. It is
425 called scripting mode because the code block contains a series of
426 commands, and the output of each command is returned. Unlike
427 functional mode, the source code block itself has no return value
428 apart from the output of the commands it contains. (This mode
429 will be familiar to Sweave users).
431 Consider the result of evaluating this source code block with scripting mode.
434 #+begin_src python :results output
436 print("Hello, today's date is %s" % time.ctime())
437 print('Two plus two is')
442 : Hello, today's date is Wed Nov 11 18:50:36 2009
445 Here, scripting mode returned the text that python sent to stdout. Because
446 the source code block doesn't include a =print()= statement for the last
447 value (2 + 2), 4 does not appear in the results.
449 *** Session-based Evaluation
450 For some languages, such as python, R, ruby and shell, it is
451 possible to run an interactive session as an "inferior process"
452 within Emacs. This means that an environment is created containing
453 data objects that persist between different source code
454 blocks. Org-babel supports evaluation of code within such sessions
455 with the =:session= header argument. If the header argument is
456 given a value then that will be used as the name of the session.
457 Thus, it is possible to run separate simultaneous sessions in the
460 With R, the session will be under the control of [[http://ess.r-project.org/][Emacs Speaks
461 Statistics]] as usual, and the full power of ESS is thus still
462 available, both in the R session, and when switching to the R code
463 edit buffer with C-c '.
465 *** Arguments to Source Code Blocks
467 :CUSTOM_ID: arguments-to-source-code-blocks
469 Org-babel supports parameterisation of source code blocks, i.e.,
470 arguments can be passed to source code blocks, which gives them
471 the status of *functions*. Arguments can be passed to source code blocks in
472 both functional and scripting modes.
474 **** Simple example of using a source block as a function
476 First let's look at a very simple example. The following source
477 code block defines a function, using python, that squares its argument.
484 In the Org-mode file, the function looks like this:
485 : #+srcname: square(x)
491 Now we use the source block:
494 (/for information on the/ =lob= /syntax see/ [[library-of-babel]])
498 #+resname: square(x=6)
501 **** A more complex example using an Org-mode table as input
503 In this example we define a function called =fibonacci-seq=, using
504 Emacs Lisp. The function =fibonacci-seq= computes a Fibonacci
505 sequence. The function takes a single argument, in this case, a
506 reference to an Org-mode table.
508 Here is the Org-mode table that is passed to =fibonacci-seq=:
510 #+tblname: fibonacci-inputs
511 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
512 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
514 The table looks like this in the Org-mode buffer:
515 : #+tblname: fibonacci-inputs
516 : | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
517 : | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
519 The [[http://www.gnu.org/software/emacs/manual/elisp.html][Emacs Lisp]] source code:
520 #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
521 #+begin_src emacs-lisp
523 (if (or (= n 0) (= n 1))
525 (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
527 (mapcar (lambda (row)
528 (mapcar #'fibonacci row)) fib-inputs)
531 In the Org-mode buffer the function looks like this:
532 : #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
533 : #+begin_src emacs-lisp
534 : (defun fibonacci (n)
535 : (if (or (= n 0) (= n 1))
537 : (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
539 : (mapcar (lambda (row)
540 : (mapcar #'fibonacci row)) fib-inputs)
543 The return value of =fibonacci-seq= is a table:
545 | 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 | 34 | 55 |
546 | 1 | 3 | 8 | 21 | 55 | 144 | 377 | 987 | 2584 | 6765 |
548 *** In-line Source Blocks
549 Code can be evaluated in-line using the following syntax:
551 : Without header args: src_lang{code} or with header args: src_lang[args]{code},
552 : for example src_python[:session]{10*x}, where x is a variable existing in the
555 * A Meta-programming Language for Org-mode
557 :CUSTOM_ID: meta-programming-language
560 Because the return value of a function written in one language can be
561 passed to a function written in another language, or to an Org-mode
562 table, which is itself programmable, Org-babel can be used as a
563 meta-functional programming language. With Org-babel, functions from
564 many languages can work together. You can mix and match languages,
565 using each language for the tasks to which it is best suited.
567 For example, let's take some system diagnostics in the shell and graph them with R.
569 1. Create a source code block, using shell code, to list
570 directories in our home directory, together with their
571 sizes. Org-babel automatically converts the output into an Org-mode
574 #+srcname: directories
575 #+begin_src sh :results replace
576 cd ~ && du -sc * |grep -v total
579 #+resname: directories
581 | 12156104 | "Documents" |
582 | 3482440 | "Downloads" |
583 | 2901720 | "Library" |
585 | 16548024 | "Music" |
587 | 7649472 | "Pictures" |
596 2. A function, written with a single line of R code, plots the data
597 in the Org-mode table as a
598 pie-chart. Note how this source code block uses the =srcname=
599 of the previous source code block to obtain the data.
600 #+srcname: directory-pie-chart(dirs = directories)
601 #+begin_src R :session R-pie-example :file ../../images/babel/dirs.png
602 pie(dirs[,1], labels = dirs[,2])
604 [[file:../../images/babel/dirs.png]]
606 * Multilingual Spreadsheet Plugins for Org-mode
608 :CUSTOM_ID: spreadsheet
611 Not only can Org-babel pass entire tables of data as [[arguments-to-source-code-blocks][arguments to
612 source code blocks]], Org-babel can also be used to call source code
613 blocks from *within* Org-mode tables using Org-mode's [[http://orgmode.org/manual/The-spreadsheet.html#The-spreadsheet][existing spreadsheet
616 *** Example 1: Data Summaries Using R
617 As a simple example, we'll fill in a cell in an Org-mode table with the
618 average value of a few numbers. First, let's make some data. The
619 following source block creates an Org-mode table filled with five random
620 numbers between 0 and 1.
622 #+srcname: tbl-example-data()
624 runif(n=5, min=0, max=1)
627 #+resname: tbl-example-data
628 | 0.836685163900256 |
629 | 0.696652316721156 |
630 | 0.382423302158713 |
631 | 0.987541858805344 |
632 | 0.994794291909784 |
634 Now we define a source block to calculate the mean.
640 Finally, we create the table which is going to make use of the R
641 code. This is done using the =sbe= ('source block evaluate') macro in
642 the table formula line.
645 |-------------------|
646 | 0.779619386699051 |
647 #+TBLFM: @2$1='(sbe "R-mean" (x "tbl-example-data()"))
649 To recalculate the table formula, use C-u C-c C-c in the
650 table. Notice that as things stand the calculated value doesn't
651 change, because the data (held in the table above named
652 =tbl-example-data=) are static. However, if you delete that data table,
653 then the reference will be interpreted as a reference to the source
654 block responsible for generating the data; each time the table formula
655 is recalculated the source block will be evaluated again, and
656 therefore the calculated average value will change.
658 *** Example 2: Org-babel Test Suite
659 While developing Org-babel, we used a suite of tests implemented
660 as a large Org-mode table. To run the entire test suite we simply
661 evaluate the table with C-u C-c C-c: all of the tests are run,
662 the results are compared with expectations, and the table is updated
663 with results and pass/fail statistics.
665 Here's a sample of our test suite.
667 #+TBLNAME: org-babel-tests
668 | functionality | block | arg | expected | results | pass |
669 |------------------+--------------+-----+-------------+-------------+------|
670 | basic evaluation | | | | | pass |
671 |------------------+--------------+-----+-------------+-------------+------|
672 | emacs lisp | basic-elisp | 2 | 4 | 4 | pass |
673 | shell | basic-shell | | 6 | 6 | pass |
674 | ruby | basic-ruby | | org-babel | org-babel | pass |
675 | python | basic-python | | hello world | hello world | pass |
676 | R | basic-R | | 13 | 13 | pass |
677 #+TBLFM: $5='(if (= (length $3) 1) (sbe $2 (n $3)) (sbe $2)) :: $6='(if (string= $4 $5) "pass" (format "expected %S but was %S" $4 $5))
679 **** code blocks for tests
681 #+srcname: basic-elisp(n)
682 #+begin_src emacs-lisp
686 #+srcname: basic-shell
687 #+begin_src sh :results silent
691 #+srcname: date-simple
692 #+begin_src sh :results silent
696 #+srcname: basic-ruby
697 #+begin_src ruby :results silent
701 #+srcname: basic-python
702 #+begin_src python :results silent
707 #+begin_src R :results silent
712 * The Library of Babel
714 :CUSTOM_ID: library-of-babel
717 As we saw above with the [[*Simple%20example%20of%20using%20a%20source%20block%20as%20a%20function][=square=]] example, once a source block
718 function has been defined it can be called using the =lob= notation:
722 But what about source code blocks that you want to make available to
723 every Org-mode buffer?
725 In addition to the current buffer, Org-babel searches for
726 pre-defined source code block functions in the Library of
727 Babel. This is a user-extensible collection of ready-made source
728 code blocks for handling common tasks. One use for the Library of
729 Babel (not yet done!) will be to provide a choice of data graphing
730 procedures for data held in Org-mode tables, using languages such as
731 R, gnuplot, asymptote, etc. If you implement something that might be
732 of use to other Org-mode users, please consider adding it to the
733 Library of Babel; similarly, feel free to request help solving a
734 problem using external code via Org-babel -- there's always a chance
735 that other Org-bable users will be able to contribute some helpful
738 Org-babel comes pre-populated with the source code blocks located in
739 the [[file:library-of-babel.org][Library of Babel]] file -- raw file at
740 #+html: <a href="http://eschulte.github.com/org-babel/library-of-babel.org">library-of-babel.org</a>
741 --. It is possible to add a source code block to the library
742 from any Org-mode file by naming it =add-file-to-lob=:
744 #+srcname: add-file-to-lob
745 #+begin_src emacs-lisp
746 (org-babel-lob-ingest "path/to/file.org")
749 Note that it is possible to pass table values or the output of
750 a source-code block to Library of Babel functions. It is also possible to
751 reference Library of Babel functions in arguments to source code blocks.
753 * Reproducible Research
755 :CUSTOM_ID: reproducable-research
758 An article about computational science in a scientific publication is
759 not the scholarship itself, it is merely advertising of the
760 scholarship. The actual scholarship is the complete software
761 development environment and the complete set of instructions which
762 generated the figures.
767 [[http://reproducibleresearch.net/index.php/Main_Page][Reproducible Research]] (RR) is the practice of distributing, along with
768 a research publication, all data, software source code, and tools
769 required to reproduce the results discussed in the publication. As
770 such the RR package not only describes the research and its results,
771 but becomes a complete laboratory in which the research can be
772 reproduced and extended.
774 Org-mode already has exceptional support for [[http://orgmode.org/manual/Exporting.html#Exporting][exporting to HTML and
775 LaTeX]]. Org-babel makes Org-mode a tool for RR by *activating* the
776 data and source code embedded in Org-mode documents; the
777 entire document becomes executable. This makes it possible, and natural, to
778 distribute research in a format that encourages readers to recreate
779 results and perform their own analyses.
781 One notable existing RR tool is [[http://en.wikipedia.org/wiki/Sweave][Sweave]], which provides a mechanism for
782 embedding [[http://www.r-project.org/][R]] code into LaTeX documents. Sweave is a mature
783 and very useful tool, but we believe that Org-babel has several
785 - it supports multiple languages (we're not aware of other RR tools that do this);
786 - the [[http://orgmode.org/manual/Exporting.html#Exporting][export process]] is flexible and powerful, including HTML as a
787 target in addition to LaTeX; and
788 - the document can make use of Org-mode features that support [[http://orgmode.org/manual/Agenda-Views.html#Agenda-Views][project
789 planning]] and [[http://orgmode.org/manual/TODO-Items.html#TODO-Items][task management]].
791 * Literate Programming
793 :CUSTOM_ID: literate-programming
797 Let us change our traditional attitude to the construction of
798 programs: Instead of imagining that our main task is to instruct a
799 /computer/ what to do, let us concentrate rather on explaining to
800 /human beings/ what we want a computer to do.
802 The practitioner of literate programming can be regarded as an
803 essayist, whose main concern is with exposition and excellence of
804 style. Such an author, with thesaurus in hand, chooses the names of
805 variables carefully and explains what each variable means. He or she
806 strives for a program that is comprehensible because its concepts have
807 been introduced in an order that is best for human understanding,
808 using a mixture of formal and informal methods that reinforce each
814 Org-babel supports [[http://en.wikipedia.org/wiki/Literate_programming][Literate Programming]] (LP) by allowing the act of
815 programming to take place inside of Org-mode documents. The Org-mode
816 file can then be exported (*woven* in LP speak) to HTML or LaTeX for
817 consumption by a human, and the embedded source code can be extracted
818 (*tangled* in LP speak) into structured source code files for
819 consumption by a computer.
821 To support these operations Org-babel relies on Org-mode's [[http://orgmode.org/manual/Exporting.html#Exporting][existing
822 exporting functionality]] for *weaving* of documentation, and on the
823 =org-babel-tangle= function which makes use of [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] [[noweb-reference-syntax][reference syntax]]
824 for *tangling* of code files.
826 The [[literate-programming-example][following example]] demonstrates the process of *tangling* in
829 *** Simple Literate Programming Example (Noweb syntax)
831 :CUSTOM_ID: literate-programming-example
834 Tangling functionality is controlled by the =tangle= family of [[tangle-header-arguments][Tangle
835 header arguments]]. These arguments can be used to turn tangling on or
836 off (the default), either for the source code block or the Org-mode
839 The following source code blocks demonstrate how to tangle them into a
840 single source code file using =org-babel-tangle=.
842 The following two source code blocks have no =tangle= header arguments
843 and so will not, by themselves, create source code files. They are
844 included in the source code file by the third source code block, which
845 does have a =tangle= header argument.
847 #+srcname: hello-world-prefix
848 #+begin_src sh :exports none
849 echo "/-----------------------------------------------------------\\"
852 : #+srcname: hello-world-prefix
853 : #+begin_src sh :exports none
854 : echo "/-----------------------------------------------------------\\"
857 #+srcname: hello-world-postfix
858 #+begin_src sh :exports none
859 echo "\-----------------------------------------------------------/"
862 : #+srcname: hello-world-postfix
863 : #+begin_src sh :exports none
864 : echo "\-----------------------------------------------------------/"
868 The third source code block does have a =tangle= header argument
869 indicating the name of the file to which the tangled source code will
870 be written. It also has [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] style references to the two previous
871 source code blocks. These references will be expanded during tangling
872 to include them in the output file as well.
874 #+srcname: hello-world
875 #+begin_src sh :tangle hello :exports none
876 # <<hello-world-prefix>>
877 echo "| hello world |"
878 # <<hello-world-postfix>>
881 : #+srcname: hello-world
882 : #+begin_src sh :tangle hello :exports none
883 : # <<hello-world-prefix>>
884 : echo "| hello world |"
885 : # <<hello-world-postfix>>
888 Calling =org-babel-tangle= will result in the following shell source
889 code being written to the hello.sh file:
891 #+srcname: hello-world-output
894 # generated by org-babel-tangle
896 # [[file:~/src/org-babel/org-babel-worg.org::#literate-programming-example][block-16]]
897 # <<hello-world-prefix>>
898 echo "/-----------------------------------------------------------\\"
900 echo "| hello world |"
901 # <<hello-world-postfix>>
902 echo "\-----------------------------------------------------------/"
906 In addition, the following syntax can be used to insert the *results*
907 of evaluating a source code block, in this case one named =example-block=.
909 : # <<example-block()>>
911 Any optional arguments can be passed to =example-block()= by placing the
912 arguments inside the parentheses following the convention defined when
913 calling source block functions (see the [[library-of-babel][Library of babel]]). For example,
915 : # <<example-block(a=9)>>
917 sets the value of argument \"a\" equal to \"9\". Note that
918 these arguments are not evaluated in the current source-code
919 block but are passed literally to =example-block()=.
922 *** Emacs Initialization with Org-babel
924 :CUSTOM_ID: emacs-initialization
927 #+attr_html: style="float:left;"
928 [[file:../../images/babel/dot-emacs.png]]
930 Org-babel has special support for embedding your Emacs initialization
931 into Org-mode files. The =org-babel-load-file= function can be used
932 to load the Emacs Lisp source code blocks embedded in a literate
933 Org-mode file in the same way that you might load a regular Emacs Lisp
934 file, such as .emacs.
936 This allows you to make use of the nice features of Org-mode, such as folding, tags,
937 notes, HTML export, etc., to organize and maintain your Emacs initialization.
939 To try this out, either see the simple [[literate-emacs-init][Literate Emacs Initialization]]
940 example, or check out the Org-babel Literate Programming version of
941 Phil Hagelberg's excellent [[http://github.com/technomancy/emacs-starter-kit/tree/master][emacs-starter-kit]] available at
942 [[http://github.com/eschulte/emacs-starter-kit/tree/master][Org-babel-emacs-starter-kit]].
944 ***** Literate Emacs Initialization
946 :CUSTOM_ID: literate-emacs-init
949 For a simple example of usage, follow these 5 steps:
951 1) create a directory named =.emacs.d= in the base of your home
956 2) checkout the latest version of Org-mode into the src subdirectory
957 of this new directory;
962 git clone git://repo.or.cz/org-mode.git
964 3) place the following source code block in a file called =init.el= in your Emacs
965 initialization directory (=~/.emacs.d=).
966 #+srcname: emacs-init
967 #+begin_src emacs-lisp
968 ;;; init.el --- Where all the magic begins
970 ;; This file loads both
971 ;; - Org-mode : http://orgmode.org/ and
972 ;; - Org-babel: http://orgmode.org/worg/org-contrib/babel/org-babel.php#library-of-babel
974 ;; It then loads the rest of our Emacs initialization from Emacs lisp
975 ;; embedded in literate Org-mode files.
977 ;; Load up Org Mode and Org Babel for elisp embedded in Org Mode files
978 (setq dotfiles-dir (file-name-directory (or (buffer-file-name) load-file-name)))
980 (let* ((org-dir (expand-file-name
981 "lisp" (expand-file-name
982 "org" (expand-file-name
983 "src" dotfiles-dir))))
984 (org-contrib-dir (expand-file-name
985 "lisp" (expand-file-name
986 "contrib" (expand-file-name
988 (load-path (append (list org-dir org-contrib-dir)
989 (or load-path nil))))
990 ;; load up Org-mode and Org-babel
991 (require 'org-install)
992 (require 'org-babel-init))
994 ;; load up all literate org-mode files in this directory
995 (mapc #'org-babel-load-file (directory-files dotfiles-dir t "\\.org$"))
997 ;;; init.el ends here
999 4) implement all of your Emacs customizations inside of Emacs Lisp
1000 source code blocks embedded in Org-mode files in this directory;
1002 5) re-start Emacs to load the customizations.
1005 [fn:1] Calling =C-c C-o= on a source code block will open the
1006 block's results in a separate buffer.