14.5 Evaluating code blocks

A note about security: With code evaluation comes the risk of harm. Org safeguards by prompting for user’s permission before executing any code in the source block. To customize this safeguard (or disable it) see Code evaluation security.

Org captures the results of the ‘src’ code block evaluation and inserts them in the Org file, right after the ‘src’ code block. The insertion point is after a newline and the #+RESULTS label. Org creates the #+RESULTS label if one is not already there.

By default, Org enables only emacs-lisp ‘src’ code blocks for execution. See Languages for identifiers to enable other languages.

Org provides many ways to execute ‘src’ code blocks. C-c C-c or C-c C-v e with the point on a ‘src’ code block¹⁴² calls the org-babel-execute-src-block function, which executes the code in the block, collects the results, and inserts them in the buffer.

By calling a named code block¹⁴³ from an Org mode buffer or a table. Org can call the named ‘src’ code blocks from the current Org mode buffer or from the “Library of Babel” (see Library of Babel). Whether inline syntax or the #+CALL: syntax is used, the result is wrapped based on the variable org-babel-inline-result-wrap, which by default is set to "=%s=" to produce verbatim text suitable for markup.

The syntax for #+CALL: is

#+CALL: <name>(<arguments>)
#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>

The syntax for inline named code block is

... call_<name>(<arguments>) ...
... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...

<name>

This is the name of the code block to be evaluated (see Structure of code blocks).

<arguments>

Org passes arguments to the code block using standard function call syntax. For example, a #+CALL: line that passes ‘4’ to a code block named double, which declares the header argument :var n=2, would be written as #+CALL: double(n=4). Note how this function call syntax is different from the header argument syntax.

<inside header arguments>

Org passes inside header arguments to the named ‘src’ code block using the header argument syntax. Inside header arguments apply to code block evaluation. For example, [:results output] collects results printed to STDOUT during code execution of that block. Note how this header argument syntax is different from the function call syntax.

<end header arguments>

End header arguments affect the results returned by the code block. For example, :results html wraps the results in a BEGIN_EXPORT html block before inserting the results in the Org buffer.

For more examples of header arguments for #+CALL: lines, see Arguments in function calls.