This is the official manual for the latest Org-mode release.
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
or not? Orthogonal to that is if the expected result is a
:results output, which is a concatenation of output from
start to finish of the ‘src’ code block's evaluation.
|value of last expression||value of last expression
|contents of STDOUT||concatenation of interpreter output
: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
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
value, code should execute like a function and return a value. For
languages like Python, an explicit
return statement is mandatory when
This is one of four evaluation contexts where Org automatically wraps the code in a function definition.
: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.
: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
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
.Last.value in ‘R’).
: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.