16.6 Results of Evaluation ¶

How Org handles results of a code block execution depends on many header arguments working together. The primary determinant, however, is the ‘results’ header argument. It accepts four classes of options. Each code block can take only one option per class:

Collection

For how the results should be collected from the code block;

Type

For which type of result the code block will return; affects how Org processes and inserts results in the Org buffer;

Format

For the result; affects how Org processes results;

Handling

For inserting results once they are properly formatted.

Collection ¶

Collection options specify the results. Choose one of the options; they are mutually exclusive.

‘value’

Default for most Babel libraries¹⁵³. Functional mode. Org gets the value by wrapping the code in a function definition in the language of the source 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’. Result is the value returned by the last statement in the code block.

When evaluating the code block in a session (see Environment of a Code Block), Org passes the code to an interpreter running as an interactive Emacs inferior process. 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 Ruby, and the value of .Last.value in R.

‘output’

Scripting mode. Org passes the code to an external process running the interpreter. Org returns the contents of the standard output stream as text results.

When using a session, Org passes the code to the interpreter running as an interactive Emacs inferior process. Org concatenates any text output from the interpreter and returns the collection as a result.

Type ¶

Type tells what result types to expect from the execution of the code block. Choose one of the options; they are mutually exclusive.

The default behavior is to automatically determine the result type. The result type detection depends on the code block language, as described in the documentation for individual languages. See Languages.

‘table’

‘vector’

Interpret the results as an Org table. If the result is a single value, create a table with one row and one column. Usage example: ‘:results value table’.

In-between each table row or below the table headings, sometimes results have horizontal lines, which are also known as “hlines”. The ‘hlines’ argument with the default ‘no’ value strips such lines from the input table. For most code, this is desirable, or else those ‘hline’ symbols raise unbound variable errors. A ‘yes’ accepts such lines, as demonstrated in the following example.

#+NAME: many-cols
| a | b | c |
|---+---+---|
| d | e | f |
|---+---+---|
| g | h | i |

#+NAME: no-hline
#+BEGIN_SRC python :var tab=many-cols :hlines no
return tab
#+END_SRC

#+RESULTS: no-hline
| a | b | c |
| d | e | f |
| g | h | i |

#+NAME: hlines
#+BEGIN_SRC python :var tab=many-cols :hlines yes
return tab
#+END_SRC

#+RESULTS: hlines
| a | b | c |
|---+---+---|
| d | e | f |
|---+---+---|
| g | h | i |

‘list’

Interpret the results as an Org list. If the result is a single value, create a list of one element.

‘scalar’

‘verbatim’

Interpret literally and insert as quoted text. Do not create a table. Usage example: ‘:results value verbatim’.

‘file’

Interpret as a filename. Save the results of execution of the code block to that file, then insert a link to it. You can control both the filename and the description associated to the link.

Org first tries to generate the filename from the value of the ‘file’ header argument and the directory specified using the ‘output-dir’ header arguments. If ‘output-dir’ is not specified, Org assumes it is the current directory.

#+BEGIN_SRC asymptote :results value file :file circle.pdf :output-dir img/
  size(2cm);
  draw(unitcircle);
#+END_SRC

If ‘file’ header argument is missing, Org generates the base name of the output file from the name of the code block, and its extension from the ‘file-ext’ header argument. In that case, both the name and the extension are mandatory.

Result can also be interpreted as path to file. See ‘:results link’.

#+name: circle
#+BEGIN_SRC asymptote :results value file :file-ext pdf
  size(2cm);
  draw(unitcircle);
#+END_SRC

The ‘file-desc’ header argument defines the description (see Link Format) for the link. If ‘file-desc’ is present but has no value, the ‘file’ value is used as the link description. When this argument is not present, the description is omitted. If you want to provide the ‘file-desc’ argument but omit the description, you can provide it with an empty vector (i.e., :file-desc []).

By default, Org assumes that a table written to a file has TAB-delimited output. You can choose a different separator with the ‘sep’ header argument.

