Header arguments and result types in Org Babel
For a complete header argument reference see the Org mode manual. This page holds ancillary notes and tricks which have not made it into the manual.
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.
| evaluation | collection | type |
|---|---|---|
| (:session) | (:results) | (:results) |
| external | value | table (vector) |
| scalar (verbatim) | ||
| file | ||
| raw (org) | ||
| html | ||
| latex | ||
| code | ||
| pp | ||
| output | table (vector) | |
| scalar (verbatim) | ||
| file | ||
| raw (org) | ||
| html | ||
| latex | ||
| code | ||
| pp | ||
| session | value | table (vector) |
| scalar (verbatim) | ||
| file | ||
| raw (org) | ||
| html | ||
| latex | ||
| code | ||
| pp | ||
| output | table (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-arg | values | |||
|---|---|---|---|---|
| :results | silent | replace | append | prepend |
| (handling) | ||||
| :exports | code | results | both | none |
| :comments | yes | (no?) | ||
| :noweb | no | yes | ||
| :tangle | yes | no | filename | |
| :no-expand | ||||
| :file | ||||
| :dir | ||||
| :cache | no | yes | ||
| :var | x=y | |||
| :hlines | no | yes | ||
| :colnames | nil | no | yes | |
| :rownames | no | yes | ||
| :shebang | "string" | |||
| :eval | never | query |
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: