Next: , Previous: , Up: Working with Source Code   [Contents][Index]


14.5 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 and inserts results in the Org buffer;

handling

For processing results after evaluation of the code block;

Collection

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

value

Default. 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 Python and 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.

Note that this collection is not the same as that would be 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 it 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, the interactive interpreter receives and prints “2”. Results show that.

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

#+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’ has no value, Org uses the generated file name for both the “link” and “description” parts of the link.

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.

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

Result is a link to the file specified in ‘:file’ header argument. However, unlike plain ‘:file’, nothing is written to the disk. The block is used for its side-effects only, as in the following example:

#+begin_src shell :results 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 unconditionnally 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 |

Footnotes

(143)

Due to the way this header argument is implemented, it implies “:results file”. Therefore if it is set for multiple blocks at once (by a subtree or buffer property for example), all blocks are forced to produce file results. This is seldom desired behavior, so it is recommended to set this header only on a per-block basis. It is possible that this aspect of the implementation might change in the future.


Next: , Previous: , Up: Working with Source Code   [Contents][Index]