UP | HOME

Header arguments and result types in Org Babel

For a complete header argument reference see the Org-mode manual's page which lists all Specific-header-arguments. This page holds ancillary notes and tricks which have not made it into the manual.

Table of Contents

Generally use verbatim when using drawer, raw or org

We often want to add verbatim (which inhibits interpretation as a value, which can often result in a list or table result), when inserting results directly into the buffer using drawer, raw or org which don't do tabular interpretation.

An example w/o verbatim.

#+begin_src sh :results drawer
cat <<EOF
| 1 | 2
|--
| a | b
EOF
#+end_src

#+RESULTS:
:RESULTS:
|   |    | 1 |   |   | 2 |
|   | -- |   |   |   |   |
|   |    | a |   |   | b |
:END:

The same block with the verbatim flag.

#+begin_src sh :results verbatim drawer
cat <<EOF
| 1 | 2
|--
| a | b
EOF
#+end_src

#+RESULTS:
:RESULTS:
| 1 | 2 |
|---+---|
| a | b |
:END:

Common combinations of header-args and result types

Many combinations of header arguments and result types are supported by Org Babel. Individual languages may even define special header args. Like always in combinatorics, the number of possible combinations increases rapidly when there are several factors with several levels each that can be freely combined.

The following table shows combinations of header arguments and result types that might be considered reasonable for many programming languages.

evaluationcollectiontype
(:session)(:results)(:results)
externalvaluetable (vector)
scalar (verbatim)
file
raw (org)
html
latex
code
pp
outputtable (vector)
scalar (verbatim)
file
raw (org)
html
latex
code
pp
sessionvaluetable (vector)
scalar (verbatim)
file
raw (org)
html
latex
code
pp
outputtable (vector)
scalar (verbatim)
file
raw (org)
html
latex
code
pp

More special header arguments and their possible values are summarized in the next table:

header-argvalues
:resultssilentreplaceappendprepend
(handling)
:exportscoderesultsbothnone
:commentsyes(no?)
:nowebnoyes
:tangleyesnofilename
:no-expand
:file
:dir
:cachenoyes
:varx=y
:hlinesnoyes
:colnamesnilnoyes
:rownamesnoyes
:shebang"string"
:evalneverquery

Setting language and file specific default header argument values

This may be useful to e.g., have all Python code blocks in a file use the same session. The following file-local-variable syntax should be used, placing the customization at the end of the Org-mode file.

#+Title: Example of default file and language session

The value in this buffer is...
#+begin_src emacs-lisp
  org-babel-default-header-args:Python
#+end_src

#+RESULTS:
| (:session . foo) |

# Local Variables:
# eval: (setq-local org-babel-default-header-args:Python '((:session . "foo")))
# End:

Documentation from the http://orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.