:var header argument is used to pass arguments to code blocks.
The specifics of how arguments are included in a code block vary by language;
these are addressed in the language-specific documentation. However, the
syntax used to specify arguments is the same across all languages. In every
case, variables require a default value when they are declared.
The values passed to arguments can either be literal values, references, or
Emacs Lisp code (see Emacs Lisp evaluation of variables).
References include anything in the Org mode file that takes a
#+RESULTS: line: tables, lists,
other code blocks and the results of other code blocks.
Note: When a reference is made to another code block, the referenced block will be evaluated unless it has current cached results (see cache).
Argument values can be indexed in a manner similar to arrays (see Indexable variable values).
The following syntax is used to pass arguments to code blocks using the
:var header argument.
assign, can either be a literal value, such as a string
‘"string"’ or a number ‘9’, or a reference to a table, a list, a
literal example, another code block (with or without arguments), or the
results of evaluating another code block.
Here are examples of passing values by reference:
an Org mode table named with either a
#+NAME: example-table | 1 | | 2 | | 3 | | 4 | #+NAME: table-length #+BEGIN_SRC emacs-lisp :var table=example-table (length table) #+END_SRC #+RESULTS: table-length : 4
a simple list named with a
#+NAME: line (note that nesting is not
carried through to the source code block)
#+NAME: example-list - simple - not - nested - list #+BEGIN_SRC emacs-lisp :var x=example-list (print x) #+END_SRC #+RESULTS: | simple | list |
a code block name (from the example above), as assigned by
optionally followed by parentheses
#+BEGIN_SRC emacs-lisp :var length=table-length() (* 2 length) #+END_SRC #+RESULTS: : 8
a code block name, as assigned by
#+NAME:, followed by parentheses and
optional arguments passed within the parentheses following the
code block name using standard function call syntax
#+NAME: double #+BEGIN_SRC emacs-lisp :var input=8 (* 2 input) #+END_SRC #+RESULTS: double : 16 #+NAME: squared #+BEGIN_SRC emacs-lisp :var input=double(input=1) (* input input) #+END_SRC #+RESULTS: squared : 4
a literal example block named with a
#+NAME: literal-example #+BEGIN_EXAMPLE A literal example on two lines #+END_EXAMPLE #+NAME: read-literal-example #+BEGIN_SRC emacs-lisp :var x=literal-example (concatenate 'string x " for you.") #+END_SRC #+RESULTS: read-literal-example : A literal example : on two lines for you.
It is possible to reference portions of variable values by “indexing” into
the variables. Indexes are 0 based with negative values counting back from
the end. If an index is separated by
,s then each subsequent section
will index into the next deepest nesting or dimension of the value. Note
that this indexing occurs before other table related header arguments
:rownames are applied. The
following example assigns the last cell of the first row the table
example-table to the variable
#+NAME: example-table | 1 | a | | 2 | b | | 3 | c | | 4 | d | #+BEGIN_SRC emacs-lisp :var data=example-table[0,-1] data #+END_SRC #+RESULTS: : a
Ranges of variable values can be referenced using two integers separated by a
:, in which case the entire inclusive range is referenced. For
example the following assigns the middle three rows of
#+NAME: example-table | 1 | a | | 2 | b | | 3 | c | | 4 | d | | 5 | 3 | #+BEGIN_SRC emacs-lisp :var data=example-table[1:3] data #+END_SRC #+RESULTS: | 2 | b | | 3 | c | | 4 | d |
Additionally, an empty index, or the single character
*, are both
interpreted to mean the entire range and as such are equivalent to
0:-1, as shown in the following example in which the entire first
column is referenced.
#+NAME: example-table | 1 | a | | 2 | b | | 3 | c | | 4 | d | #+BEGIN_SRC emacs-lisp :var data=example-table[,0] data #+END_SRC #+RESULTS: | 1 | 2 | 3 | 4 |
It is possible to index into the results of code blocks as well as tables. Any number of dimensions can be indexed. Dimensions are separated from one another by commas, as shown in the following example.
#+NAME: 3D #+BEGIN_SRC emacs-lisp '(((1 2 3) (4 5 6) (7 8 9)) ((10 11 12) (13 14 15) (16 17 18)) ((19 20 21) (22 23 24) (25 26 27))) #+END_SRC #+BEGIN_SRC emacs-lisp :var data=3D[1,,1] data #+END_SRC #+RESULTS: | 11 | 14 | 17 |
Emacs lisp code can be used to initialize variable values. When a variable
value starts with
` it will be
evaluated as Emacs Lisp and the result of the evaluation will be assigned as
the variable value. The following example demonstrates use of this
evaluation to reliably pass the file-name of the Org mode buffer to a code
block—note that evaluation of header arguments is guaranteed to take place
in the original Org mode file, while there is no such guarantee for
evaluation of the code block body.
#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both wc -w $filename #+END_SRC
Note that values read from tables and lists will not be evaluated as Emacs Lisp, as shown in the following example.
#+NAME: table | (a b c) | #+HEADERS: :var data=table[0,0] #+BEGIN_SRC perl $data #+END_SRC #+RESULTS: : (a b c)