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

Code blocks can be evaluated1 and the results of evaluation optionally placed in the Org mode buffer. The results of evaluation are placed following a line that begins by default with #+RESULTS and optionally a cache identifier and/or the name of the evaluated code block. The default value of #+RESULTS can be changed with the customizable variable org-babel-results-keyword.

By default, the evaluation facility is only enabled for Lisp code blocks specified as emacs-lisp. See Languages to enable other supported languages. See Structure of code blocks for information on the syntax used to define a code block.

There are a number of ways to evaluate code blocks. The simplest is to press C-c C-c or C-c C-v e with the point on a code block2. This will call the org-babel-execute-src-block function to evaluate the block and insert its results into the Org mode buffer.

It is also possible to evaluate named code blocks from anywhere3 in an Org mode buffer or an Org mode table. These named code blocks can be located in the current Org mode buffer or in the “Library of Babel” (see Library of Babel). Named code blocks can be evaluated with a separate #+CALL: line or inline within a block of text. In both cases the result is wrapped according to the value of org-babel-inline-result-wrap, which by default is "=%s=" for markup that produces verbatim text.

The syntax of the #+CALL: line is

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

The syntax for inline evaluation of named code blocks is

     ... call_<name>(<arguments>) ...
     ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
The name of the code block to be evaluated (see Structure of code blocks).
Arguments specified in this section will be passed to the code block. These arguments use standard function call syntax, rather than header argument syntax. For example, a #+CALL: line that passes the number four 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>
Inside header arguments are passed through and applied to the named code block. These arguments use header argument syntax rather than standard function call syntax. Inside header arguments affect how the code block is evaluated. For example, [:results output] will collect the results of everything printed to STDOUT during execution of the code block.
<end header arguments>
End header arguments are applied to the calling instance and do not affect evaluation of the named code block. They affect how the results are incorporated into the Org mode buffer and how the call line is exported. For example, :results html will insert the results of the call line evaluation in the Org buffer, wrapped in a BEGIN_HTML: block.

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


[1] Whenever code is evaluated there is a potential for that code to do harm. Org mode provides safeguards to ensure that code is only evaluated after explicit confirmation from the user. For information on these safeguards (and on how to disable them) see Code evaluation security.

[2] 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.

[3] 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).