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

How to evaluate source code

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

By default, Org enables only Emacs Lisp code blocks for execution. See Languages 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 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 code blocks from the current Org mode buffer or from the “Library of Babel” (see Library of Babel).

The syntax for ‘CALL’ keyword is:

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

The syntax for inline named code blocks is:

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

When inline 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.

‘<name>’

This is the name of the code block (see Structure of Code Blocks) to be evaluated in the current document. If the block is located in another file, start ‘<name>’ with the file name followed by a colon. For example, in order to execute a block named ‘clear-data’ in ‘file.org’, you can write the following:

#+CALL: file.org:clear-data()

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

Limit code block evaluation

The ‘eval’ header argument can limit evaluation of specific code blocks and ‘CALL’ keyword. It is useful for protection against evaluating untrusted code blocks by prompting for a confirmation.

‘never’ or ‘no’

Org never evaluates the source code.

‘query’

Org prompts the user for permission to evaluate the source code.

‘never-export’ or ‘no-export’

Org does not evaluate the source code when exporting, yet the user can evaluate it interactively.

‘query-export’

Org prompts the user for permission to evaluate the source code during export.

If ‘eval’ header argument is not set, then Org determines whether to evaluate the source code from the org-confirm-babel-evaluate variable (see Code Evaluation Security).

Cache results of evaluation

The ‘cache’ header argument is for caching results of evaluating code blocks. Caching results can avoid re-evaluating a code block that have not changed since the previous run. To benefit from the cache and avoid redundant evaluations, the source block must have a result already present in the buffer, and neither the header arguments—including the value of ‘var’ references—nor the text of the block itself has changed since the result was last computed. This feature greatly helps avoid long-running calculations. For some edge cases, however, the cached results may not be reliable.

The caching feature is best for when code blocks are pure functions, that is functions that return the same value for the same input arguments (see Environment of a Code Block), and that do not have side effects, and do not rely on external variables other than the input arguments. Functions that depend on a timer, file system objects, and random number generators are clearly unsuitable for caching.

A note of warning: when ‘cache’ is used in a session, caching may cause unexpected results.

When the caching mechanism tests for any source code changes, it does not expand noweb style references (see Noweb Reference Syntax).

The ‘cache’ header argument can have one of two values: ‘yes’ or ‘no’.

‘no’

Default. No caching of results; code block evaluated every time.

‘yes’

Whether to run the code or return the cached results is determined by comparing the SHA1 hash value of the combined code block and arguments passed to it. This hash value is packed on the ‘#+RESULTS:’ line from previous evaluation. When hash values match, Org does not evaluate the code block. When hash values mismatch, Org evaluates the code block, inserts the results, recalculates the hash value, and updates ‘#+RESULTS:’ line.

In this example, both functions are cached. But ‘caller’ runs only if the result from ‘random’ has changed since the last run.

#+NAME: random
#+BEGIN_SRC R :cache yes
  runif(1)
#+END_SRC

#+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
0.4659510825295

#+NAME: caller
#+BEGIN_SRC emacs-lisp :var x=random :cache yes
  x
#+END_SRC

#+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
0.254227238707244