path: root/third_party/nix/doc/manual/expressions/builtins.xml

<section xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      version="5.0"
      xml:id='ssec-builtins'>

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


  <varlistentry xml:id='builtin-abort'>
    <term><function>abort</function> <replaceable>s</replaceable></term>
    <term><function>builtins.abort</function> <replaceable>s</replaceable></term>

    <listitem><para>Abort Nix expression evaluation, print error
    message <replaceable>s</replaceable>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-add'>
    <term><function>builtins.add</function>
    <replaceable>e1</replaceable> <replaceable>e2</replaceable>
    </term>

    <listitem><para>Return the sum of the numbers
    <replaceable>e1</replaceable> and
    <replaceable>e2</replaceable>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-all'>
    <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 xml:id='builtin-any'>
    <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 xml:id='builtin-attrNames'>
    <term><function>builtins.attrNames</function>
    <replaceable>set</replaceable></term>

    <listitem><para>Return the names of the attributes in the set
    <replaceable>set</replaceable> in an alphabetically sorted list.  For instance,
    <literal>builtins.attrNames { y = 1; x = "foo"; }</literal>
    evaluates to <literal>[ "x" "y" ]</literal>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-attrValues'>
    <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>


  <varlistentry xml:id='builtin-baseNameOf'>
    <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>


  <varlistentry xml:id='builtin-bitAnd'>
    <term><function>builtins.bitAnd</function>
    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the bitwise AND of the integers
    <replaceable>e1</replaceable> and
    <replaceable>e2</replaceable>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-bitOr'>
    <term><function>builtins.bitOr</function>
    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the bitwise OR of the integers
    <replaceable>e1</replaceable> and
    <replaceable>e2</replaceable>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-bitXor'>
    <term><function>builtins.bitXor</function>
    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the bitwise XOR of the integers
    <replaceable>e1</replaceable> and
    <replaceable>e2</replaceable>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-builtins'>
    <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
    installations that don’t have the desired built-in
    function.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-compareVersions'>
    <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>


  <varlistentry xml:id='builtin-concatLists'>
    <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-concatStringsSep'>
    <term><function>builtins.concatStringsSep</function>
    <replaceable>separator</replaceable> <replaceable>list</replaceable></term>

    <listitem><para>Concatenate a list of strings with a separator
    between each element, e.g. <literal>concatStringsSep "/"
    ["usr" "local" "bin"] == "usr/local/bin"</literal></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>
  -->


  <!--
  <varlistentry><term><function>dependencyClosure</function></term>

    <listitem><para>TODO</para></listitem>

  </varlistentry>
  -->


  <varlistentry xml:id='builtin-deepSeq'>
    <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 it’s a list or set, its elements
    or attributes are also evaluated recursively.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-derivation'>
    <term><function>derivation</function>
    <replaceable>attrs</replaceable></term>
    <term><function>builtins.derivation</function>
    <replaceable>attrs</replaceable></term>

    <listitem><para><function>derivation</function> is described in
    <xref linkend='ssec-derivation' />.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-dirOf'>
    <term><function>dirOf</function> <replaceable>s</replaceable></term>
    <term><function>builtins.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>


  <varlistentry xml:id='builtin-div'>
    <term><function>builtins.div</function>
    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the quotient of the numbers
    <replaceable>e1</replaceable> and
    <replaceable>e2</replaceable>.</para></listitem>

  </varlistentry>

  <varlistentry xml:id='builtin-elem'>
    <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 xml:id='builtin-elemAt'>
    <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 if the index is out of
    bounds.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-fetchurl'>
    <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 xml:id='builtin-fetchTarball'>
    <term><function>fetchTarball</function>
    <replaceable>url</replaceable></term>
    <term><function>builtins.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>The fetched tarball is cached for a certain amount of time
    (1 hour by default) in <filename>~/.cache/nix/tarballs/</filename>.
    You can change the cache timeout either on the command line with
    <option>--option tarball-ttl <replaceable>number of seconds</replaceable></option> or
    in the Nix configuration file with this option:
    <literal><xref linkend="conf-tarball-ttl" /> <replaceable>number of seconds to cache</replaceable></literal>.
    </para>

    <para>Note that when obtaining the hash with <varname>nix-prefetch-url
    </varname> the option <varname>--unpack</varname> is required.
    </para>

    <para>This function can also verify the contents against a hash.
    In that case, the function takes a set instead of a URL. The set
    requires the attribute <varname>url</varname> and the attribute
    <varname>sha256</varname>, e.g.

