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">from <a href="http://www.flickr.com/photos/23379658@N05/" title=""><b>Martijn Streefkerk</b></a></div>
  19     </p>
  20   </div>
  21 #+end_html
  22
  23 * Introduction
  24   Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
  25   support]] for blocks of source code examples in the org-mode core.
  26   1. source code execution
  27   2. arguments to source code blocks
  28
  29 * Basic org-babel functionality
  30 *** Source code execution
  31     For interpreted languages such as shell, python, R, etc, org-babel
  32     allows source blocks to be executed: the code is passed to the
  33     interpreter and you have control over what is done with the
  34     results of excecution. E.g. place point anywhere in the following
  35     block and use C-c C-c to run the code:
  36
  37 #+begin_src python :results output
  38 import time
  39 x = 4
  40 print("hello\n")
  41 #print time.ctime()
  42 print [5, 10]
  43 #+end_src
  44
  45 #+resname:
  46 : hello
  47 : 510
  48
  49 #+begin_src R :results value
  50 x = 4
  51 date()
  52 c(5, 10)
  53 #+end_src
  54
  55 #+resname:
  56 |  5 |
  57 | 10 |
  58
  59 *** What happens to the results?
  60     Org-babel provides two fundamentally different modes for capturing
  61     the results of code evaluation, specified by the :results header
  62     argument:
  63 **** :results value
  64      This means that the 'result' of code evaluation is defined to be
  65      the *value* of the last statement in the block. Thus with this
  66      setting, one can view the code block as a function with a return
  67      value. And not only can one view it that way, but you can
  68      actually use the return value of one source block as input for
  69      another (see later). This setting is the default.
  70 **** :results output
  71      With this setting, org-babel captures all the text output of the
  72      code block and places it in the org buffer. One can think of this
  73      as a 'scripting' mode: the code block contains a series of
  74      commands, and you get the output of all the commands. Unlike in
  75      the 'functional' mode specified by =:results value=, the code
  76      block has no return value. (This mode will be familiar to Sweave
  77      users).
  78 **** Additional :results settings
  79
  80 *** Arguments to source code blocks
  81     In addition to evaluation of code blocks, org-babel allows them to
  82     be parameterised (i.e. have arguments). Thus source code blocks
  83     now have the status of *functions*.
  84
  85 * A meta-programming language for org-mode
  86 * Spreadsheet plugins for org-mode in any language
  87 * Library of Babel
  88 Org-babel support saving of source-code blocks in a library from which
  89 they can be call in any org-mode file.  This library is called the
  90 [[file:library-of-babel.org][Library of Babel]].  It is possible to add source-code blocks from any
  91 org-mode file to the library by calling
  92
  93 #+srcname: add-file-to-lob
  94 #+begin_src emacs-lisp
  95 (org-babel-lob-ingest "path/to/file.org")
  96 #+end_src
  97
  98 * Reproducible research
  99   - output vs. value mode
 100   - file & graphical output
 101   - controlling export
 102 * Literate programming
 103   - org-babel-tangle
 104   - org-babel-load-file
 105 * Reference / Documentation
 106
 107 *** Source Code block syntax
 108
 109 The basic syntax of source-code blocks is as follows:
 110
 111 : #+srcname: name
 112 : #+begin_src language header-arguments
 113 : body
 114 : #+end_src
 115
 116 - name :: This name is associated with the source-code block.  This is
 117      similar to the =#+TBLNAME= lines which can be used to name tables
 118      in org-mode files.  By referencing the srcname of a source-code
 119      block it is possible to evaluate the block for other places,
 120      files, or from inside tables.
 121 - language :: The language of the code in the source-code block, valid
 122      values must be members of `org-babel-interpreters'.
 123 - header-arguments :: Header arguments control many facets of the
 124      input to, evaluation of, and output of source-code blocks.  See
 125      the [[* Header Arguments][Header Arguments]] section for a complete review of available
 126      header arguments.
 127 - body :: The actual source code which will be evaluated.  This can be
 128           edited with `org-edit-special'.
 129
 130 **** Header Arguments
 131
 132 - results :: results arguments specify what should be done with the
 133              output of source-code blocks
 134   - The following options are mutually exclusive, and specify how the
 135     results should be collected from the source-code block
 136     - value ::
 137     - output ::
 138   - The following options are mutually exclusive and specify what type
 139     of results the code block will return
 140     - vector :: specifies that the results should be interpreted as a
 141                 multidimensional vector (even if the vector is
 142                 trivial), and will be inserted into the org-mode file
 143                 as a table
 144     - scalar :: specifies that the results should be interpreted as a
 145                 scalar value, and will be inserted into the org-mode
 146                 file as quoted text
 147     - file :: specifies that the results should be interpreted as the
 148               path to a file, and will be inserted into the org-mode
 149               file as a link
 150   - The following options specify how the results should be inserted
 151     into the org-mode file
 152     - replace :: the current results replace any previously inserted
 153                  results from the code block
 154     - silent :: rather than being inserted into the org-mode file the
 155                 results are echoed into the message bar
 156 - exports :: exports arguments specify what should be included in html
 157              or latex exports of the org-mode file
 158   - code :: the body of code is included into the exported file
 159   - results :: the results of evaluating the code is included in the
 160                exported file
 161   - both :: both the code and results are included in the exported
 162             file
 163   - none :: nothing is included in the exported file
 164 - tangle :: tangle arguments specify whether or not the source-code
 165             block should be included in tangled extraction of
 166             source-code files
 167   - yes :: the source-code block is exported to a source-code file
 168            named after the basename (name w/o extension) of the
 169            org-mode file
 170   - no :: (default) the source-code block is not exported to a
 171           source-code file
 172   - other :: any other string passed to the =tangle= header argument
 173              is interpreted as a file basename to which the block will
 174              be exported
 175