org-mode/org-babel-worg.org

#+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
#+TITLE:      org-babel: executable source code blocks in org-mode
#+AUTHOR:     Dan Davison, Eric Schulte
#+EMAIL:      davison at stats dot ox dot ac dot uk
#+LANGUAGE:   en
#+CATEGORY:   worg

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

#+begin_src python :results output
import time
x = 4
print("hello\n")
#print time.ctime()
print [5, 10]
#+end_src

#+resname:
: hello
: 510

#+begin_src R :results value
x = 4
date()
c(5, 10)
#+end_src

#+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*.

* A meta-programming language for org-mode
* Spreadsheet plugins for org-mode in any language
* 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