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

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

#+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.

‘code’

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

‘drawer’

Result wrapped in a ‘RESULTS’ drawer. Useful for containing ‘raw’ or ‘org’ results 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, nothing is written to the disk. The block is used for its side-effects only, as in the following example:

#+begin_src shell :results file link :file "download.tar.gz"
wget -c "http://example.com/download.tar.gz"
#+end_src

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

‘raw’

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

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.

‘silent’

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

‘replace’

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

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