14.8.2.1 :var

Use :var for passing arguments to ‘src’ code blocks. The specifics of variables in ‘src’ code blocks vary by the source language and are covered in the language-specific documentation. The syntax for :var, however, is the same for all languages. This includes declaring a variable, and assigning a default value.

Arguments can take values as literals, or as references, or even as Emacs Lisp code (see Emacs Lisp evaluation of variables). References are names from the Org file from the lines #+NAME: or #+RESULTS:. References can also refer to tables, lists, #+BEGIN_EXAMPLE blocks, other types of ‘src’ code blocks, or the results of execution of ‘src’ code blocks.

For better performance, Org can cache results of evaluations. But caching comes with severe limitations (see cache).

Argument values are indexed like arrays (see Indexable variable values).

The following syntax is used to pass arguments to ‘src’ code blocks using the :var header argument.

:var name=assign

The assign is a literal value, such as a string ‘"string"’, a number ‘9’, a reference to a table, a list, a literal example, another code block (with or without arguments), or the results from evaluating a 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 only the top level list items are passed along. Nested list items are ignored.

#+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 ‘src’ code block name, as assigned by #+NAME:, followed by parentheses and optional arguments passed within the parentheses following the ‘src’ 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=2)
(* 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

Indexing variable values enables referencing portions of a variable. Indexes are 0 based with negative values counting backwards from the end. If an index is separated by ,s then each subsequent section will index as the next dimension. Note that this indexing occurs before other table-related header arguments are applied, such as :hlines, :colnames and :rownames. 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 |

To pick the entire range, use an empty index, or the single character *. 0:-1 does the same thing. Example below shows how to reference the first column only.

#+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 |

Index referencing can be used for tables and code blocks. Index referencing can handle any number of dimensions. Commas delimit multiple dimensions, as shown below.

#+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 set the values for variables. To differentiate a value from lisp code, Org interprets any value starting with (, [, ' or ` as Emacs Lisp code. The result of evaluating that code is then assigned to the value of that variable. The following example shows how to reliably query and pass file name of the Org mode buffer to a code block using headers. We need reliability here because the file’s name could change once the code in the block starts executing.

#+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 mistakenly evaluated as Emacs Lisp code, as illustrated in the following example.

#+NAME: table
| (a b c) |

#+HEADER: :var data=table[0,0]
#+BEGIN_SRC perl
  $data
#+END_SRC

#+RESULTS:
: (a b c)