header-args.org 5.6 KB

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.

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 <

The same block with the verbatim flag.

#+begin_src sh :results verbatim drawer
cat <

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: