Results of Evaluation (The Org Manual)

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

### 15.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 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. 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`’ 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`’ 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 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 |

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