<programlisting>
with import (fetchTarball {
  url = https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz;
  sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2";
}) {};

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>

  <varlistentry xml:id='builtin-fetchGit'>
    <term>
      <function>builtins.fetchGit</function>
      <replaceable>args</replaceable>
    </term>

    <listitem>
      <para>
        Fetch a path from git. <replaceable>args</replaceable> can be
        a URL, in which case the HEAD of the repo at that URL is
        fetched. Otherwise, it can be an attribute with the following
        attributes (all except <varname>url</varname> optional):
      </para>

      <variablelist>
        <varlistentry>
          <term>url</term>
          <listitem>
            <para>
              The URL of the repo.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>name</term>
          <listitem>
            <para>
              The name of the directory the repo should be exported to
              in the store. Defaults to the basename of the URL.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>rev</term>
          <listitem>
            <para>
              The git revision to fetch. Defaults to the tip of
              <varname>ref</varname>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>ref</term>
          <listitem>
            <para>
              The git ref to look for the requested revision under.
              This is often a branch or tag name. Defaults to
              <literal>HEAD</literal>.
            </para>

            <para>
              By default, the <varname>ref</varname> value is prefixed
              with <literal>refs/heads/</literal>. As of Nix 2.3.0
              Nix will not prefix <literal>refs/heads/</literal> if
              <varname>ref</varname> starts with <literal>refs/</literal>.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>

      <example>
        <title>Fetching a private repository over SSH</title>
        <programlisting>builtins.fetchGit {
  url = "git@github.com:my-secret/repository.git";
  ref = "master";
  rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
}</programlisting>
      </example>

      <example>
        <title>Fetching an arbitrary ref</title>
        <programlisting>builtins.fetchGit {
  url = "https://github.com/NixOS/nix.git";
  ref = "refs/heads/0.5-release";
}</programlisting>
      </example>

      <example>
        <title>Fetching a repository's specific commit on an arbitrary branch</title>
        <para>
          If the revision you're looking for is in the default branch
          of the git repository you don't strictly need to specify
          the branch name in the <varname>ref</varname> attribute.
        </para>
        <para>
          However, if the revision you're looking for is in a future
          branch for the non-default branch you will need to specify
          the the <varname>ref</varname> attribute as well.
        </para>
        <programlisting>builtins.fetchGit {
  url = "https://github.com/nixos/nix.git";
  rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
  ref = "1.11-maintenance";
}</programlisting>
        <note>
          <para>
            It is nice to always specify the branch which a revision
            belongs to. Without the branch being specified, the
            fetcher might fail if the default branch changes.
            Additionally, it can be confusing to try a commit from a
            non-default branch and see the fetch fail. If the branch
            is specified the fault is much more obvious.
          </para>
        </note>
      </example>

      <example>
        <title>Fetching a repository's specific commit on the default branch</title>
        <para>
          If the revision you're looking for is in the default branch
          of the git repository you may omit the
          <varname>ref</varname> attribute.
        </para>
        <programlisting>builtins.fetchGit {
  url = "https://github.com/nixos/nix.git";
  rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
}</programlisting>
      </example>

      <example>
        <title>Fetching a tag</title>
        <programlisting>builtins.fetchGit {
  url = "https://github.com/nixos/nix.git";
  ref = "refs/tags/1.9";
}</programlisting>
      </example>

      <example>
        <title>Fetching the latest version of a remote branch</title>
        <para>
          <function>builtins.fetchGit</function> can behave impurely
           fetch the latest version of a remote branch.
        </para>
        <note><para>Nix will refetch the branch in accordance to
        <xref linkend="conf-tarball-ttl" />.</para></note>
        <note><para>This behavior is disabled in
        <emphasis>Pure evaluation mode</emphasis>.</para></note>
        <programlisting>builtins.fetchGit {
  url = "ssh://git@github.com/nixos/nix.git";
  ref = "master";
}</programlisting>
      </example>
    </listitem>
  </varlistentry>


  <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 xml:id='builtin-filterSource'>
    <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). If you
      exclude a directory, the entire corresponding subtree of
      <replaceable>e2</replaceable> will be excluded.</para>

    </listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-foldl-prime'>
    <term><function>builtins.foldl’</function>
    <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 xml:id='builtin-functionArgs'>
    <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 xml:id='builtin-fromJSON'>
    <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>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-genList'>
    <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 xml:id='builtin-getAttr'>
    <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 doesn’t 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>


  <varlistentry xml:id='builtin-getEnv'>
    <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 doesn’t 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 user’s home
    directory.)</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-hasAttr'>
    <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 xml:id='builtin-hashString'>
    <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>,
    <literal>"sha256"</literal> or <literal>"sha512"</literal>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-hashFile'>
    <term><function>builtins.hashFile</function>
    <replaceable>type</replaceable> <replaceable>p</replaceable></term>

    <listitem><para>Return a base-16 representation of the
    cryptographic hash of the file at path <replaceable>p</replaceable>.  The
    hash algorithm specified by <replaceable>type</replaceable> must
    be one of <literal>"md5"</literal>, <literal>"sha1"</literal>,
    <literal>"sha256"</literal> or <literal>"sha512"</literal>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-head'>
    <term><function>builtins.head</function>
    <replaceable>list</replaceable></term>

    <listitem><para>Return the first element of a list; abort
    evaluation if the argument isn’t a list or is an empty list.  You
    can test whether a list is empty by comparing it with
    <literal>[]</literal>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-import'>
    <term><function>import</function>
    <replaceable>path</replaceable></term>
    <term><function>builtins.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 doesn’t exist or contains an incorrect Nix expression.
    <function>import</function> implements Nix’s 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>

    <note><para>Unlike some languages, <function>import</function> is a regular
    function in Nix. Paths using the angle bracket syntax (e.g., <function>
    import</function> <replaceable>&lt;foo&gt;</replaceable>) are normal path
    values (see <xref linkend='ssec-values' />).</para></note>

    <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

<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 doesn’t have to be called
    <varname>x</varname> in <filename>foo.nix</filename>; any name
    would work.)</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-intersectAttrs'>
    <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>

  </varlistentry>


  <varlistentry xml:id='builtin-isAttrs'>
    <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>


  <varlistentry xml:id='builtin-isList'>
    <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>


  <varlistentry xml:id='builtin-isFunction'><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>


  <varlistentry xml:id='builtin-isString'>
    <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>


  <varlistentry xml:id='builtin-isInt'>
    <term><function>builtins.isInt</function>
    <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
    <replaceable>e</replaceable> evaluates to an int, and
    <literal>false</literal> otherwise.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-isFloat'>
    <term><function>builtins.isFloat</function>
    <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
    <replaceable>e</replaceable> evaluates to a float, and
    <literal>false</literal> otherwise.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-isBool'>
    <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>

  <varlistentry><term><function>builtins.isPath</function>
  <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
    <replaceable>e</replaceable> evaluates to a path, and
    <literal>false</literal> otherwise.</para></listitem>

  </varlistentry>

  <varlistentry xml:id='builtin-isNull'>
    <term><function>isNull</function>
    <replaceable>e</replaceable></term>
    <term><function>builtins.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>

    </listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-length'>
    <term><function>builtins.length</function>
    <replaceable>e</replaceable></term>

    <listitem><para>Return the length of the list
    <replaceable>e</replaceable>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-lessThan'>
    <term><function>builtins.lessThan</function>
    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <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>
    does not evaluate to a number.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-listToAttrs'>
    <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>
builtins.listToAttrs
  [ { name = "foo"; value = 123; }
    { name = "bar"; value = 456; }
  ]
</programlisting>

    evaluates to

<programlisting>
{ foo = 123; bar = 456; }
</programlisting>

    </para></listitem>

  </varlistentry>

  <varlistentry xml:id='builtin-map'>
    <term><function>map</function>
    <replaceable>f</replaceable> <replaceable>list</replaceable></term>
    <term><function>builtins.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>
