org-babel-worg.org

   1 #+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
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   5 #+TITLE:      org-babel: executable source code blocks in org-mode
   6 #+AUTHOR:     Dan Davison, Eric Schulte
   7 #+EMAIL:      davison at stats dot ox dot ac dot uk
   8 #+LANGUAGE:   en
   9 #+CATEGORY:   worg
  10
  11 * Introduction
  12   Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
  13   support]] for blocks of source code examples in the org-mode core.
  14   1. source code execution
  15   2. arguments to source code blocks
  16
  17 * Basic org-babel functionality
  18 *** Source code execution
  19     For interpreted languages such as shell, python, R, etc, org-babel
  20     allows source blocks to be executed: the code is passed to the
  21     interpreter and you have control over what is done with the
  22     results of excecution. E.g. place point anywhere in the following
  23     block and use C-c C-c to run the code:
  24
  25 #+begin_src python :results output
  26 import time
  27 x = 4
  28 print("hello\n")
  29 #print time.ctime()
  30 print [5, 10]
  31 #+end_src
  32
  33 #+resname:
  34 : hello
  35 : 510
  36
  37 #+begin_src R :results value
  38 x = 4
  39 date()
  40 c(5, 10)
  41 #+end_src
  42
  43 #+resname:
  44 |  5 |
  45 | 10 |
  46
  47 *** What happens to the results?
  48     Org-babel provides two fundamentally different modes for capturing
  49     the results of code evaluation, specified by the :results header
  50     argument:
  51 **** :results value
  52      This means that the 'result' of code evaluation is defined to be
  53      the *value* of the last statement in the block. Thus with this
  54      setting, one can view the code block as a function with a return
  55      value. And not only can one view it that way, but you can
  56      actually use the return value of one source block as input for
  57      another (see later). This setting is the default.
  58 **** :results output
  59      With this setting, org-babel captures all the text output of the
  60      code block and places it in the org buffer. One can think of this
  61      as a 'scripting' mode: the code block contains a series of
  62      commands, and you get the output of all the commands. Unlike in
  63      the 'functional' mode specified by =:results value=, the code
  64      block has no return value. (This mode will be familiar to Sweave
  65      users).
  66 **** Additional :results settings
  67
  68 *** Arguments to source code blocks
  69     In addition to evaluation of code blocks, org-babel allows them to
  70     be parameterised (i.e. have arguments). Thus source code blocks
  71     now have the status of *functions*.
  72
  73 * A meta-programming language for org-mode
  74 * Spreadsheet plugins for org-mode in any language
  75 * Reproducible research
  76   - output vs. value mode
  77   - file & graphical output
  78   - controlling export
  79 * Literate programming
  80   - org-babel-tangle
  81   - org-babel-load-file
  82 * Reference / Documentation
  83
  84 *** Source Code block syntax
  85
  86 The basic syntax of source-code blocks is as follows:
  87
  88 : #+srcname: name
  89 : #+begin_src language header-arguments
  90 : body
  91 : #+end_src
  92
  93 - name :: This name is associated with the source-code block.  This is
  94      similar to the =#+TBLNAME= lines which can be used to name tables
  95      in org-mode files.  By referencing the srcname of a source-code
  96      block it is possible to evaluate the block for other places,
  97      files, or from inside tables.
  98 - language :: The language of the code in the source-code block, valid
  99      values must be members of `org-babel-interpreters'.
 100 - header-arguments :: Header arguments control many facets of the
 101      input to, evaluation of, and output of source-code blocks.  See
 102      the [[* Header Arguments][Header Arguments]] section for a complete review of available
 103      header arguments.
 104 - body :: The actual source code which will be evaluated.  This can be
 105           edited with `org-edit-special'.
 106
 107 **** Header Arguments
 108
 109 - results :: results arguments specify what should be done with the
 110              output of source-code blocks
 111   - The following options are mutually exclusive, and specify how the
 112     results should be collected from the source-code block
 113     - value ::
 114     - output ::
 115   - The following options are mutually exclusive and specify what type
 116     of results the code block will return
 117     - vector :: specifies that the results should be interpreted as a
 118                 multidimensional vector (even if the vector is
 119                 trivial), and will be inserted into the org-mode file
 120                 as a table
 121     - scalar :: specifies that the results should be interpreted as a
 122                 scalar value, and will be inserted into the org-mode
 123                 file as quoted text
 124     - file :: specifies that the results should be interpreted as the
 125               path to a file, and will be inserted into the org-mode
 126               file as a link
 127   - The following options specify how the results should be inserted
 128     into the org-mode file
 129     - replace :: the current results replace any previously inserted
 130                  results from the code block
 131     - silent :: rather than being inserted into the org-mode file the
 132                 results are echoed into the message bar
 133 - exports :: exports arguments specify what should be included in html
 134              or latex exports of the org-mode file
 135   - code :: the body of code is included into the exported file
 136   - results :: the results of evaluating the code is included in the
 137                exported file
 138   - both :: both the code and results are included in the exported
 139             file
 140   - none :: nothing is included in the exported file
 141 - tangle :: tangle arguments specify whether or not the source-code
 142             block should be included in tangled extraction of
 143             source-code files
 144   - on :: the source-code block is included in tangled files
 145   - off :: the source-code block is ignored when tangling
 146