ba596a2dd8060e88fdb1e8a9b629f2cefb0556e4
[worg.git] / 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 #+LINK_UP:    index.php
10 #+LINK_HOME:  http://orgmode.org/worg/
11 #+EXPORT_EXCLUDE_TAGS: noexport
12
13 * Common combinations of header-args and result types
14    Many combinations of header arguments and result types are
15    supported by Org Babel. Individual languages may even define
16    special header args. Like always in combinatorics, the number
17    of possible combinations increases rapidly when there are several
18    factors with several levels each that can be freely combined.
19
20    The following table shows combinations of header arguments and
21    result types that might be considered reasonable for many
22    programming languages.
23
24     #+tblname: header-args-combinations
25     | evaluation | collection | type              |
26     | (:session) | (:results) | (:results)        |
27     |------------+------------+-------------------|
28     | external   | value      | table (vector)    |
29     |            |            | scalar (verbatim) |
30     |            |            | file              |
31     |            |            | raw (org)         |
32     |            |            | html              |
33     |            |            | latex             |
34     |            |            | code              |
35     |            |            | pp                |
36     |            | output     | table (vector)    |
37     |            |            | scalar (verbatim) |
38     |            |            | file              |
39     |            |            | raw (org)         |
40     |            |            | html              |
41     |            |            | latex             |
42     |            |            | code              |
43     |            |            | pp                |
44     | session    | value      | table (vector)    |
45     |            |            | scalar (verbatim) |
46     |            |            | file              |
47     |            |            | raw (org)         |
48     |            |            | html              |
49     |            |            | latex             |
50     |            |            | code              |
51     |            |            | pp                |
52     |            | output     | table (vector)    |
53     |            |            | scalar (verbatim) |
54     |            |            | file              |
55     |            |            | raw (org)         |
56     |            |            | html              |
57     |            |            | latex             |
58     |            |            | code              |
59     |            |            | pp                |
60
61      
62     More special header arguments and their possible values are
63     summarized in the next table:
64    
65     #+tblname: other-header-args
66     
67     | header-arg |          | values  |          |         |
68     |------------+----------+---------+----------+---------|
69     | :results   | silent   | replace | append   | prepend |
70     | (handling) |          |         |          |         |
71     | :exports   | code     | results | both     | none    |
72     | :comments  | yes      | (no?)   |          |         |
73     | :noweb     | no       | yes     |          |         |
74     | :tangle    | yes      | no      | filename |         |
75     | :no-expand |          |         |          |         |
76     | :file      |          |         |          |         |
77     | :dir       |          |         |          |         |
78     | :cache     | no       | yes     |          |         |
79     | :var       | x=y      |         |          |         |
80     | :hlines    | no       | yes     |          |         |
81     | :colnames  | nil      | no      | yes      |         |
82     | :rownames  | no       | yes     |          |         |
83     | :shebang   | "string" |         |          |         |
84     | :eval      | never    | query   |          |         |
85
86
87 * Setting language and file specific default header argument values
88 This may be useful to e.g., have all Python code blocks in a file use
89 the same session.  The following file-local-variable syntax should be
90 used, placing the customization at the end of the Org-mode file.
91
92 : #+Title: Example of default file and language session
93
94 : The value in this buffer is...
95 : #+begin_src emacs-lisp
96 :   org-babel-default-header-args:Python
97 : #+end_src
98
99 : #+RESULTS:
100 : | (:session . foo) |
101
102 : # Local Variables:
103 : # eval: (setq-local org-babel-default-header-args:Python '((:session . "foo")))
104 : # End: