org-contrib/babel/header-args.org

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