map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting>

    evaluates to <literal>[ "foobar" "foobla" "fooabc"
    ]</literal>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-match'>
    <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.

<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>.

    </para></listitem>
  </varlistentry>

  <varlistentry xml:id='builtin-mul'>
    <term><function>builtins.mul</function>
    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the product of the numbers
    <replaceable>e1</replaceable> and
    <replaceable>e2</replaceable>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-parseDrvName'>
    <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,
    <literal>builtins.parseDrvName "nix-0.12pre12876"</literal>
    returns <literal>{ name = "nix"; version = "0.12pre12876";
    }</literal>.</para></listitem>

  </varlistentry>

  <varlistentry xml:id='builtin-path'>
    <term>
      <function>builtins.path</function>
      <replaceable>args</replaceable>
    </term>

    <listitem>
      <para>
        An enrichment of the built-in path type, based on the attributes
        present in <replaceable>args</replaceable>. All are optional
        except <varname>path</varname>:
      </para>

      <variablelist>
        <varlistentry>
          <term>path</term>
          <listitem>
            <para>The underlying path.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>name</term>
          <listitem>
            <para>
              The name of the path when added to the store. This can
              used to reference paths that have nix-illegal characters
              in their names, like <literal>@</literal>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>filter</term>
          <listitem>
            <para>
              A function of the type expected by
              <link linkend="builtin-filterSource">builtins.filterSource</link>,
              with the same semantics.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>recursive</term>
          <listitem>
            <para>
              When <literal>false</literal>, when
              <varname>path</varname> is added to the store it is with a
              flat hash, rather than a hash of the NAR serialization of
              the file. Thus, <varname>path</varname> must refer to a
              regular file, not a directory. This allows similar
              behavior to <literal>fetchurl</literal>. Defaults to
              <literal>true</literal>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>sha256</term>
          <listitem>
            <para>
              When provided, this is the expected hash of the file at
              the path. Evaluation will fail if the hash is incorrect,
              and providing a hash allows
              <literal>builtins.path</literal> to be used even when the
              <literal>pure-eval</literal> nix config option is on.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
  </varlistentry>

  <varlistentry xml:id='builtin-pathExists'>
    <term><function>builtins.pathExists</function>
    <replaceable>path</replaceable></term>

    <listitem><para>Return <literal>true</literal> if the path
    <replaceable>path</replaceable> exists at evaluation time, and
    <literal>false</literal> otherwise.</para></listitem>

  </varlistentry>

  <varlistentry xml:id='builtin-placeholder'>
    <term><function>builtins.placeholder</function>
    <replaceable>output</replaceable></term>

    <listitem><para>Return a placeholder string for the specified
    <replaceable>output</replaceable> that will be substituted by the
    corresponding output path at build time. Typical outputs would be
    <literal>"out"</literal>, <literal>"bin"</literal> or
    <literal>"dev"</literal>.</para></listitem>
  </varlistentry>

  <varlistentry xml:id='builtin-readDir'>
    <term><function>builtins.readDir</function>
    <replaceable>path</replaceable></term>

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

    The possible values for the file type are
    <literal>"regular"</literal>, <literal>"directory"</literal>,
    <literal>"symlink"</literal> and
    <literal>"unknown"</literal>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-readFile'>
    <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>


  <varlistentry xml:id='builtin-removeAttrs'>
    <term><function>removeAttrs</function>
    <replaceable>set</replaceable> <replaceable>list</replaceable></term>
    <term><function>builtins.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 don’t have to
    exist in <replaceable>set</replaceable>. For instance,

<programlisting>
removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting>

    evaluates to <literal>{ y = 2; }</literal>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-replaceStrings'>
    <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>


  <varlistentry xml:id='builtin-seq'>
    <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>


  <varlistentry xml:id='builtin-sort'>
    <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 xml:id='builtin-split'>
    <term><function>builtins.split</function>
    <replaceable>regex</replaceable> <replaceable>str</replaceable></term>

    <listitem><para>Returns a list composed of non matched strings interleaved
    with the lists of 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
    of <replaceable>str</replaceable>. Each item in the lists of matched
    sequences is a regex group.

<programlisting>
builtins.split "(a)b" "abc"
</programlisting>

