wiki/org-mode-babel.org

Org-mode: Babel

• The fundamental concepts
• Sessions
• Integrating between different programming languages

Org-babel is the framework that enables Org-mode to insert output of the code from programming languages. It is also the one thing that makes Org-mode to be used as a tool for reproducible research. As of 2020-06-08, Babel supports more than 50 languages with the possibility of adding of other languages that are not supported yet.

The fundamental concepts

Here's an example of a code block executed with the shell.

echo "HELLO WORLD"

HELLO WORLD

To execute the code block, simply run org-babel-execute-src-block (by default, this is mapped in <C-c> <C-c>). The results will be printed into a result block.

Each of the supported language may also have an exclusive option with each language suitable for certain processes.

For example, with Python 3, you can pretty print it in accordance to Org-mode display. An array will create a table, for instance with :results value header argument.

[["Item", "Value"], ["Baseball bat", 123], ["Baseball glove", 25], ["Printed shirt", 42]]

Item	Value
Baseball bat	123
Baseball glove	25
Printed shirt	42

You can also export graphics with tools such as Gnuplot, GNU Octave, R, and even LaTeX. With it, you can export the resulting graphical into a file (commonly with :file <PATH>).

unset arrow
unset label
set grid
splot x**2+y**2, x**2-y**2

With Org-babel, you can share either the output, the code used to generate the output, or both. This is commonly set with the :exports header argument. ¹

Here's an example where I decided to show only the output with :exports results.

Sessions

Each of the source code block runs in its own session meaning context is basically nonexistent between each block.

What if you want each source block to be connected with each other with all of the variables and functions passed to one another? You can simply declare them to be in the same session with :session <SESSION NAME>.

Let's start with a simple example where we want to demonstrate some Python shenanigans. Here's one Python code block.

x = 35
print(x)

Python 3.8.3 (default, May 17 2020, 18:15:42)
[GCC 10.1.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
35
python.el: native completion setup loaded

After a few explanations later…

for i in range(5):
  x += 5
  print(x)

40
45
50
55
60

In certain code where the output can still change (for example, try executing the previous code block again), this may not be the desired behavior. To correct this, simply execute org-babel-execute-buffer.

Integrating between different programming languages

You can also pass Org-mode variables (from #+NAME: <VAR>) ² into the source code blocks with the :var <NAMEC>=<DATA> (though, this may vary among Babel runtimes).

This is the string.

example

This is the string.

This is the source code from the document, for reference.

#+NAME: example_string
This is the string.

#+BEGIN_SRC python  :var example=example_string  :outputs value
example
#+END_SRC

#+RESULTS:
,: This is the string.

#+NAME: example_string
This is the string.

#+BEGIN_SRC python  :var example=example_string  :outputs value
example
#+END_SRC

#+RESULTS:
: This is the string.

Org-mode variables does capture an element as its input. This has a lot of implications of passing data between different sessions and even different languages.

For example, we could still capture the x variable from the previous Python code blocks.

x # Which should be 60 at this point.

Then, pass it to some other Org-mode blocks with the variable. (Since the captured variable are always going to be a string, we have to convert it into the appropriate type.)

as.numeric(python_var) + 2

[1] 62

---

¹

Again, this varies whether export options are available for each Babel-supported lanaguages.

²

Technically called an internal link (https://orgmode.org/org.html#Internal-Links).