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

Table of Contents

Next: , Previous: Header arguments, Up: Working with source code


14.9 Results of evaluation

How Org handles results of a code block execution depends on many header arguments working together. Here is only a summary of these. For an enumeration of all the header arguments that affect results, see results.

The primary determinant is the execution context. Is it in a :session or not? Orthogonal to that is if the expected result is a :results value or :results output, which is a concatenation of output from start to finish of the ‘src’ code block's evaluation.

Non-session Session
:results value value of last expression value of last expression
:results output contents of STDOUT concatenation of interpreter output

For :session and non-session, the :results value turns the results into an Org mode table format. Single values are wrapped in a one dimensional vector. Rows and columns of a table are wrapped in a two-dimensional vector.

14.9.1 Non-session

14.9.1.1 :results value

Default. Org gets the value by wrapping the code in a function definition in the language of the ‘src’ block. That is why when using :results value, code should execute like a function and return a value. For languages like Python, an explicit return statement is mandatory when using :results value.

This is one of four evaluation contexts where Org automatically wraps the code in a function definition.

14.9.1.2 :results output

For :results output, the code is passed to an external process running the interpreter. Org returns the contents of the standard output stream as as text results.

14.9.2 Session

14.9.2.1 :results value

For :results value from a :session, Org passes the code to an interpreter running as an interactive Emacs inferior process. So only languages that provide interactive evaluation can have session support. Not all languages provide this support, such as ‘C’ and ‘ditaa’. Even those that do support, such as ‘Python’ and ‘Haskell’, they impose limitations on allowable language constructs that can run interactively. Org inherits those limitations for those ‘src’ code blocks running in a :session.

Org gets the value from the source code interpreter's last statement output. Org has to use language-specific methods to obtain the value. For example, from the variable _ in ‘Python’ and ‘Ruby’, and the value of .Last.value in ‘R’).

14.9.2.2 :results output

For :results output, Org passes the code to the interpreter running as an interactive Emacs inferior process. Org concatenates whatever text output emitted by the interpreter to return the collection as a result. Note that this collection is not the same as collected from STDOUT of a non-interactive interpreter running as an external process. Compare for example these two blocks:

     #+BEGIN_SRC python :results output
      print "hello"
      2
      print "bye"
     #+END_SRC
     
     #+RESULTS:
     : hello
     : bye

In the above non-session mode, the “2” is not printed; so does not appear in results.

     #+BEGIN_SRC python :results output :session
      print "hello"
      2
      print "bye"
     #+END_SRC
     
     #+RESULTS:
     : hello
     : 2
     : bye

In the above :session mode, the interactive interpreter receives and prints “2”. Results show that.