tec/org-mode

Fork 0

forked from mirrors/org-mode

Dan Davison b10b07c475 Changes to source code (execution) section of o-b-worg.org

2009-09-04 18:16:27 -04:00

26 KiB

Raw Blame History

Org-babel

Introduction
Getting started
Basic org-babel functionality
A meta-programming language for org-mode
Spreadsheet plugins for org-mode in any language
Library of Babel
Reproducible Research
Literate programming
Reference / Documentation

<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" 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"/> <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 is an extension to the very excellent Org-mode; an Emacs major mode for doing almost anything with plain text. If you are not familiar with Org-mode please take a moment to read the Org-mode homepage before continuing.

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

Interactive 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
```
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)
```

Then activate the subset of supported Org-babel languages which you will want to be able to execute on your system. The following can be added to your .emacs and used to activate languages. It includes a brief list of the requirements for each language. Note: this also serves as the list of languages currently supported by Org-babel.

  ;; Uncomment each of the following require lines if you want org-babel
  ;; to support that language.  Each language has a comment explaining
  ;; it's dependencies.  See the related files in lisp/langs for more
  ;; detailed explanations of requirements.
  ;; (require 'org-babel-R)         ;; R and ess-mode
  ;; (require 'org-babel-asymptote) ;; asymptote
  ;; (require 'org-babel-css)       ;; none
  ;; (require 'org-babel-ditaa)     ;; ditaa
  ;; (require 'org-babel-dot)       ;; dot
  ;; (require 'org-babel-gnuplot)   ;; gnuplot, and gnuplot-mode
  ;; (require 'org-babel-haskell)   ;; haskell, haskell-mode, inf-haskell
  ;; (require 'org-babel-ocaml)     ;; ocaml, and tuareg-mode
  ;; (require 'org-babel-python)    ;; python, and python-mode
  ;; (require 'org-babel-ruby)      ;; ruby, irb, ruby-mode, and inf-ruby
  ;; (require 'org-babel-sass)      ;; sass, sass-mode
  ;; (require 'org-babel-sql)       ;; none
  ;; 
  ;; Once you've activated languages, load the library of babel for
  ;; pre-built helpers in the languages you will be using.
  (org-babel-load-library-of-babel)

Basic org-babel functionality

Source code blocks

Org-babel is all about source blocks in org mode. These are blocks of code (in whatever language), surrounded by special starting and ending lines. For example, the following is a source block containing ruby code:

#+begin_src ruby
"This file was last evaluated on #{Date.today}"
#+end_src

If you are unfamiliar with the notion of source blocks in org-mode, please have a look at the relevant manual section before proceding.

Note that above is what the source block looks like in the org-mode file. We had to take special steps to make it look that way in the HTML output; normally, when exported to HTML, source blocks are fontified according to their language, and the begin_src…end_src mark-up is omitted, like this:

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

From now on, if you are viewing the HTML version, you will see the HTML output only. However, much of this document consists of interactive examples, and therefore in order to get a feeling for the mechanics of Org-babel it might make most sense to grab the plain text version of this file

org-babel-worg.org

and work through it in Emacs. Alternatively the htmlized version of the plain text of this file at

org-babel-worg.html

allows the plain text version to be viewed (non-interactively) in a web browser.

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:

Note: calling C-c C-o on a source-code block will open the block's results.

Ruby

Here's the result of evaluating the ruby block above

This file was last evaluated on 2009-08-09

R

Source block:

matrix(rnorm(6), nrow=2)

Results of R evaluation:

"-0.0519932008632584"	"-0.226627055077931"	0.117163647485067
0.61982500448072	"-1.47733875944235"	0.482345264970892

ditaa

Source block:

+---------+
| cBLU    |
|         |
|    +----+
|    |cPNK|
|    |    |
+----+----+

Results of ditaa evaluation:

/tec/org-mode/media/commit/b10b07c475fd3f87002d25de7746742f567a8790/images/blue.png

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

Since information can pass freely between source-code blocks and org-mode tables you can mix and match languages using each language for those tasks to which it is suited. This makes Org-mode files with Org-babel into a kind of meta-functional programming language in which functions from many languages can work together.

As an example, lets take some system diagnostics in the shell, and then graph them with R.

Shell source code

cd ~ && du -sc * |grep -v total

Results of the shell source code (on my system, grab this org-mode files and try running it on your own)

72	"Desktop"
12156104	"Documents"
3482440	"Downloads"
2901720	"Library"
57344	"Movies"
16548024	"Music"
120	"News"
7649472	"Pictures"
0	"Public"
152224	"Sites"
8	"System"
56	"bin"
3821872	"mail"
10605392	"src"
1264	"tools"

R source code (which calls the previous shell source code)

pie(dirs[,1], labels = dirs[,2])

Results of R code

Spreadsheet plugins for org-mode in any language

NOTE: Maybe in-addition-to/in-stead-of this example we should do a more traditional "spreadsheet" example with R [Eric]

Not only can Org-babel pass entire tables of data to source code blocks (see /tec/org-mode/src/commit/b10b07c475fd3f87002d25de7746742f567a8790/arguments-to-source-code-blocks), Org-babel can also be used to call source code blocks from within tables using the Org-mode's existing spreadsheet functionality.

In fact the functional test suite for Org-babel is implemented as a large Org-mode table. To run the entire test suite you simple evaluate the table C-u C-c C-c, and all of the tests are run updating the table with pass/fail statistics.

Here's a sample of our test suite.

functionality	block	arg	expected	results	pass
basic evaluation					pass
emacs lisp	basic-elisp	2	4	4	pass
shell	basic-shell		6	6	pass
ruby	basic-ruby		org-babel	org-babel	pass
python	basic-python		hello world	hello world	pass
R	basic-R		13	13	pass

code blocks for tests

(* 2 n)

expr 1 + 5

date

"org-babel"

'hello world'

b <- 9
b + 4

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

An article about computational science in a scientific publication is not the scholarship itself, it is merely advertising of the scholarship. The actual scholarship is the complete software development environment and the complete set of instructions which generated the figures.

– D. Donoho

Reproducible Research (RR) is the practice of distributing along with an article of research all data, code, and tools required to reproduce the results discussed in the paper. As such the paper becomes not only a document describing the research but a complete laboratory reproducing the research.

Org-mode already has exceptional support for exporting to html and LaTeX. Org-babel makes Org-mode a tool for RR by activating the data and source code embedded into Org-mode documents making the entire document executable. This makes it not only possible, but natural to distribute research in a format that encourages readers to recreate your results, and perform their own analysis.

Existing RR tools like Sweave provide for the embedding of R code into LaTeX documents. While this is very useful, such documents often still require a large degree of "glue code" in the form of external shell scripts, python scripts, and Makefiles. To our knowledge Org-babel is the only RR tool which allows multiple languages and data to coexist and cooperate inside of a single document.

Literate programming

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.

– Donald Knuth

Org-babel supports Literate Programming (LP) by allowing the act of programming to take place inside of Org-mode documents. The Org-mode file can then be exported (woven in LP speak) to html or LaTeX for consumption by a human, and the embedded source code can be extracted (tangled in LP speak) into structured source code files for consumption by a computer.

To support these operations Org-babel relies on Org-mode's existing exporting functionality for weaving of documentation, and on the org-babel-tangle function which makes use of Noweb reference syntax for tangling of code files.

The following example demonstrates the process of tangling in Org-babel.

Simple Literate Programming Example (Noweb syntax)

Tangling functionality is controlled by the tangle family of /tec/org-mode/src/commit/b10b07c475fd3f87002d25de7746742f567a8790/header-arguments. These arguments can be used to turn tangling on or off (the default) on the source code block, or the outline heading level.

The following demonstrates the combination of three source code blocks into a single source code file using org-babel-tangle.

The following two blocks will not be tangled by default since they have no tangle header arguments.

#+srcname: hello-world-prefix
#+begin_src sh :exports none
  echo "/-----------------------------------------------------------\\"
#+end_src

#+srcname: hello-world-postfix
#+begin_src sh :exports none
  echo "\-----------------------------------------------------------/"
#+end_src

The third block does have a tangle header argument indicating the name of the file to which it should be written. It also has Noweb style references to the two previous source code blocks which will be expanded during tangling to include them in the output file as well.

#+srcname: hello-world
#+begin_src sh :tangle hello :exports none
  # <<hello-world-prefix>>
  echo "|                       hello world                         |"
  # <<hello-world-postfix>>
#+end_src

Calling org-babel-tangle will result in the following being written to the hello.sh file.

  #!/usr/bin/env sh
  # generated by org-babel-tangle
  
  # [[file:~/src/org-babel/org-babel-worg.org::#literate-programming-example][block-16]]
  # <<hello-world-prefix>>
  echo "/-----------------------------------------------------------\\"
  
  echo "|                       hello world                         |"
  # <<hello-world-postfix>>
  echo "\-----------------------------------------------------------/"
  # block-16 ends here

Emacs Initialization with Org-babel

Org-babel has special support for embedding your emacs initialization into Org-mode files. The org-babel-load-file function can be used to load the emacs lisp embedded in a literate Org-mode file in the same way that you might load a regular elisp file.

This allows you to have all the niceness of Org-mode (folding, tags, notes, html export, etc…) available in your emacs initialization.

To try this out either see the simple Literate Emacs Initialization example directly below, or check out the Org-babel Literate Programming version of Phil Hagelberg's excellent emacs-starter-kit available at Org-babel-emacs-starter-kit.

Literate Emacs Initialization

For a simple example of usage follow these 4 steps.

create a directory named .emacs.d in the base of your home directory.
```
mkdir ~/.emacs.d
```

checkout the latest versions of Org-mode and Org-babel into the src subdirectory of this new directory

cd ~/.emacs.d
mkdir src
cd src
git clone git://repo.or.cz/org-mode.git
git clone git://github.com/eschulte/org-babel.git

place the following in a file called init.el in your emacs initialization directory (~/.emacs.d).

  ;;; init.el --- Where all the magic begins
  ;;
  ;; This file loads both
  ;; - Org-mode : http://orgmode.org/ and
  ;; - Org-babel: http://eschulte.github.com/org-babel/
  ;;
  ;; It then loads the rest of our Emacs initialization from Emacs lisp
  ;; embedded in literate Org-mode files.
  
  ;; Load up Org Mode and Org Babel for elisp embedded in Org Mode files
  (setq dotfiles-dir (file-name-directory (or (buffer-file-name) load-file-name)))
  (add-to-list 'load-path (expand-file-name
                           "lisp" (expand-file-name
                                   "org" (expand-file-name
                                          "src" dotfiles-dir))))
  (add-to-list 'load-path (expand-file-name
                           "lisp" (expand-file-name
                                   "org-babel" (expand-file-name
                                                "src" dotfiles-dir))))
  (require 'org-babel-init)
  
  ;; load up all literate org-mode files in this directory
  (mapc #'org-babel-load-file (directory-files dotfiles-dir t "\\.org$"))
  
  ;;; init.el ends here

Implement all of your emacs customizations inside of elisp source-code blocks located in Org-mode files in this directory. They will be loaded by emacs on startup.

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

Noweb reference syntax

The Noweb Literate Programming system allows named blocks of code to be referenced by using a <<code-block-name>> syntax. When a document is tangled these references are replaced with the named code. An example is provided in the /tec/org-mode/src/commit/b10b07c475fd3f87002d25de7746742f567a8790/literate-programming-example in this document.

26 KiB Raw Blame History Unescape Escape