org-contrib/babel/header-args.org

   1 #+TITLE:      Header arguments and result types in Org Babel
   2 #+AUTHOR:     Thorsten Jolitz, Eric Schulte
   3 #+EMAIL:      tj[at]data-driven[dot]de
   4 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   5 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
   6 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   7 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
   8 #+LANGUAGE:   en
   9 #+HTML_LINK_UP:    index.php
  10 #+HTML_LINK_HOME:  https://orgmode.org/worg/
  11 #+EXPORT_EXCLUDE_TAGS: noexport
  12
  13 # This file is released by its authors and contributors under the GNU
  14 # Free Documentation license v1.3 or later, code examples are released
  15 # under the GNU General Public License v3 or later.
  16
  17 For a complete header argument reference see the Org-mode manual's
  18 page which lists all [[https://orgmode.org/manual/Specific-header-arguments.html][Specific-header-arguments]].  This page holds
  19 ancillary notes and tricks which have not made it into the manual.
  20
  21 * Generally use =verbatim= when using =drawer=, =raw= or =org=
  22 We often want to add =verbatim= (which inhibits interpretation as a
  23 value, which can often result in a list or table result), when
  24 inserting results directly into the buffer using =drawer=, =raw= or
  25 =org= which don't do tabular interpretation.
  26
  27 An example w/o =verbatim=.
  28 : #+begin_src sh :results drawer
  29 : cat <<EOF
  30 : | 1 | 2
  31 : |--
  32 : | a | b
  33 : EOF
  34 : #+end_src
  35 :
  36 : #+RESULTS:
  37 : :RESULTS:
  38 : |   |    | 1 |   |   | 2 |
  39 : |   | -- |   |   |   |   |
  40 : |   |    | a |   |   | b |
  41 : :END:
  42
  43 The same block /with/ the =verbatim= flag.
  44 : #+begin_src sh :results verbatim drawer
  45 : cat <<EOF
  46 : | 1 | 2
  47 : |--
  48 : | a | b
  49 : EOF
  50 : #+end_src
  51 :
  52 : #+RESULTS:
  53 : :RESULTS:
  54 : | 1 | 2 |
  55 : |---+---|
  56 : | a | b |
  57 : :END:
  58
  59 * Common combinations of header-args and result types
  60    Many combinations of header arguments and result types are
  61    supported by Org Babel. Individual languages may even define
  62    special header args. Like always in combinatorics, the number
  63    of possible combinations increases rapidly when there are several
  64    factors with several levels each that can be freely combined.
  65
  66    The following table shows combinations of header arguments and
  67    result types that might be considered reasonable for many
  68    programming languages.
  69
  70     | evaluation | collection | type              |
  71     | (:session) | (:results) | (:results)        |
  72     |------------+------------+-------------------|
  73     | external   | value      | table (vector)    |
  74     |            |            | scalar (verbatim) |
  75     |            |            | file              |
  76     |            |            | raw (org)         |
  77     |            |            | html              |
  78     |            |            | latex             |
  79     |            |            | code              |
  80     |            |            | pp                |
  81     |            | output     | table (vector)    |
  82     |            |            | scalar (verbatim) |
  83     |            |            | file              |
  84     |            |            | raw (org)         |
  85     |            |            | html              |
  86     |            |            | latex             |
  87     |            |            | code              |
  88     |            |            | pp                |
  89     | session    | value      | table (vector)    |
  90     |            |            | scalar (verbatim) |
  91     |            |            | file              |
  92     |            |            | raw (org)         |
  93     |            |            | html              |
  94     |            |            | latex             |
  95     |            |            | code              |
  96     |            |            | pp                |
  97     |            | output     | table (vector)    |
  98     |            |            | scalar (verbatim) |
  99     |            |            | file              |
 100     |            |            | raw (org)         |
 101     |            |            | html              |
 102     |            |            | latex             |
 103     |            |            | code              |
 104     |            |            | pp                |
 105
 106     More special header arguments and their possible values are
 107     summarized in the next table:
 108
 109     | header-arg |          | values  |          |         |
 110     |------------+----------+---------+----------+---------|
 111     | :results   | silent   | replace | append   | prepend |
 112     | (handling) |          |         |          |         |
 113     | :exports   | code     | results | both     | none    |
 114     | :comments  | yes      | (no?)   |          |         |
 115     | :noweb     | no       | yes     |          |         |
 116     | :tangle    | yes      | no      | filename |         |
 117     | :no-expand |          |         |          |         |
 118     | :file      |          |         |          |         |
 119     | :dir       |          |         |          |         |
 120     | :cache     | no       | yes     |          |         |
 121     | :var       | x=y      |         |          |         |
 122     | :hlines    | no       | yes     |          |         |
 123     | :colnames  | nil      | no      | yes      |         |
 124     | :rownames  | no       | yes     |          |         |
 125     | :shebang   | "string" |         |          |         |
 126     | :eval      | never    | query   |          |         |
 127
 128 * Setting language and file specific default header argument values
 129 This may be useful to e.g., have all Python code blocks in a file use
 130 the same session.  The following file-local-variable syntax should be
 131 used, placing the customization at the end of the Org-mode file.
 132
 133 : #+Title: Example of default file and language session
 134 :
 135 : The value in this buffer is...
 136 : #+begin_src emacs-lisp
 137 :   org-babel-default-header-args:Python
 138 : #+end_src
 139 :
 140 : #+RESULTS:
 141 : | (:session . foo) |
 142 :
 143 : # Local Variables:
 144 : # eval: (setq-local org-babel-default-header-args:Python '((:session . "foo")))
 145 : # End: