6.3 KiB
org-babel: execution of source code blocks in org-mode
Introduction
Org-babel provides the following modifications to the existing support for blocks of source code examples in the org-mode core.
- source code execution
- 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:
import time
x = 4
print("hello\n")
#print time.ctime()
print [5, 10]
hello 510
x = 4
date()
c(5, 10)
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
- parses source block info (recognises language, looks for
arguments (there aren't any))
- calls
org-babel-execute:LANG
- resolves referenced variables (there aren't any)
- assigns any referenced variables and evaluates body
org-babel-LANG-evaluate
Returns a string corresponding to either output or value of block.
Sun Jul 5 14:17:31 EDT 2009
date()
Sun Jul 5 14:00:20 2009
import time
time.ctime()
Sun Jul 5 14:13:07 2009
Reference / Documentation
Source Code block syntax
The basic syntax of source-code blocks is as follows:
#+srcname: name #+begin_src language header-arguments body #+end_src
- name
- This name is associated with the source-code block. This is
similar to the
#+TBLNAME
lines which can be used to name tables in org-mode files. By referencing the srcname of a source-code block it is possible to evaluate the block for other places, files, or from inside tables. - language
- The language of the code in the source-code block, valid values must be members of `org-babel-interpreters'.
- header-arguments
- Header arguments control many facets of the input to, evaluation of, and output of source-code blocks. See the Header Arguments section for a complete review of available header arguments.
- body
- The actual source code which will be evaluated. This can be edited with `org-edit-special'.
Header Arguments
- results
-
results arguments specify what should be done with the output of source-code blocks
-
The following options are mutually exclusive, and specify how the results should be collected from the source-code block
- value
- output
-
The following options are mutually exclusive and specify what type of results the code block will return
- vector
- specifies that the results should be interpreted as a multidimensional vector (even if the vector is trivial), and will be inserted into the org-mode file as a table
- scalar
- specifies that the results should be interpreted as a scalar value, and will be inserted into the org-mode file as quoted text
- file
- specifies that the results should be interpreted as the path to a file, and will be inserted into the org-mode file as a link
-
The following options specify how the results should be inserted into the org-mode file
- replace
- the current results replace any previously inserted results from the code block
- silent
- rather than being inserted into the org-mode file the results are echoed into the message bar
-
- exports
-
exports arguments specify what should be included in html or latex exports of the org-mode file
- code
- the body of code is included into the exported file
- results
- the results of evaluating the code is included in the exported file
- both
- both the code and results are included in the exported file
- none
- nothing is included in the exported file
- tangle
-
tangle arguments specify whether or not the source-code block should be included in tangled extraction of source-code files
- on
- the source-code block is included in tangled files
- off
- the source-code block is ignored when tangling