The ‘file-mode’ header argument defines the file permissions. To make it executable, use ‘:file-mode (identity #o755)’.

#+BEGIN_SRC shell :results file :file script.sh :file-mode (identity #o755)
  echo "#!/bin/bash"
  echo "echo Hello World"
#+END_SRC

Format ¶

Format pertains to the type of the result returned by the code block. Choose one of the options; they are mutually exclusive. The default follows from the type specified above.

‘raw’

Interpreted as raw Org mode. Inserted directly into the buffer. Aligned if it is a table. Usage example: ‘:results value raw’.

‘code’

Result enclosed in a code block. Useful for parsing. Usage example: ‘:results value code’.

‘drawer’

Results are added directly to the Org file as with ‘raw’, but are wrapped in a ‘RESULTS’ drawer or results macro (for inline code blocks), for later scripting and automated processing. Usage example: ‘:results value drawer’.

‘html’

Results enclosed in a ‘BEGIN_EXPORT html’ block. Usage example: ‘:results value html’.

‘latex’

Results enclosed in a ‘BEGIN_EXPORT latex’ block. Usage example: ‘:results value latex’.

‘link’

‘graphics’

When used along with ‘file’ type, the result is a link to the file specified in ‘:file’ header argument. However, unlike plain ‘file’ type, code block output is not written to the disk. The block is expected to generate the file by its side-effects only, as in the following example:

#+begin_src shell :results file link :file "org-mode-unicorn.svg"
  wget -c "https://orgmode.org/resources/img/org-mode-unicorn.svg"
#+end_src

#+RESULTS:
[[file:org-mode-unicorn.svg]]

If ‘:file’ header argument is omitted, interpret source block result as the file path.

‘org’

Results enclosed in a ‘BEGIN_SRC org’ block. For comma-escape, either TAB in the block, or export the file. Usage example: ‘:results value org’.

‘pp’

Result converted to pretty-print source code. Enclosed in a code block. Languages supported: Emacs Lisp, Python, and Ruby. Usage example: ‘:results value pp’.

The ‘wrap’ header argument unconditionally marks the results block by appending strings to ‘#+BEGIN_’ and ‘#+END_’. If no string is specified, Org wraps the results in a ‘#+BEGIN_results’ … ‘#+END_results’ block. It takes precedent over the ‘results’ value listed above. E.g.,

#+BEGIN_SRC emacs-lisp :results html :wrap EXPORT markdown
"<blink>Welcome back to the 90's</blink>"
#+END_SRC

#+RESULTS:
#+BEGIN_EXPORT markdown
<blink>Welcome back to the 90's</blink>
#+END_EXPORT

Handling ¶

Handling options after collecting the results. Choose one of the options; they are mutually exclusive.

‘replace’

Default. Insert results in the Org buffer. Remove previous results. Usage example: ‘:results output replace’.

‘silent’

Do not insert results in the Org mode buffer, but echo them in the minibuffer. Usage example: ‘:results output silent’.

‘none’

Compute results, but do not do anything with them. No inserting in the Org mode buffer nor echo them in the minibuffer. The results can still be used when referenced from another code block. Usage example: ‘:results none’.

‘discard’

Ignore the results completely. This option is similar to ‘none’, but no processing is performed on the return value. Calling the code block programmatically (see How to evaluate source code) or by reference (see Passing arguments and Noweb Reference Syntax) will always yield nil.

‘append’

Append results to the Org buffer. Latest results are at the bottom. Does not remove previous results. Usage example: ‘:results output append’.

‘prepend’

Prepend results to the Org buffer. Latest results are at the top. Does not remove previous results. Usage example: ‘:results output prepend’.

Post-processing ¶

The ‘post’ header argument is for post-processing results from block evaluation. When ‘post’ has any value, Org binds the results to *this* variable for easy passing to ‘var’ header argument specifications (see Environment of a Code Block). That makes results available to other code blocks, or even for direct Emacs Lisp code execution.

The following two examples illustrate ‘post’ header argument in action. The first one shows how to attach an ‘ATTR_LATEX’ keyword using ‘post’.

#+NAME: attr_wrap
#+BEGIN_SRC sh :var data="" :var width="\\textwidth" :results output
  echo "#+ATTR_LATEX: :width $width"
  echo "$data"
#+END_SRC

#+HEADER: :file /tmp/it.png
#+BEGIN_SRC dot :post attr_wrap(width="5cm", data=*this*) :results drawer
  digraph{
          a -> b;
          b -> c;
          c -> a;
  }
#+end_src

#+RESULTS:
:RESULTS:
#+ATTR_LATEX :width 5cm
[[file:/tmp/it.png]]
:END:

The second example shows use of ‘colnames’ header argument in ‘post’ to pass data between code blocks.

#+NAME: round-tbl
#+BEGIN_SRC emacs-lisp :var tbl="" fmt="%.3f"
  (mapcar (lambda (row)
            (mapcar (lambda (cell)
                      (if (numberp cell)
                          (format fmt cell)
                        cell))
                    row))
          tbl)
#+end_src

#+BEGIN_SRC R :colnames yes :post round-tbl[:colnames yes](*this*)
  set.seed(42)
  data.frame(foo=rnorm(1))
#+END_SRC

#+RESULTS:
|   foo |
|-------|
| 1.371 |