org: var
14.8.2.1 ‘:var’
...............
The ‘: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 var.). References include anything in the Org mode file that
takes a ‘#+NAME:’ or ‘#+RESULTS:’ line: tables, lists, ‘#+BEGIN_EXAMPLE’
blocks, 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 var.).
The following syntax is used to pass arguments to code blocks using
the ‘:var’ header argument.
:var name=assign
The 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:
“table”
an Org mode table named with either a ‘#+NAME:’ line
#+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
“list”
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 |
“code block without arguments”
a code block name (from the example above), as assigned by
‘#+NAME:’, optionally followed by parentheses
#+BEGIN_SRC emacs-lisp :var length=table-length()
(* 2 length)
#+END_SRC
#+RESULTS:
: 8
“code block with arguments”
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
“literal example”
a literal example block named with a ‘#+NAME:’ line
#+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.
Indexable variable values
.........................
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 like ‘:hlines’, ‘:colnames’ and ‘:rownames’ are
applied. The following example assigns the last cell of the first row
the table ‘example-table’ to the variable ‘data’:
#+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
‘example-table’ to ‘data’.
#+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 evaluation of variables
..................................
Emacs lisp code can be used to initialize variable values. When a
variable value starts with ‘(’, ‘[’, ‘'’ or ‘`’ 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)
Info Catalog
org: Specific header arguments
org: Specific header arguments
org: results