org-babel-ded-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: execution of source code blocks in org-mode
   6 #+AUTHOR:     Dan Davison
   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
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57 *** What happens to the results?
  58     Org-babel provides two fundamentally different modes for capturing
  59     the results of code evaluation, specified by the :results header
  60     argument:
  61 **** :results value
  62      This means that the 'result' of code evaluation is defined to be
  63      the *value* of the last statement in the block. Thus with this
  64      setting, one can view the code block as a function with a return
  65      value. And not only can one view it that way, but you can
  66      actually use the return value of one source block as input for
  67      another (see later). This setting is the default.
  68 **** :results output
  69      With this setting, org-babel captures all the text output of the
  70      code block and places it in the org buffer. One can think of this
  71      as a 'scripting' mode: the code block contains a series of
  72      commands, and you get the output of all the commands. Unlike in
  73      the 'functional' mode specified by =:results value=, the code
  74      block has no return value. (This mode will be familiar to Sweave
  75      users).
  76 **** Additional :results settings
  77
  78
  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
  86 *** Internals
  87     For those interested in hacking org-babel, it's worth going
  88     through what actually happened there:
  89 ***** org-babel-execute-src
  90       1. parses source block info (recognises language, looks for
  91          arguments (there aren't any))
  92       2. calls
  93 ***** org-babel-execute:LANG
  94       1. resolves referenced variables (there aren't any)
  95       2. assigns any referenced variables and evaluates body
  96 ***** org-babel-LANG-evaluate
  97       Returns a string corresponding to either output or value of block.
  98
  99 #+resname:
 100 : Sun Jul  5 14:17:31 EDT 2009
 101
 102
 103 #+begin_src R :results output
 104     date()
 105 #+end_src
 106
 107 #+resname:
 108 : Sun Jul  5 14:00:20 2009
 109
 110
 111 #+begin_src python
 112     import time
 113     time.ctime()
 114 #+end_src
 115
 116 #+resname:
 117 : Sun Jul  5 14:13:07 2009
 118
 119 * Reference / Documentation
 120
 121 *** Source Code block syntax
 122
 123 The basic syntax of source-code blocks is as follows:
 124
 125 : #+srcname: name
 126 : #+begin_src language header-arguments
 127 : body
 128 : #+end_src
 129
 130 - name :: This name is associated with the source-code block.  This is
 131      similar to the =#+TBLNAME= lines which can be used to name tables
 132      in org-mode files.  By referencing the srcname of a source-code
 133      block it is possible to evaluate the block for other places,
 134      files, or from inside tables.
 135 - language :: The language of the code in the source-code block, valid
 136      values must be members of `org-babel-interpreters'.
 137 - header-arguments :: Header arguments control many facets of the
 138      input to, evaluation of, and output of source-code blocks.  See
 139      the [[* Header Arguments][Header Arguments]] section for a complete review of available
 140      header arguments.
 141 - body :: The actual source code which will be evaluated.  This can be
 142           edited with `org-edit-special'.
 143
 144 **** Header Arguments
 145
 146 - results :: results arguments specify what should be done with the
 147              output of source-code blocks
 148   - The following options are mutually exclusive, and specify how the
 149     results should be collected from the source-code block
 150     - value ::
 151     - output ::
 152   - The following options are mutually exclusive and specify what type
 153     of results the code block will return
 154     - vector :: specifies that the results should be interpreted as a
 155                 multidimensional vector (even if the vector is
 156                 trivial), and will be inserted into the org-mode file
 157                 as a table
 158     - scalar :: specifies that the results should be interpreted as a
 159                 scalar value, and will be inserted into the org-mode
 160                 file as quoted text
 161     - file :: specifies that the results should be interpreted as the
 162               path to a file, and will be inserted into the org-mode
 163               file as a link
 164   - The following options specify how the results should be inserted
 165     into the org-mode file
 166     - replace :: the current results replace any previously inserted
 167                  results from the code block
 168     - silent :: rather than being inserted into the org-mode file the
 169                 results are echoed into the message bar
 170 - exports :: exports arguments specify what should be included in html
 171              or latex exports of the org-mode file
 172   - code :: the body of code is included into the exported file
 173   - results :: the results of evaluating the code is included in the
 174                exported file
 175   - both :: both the code and results are included in the exported
 176             file
 177   - none :: nothing is included in the exported file
 178 - tangle :: tangle arguments specify whether or not the source-code
 179             block should be included in tangled extraction of
 180             source-code files
 181   - on :: the source-code block is included in tangled files
 182   - off :: the source-code block is ignored when tangling
 183