wiki/2020-04-17-21-41-30.org

Org mode: Babel

• Functional and scripting mode
• Functional mode values and passing them around
• Creating dynamic content with meta-programming
• Executing code blocks in the same session

Babel is the framework that enables Org mode to be a Reproducible research tool. It is what makes Org mode works with source code blocks. As of 2021-04-22, Babel supports more than 50 languages with the ability to support unsupported languages. Though, it does have its quirks with different languages. Your mileage may vary.

Functional and scripting mode

Babel works in two modes: functional and scripting mode.

• Functional mode returns a value either from the last statement or the return statement. The value can then be used in other source code blocks and appropriately converted into Org mode equivalents. If the return value is a vector type, it will be printed as tables in Org mode which will then be rendered as a vector when used in another source code block.
• Scripting mode simply prints the output. Do keep in mind different languages have different ways of capturing the output. ¹

The default mode is in functional mode but you can change it by setting :results header argument with the values from the collection class.

Functional mode values and passing them around

With functional mode, the value return will appear as an appropriate element in the Org mode buffer. The following examples are in Python.

Scalar values appear as strings…

return "The quick brown fox jumps over the lazy dog."

The quick brown fox jumps over the lazy dog.

…and vector values print as tables.

return [
    ["Monty", 45],
    ["Soup", 54],
    ["Cabbages", 63]
]

Monty	45
Soup	54
Cabbages	63

To pass values between different code blocks, you have to give the blocks a name. The previous code block was given a name data and passed it to the next block.

return o[0]

Monty

45

Creating dynamic content with meta-programming

With Babel, you can call named code blocks anywhere from blocks to inline. This creates a "function" with Babel using different languages. The following block creates init function with a default value for its argument.

return f"Hello {name}"

You can then call the init function inline with call_init[${HEADER_ARGS}](${ARGS}) which should contain "call_init[:results raw]() Hello world". For blocks, you can use the #+call block with a similar syntax to inline functions — i.e., #+call: init[${HEADER_ARGS}](${ARGS}).

Hello world

You can also use it inside of code blocks with <<init>> which makes it perfect for code blocks templates like configuring paper output for Lilypond blocks. Though, you have to set :noweb yes in the header arguments or configure it in org-babel-default-header-args as one of the default.

echo -n <<init(name="Canavan")>>

Hello Canavan

Babel functions are commonly used for inserting dynamic values. Very helpful in reducing places you need to edit (not to mention less prone to errors).

Executing code blocks in the same session

Each of the source code block runs on an individual session. However, you can connect source code blocks in the same session with :session <SESSION NAME>. This allows you to cut code blocks and add more detailed explanations for them.

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

x = 30
print(x)

30

Then here's another code block in the same session.

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

35
40
45
50
55

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.

---

¹

Most of them involves capturing the stdout.