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
   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 #+begin_html
  12   <div id="subtitle">
  13     <p>executable source code blocks in org-mode</p>
  14   </div>
  15   <div id="logo">
  16     <p>
  17       <img src="images/tower-of-babel.png"  alt="images/tower-of-babel.png" />
  18       <div id="attr">
  19         from
  20         <a href="http://www.flickr.com/photos/23379658@N05/" title=""><b>Martijn Streefkerk</b></a>
  21       </div>
  22     </p>
  23   </div>
  24 #+end_html
  25
  26 * Introduction
  27   Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
  28   support]] for blocks of source code examples in the org-mode core.
  29   1. source code execution
  30   2. arguments to source code blocks
  31   3. exportation of source code blocks to files (literate programming)
  32
  33 * Getting started
  34   Grab the latest code from the git repo at [[http://github.com/eschulte/org-babel/tree/master][github/org-babel]]
  35 #+begin_src sh
  36 git clone git://github.com/eschulte/org-babel.git
  37 #+end_src
  38
  39   And add the following lines to your .emacs, replacing the path as
  40   appropriate. A good place to check that things are up and running
  41   would the examples in [[* Basic org-babel functionality][Basic org-babel functionality]].
  42 #+begin_src emacs-lisp
  43   (add-to-list 'load-path "/path/to/org-babel/lisp")
  44   (require 'org-babel-init)
  45 #+end_src
  46
  47 * Basic org-babel functionality
  48 *** Source code execution
  49     For interpreted languages such as shell, python, R, etc, org-babel
  50     allows source blocks to be executed: the code is passed to the
  51     interpreter and you have control over what is done with the
  52     results of excecution. E.g. place point anywhere in the following
  53     block and use C-c C-c to run the code:
  54
  55 #+begin_src ruby
  56 "This file was last evaluated on #{Date.today}"
  57 #+end_src
  58
  59 #+resname:
  60 : This file was last evaluated on 2009-08-09
  61
  62 #+begin_src R :results value
  63 x = 4
  64 date()
  65 c(5, 10)
  66 #+end_src
  67
  68 #+resname:
  69 |  5 |
  70 | 10 |
  71
  72 *** What happens to the results?
  73     Org-babel provides two fundamentally different modes for capturing
  74     the results of code evaluation, specified by the :results header
  75     argument:
  76 **** :results value
  77      This means that the 'result' of code evaluation is defined to be
  78      the *value* of the last statement in the block. Thus with this
  79      setting, one can view the code block as a function with a return
  80      value. And not only can one view it that way, but you can
  81      actually use the return value of one source block as input for
  82      another (see later). This setting is the default.
  83 **** :results output
  84      With this setting, org-babel captures all the text output of the
  85      code block and places it in the org buffer. One can think of this
  86      as a 'scripting' mode: the code block contains a series of
  87      commands, and you get the output of all the commands. Unlike in
  88      the 'functional' mode specified by =:results value=, the code
  89      block has no return value. (This mode will be familiar to Sweave
  90      users).
  91 **** Additional :results settings
  92
  93 *** QUOTE Arguments to source code blocks
  94     In addition to evaluation of code blocks, org-babel allows them to
  95     be parameterised (i.e. have arguments). Thus source code blocks
  96     now have the status of *functions*.
  97
  98 Inputs for fibonacci-seq
  99
 100 #+tblname: fibonacci-inputs
 101 | 1 | 2 | 3 | 4 |  5 |  6 |  7 |  8 |  9 | 10 |
 102 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
 103
 104 #+srcname: fibonacci-seq
 105 #+begin_src emacs-lisp :var fib-inputs=fibonacci-inputs
 106   (defun fibonacci (n)
 107     (if (or (= n 0) (= n 1))
 108         n
 109       (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
 110
 111   (mapcar (lambda (row)
 112             (mapcar #'fibonacci row)) fib-inputs)
 113 #+end_src
 114
 115 #+resname:
 116 | 1 | 1 | 2 |  3 |  5 |   8 |  13 |  21 |   34 |   55 |
 117 | 1 | 3 | 8 | 21 | 55 | 144 | 377 | 987 | 2584 | 6765 |
 118
 119 * A meta-programming language for org-mode
 120 * Spreadsheet plugins for org-mode in any language
 121 * Library of Babel
 122   What about those source code blocks which are so useful you want to
 123   have them available in every org-mode buffer?
 124
 125   The [[file:library-of-babel.org][Library of Babel]] is an extensible collection of ready-made and
 126   easily-shortcut-callable source-code blocks for handling common
 127   tasks.  Org-babel comes pre-populated with the source-code blocks
 128   located in the [[file:library-of-babel.org][library-of-babel.org]] file. It is possible to add
 129   source-code blocks from any org-mode file to the library by calling
 130
 131 #+srcname: add-file-to-lob
 132 #+begin_src emacs-lisp
 133 (org-babel-lob-ingest "path/to/file.org")
 134 #+end_src
 135
 136 * Reproducible research
 137   - output vs. value mode
 138   - file & graphical output
 139   - controlling export
 140 * Literate programming
 141   - org-babel-tangle
 142   - org-babel-load-file
 143 * Reference / Documentation
 144
 145 *** Source Code block syntax
 146
 147 The basic syntax of source-code blocks is as follows:
 148
 149 : #+srcname: name
 150 : #+begin_src language header-arguments
 151 : body
 152 : #+end_src
 153
 154 - name :: This name is associated with the source-code block.  This is
 155      similar to the =#+TBLNAME= lines which can be used to name tables
 156      in org-mode files.  By referencing the srcname of a source-code
 157      block it is possible to evaluate the block for other places,
 158      files, or from inside tables.
 159 - language :: The language of the code in the source-code block, valid
 160      values must be members of `org-babel-interpreters'.
 161 - header-arguments :: Header arguments control many facets of the
 162      input to, evaluation of, and output of source-code blocks.  See
 163      the [[* Header Arguments][Header Arguments]] section for a complete review of available
 164      header arguments.
 165 - body :: The actual source code which will be evaluated.  This can be
 166           edited with `org-edit-special'.
 167
 168 **** Header Arguments
 169
 170 - results :: results arguments specify what should be done with the
 171              output of source-code blocks
 172   - The following options are mutually exclusive, and specify how the
 173     results should be collected from the source-code block
 174     - value ::
 175     - output ::
 176   - The following options are mutually exclusive and specify what type
 177     of results the code block will return
 178     - vector :: specifies that the results should be interpreted as a
 179                 multidimensional vector (even if the vector is
 180                 trivial), and will be inserted into the org-mode file
 181                 as a table
 182     - scalar :: specifies that the results should be interpreted as a
 183                 scalar value, and will be inserted into the org-mode
 184                 file as quoted text
 185     - file :: specifies that the results should be interpreted as the
 186               path to a file, and will be inserted into the org-mode
 187               file as a link
 188   - The following options specify how the results should be inserted
 189     into the org-mode file
 190     - replace :: the current results replace any previously inserted
 191                  results from the code block
 192     - silent :: rather than being inserted into the org-mode file the
 193                 results are echoed into the message bar
 194 - exports :: exports arguments specify what should be included in html
 195              or latex exports of the org-mode file
 196   - code :: the body of code is included into the exported file
 197   - results :: the results of evaluating the code is included in the
 198                exported file
 199   - both :: both the code and results are included in the exported
 200             file
 201   - none :: nothing is included in the exported file
 202 - tangle :: tangle arguments specify whether or not the source-code
 203             block should be included in tangled extraction of
 204             source-code files
 205   - yes :: the source-code block is exported to a source-code file
 206            named after the basename (name w/o extension) of the
 207            org-mode file
 208   - no :: (default) the source-code block is not exported to a
 209           source-code file
 210   - other :: any other string passed to the =tangle= header argument
 211              is interpreted as a file basename to which the block will
 212              be exported
 213