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

org-babel: execution of source code blocks in org-mode

• Introduction
• Basic org-babel functionality

Introduction

Org-babel provides the following modifications to 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:

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

1. parses source block info (recognises language, looks for

arguments (there aren't any))

1. 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.

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