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 sh
  26     date
  27     hostname
  28     whoami
  29 #+end_src
  30
  31 #+resname:
  32 : Sun Jul  5 18:49:46 EDT 2009
  33 : Tichodroma
  34 : dan
  35
  36
  37
  38 *** What happens to the results?
  39     Org-babel provides two fundamentally different modes for capturing
  40     the results of code evaluation, specified by the :results header
  41     argument:
  42 **** :results value
  43      This means that the 'result' of code evaluation is defined to be
  44      the *value* of the last statement in the block. Thus with this
  45      setting, one can view the code block as a function with a return
  46      value. And not only can one view it that way, but you can
  47      actually use the return value of one source block as input for
  48      another (see later). This setting is the default.
  49 **** :results output
  50      With this setting, org-babel captures all the text output of the
  51      code block and places it in the org buffer. One can think of this
  52      as a 'scripting' mode: the code block contains a series of
  53      commands, and you get the output of all the commands. Unlike in
  54      the 'functional' mode specified by =:results value=, the code
  55      block has no return value. (This mode will be familiar to Sweave
  56      users).
  57 **** Additional :results settings
  58
  59
  60
  61 *** Arguments to source code blocks
  62     In addition to evaluation of code blocks, org-babel allows them to
  63     be parameterised (i.e. have arguments). Thus source code blocks
  64     now have the status of *functions*.
  65
  66 *** Internals
  67     For those interested in hacking org-babel, it's worth going
  68     through what actually happened there:
  69 ***** org-babel-execute-src
  70       1. parses source block info (recognises language, looks for
  71          arguments (there aren't any))
  72       2. calls
  73 ***** org-babel-execute:LANG
  74       1. resolves referenced variables (there aren't any)
  75       2. assigns any referenced variables and evaluates body
  76 ***** org-babel-LANG-evaluate
  77       Returns a string corresponding to either output or value of block.
  78
  79 #+resname:
  80 : Sun Jul  5 14:17:31 EDT 2009
  81
  82
  83 #+begin_src R :results output
  84     date()
  85 #+end_src
  86
  87 #+resname:
  88 : Sun Jul  5 14:00:20 2009
  89
  90
  91 #+begin_src python
  92     import time
  93     time.ctime()
  94 #+end_src
  95
  96 #+resname:
  97 : Sun Jul  5 14:13:07 2009