: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
References can also refer to tables, lists,
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
:var header argument.
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
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 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 |
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 ‘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
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.
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
:rownames. 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 |
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 code can set the values for variables. To differentiate a value
from lisp code, Org interprets any value starting with
` 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)