Evaluates to <literal>[ "" [ "a" ] "c" ]</literal>.

<programlisting>
builtins.split "([ac])" "abc"
</programlisting>

Evaluates to <literal>[ "" [ "a" ] "b" [ "c" ] "" ]</literal>.

<programlisting>
builtins.split "(a)|(c)" "abc"
</programlisting>

Evaluates to <literal>[ "" [ "a" null ] "b" [ null "c" ] "" ]</literal>.

<programlisting>
builtins.split "([[:upper:]]+)" "  FOO   "
</programlisting>

Evaluates to <literal>[ "  " [ "FOO" ] "   " ]</literal>.

    </para></listitem>
  </varlistentry>


  <varlistentry xml:id='builtin-splitVersion'>
    <term><function>builtins.splitVersion</function>
    <replaceable>s</replaceable></term>

    <listitem><para>Split a string representing a version into its
    components, by the same version splitting logic underlying the
    version comparison in <link linkend="ssec-version-comparisons">
    <command>nix-env -u</command></link>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-stringLength'>
    <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>


  <varlistentry xml:id='builtin-sub'>
    <term><function>builtins.sub</function>
    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the difference between the numbers
    <replaceable>e1</replaceable> and
    <replaceable>e2</replaceable>.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-substring'>
    <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>


  <varlistentry xml:id='builtin-tail'>
    <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 isn’t a list or is an empty
    list.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-throw'>
    <term><function>throw</function>
    <replaceable>s</replaceable></term>
    <term><function>builtins.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>


  <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>
{ stdenv, fetchurl, perl }:

stdenv.mkDerivation {
  name = "hello-2.1.1";

  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://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
    sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
  };
  inherit perl;
}</programlisting>

    </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>
    <para>It is also not possible to reference the result of a derivation.
    If you are using Nixpkgs, the <literal>writeTextFile</literal> function is able to
    do that.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-toJSON'>
    <term><function>builtins.toJSON</function> <replaceable>e</replaceable></term>

    <listitem><para>Return a string containing a JSON representation
    of <replaceable>e</replaceable>.  Strings, integers, floats, booleans,
    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 derivation’s output
    path.  Paths are copied to the store and represented as a JSON
    string of the resulting store path.</para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-toPath'>
    <term><function>builtins.toPath</function> <replaceable>s</replaceable></term>

    <listitem><para> DEPRECATED. Use <literal>/. + "/path"</literal>
    to convert a string into an absolute path. For relative paths,
    use <literal>./. + "/path"</literal>.
    </para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-toString'>
    <term><function>toString</function> <replaceable>e</replaceable></term>
    <term><function>builtins.toString</function> <replaceable>e</replaceable></term>

    <listitem><para>Convert the expression
    <replaceable>e</replaceable> to a string.
    <replaceable>e</replaceable> can be:</para>
    <itemizedlist>
      <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>
    </itemizedlist>
    </listitem>

  </varlistentry>


  <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 wouldn’t 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>

<programlisting><![CDATA[
{ stdenv, fetchurl, libxslt, jira, uberwiki }:

stdenv.mkDerivation (rec {
  name = "web-server";

  buildInputs = [ libxslt ];

  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>

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


  <varlistentry xml:id='builtin-trace'>
    <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>

  <varlistentry xml:id='builtin-tryEval'>
    <term><function>builtins.tryEval</function>
    <replaceable>e</replaceable></term>

    <listitem><para>Try to shallowly 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. Note that this
    doesn't evaluate <replaceable>e</replaceable> deeply, so
    <literal>let e = { x = throw ""; }; in (builtins.tryEval e).success
    </literal> will be <literal>true</literal>. Using <literal>builtins.deepSeq
    </literal> one can get the expected result: <literal>let e = { x = throw "";
    }; in (builtins.tryEval (builtins.deepSeq e e)).success</literal> will be
    <literal>false</literal>.
    </para></listitem>

  </varlistentry>


  <varlistentry xml:id='builtin-typeOf'>
    <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>,
    <literal>"set"</literal>, <literal>"list"</literal>,
    <literal>"lambda"</literal> or
    <literal>"float"</literal>.</para></listitem>

  </varlistentry>


</variablelist>


</section>