lix/doc/manual/expressions/builtins.xml

1203 lines
40 KiB
XML
Raw Normal View History

<section xmlns="http://docbook.org/ns/docbook"
2014-08-27 16:41:09 +00:00
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='ssec-builtins'>
2014-08-27 16:41:09 +00:00
<title>Built-in Functions</title>
<para>This section lists the functions and constants built into the
Nix expression evaluator. (The built-in function
<function>derivation</function> is discussed above.) Some built-ins,
such as <function>derivation</function>, are always in scope of every
Nix expression; you can just access them right away. But to prevent
polluting the namespace too much, most built-ins are not in scope.
Instead, you can access them through the <varname>builtins</varname>
built-in value, which is a set that contains all built-in functions
and values. For instance, <function>derivation</function> is also
available as <function>builtins.derivation</function>.</para>
<variablelist>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>abort</function> <replaceable>s</replaceable></term>
<listitem><para>Abort Nix expression evaluation, print error
message <replaceable>s</replaceable>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.add</function>
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
2016-01-06 07:41:53 +00:00
<listitem><para>Return the sum of the numbers
<replaceable>e1</replaceable> and
<replaceable>e2</replaceable>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.all</function>
<replaceable>pred</replaceable> <replaceable>list</replaceable></term>
<listitem><para>Return <literal>true</literal> if the function
<replaceable>pred</replaceable> returns <literal>true</literal>
for all elements of <replaceable>list</replaceable>,
and <literal>false</literal> otherwise.</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.any</function>
<replaceable>pred</replaceable> <replaceable>list</replaceable></term>
<listitem><para>Return <literal>true</literal> if the function
<replaceable>pred</replaceable> returns <literal>true</literal>
for at least one element of <replaceable>list</replaceable>,
and <literal>false</literal> otherwise.</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.attrNames</function>
<replaceable>set</replaceable></term>
<listitem><para>Return the names of the attributes in the set
2017-05-10 16:38:17 +00:00
<replaceable>set</replaceable> in an alphabetically sorted list. For instance,
<literal>builtins.attrNames { y = 1; x = "foo"; }</literal>
2014-10-29 15:18:03 +00:00
evaluates to <literal>[ "x" "y" ]</literal>.</para></listitem>
2014-10-29 15:18:03 +00:00
</varlistentry>
2014-10-29 15:18:03 +00:00
<varlistentry><term><function>builtins.attrValues</function>
<replaceable>set</replaceable></term>
<listitem><para>Return the values of the attributes in the set
<replaceable>set</replaceable> in the order corresponding to the
sorted attribute names.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>baseNameOf</function> <replaceable>s</replaceable></term>
<listitem><para>Return the <emphasis>base name</emphasis> of the
string <replaceable>s</replaceable>, that is, everything following
the final slash in the string. This is similar to the GNU
<command>basename</command> command.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><varname>builtins</varname></term>
<listitem><para>The set <varname>builtins</varname> contains all
the built-in functions and values. You can use
<varname>builtins</varname> to test for the availability of
features in the Nix installation, e.g.,
<programlisting>
if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
This allows a Nix expression to fall back gracefully on older Nix
2009-04-14 13:03:27 +00:00
installations that dont have the desired built-in
function.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
2008-11-19 17:27:52 +00:00
<varlistentry><term><function>builtins.compareVersions</function>
<replaceable>s1</replaceable> <replaceable>s2</replaceable></term>
<listitem><para>Compare two strings representing versions and
return <literal>-1</literal> if version
<replaceable>s1</replaceable> is older than version
<replaceable>s2</replaceable>, <literal>0</literal> if they are
the same, and <literal>1</literal> if
<replaceable>s1</replaceable> is newer than
<replaceable>s2</replaceable>. The version comparison algorithm
is the same as the one used by <link
linkend="ssec-version-comparisons"><command>nix-env
-u</command></link>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.concatLists</function>
<replaceable>lists</replaceable></term>
<listitem><para>Concatenate a list of lists into a single
list.</para></listitem>
</varlistentry>
<varlistentry
xml:id='builtin-currentSystem'><term><varname>builtins.currentSystem</varname></term>
<listitem><para>The built-in value <varname>currentSystem</varname>
evaluates to the Nix platform identifier for the Nix installation
on which the expression is being evaluated, such as
<literal>"i686-linux"</literal> or
<literal>"x86_64-darwin"</literal>.</para></listitem>
</varlistentry>
<!--
<varlistentry><term><function>currentTime</function></term>
<listitem><para>The built-in value <varname>currentTime</varname>
returns the current system time in seconds since 00:00:00 1/1/1970
UTC. Due to the evaluation model of Nix expressions
(<emphasis>maximal laziness</emphasis>), it always yields the same
value within an execution of Nix.</para></listitem>
</varlistentry>
-->
2012-12-04 16:15:32 +00:00
<!--
<varlistentry><term><function>dependencyClosure</function></term>
<listitem><para>TODO</para></listitem>
</varlistentry>
-->
2012-12-04 16:15:32 +00:00
2014-10-29 15:18:03 +00:00
<varlistentry><term><function>builtins.deepSeq</function>
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
<listitem><para>This is like <literal>seq
<replaceable>e1</replaceable>
<replaceable>e2</replaceable></literal>, except that
<replaceable>e1</replaceable> is evaluated
<emphasis>deeply</emphasis>: if its a list or set, its elements
or attributes are also evaluated recursively.</para></listitem>
</varlistentry>
<varlistentry><term><function>derivation</function>
<replaceable>attrs</replaceable></term>
<listitem><para><function>derivation</function> is described in
<xref linkend='ssec-derivation' />.</para></listitem>
</varlistentry>
<varlistentry><term><function>dirOf</function> <replaceable>s</replaceable></term>
<listitem><para>Return the directory part of the string
<replaceable>s</replaceable>, that is, everything before the final
slash in the string. This is similar to the GNU
<command>dirname</command> command.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
2008-11-19 17:27:52 +00:00
<varlistentry><term><function>builtins.div</function>
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
2016-01-06 07:41:53 +00:00
<listitem><para>Return the quotient of the numbers
2008-11-19 17:27:52 +00:00
<replaceable>e1</replaceable> and
<replaceable>e2</replaceable>.</para></listitem>
</varlistentry>
2016-12-09 19:40:55 +00:00
<varlistentry><term><function>builtins.match</function>
<replaceable>regex</replaceable> <replaceable>str</replaceable></term>
<listitem><para>Returns a list if the <link
xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended
POSIX regular expression</link> <replaceable>regex</replaceable>
matches <replaceable>str</replaceable> precisely, otherwise returns
<literal>null</literal>. Each item in the list is a regex group.
2016-12-09 19:40:55 +00:00
<programlisting>
builtins.match "ab" "abc"
</programlisting>
Evaluates to <literal>null</literal>.
<programlisting>
builtins.match "abc" "abc"
</programlisting>
Evaluates to <literal>[ ]</literal>.
<programlisting>
builtins.match "a(b)(c)" "abc"
</programlisting>
Evaluates to <literal>[ "b" "c" ]</literal>.
<programlisting>
builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO "
</programlisting>
Evaluates to <literal>[ "foo" ]</literal>.
2016-12-09 19:40:55 +00:00
</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.elem</function>
<replaceable>x</replaceable> <replaceable>xs</replaceable></term>
<listitem><para>Return <literal>true</literal> if a value equal to
<replaceable>x</replaceable> occurs in the list
<replaceable>xs</replaceable>, and <literal>false</literal>
otherwise.</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.elemAt</function>
<replaceable>xs</replaceable> <replaceable>n</replaceable></term>
<listitem><para>Return element <replaceable>n</replaceable> from
the list <replaceable>xs</replaceable>. Elements are counted
starting from 0. A fatal error occurs in the index is out of
bounds.</para></listitem>
</varlistentry>
2015-06-01 13:14:44 +00:00
<varlistentry><term><function>builtins.fetchurl</function>
<replaceable>url</replaceable></term>
<listitem><para>Download the specified URL and return the path of
the downloaded file. This function is not available if <link
linkend="conf-restrict-eval">restricted evaluation mode</link> is
enabled.</para></listitem>
</varlistentry>
<varlistentry><term><function>fetchTarball</function>
<replaceable>url</replaceable></term>
<listitem><para>Download the specified URL, unpack it and return
the path of the unpacked tree. The file must be a tape archive
(<filename>.tar</filename>) compressed with
<literal>gzip</literal>, <literal>bzip2</literal> or
<literal>xz</literal>. The top-level path component of the files
in the tarball is removed, so it is best if the tarball contains a
single directory at top level. The typical use of the function is
to obtain external Nix expression dependencies, such as a
particular version of Nixpkgs, e.g.
<programlisting>
with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {};
stdenv.mkDerivation { … }
</programlisting>
</para>
<para>This function is not available if <link
linkend="conf-restrict-eval">restricted evaluation mode</link> is
enabled.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.filter</function>
<replaceable>f</replaceable> <replaceable>xs</replaceable></term>
<listitem><para>Return a list consisting of the elements of
<replaceable>xs</replaceable> for which the function
<replaceable>f</replaceable> returns
<literal>true</literal>.</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.filterSource</function>
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
<listitem>
<para>This function allows you to copy sources into the Nix
store while filtering certain files. For instance, suppose that
you want to use the directory <filename>source-dir</filename> as
an input to a Nix expression, e.g.
<programlisting>
stdenv.mkDerivation {
...
src = ./source-dir;
}
</programlisting>
However, if <filename>source-dir</filename> is a Subversion
working copy, then all those annoying <filename>.svn</filename>
subdirectories will also be copied to the store. Worse, the
contents of those directories may change a lot, causing lots of
spurious rebuilds. With <function>filterSource</function> you
can filter out the <filename>.svn</filename> directories:
<programlisting>
src = builtins.filterSource
(path: type: type != "directory" || baseNameOf path != ".svn")
./source-dir;
</programlisting>
</para>
<para>Thus, the first argument <replaceable>e1</replaceable>
must be a predicate function that is called for each regular
file, directory or symlink in the source tree
<replaceable>e2</replaceable>. If the function returns
<literal>true</literal>, the file is copied to the Nix store,
otherwise it is omitted. The function is called with two
arguments. The first is the full path of the file. The second
is a string that identifies the type of the file, which is
either <literal>"regular"</literal>,
<literal>"directory"</literal>, <literal>"symlink"</literal> or
<literal>"unknown"</literal> (for other kinds of files such as
device nodes or fifos — but note that those cannot be copied to
the Nix store, so if the predicate returns
<literal>true</literal> for them, the copy will fail).</para>
</listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.foldl</function>
2015-07-23 15:03:02 +00:00
<replaceable>op</replaceable> <replaceable>nul</replaceable> <replaceable>list</replaceable></term>
<listitem><para>Reduce a list by applying a binary operator, from
left to right, e.g. <literal>foldl op nul [x0 x1 x2 ...] = op (op
(op nul x0) x1) x2) ...</literal>. The operator is applied
strictly, i.e., its arguments are evaluated first. For example,
<literal>foldl (x: y: x + y) 0 [1 2 3]</literal> evaluates to
6.</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.functionArgs</function>
<replaceable>f</replaceable></term>
<listitem><para>
Return a set containing the names of the formal arguments expected
by the function <replaceable>f</replaceable>.
The value of each attribute is a Boolean denoting whether the corresponding
argument has a default value. For instance,
<literal>functionArgs ({ x, y ? 123}: ...) = { x = false; y = true; }</literal>.
</para>
<para>"Formal argument" here refers to the attributes pattern-matched by
the function. Plain lambdas are not included, e.g.
<literal>functionArgs (x: ...) = { }</literal>.
</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.fromJSON</function> <replaceable>e</replaceable></term>
<listitem><para>Convert a JSON string to a Nix
value. For example,
<programlisting>
builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''
</programlisting>
returns the value <literal>{ x = [ 1 2 3 ]; y = null;
}</literal>. Floating point numbers are not
supported.</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.genList</function>
<replaceable>generator</replaceable> <replaceable>length</replaceable></term>
<listitem><para>Generate list of size
<replaceable>length</replaceable>, with each element
<replaceable>i></replaceable> equal to the value returned by
<replaceable>generator</replaceable> <literal>i</literal>. For
example,
<programlisting>
builtins.genList (x: x * x) 5
</programlisting>
returns the list <literal>[ 0 1 4 9 16 ]</literal>.</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.getAttr</function>
<replaceable>s</replaceable> <replaceable>set</replaceable></term>
<listitem><para><function>getAttr</function> returns the attribute
named <replaceable>s</replaceable> from
<replaceable>set</replaceable>. Evaluation aborts if the
attribute doesnt exist. This is a dynamic version of the
<literal>.</literal> operator, since <replaceable>s</replaceable>
is an expression rather than an identifier.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.getEnv</function>
<replaceable>s</replaceable></term>
<listitem><para><function>getEnv</function> returns the value of
the environment variable <replaceable>s</replaceable>, or an empty
string if the variable doesnt exist. This function should be
used with care, as it can introduce all sorts of nasty environment
dependencies in your Nix expression.</para>
<para><function>getEnv</function> is used in Nix Packages to
locate the file <filename>~/.nixpkgs/config.nix</filename>, which
contains user-local settings for Nix Packages. (That is, it does
a <literal>getEnv "HOME"</literal> to locate the users home
directory.)</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.hasAttr</function>
<replaceable>s</replaceable> <replaceable>set</replaceable></term>
<listitem><para><function>hasAttr</function> returns
<literal>true</literal> if <replaceable>set</replaceable> has an
attribute named <replaceable>s</replaceable>, and
<literal>false</literal> otherwise. This is a dynamic version of
the <literal>?</literal> operator, since
<replaceable>s</replaceable> is an expression rather than an
identifier.</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.hashString</function>
<replaceable>type</replaceable> <replaceable>s</replaceable></term>
<listitem><para>Return a base-16 representation of the
cryptographic hash of string <replaceable>s</replaceable>. The
hash algorithm specified by <replaceable>type</replaceable> must
be one of <literal>"md5"</literal>, <literal>"sha1"</literal> or
<literal>"sha256"</literal>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.head</function>
<replaceable>list</replaceable></term>
<listitem><para>Return the first element of a list; abort
evaluation if the argument isnt a list or is an empty list. You
can test whether a list is empty by comparing it with
<literal>[]</literal>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>import</function>
<replaceable>path</replaceable></term>
<listitem><para>Load, parse and return the Nix expression in the
file <replaceable>path</replaceable>. If <replaceable>path
</replaceable> is a directory, the file <filename>default.nix
</filename> in that directory is loaded. Evaluation aborts if the
file doesnt exist or contains an incorrect Nix expression.
<function>import</function> implements Nixs module system: you
can put any Nix expression (such as a set or a function) in a
separate file, and use it from Nix expressions in other
files.</para>
<para>A Nix expression loaded by <function>import</function> must
not contain any <emphasis>free variables</emphasis> (identifiers
that are not defined in the Nix expression itself and are not
built-in). Therefore, it cannot refer to variables that are in
scope at the call site. For instance, if you have a calling
expression
2012-12-04 16:15:32 +00:00
<programlisting>
rec {
x = 123;
y = import ./foo.nix;
}</programlisting>
then the following <filename>foo.nix</filename> will give an
error:
<programlisting>
x + 456</programlisting>
since <varname>x</varname> is not in scope in
<filename>foo.nix</filename>. If you want <varname>x</varname>
to be available in <filename>foo.nix</filename>, you should pass
it as a function argument:
<programlisting>
rec {
x = 123;
y = import ./foo.nix x;
}</programlisting>
and
<programlisting>
x: x + 456</programlisting>
(The function argument doesnt have to be called
<varname>x</varname> in <filename>foo.nix</filename>; any name
would work.)</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
2009-11-04 16:52:35 +00:00
<varlistentry><term><function>builtins.intersectAttrs</function>
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
<listitem><para>Return a set consisting of the attributes in the
set <replaceable>e2</replaceable> that also exist in the set
<replaceable>e1</replaceable>.</para></listitem>
2009-11-04 16:52:35 +00:00
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.isAttrs</function>
<replaceable>e</replaceable></term>
<listitem><para>Return <literal>true</literal> if
<replaceable>e</replaceable> evaluates to a set, and
<literal>false</literal> otherwise.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.isList</function>
<replaceable>e</replaceable></term>
<listitem><para>Return <literal>true</literal> if
<replaceable>e</replaceable> evaluates to a list, and
<literal>false</literal> otherwise.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.isFunction</function>
<replaceable>e</replaceable></term>
<listitem><para>Return <literal>true</literal> if
<replaceable>e</replaceable> evaluates to a function, and
<literal>false</literal> otherwise.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
2009-02-05 19:35:44 +00:00
<varlistentry><term><function>builtins.isString</function>
<replaceable>e</replaceable></term>
<listitem><para>Return <literal>true</literal> if
<replaceable>e</replaceable> evaluates to a string, and
<literal>false</literal> otherwise.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
2009-02-05 19:35:44 +00:00
<varlistentry><term><function>builtins.isInt</function>
<replaceable>e</replaceable></term>
<listitem><para>Return <literal>true</literal> if
<replaceable>e</replaceable> evaluates to an int, and
2009-02-05 19:35:44 +00:00
<literal>false</literal> otherwise.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
2009-02-05 19:35:44 +00:00
<varlistentry><term><function>builtins.isBool</function>
<replaceable>e</replaceable></term>
<listitem><para>Return <literal>true</literal> if
<replaceable>e</replaceable> evaluates to a bool, and
<literal>false</literal> otherwise.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>isNull</function>
<replaceable>e</replaceable></term>
<listitem><para>Return <literal>true</literal> if
<replaceable>e</replaceable> evaluates to <literal>null</literal>,
and <literal>false</literal> otherwise.</para>
<warning><para>This function is <emphasis>deprecated</emphasis>;
just write <literal>e == null</literal> instead.</para></warning>
2012-12-04 16:15:32 +00:00
</listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
2008-11-19 17:27:52 +00:00
<varlistentry><term><function>builtins.length</function>
<replaceable>e</replaceable></term>
<listitem><para>Return the length of the list
<replaceable>e</replaceable>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.lessThan</function>
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
2016-01-06 07:41:53 +00:00
<listitem><para>Return <literal>true</literal> if the number
<replaceable>e1</replaceable> is less than the number
<replaceable>e2</replaceable>, and <literal>false</literal>
otherwise. Evaluation aborts if either
<replaceable>e1</replaceable> or <replaceable>e2</replaceable>
2016-01-06 07:41:53 +00:00
does not evaluate to a number.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.listToAttrs</function>
<replaceable>e</replaceable></term>
<listitem><para>Construct a set from a list specifying the names
and values of each attribute. Each element of the list should be
a set consisting of a string-valued attribute
<varname>name</varname> specifying the name of the attribute, and
an attribute <varname>value</varname> specifying its value.
Example:
<programlisting>
2011-12-30 17:39:03 +00:00
builtins.listToAttrs
[ { name = "foo"; value = 123; }
{ name = "bar"; value = 456; }
]
</programlisting>
evaluates to
<programlisting>
{ foo = 123; bar = 456; }
</programlisting>
</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>map</function>
<replaceable>f</replaceable> <replaceable>list</replaceable></term>
<listitem><para>Apply the function <replaceable>f</replaceable> to
each element in the list <replaceable>list</replaceable>. For
example,
<programlisting>
2011-12-30 17:39:03 +00:00
map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting>
2011-12-30 17:39:03 +00:00
evaluates to <literal>[ "foobar" "foobla" "fooabc"
]</literal>.</para></listitem>
2012-12-04 16:15:32 +00:00
</varlistentry>
2012-12-04 16:15:32 +00:00
2008-11-19 17:27:52 +00:00
<varlistentry><term><function>builtins.mul</function>
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
2016-01-06 07:41:53 +00:00
<listitem><para>Return the product of the numbers
2008-11-19 17:27:52 +00:00
<replaceable>e1</replaceable> and
<replaceable>e2</replaceable>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
2008-11-19 17:27:52 +00:00
<varlistentry><term><function>builtins.parseDrvName</function>
<replaceable>s</replaceable></term>
<listitem><para>Split the string <replaceable>s</replaceable> into
a package name and version. The package name is everything up to
but not including the first dash followed by a digit, and the
version is everything following that dash. The result is returned
in a set <literal>{ name, version }</literal>. Thus,
2008-11-19 17:27:52 +00:00
<literal>builtins.parseDrvName "nix-0.12pre12876"</literal>
2011-12-30 17:39:03 +00:00
returns <literal>{ name = "nix"; version = "0.12pre12876";
}</literal>.</para></listitem>
2008-11-19 17:27:52 +00:00
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.pathExists</function>
<replaceable>path</replaceable></term>
<listitem><para>Return <literal>true</literal> if the path
<replaceable>path</replaceable> exists, and
<literal>false</literal> otherwise. One application of this
function is to conditionally include a Nix expression containing
user configuration:
<programlisting>
let
fileName = builtins.getEnv "CONFIG_FILE";
config =
if fileName != "" &amp;&amp; builtins.pathExists (builtins.toPath fileName)
then import (builtins.toPath fileName)
else { someSetting = false; }; <lineannotation># default configuration</lineannotation>
in config.someSetting</programlisting>
(Note that <envar>CONFIG_FILE</envar> must be an absolute path for
this to work.)</para></listitem>
</varlistentry>
2014-10-29 15:18:03 +00:00
<varlistentry><term><function>builtins.readDir</function>
<replaceable>path</replaceable></term>
2014-10-29 15:18:03 +00:00
<listitem><para>Return the contents of the directory
<replaceable>path</replaceable> as a set mapping directory entries
to the corresponding file type. For instance, if directory
<filename>A</filename> contains a regular file
<filename>B</filename> and another directory
<filename>C</filename>, then <literal>builtins.readDir
./A</literal> will return the set
<programlisting>
{ B = "regular"; C = "directory"; }</programlisting>
2014-10-29 15:18:03 +00:00
The possible values for the file type are
<literal>"regular"</literal>, <literal>"directory"</literal>,
<literal>"symlink"</literal> and
<literal>"unknown"</literal>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.readFile</function>
<replaceable>path</replaceable></term>
<listitem><para>Return the contents of the file
<replaceable>path</replaceable> as a string.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>removeAttrs</function>
<replaceable>set</replaceable> <replaceable>list</replaceable></term>
<listitem><para>Remove the attributes listed in
<replaceable>list</replaceable> from
<replaceable>set</replaceable>. The attributes dont have to
exist in <replaceable>set</replaceable>. For instance,
2014-10-29 15:18:03 +00:00
<programlisting>
removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting>
2011-12-30 17:39:03 +00:00
evaluates to <literal>{ y = 2; }</literal>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.replaceStrings</function>
<replaceable>from</replaceable> <replaceable>to</replaceable> <replaceable>s</replaceable></term>
<listitem><para>Given string <replaceable>s</replaceable>, replace
every occurrence of the strings in <replaceable>from</replaceable>
with the corresponding string in
<replaceable>to</replaceable>. For example,
<programlisting>
builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar"
</programlisting>
evaluates to <literal>"fabir"</literal>.</para></listitem>
</varlistentry>
2014-10-29 15:18:03 +00:00
<varlistentry><term><function>builtins.seq</function>
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
<listitem><para>Evaluate <replaceable>e1</replaceable>, then
evaluate and return <replaceable>e2</replaceable>. This ensures
that a computation is strict in the value of
<replaceable>e1</replaceable>.</para></listitem>
</varlistentry>
2015-07-28 16:39:00 +00:00
<varlistentry><term><function>builtins.sort</function>
<replaceable>comparator</replaceable> <replaceable>list</replaceable></term>
<listitem><para>Return <replaceable>list</replaceable> in sorted
order. It repeatedly calls the function
<replaceable>comparator</replaceable> with two elements. The
comparator should return <literal>true</literal> if the first
element is less than the second, and <literal>false</literal>
otherwise. For example,
<programlisting>
builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ]
</programlisting>
produces the list <literal>[ 42 77 147 249 483 526
]</literal>.</para>
<para>This is a stable sort: it preserves the relative order of
elements deemed equal by the comparator.</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.stringLength</function>
<replaceable>e</replaceable></term>
<listitem><para>Return the length of the string
<replaceable>e</replaceable>. If <replaceable>e</replaceable> is
not a string, evaluation is aborted.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.sub</function>
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
2016-01-06 07:41:53 +00:00
<listitem><para>Return the difference between the numbers
<replaceable>e1</replaceable> and
<replaceable>e2</replaceable>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.substring</function>
<replaceable>start</replaceable> <replaceable>len</replaceable>
<replaceable>s</replaceable></term>
<listitem><para>Return the substring of
<replaceable>s</replaceable> from character position
<replaceable>start</replaceable> (zero-based) up to but not
including <replaceable>start + len</replaceable>. If
<replaceable>start</replaceable> is greater than the length of the
string, an empty string is returned, and if <replaceable>start +
len</replaceable> lies beyond the end of the string, only the
substring up to the end of the string is returned.
<replaceable>start</replaceable> must be
non-negative. For example,
<programlisting>
builtins.substring 0 3 "nixos"
</programlisting>
evaluates to <literal>"nix"</literal>.
</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.tail</function>
<replaceable>list</replaceable></term>
<listitem><para>Return the second to last elements of a list;
abort evaluation if the argument isnt a list or is an empty
list.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>throw</function>
<replaceable>s</replaceable></term>
<listitem><para>Throw an error message
<replaceable>s</replaceable>. This usually aborts Nix expression
evaluation, but in <command>nix-env -qa</command> and other
commands that try to evaluate a set of derivations to get
information about those derivations, a derivation that throws an
error is silently skipped (which is not the case for
<function>abort</function>).</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry
xml:id='builtin-toFile'><term><function>builtins.toFile</function>
<replaceable>name</replaceable> <replaceable>s</replaceable></term>
<listitem><para>Store the string <replaceable>s</replaceable> in a
file in the Nix store and return its path. The file has suffix
<replaceable>name</replaceable>. This file can be used as an
input to derivations. One application is to write builders
“inline”. For instance, the following Nix expression combines
<xref linkend='ex-hello-nix' /> and <xref
linkend='ex-hello-builder' /> into one file:
<programlisting>
2011-12-30 17:39:03 +00:00
{ stdenv, fetchurl, perl }:
stdenv.mkDerivation {
name = "hello-2.1.1";
2012-12-04 16:15:32 +00:00
builder = builtins.toFile "builder.sh" "
source $stdenv/setup
PATH=$perl/bin:$PATH
tar xvfz $src
cd hello-*
./configure --prefix=$out
make
make install
";
src = fetchurl {
url = http://nix.cs.uu.nl/dist/tarballs/hello-2.1.1.tar.gz;
md5 = "70c9ccf9fac07f762c24f2df2290784d";
};
inherit perl;
}</programlisting>
2012-12-04 16:15:32 +00:00
</para>
<para>It is even possible for one file to refer to another, e.g.,
<programlisting>
builder = let
configFile = builtins.toFile "foo.conf" "
# This is some dummy configuration file.
<replaceable>...</replaceable>
";
in builtins.toFile "builder.sh" "
source $stdenv/setup
<replaceable>...</replaceable>
cp ${configFile} $out/etc/foo.conf
";</programlisting>
Note that <literal>${configFile}</literal> is an antiquotation
(see <xref linkend='ssec-values' />), so the result of the
expression <literal>configFile</literal> (i.e., a path like
<filename>/nix/store/m7p7jfny445k...-foo.conf</filename>) will be
spliced into the resulting string.</para>
<para>It is however <emphasis>not</emphasis> allowed to have files
mutually referring to each other, like so:
<programlisting>
let
foo = builtins.toFile "foo" "...${bar}...";
bar = builtins.toFile "bar" "...${foo}...";
in foo</programlisting>
This is not allowed because it would cause a cyclic dependency in
the computation of the cryptographic hashes for
<varname>foo</varname> and <varname>bar</varname>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
2013-11-18 23:03:11 +00:00
<varlistentry><term><function>builtins.toJSON</function> <replaceable>e</replaceable></term>
<listitem><para>Return a string containing a JSON representation
2016-01-06 07:41:53 +00:00
of <replaceable>e</replaceable>. Strings, integers, floats, booleans,
2013-11-18 23:03:11 +00:00
nulls and lists are mapped to their JSON equivalents. Sets
(except derivations) are represented as objects. Derivations are
translated to a JSON string containing the derivations output
path. Paths are copied to the store and represented as a JSON
string of the resulting store path.</para></listitem>
</varlistentry>
<varlistentry><term><function>builtins.toPath</function> <replaceable>s</replaceable></term>
<listitem><para>Convert the string value
<replaceable>s</replaceable> into a path value. The string
<replaceable>s</replaceable> must represent an absolute path
(i.e., must start with <literal>/</literal>). The path need not
exist. The resulting path is canonicalised, e.g.,
<literal>builtins.toPath "//foo/xyzzy/../bar/"</literal> returns
<literal>/foo/bar</literal>.</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>toString</function> <replaceable>e</replaceable></term>
<listitem><para>Convert the expression
<replaceable>e</replaceable> to a string.
2017-02-21 12:04:31 +00:00
<replaceable>e</replaceable> can be:</para>
2017-02-19 18:54:18 +00:00
<itemizedlist>
2017-02-21 12:04:31 +00:00
<listitem><para>A string (in which case the string is returned unmodified).</para></listitem>
<listitem><para>A path (e.g., <literal>toString /foo/bar</literal> yields <literal>"/foo/bar"</literal>.</para></listitem>
<listitem><para>A set containing <literal>{ __toString = self: ...; }</literal>.</para></listitem>
<listitem><para>An integer.</para></listitem>
<listitem><para>A list, in which case the string representations of its elements are joined with spaces.</para></listitem>
<listitem><para>A Boolean (<literal>false</literal> yields <literal>""</literal>, <literal>true</literal> yields <literal>"1"</literal>.</para></listitem>
<listitem><para><literal>null</literal>, which yields the empty string.</para></listitem>
2017-02-19 18:54:18 +00:00
</itemizedlist>
</listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry xml:id='builtin-toXML'><term><function>builtins.toXML</function> <replaceable>e</replaceable></term>
<listitem><para>Return a string containing an XML representation
of <replaceable>e</replaceable>. The main application for
<function>toXML</function> is to communicate information with the
builder in a more structured format than plain environment
variables.</para>
<!-- TODO: more formally describe the schema of the XML
representation -->
<para><xref linkend='ex-toxml' /> shows an example where this is
the case. The builder is supposed to generate the configuration
file for a <link xlink:href='http://jetty.mortbay.org/'>Jetty
servlet container</link>. A servlet container contains a number
of servlets (<filename>*.war</filename> files) each exported under
a specific URI prefix. So the servlet configuration is a list of
sets containing the <varname>path</varname> and
<varname>war</varname> of the servlet (<xref
linkend='ex-toxml-co-servlets' />). This kind of information is
difficult to communicate with the normal method of passing
information through an environment variable, which just
concatenates everything together into a string (which might just
work in this case, but wouldnt work if fields are optional or
contain lists themselves). Instead the Nix expression is
converted to an XML representation with
<function>toXML</function>, which is unambiguous and can easily be
processed with the appropriate tools. For instance, in the
example an XSLT stylesheet (<xref linkend='ex-toxml-co-stylesheet'
/>) is applied to it (<xref linkend='ex-toxml-co-apply' />) to
generate the XML configuration file for the Jetty server. The XML
representation produced from <xref linkend='ex-toxml-co-servlets'
/> by <function>toXML</function> is shown in <xref
linkend='ex-toxml-result' />.</para>
<para>Note that <xref linkend='ex-toxml' /> uses the <function
linkend='builtin-toFile'>toFile</function> built-in to write the
builder and the stylesheet “inline” in the Nix expression. The
path of the stylesheet is spliced into the builder at
<literal>xsltproc ${stylesheet}
<replaceable>...</replaceable></literal>.</para>
<example xml:id='ex-toxml'><title>Passing information to a builder
using <function>toXML</function></title>
2012-12-04 16:15:32 +00:00
<programlisting><![CDATA[
2011-12-30 17:39:03 +00:00
{ stdenv, fetchurl, libxslt, jira, uberwiki }:
stdenv.mkDerivation (rec {
name = "web-server";
2011-12-30 17:39:03 +00:00
buildInputs = [ libxslt ];
2012-12-04 16:15:32 +00:00
builder = builtins.toFile "builder.sh" "
source $stdenv/setup
mkdir $out
echo $servlets | xsltproc ${stylesheet} - > $out/server-conf.xml]]> <co xml:id='ex-toxml-co-apply' /> <![CDATA[
";
stylesheet = builtins.toFile "stylesheet.xsl"]]> <co xml:id='ex-toxml-co-stylesheet' /> <![CDATA[
"<?xml version='1.0' encoding='UTF-8'?>
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>
<xsl:template match='/'>
<Configure>
<xsl:for-each select='/expr/list/attrs'>
<Call name='addWebApplication'>
<Arg><xsl:value-of select=\"attr[@name = 'path']/string/@value\" /></Arg>
<Arg><xsl:value-of select=\"attr[@name = 'war']/path/@value\" /></Arg>
</Call>
</xsl:for-each>
</Configure>
</xsl:template>
</xsl:stylesheet>
";
servlets = builtins.toXML []]> <co xml:id='ex-toxml-co-servlets' /> <![CDATA[
{ path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; }
{ path = "/wiki"; war = uberwiki + "/uberwiki.war"; }
];
})]]></programlisting>
</example>
<example xml:id='ex-toxml-result'><title>XML representation produced by
<function>toXML</function></title>
2012-12-04 16:15:32 +00:00
<programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?>
<expr>
<list>
<attrs>
<attr name="path">
<string value="/bugtracker" />
</attr>
<attr name="war">
<path value="/nix/store/d1jh9pasa7k2...-jira/lib/atlassian-jira.war" />
</attr>
</attrs>
<attrs>
<attr name="path">
<string value="/wiki" />
</attr>
<attr name="war">
<path value="/nix/store/y6423b1yi4sx...-uberwiki/uberwiki.war" />
</attr>
</attrs>
</list>
</expr>]]></programlisting>
</example>
</listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
<varlistentry><term><function>builtins.trace</function>
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
<listitem><para>Evaluate <replaceable>e1</replaceable> and print its
abstract syntax representation on standard error. Then return
<replaceable>e2</replaceable>. This function is useful for
debugging.</para></listitem>
</varlistentry>
2017-04-17 09:33:53 +00:00
<varlistentry><term><function>builtins.tryEval</function>
<replaceable>e</replaceable></term>
<listitem><para>Try to evaluate <replaceable>e</replaceable>.
Return a set containing the attributes <literal>success</literal>
(<literal>true</literal> if <replaceable>e</replaceable> evaluated
successfully, <literal>false</literal> if an error was thrown) and
<literal>value</literal>, equalling <replaceable>e</replaceable>
if successful and <literal>false</literal> otherwise.
</para></listitem>
</varlistentry>
2012-12-04 16:15:32 +00:00
2013-10-24 00:56:00 +00:00
<varlistentry><term><function>builtins.typeOf</function>
<replaceable>e</replaceable></term>
<listitem><para>Return a string representing the type of the value
<replaceable>e</replaceable>, namely <literal>"int"</literal>,
<literal>"bool"</literal>, <literal>"string"</literal>,
<literal>"path"</literal>, <literal>"null"</literal>,
2013-10-24 20:05:58 +00:00
<literal>"set"</literal>, <literal>"list"</literal> or
2013-10-24 00:56:00 +00:00
<literal>"lambda"</literal>.</para></listitem>
</varlistentry>
</variablelist>
</section>