org-mode/org-babel-ded-worg.org

120 lines
3.4 KiB
Org Mode

#+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
#+STARTUP: align fold nodlcheck hidestars oddeven lognotestate
#+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TAGS: Write(w) Update(u) Fix(f) Check(c)
#+TITLE: org-babel: execution of source code blocks in org-mode
#+AUTHOR: Dan Davison
#+EMAIL: davison at stats dot ox dot ac dot uk
#+LANGUAGE: en
#+CATEGORY: worg
* Introduction
Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
support]] for blocks of source code examples in the org-mode core.
1. source code execution
2. arguments to source code blocks
* Basic org-babel functionality
*** Source code execution
For interpreted languages such as shell, python, R, etc, org-babel
allows source blocks to be executed: the code is passed to the
interpreter and you have control over what is done with the
results of excecution. E.g. place point anywhere in the following
block and use C-c C-c to run the code:
#+begin_src python :results output
import time
x = 4
print("hello\n")
#print time.ctime()
print [5, 10]
#+end_src
#+resname:
: hello
: 510
#+begin_src R :results value
x = 4
date()
c(5, 10)
#+end_src
#+resname:
| 5 |
| 10 |
*** What happens to the results?
Org-babel provides two fundamentally different modes for capturing
the results of code evaluation, specified by the :results header
argument:
**** :results value
This means that the 'result' of code evaluation is defined to be
the *value* of the last statement in the block. Thus with this
setting, one can view the code block as a function with a return
value. And not only can one view it that way, but you can
actually use the return value of one source block as input for
another (see later). This setting is the default.
**** :results output
With this setting, org-babel captures all the text output of the
code block and places it in the org buffer. One can think of this
as a 'scripting' mode: the code block contains a series of
commands, and you get the output of all the commands. Unlike in
the 'functional' mode specified by =:results value=, the code
block has no return value. (This mode will be familiar to Sweave
users).
**** Additional :results settings
*** Arguments to source code blocks
In addition to evaluation of code blocks, org-babel allows them to
be parameterised (i.e. have arguments). Thus source code blocks
now have the status of *functions*.
*** Internals
For those interested in hacking org-babel, it's worth going
through what actually happened there:
***** org-babel-execute-src
1. parses source block info (recognises language, looks for
arguments (there aren't any))
2. calls
***** org-babel-execute:LANG
1. resolves referenced variables (there aren't any)
2. assigns any referenced variables and evaluates body
***** org-babel-LANG-evaluate
Returns a string corresponding to either output or value of block.
#+resname:
: Sun Jul 5 14:17:31 EDT 2009
#+begin_src R :results output
date()
#+end_src
#+resname:
: Sun Jul 5 14:00:20 2009
#+begin_src python
import time
time.ctime()
#+end_src
#+resname:
: Sun Jul 5 14:13:07 2009