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