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 python :results output
  56 import time
  57 x = 4
  58 print("hello\n")
  59 #print time.ctime()
  60 print [5, 10]
  61 #+end_src
  62
  63 #+resname:
  64 : hello
  65 : 510
  66
  67 #+begin_src R :results value
  68 x = 4
  69 date()
  70 c(5, 10)
  71 #+end_src
  72
  73 #+resname:
  74 |  5 |
  75 | 10 |
  76
  77 *** What happens to the results?
  78     Org-babel provides two fundamentally different modes for capturing
  79     the results of code evaluation, specified by the :results header
  80     argument:
  81 **** :results value
  82      This means that the 'result' of code evaluation is defined to be
  83      the *value* of the last statement in the block. Thus with this
  84      setting, one can view the code block as a function with a return
  85      value. And not only can one view it that way, but you can
  86      actually use the return value of one source block as input for
  87      another (see later). This setting is the default.
  88 **** :results output
  89      With this setting, org-babel captures all the text output of the
  90      code block and places it in the org buffer. One can think of this
  91      as a 'scripting' mode: the code block contains a series of
  92      commands, and you get the output of all the commands. Unlike in
  93      the 'functional' mode specified by =:results value=, the code
  94      block has no return value. (This mode will be familiar to Sweave
  95      users).
  96 **** Additional :results settings
  97
  98 *** Arguments to source code blocks
  99     In addition to evaluation of code blocks, org-babel allows them to
 100     be parameterised (i.e. have arguments). Thus source code blocks
 101     now have the status of *functions*.
 102
 103 * A meta-programming language for org-mode
 104 * Spreadsheet plugins for org-mode in any language
 105 * Library of Babel
 106   What about those source code blocks which are so useful you want to
 107   have them available in every org-mode buffer?
 108
 109   The [[file:library-of-babel.org][Library of Babel]] is an extensible collection of ready-made and
 110   easily-shortcut-callable source-code blocks for handling common
 111   tasks.  Org-babel comes pre-populated with the source-code blocks
 112   located in the [[file:library-of-babel.org][library-of-babel.org]] file. It is possible to add
 113   source-code blocks from any org-mode file to the library by calling
 114
 115 #+srcname: add-file-to-lob
 116 #+begin_src emacs-lisp
 117 (org-babel-lob-ingest "path/to/file.org")
 118 #+end_src
 119
 120 * Reproducible research
 121   - output vs. value mode
 122   - file & graphical output
 123   - controlling export
 124 * Literate programming
 125   - org-babel-tangle
 126   - org-babel-load-file
 127 * Reference / Documentation
 128
 129 *** Source Code block syntax
 130
 131 The basic syntax of source-code blocks is as follows:
 132
 133 : #+srcname: name
 134 : #+begin_src language header-arguments
 135 : body
 136 : #+end_src
 137
 138 - name :: This name is associated with the source-code block.  This is
 139      similar to the =#+TBLNAME= lines which can be used to name tables
 140      in org-mode files.  By referencing the srcname of a source-code
 141      block it is possible to evaluate the block for other places,
 142      files, or from inside tables.
 143 - language :: The language of the code in the source-code block, valid
 144      values must be members of `org-babel-interpreters'.
 145 - header-arguments :: Header arguments control many facets of the
 146      input to, evaluation of, and output of source-code blocks.  See
 147      the [[* Header Arguments][Header Arguments]] section for a complete review of available
 148      header arguments.
 149 - body :: The actual source code which will be evaluated.  This can be
 150           edited with `org-edit-special'.
 151
 152 **** Header Arguments
 153
 154 - results :: results arguments specify what should be done with the
 155              output of source-code blocks
 156   - The following options are mutually exclusive, and specify how the
 157     results should be collected from the source-code block
 158     - value ::
 159     - output ::
 160   - The following options are mutually exclusive and specify what type
 161     of results the code block will return
 162     - vector :: specifies that the results should be interpreted as a
 163                 multidimensional vector (even if the vector is
 164                 trivial), and will be inserted into the org-mode file
 165                 as a table
 166     - scalar :: specifies that the results should be interpreted as a
 167                 scalar value, and will be inserted into the org-mode
 168                 file as quoted text
 169     - file :: specifies that the results should be interpreted as the
 170               path to a file, and will be inserted into the org-mode
 171               file as a link
 172   - The following options specify how the results should be inserted
 173     into the org-mode file
 174     - replace :: the current results replace any previously inserted
 175                  results from the code block
 176     - silent :: rather than being inserted into the org-mode file the
 177                 results are echoed into the message bar
 178 - exports :: exports arguments specify what should be included in html
 179              or latex exports of the org-mode file
 180   - code :: the body of code is included into the exported file
 181   - results :: the results of evaluating the code is included in the
 182                exported file
 183   - both :: both the code and results are included in the exported
 184             file
 185   - none :: nothing is included in the exported file
 186 - tangle :: tangle arguments specify whether or not the source-code
 187             block should be included in tangled extraction of
 188             source-code files
 189   - yes :: the source-code block is exported to a source-code file
 190            named after the basename (name w/o extension) of the
 191            org-mode file
 192   - no :: (default) the source-code block is not exported to a
 193           source-code file
 194   - other :: any other string passed to the =tangle= header argument
 195              is interpreted as a file basename to which the block will
 196              be exported
 197