#+end_html
* Introduction
Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
support]] for blocks of source code examples in the org-mode core.
1. source code execution
2. arguments to source code blocks
3. exportation of source code blocks to files (literate programming)
* Getting started
Grab the latest code from the git repo at [[http://github.com/eschulte/org-babel/tree/master][github/org-babel]]
#+begin_src sh
git clone git://github.com/eschulte/org-babel.git
#+end_src
And add the following lines to your .emacs, replacing the path as
appropriate. A good place to check that things are up and running
would the examples in [[* Basic org-babel functionality][Basic org-babel functionality]].
#+begin_src emacs-lisp
(add-to-list 'load-path "/path/to/org-babel/lisp")
(require 'org-babel-init)
#+end_src
* Basic org-babel functionality
*** Source code execution
For interpreted languages such as shell, python, R, etc, org-babel
allows source blocks to be executed: the code is passed to the
interpreter and you have control over what is done with the
results of excecution. E.g. place point anywhere in the following
block and use C-c C-c to run the code:
[[http://www.ruby-lang.org/][Ruby]] source code
#+begin_src ruby
"This file was last evaluated on #{Date.today}"
#+end_src
Results of Ruby evaluation
#+resname:
: This file was last evaluated on 2009-08-09
[[http://www.r-project.org/][R]] source code
#+begin_src R :results value
x = 4
date()
c(5, 10)
#+end_src
Results of R evaluation
#+resname:
| 5 |
| 10 |
*** What happens to the results?
Org-babel provides two fundamentally different modes for capturing
the results of code evaluation, specified by the :results header
argument:
**** :results value
This means that the 'result' of code evaluation is defined to be
the *value* of the last statement in the block. Thus with this
setting, one can view the code block as a function with a return
value. And not only can one view it that way, but you can
actually use the return value of one source block as input for
another (see later). This setting is the default.
**** :results output
With this setting, org-babel captures all the text output of the
code block and places it in the org buffer. One can think of this
as a 'scripting' mode: the code block contains a series of
commands, and you get the output of all the commands. Unlike in
the 'functional' mode specified by =:results value=, the code
block has no return value. (This mode will be familiar to Sweave
users).
**** Additional :results settings
*** Arguments to source code blocks
In addition to evaluation of code blocks, org-babel allows them to
be parameterised (i.e. have arguments). Thus source code blocks
now have the status of *functions*.
Inputs for fibonacci-seq
#+tblname: fibonacci-inputs
| 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
in the Org-mode buffer this looks like
: #+tblname: fibonacci-inputs
: | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
: | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
[[http://www.gnu.org/software/emacs/manual/elisp.html][Emacs Lisp]] source code
#+srcname: fibonacci-seq
#+begin_src emacs-lisp :var fib-inputs=fibonacci-inputs
(defun fibonacci (n)
(if (or (= n 0) (= n 1))
n
(+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
(mapcar (lambda (row)
(mapcar #'fibonacci row)) fib-inputs)
#+end_src
in the Org-mode buffer this looks like
: #+srcname: fibonacci-seq
: #+begin_src emacs-lisp :var fib-inputs=fibonacci-inputs
: (defun fibonacci (n)
: (if (or (= n 0) (= n 1))
: n
: (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
:
: (mapcar (lambda (row)
: (mapcar #'fibonacci row)) fib-inputs)
: #+end_src
Results of Emacs Lisp code evaluation
#+resname:
| 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 | 34 | 55 |
| 1 | 3 | 8 | 21 | 55 | 144 | 377 | 987 | 2584 | 6765 |
* A meta-programming language for org-mode
* Spreadsheet plugins for org-mode in any language
* Library of Babel
What about those source code blocks which are so useful you want to
have them available in every org-mode buffer?
The [[file:library-of-babel.org][Library of Babel]] is an extensible collection of ready-made and
easily-shortcut-callable source-code blocks for handling common
tasks. Org-babel comes pre-populated with the source-code blocks
located in the [[file:library-of-babel.org][library-of-babel.org]] file. It is possible to add
source-code blocks from any org-mode file to the library by calling
#+srcname: add-file-to-lob
#+begin_src emacs-lisp
(org-babel-lob-ingest "path/to/file.org")
#+end_src
* Reproducible research
- output vs. value mode
- file & graphical output
- controlling export
* Literate programming
- org-babel-tangle
- org-babel-load-file
* Reference / Documentation
*** Source Code block syntax
The basic syntax of source-code blocks is as follows:
: #+srcname: name
: #+begin_src language header-arguments
: body
: #+end_src
- name :: This name is associated with the source-code block. This is
similar to the =#+TBLNAME= lines which can be used to name tables
in org-mode files. By referencing the srcname of a source-code
block it is possible to evaluate the block for other places,
files, or from inside tables.
- language :: The language of the code in the source-code block, valid
values must be members of `org-babel-interpreters'.
- header-arguments :: Header arguments control many facets of the
input to, evaluation of, and output of source-code blocks. See
the [[* Header Arguments][Header Arguments]] section for a complete review of available
header arguments.
- body :: The actual source code which will be evaluated. This can be
edited with `org-edit-special'.
**** Header Arguments
- results :: results arguments specify what should be done with the
output of source-code blocks
- The following options are mutually exclusive, and specify how the
results should be collected from the source-code block
- value ::
- output ::
- The following options are mutually exclusive and specify what type
of results the code block will return
- vector :: specifies that the results should be interpreted as a
multidimensional vector (even if the vector is
trivial), and will be inserted into the org-mode file
as a table
- scalar :: specifies that the results should be interpreted as a
scalar value, and will be inserted into the org-mode
file as quoted text
- file :: specifies that the results should be interpreted as the
path to a file, and will be inserted into the org-mode
file as a link
- The following options specify how the results should be inserted
into the org-mode file
- replace :: the current results replace any previously inserted
results from the code block
- silent :: rather than being inserted into the org-mode file the
results are echoed into the message bar
- exports :: exports arguments specify what should be included in html
or latex exports of the org-mode file
- code :: the body of code is included into the exported file
- results :: the results of evaluating the code is included in the
exported file
- both :: both the code and results are included in the exported
file
- none :: nothing is included in the exported file
- tangle :: tangle arguments specify whether or not the source-code
block should be included in tangled extraction of
source-code files
- yes :: the source-code block is exported to a source-code file
named after the basename (name w/o extension) of the
org-mode file
- no :: (default) the source-code block is not exported to a
source-code file
- other :: any other string passed to the =tangle= header argument
is interpreted as a file basename to which the block will
be exported
