Org-babel

<div id="subtitle"> <p>executable source code blocks in org-mode</p> </div> <div id="logo"> <p> <img src="images/tower-of-babel.png" alt="images/tower-of-babel.png" /> <div id="attr"> from <a href="http://www.flickr.com/photos/23379658@N05/" title=""><b>Martijn Streefkerk</b></a> </div> </p> </div>

Introduction

Org-babel provides the following modifications to the existing support for blocks of source code examples in the org-mode core.

source code execution
arguments to source code blocks
exportation of source code blocks to files (literate programming)

Getting started

Grab the latest code from the git repo at github/org-babel

git clone git://github.com/eschulte/org-babel.git

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.

  (add-to-list 'load-path "/path/to/org-babel/lisp")
  (require 'org-babel-init)

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:

Ruby source code

"This file was last evaluated on #{Date.today}"

Results of Ruby evaluation

This file was last evaluated on 2009-08-09

R source code

x = 4
date()
c(5, 10)

Results of R evaluation

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

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 |

Emacs Lisp source code

  (defun fibonacci (n)
    (if (or (= n 0) (= n 1))
        n
      (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
  
  (mapcar (lambda (row)
            (mapcar #'fibonacci row)) fib-inputs)

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

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 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 library-of-babel.org file. It is possible to add source-code blocks from any org-mode file to the library by calling

(org-babel-lob-ingest "path/to/file.org")

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 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

org-babel-worg.org 9.0 KB History Raw