This is the official manual for the latest Org-mode release.

Table of Contents

Next: , Previous: Extracting source code, Up: Working with source code

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 source code blocks for execution. See Languages for identifiers to enable other languages.

Org provides many ways to execute code blocks. C-c C-c or C-c C-v e with the point on a code block1 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 block2 from an Org mode buffer or table. These named code blocks can be located in the current Org mode buffer or in the “Library of Babel” (see Library of Babel). Using either the inline syntax or the #+CALL: syntax, the result is then wrapped based on org-babel-inline-result-wrap, which by default is "=%s=" that produces 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>] ...
This is the name of the code block to be evaluated (see Structure of code blocks).
Org passes arguments to the code block using standard function call syntax —instead of the header argument 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).
<inside header arguments>
Org passes inside header arguments to the named source code block. These arguments use header argument syntax—instead of the standard function call syntax. Inside header arguments affect code block evaluation. For example, [:results output] collects results printed to STDOUT during code execution of that block.
<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 and then inserts them in the Org buffer.

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


[1] The option org-babel-no-eval-on-ctrl-c-ctrl-c can be used to remove code evaluation from the C-c C-c key binding.

[2] Actually, the constructs call_<name>() and src_<lang>{} are not evaluated when they appear in a keyword line (i.e. lines starting with #+KEYWORD:, see In-buffer settings).