Nix (builtins) & Nixpkgs (lib) Functions

Nix Builtin Functions

builtins.abort

s

Abort Nix expression evaluation and print the error message s.

builtins.add

e1, e2

Return the sum of the numbers e1 and e2.

builtins.all

pred, list

Return true if the function pred returns true for all elements of list, and false otherwise.

builtins.any

pred, list

Return true if the function pred returns true for at least one element of list, and false otherwise.

builtins.attrNames

set

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

builtins.attrValues

set

Return the values of the attributes in the set set in the order corresponding to the sorted attribute names.

builtins.baseNameOf

s

Return the base name of the string s, that is, everything following the final slash in the string. This is similar to the GNU basename command.

builtins.bitAnd

e1, e2

Return the bitwise AND of the integers e1 and e2.

builtins.bitOr

e1, e2

Return the bitwise OR of the integers e1 and e2.

builtins.bitXor

e1, e2

Return the bitwise XOR of the integers e1 and e2.

builtins.catAttrs

attr, list

Collect each attribute named attr from a list of attribute sets. Attrsets that don’t contain the named attribute are ignored. For example,

builtins.catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]

evaluates to [1 2].

builtins.ceil

double

Converts an IEEE-754 double-precision floating-point number (double) to the next higher integer.

If the datatype is neither an integer nor a “float”, an evaluation error will be thrown.

builtins.compareVersions

s1, s2

Compare two strings representing versions and return -1 if version s1 is older than version s2, 0 if they are the same, and 1 if s1 is newer than s2. The version comparison algorithm is the same as the one used by nix-env -u.

builtins.concatLists

lists

Concatenate a list of lists into a single list.

builtins.concatMap

f, list

This function is equivalent to builtins.concatLists (map f list) but is more efficient.

builtins.concatStringsSep

separator, list

Concatenate a list of strings with a separator between each element, e.g. concatStringsSep "/" ["usr" "local" "bin"] == "usr/local/bin".

builtins.deepSeq

e1, e2

This is like seq e1 e2, except that e1 is evaluated deeply: if it’s a list or set, its elements or attributes are also evaluated recursively.

builtins.dirOf

s

Return the directory part of the string s, that is, everything before the final slash in the string. This is similar to the GNU dirname command.

builtins.div

e1, e2

Return the quotient of the numbers e1 and e2.

builtins.elem

x, xs

Return true if a value equal to x occurs in the list xs, and false otherwise.

builtins.elemAt

xs, n

Return element n from the list xs. Elements are counted starting from 0. A fatal error occurs if the index is out of bounds.

builtins.fetchClosure

args

Fetch a Nix store closure from a binary cache, rewriting it into content-addressed form. For example,

builtins.fetchClosure {
  fromStore = "https://cache.nixos.org";
  fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
  toPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
}

fetches /nix/store/r2jd... from the specified binary cache, and rewrites it into the content-addressed store path /nix/store/ldbh....

If fromPath is already content-addressed, or if you are allowing impure evaluation (--impure), then toPath may be omitted.

To find out the correct value for toPath given a fromPath, you can use nix store make-content-addressed:

# nix store make-content-addressed --from https://cache.nixos.org /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1
rewrote '/nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1' to '/nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1'

This function is similar to builtins.storePath in that it allows you to use a previously built store path in a Nix expression. However, it is more reproducible because it requires specifying a binary cache from which the path can be fetched. Also, requiring a content-addressed final store path avoids the need for users to configure binary cache public keys.

This function is only available if you enable the experimental feature fetch-closure.

builtins.fetchGit

args

Fetch a path from git. args 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 url optional):

Here are some examples of how to use fetchGit.

builtins.fetchTarball

args

Download the specified URL, unpack it and return the path of the unpacked tree. The file must be a tape archive (.tar) compressed with gzip, bzip2 or xz. 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.

with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz) {};

stdenv.mkDerivation {}

The fetched tarball is cached for a certain amount of time (1 hour by default) in ~/.cache/nix/tarballs/. You can change the cache timeout either on the command line with --tarball-ttl number-of-seconds or in the Nix configuration file by adding the line tarball-ttl = number-of-seconds.

Note that when obtaining the hash with nix-prefetch-url the option --unpack is required.

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 url and the attribute sha256, e.g.

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

stdenv.mkDerivation {}

This function is not available if restricted evaluation mode is enabled.

builtins.fetchurl

url

Download the specified URL and return the path of the downloaded file. This function is not available if restricted evaluation mode is enabled.

builtins.filter

f, list

Return a list consisting of the elements of list for which the function f returns true.

builtins.filterSource

e1, e2

Warning

filterSource should not be used to filter store paths. Since filterSource uses the name of the input directory while naming the output directory, doing so will produce a directory name in the form of <hash2>-<hash>-<name>, where <hash>-<name> is the name of the input directory. Since <hash> depends on the unfiltered directory, the name of the output directory will indirectly depend on files that are filtered out by the function. This will trigger a rebuild even when a filtered out file is changed. Use builtins.path instead, which allows specifying the name of the output directory.

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 source-dir as an input to a Nix expression, e.g.

stdenv.mkDerivation {
  ...
  src = ./source-dir;
}

However, if source-dir is a Subversion working copy, then all those annoying .svn subdirectories will also be copied to the store. Worse, the contents of those directories may change a lot, causing lots of spurious rebuilds. With filterSource you can filter out the .svn directories:

src = builtins.filterSource
  (path: type: type != "directory" || baseNameOf path != ".svn")
  ./source-dir;

Thus, the first argument e1 must be a predicate function that is called for each regular file, directory or symlink in the source tree e2. If the function returns true, 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 "regular", "directory", "symlink" or "unknown" (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 true for them, the copy will fail). If you exclude a directory, the entire corresponding subtree of e2 will be excluded.

builtins.floor

double

Converts an IEEE-754 double-precision floating-point number (double) to the next lower integer.

If the datatype is neither an integer nor a “float”, an evaluation error will be thrown.

builtins.foldl’

op, nul, list

Reduce a list by applying a binary operator, from left to right, e.g. foldl' op nul [x0 x1 x2 ...] = op (op (op nul x0) x1) x2) .... The operator is applied strictly, i.e., its arguments are evaluated first. For example, foldl' (x: y: x + y) 0 [1 2 3] evaluates to 6.

builtins.fromJSON

e

Convert a JSON string to a Nix value. For example,

builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''

returns the value { x = [ 1 2 3 ]; y = null; }.

builtins.functionArgs

f

Return a set containing the names of the formal arguments expected by the function f. The value of each attribute is a Boolean denoting whether the corresponding argument has a default value. For instance, functionArgs ({ x, y ? 123}: ...) = { x = false; y = true; }.

“Formal argument” here refers to the attributes pattern-matched by the function. Plain lambdas are not included, e.g. functionArgs (x: ...) = { }.

builtins.genList

generator, length

Generate list of size length, with each element i equal to the value returned by generator i. For example,

builtins.genList (x: x * x) 5

returns the list [ 0 1 4 9 16 ].

builtins.genericClosure

attrset

Take an attrset with values named startSet and operator in order to return a list of attrsets by starting with the startSet, recursively applying the operator function to each element. The attrsets in the startSet and produced by the operator must each contain value named key which are comparable to each other. The result is produced by repeatedly calling the operator for each element encountered with a unique key, terminating when no new elements are produced. For example,

builtins.genericClosure {
  startSet = [ {key = 5;} ];
  operator = item: [{
    key = if (item.key / 2 ) * 2 == item.key
         then item.key / 2
         else 3 * item.key + 1;
  }];
}

evaluates to

[ { key = 5; } { key = 16; } { key = 8; } { key = 4; } { key = 2; } { key = 1; } ]

builtins.getAttr

s, set

getAttr returns the attribute named s from set. Evaluation aborts if the attribute doesn’t exist. This is a dynamic version of the . operator, since s is an expression rather than an identifier.

builtins.getEnv

s

getEnv returns the value of the environment variable s, 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.

getEnv is used in Nix Packages to locate the file ~/.nixpkgs/config.nix, which contains user-local settings for Nix Packages. (That is, it does a getEnv "HOME" to locate the user’s home directory.)

builtins.getFlake

args

Fetch a flake from a flake reference, and return its output attributes and some metadata. For example:

(builtins.getFlake "nix/55bc52401966fbffa525c574c14f67b00bc4fb3a").packages.x86_64-linux.nix

Unless impure evaluation is allowed (--impure), the flake reference must be “locked”, e.g. contain a Git revision or content hash. An example of an unlocked usage is:

(builtins.getFlake "github:edolstra/dwarffs").rev

This function is only available if you enable the experimental feature flakes.

builtins.groupBy

f, list

Groups elements of list together by the string returned from the function f called on each element. It returns an attribute set where each attribute value contains the elements of list that are mapped to the same corresponding attribute name returned by f.

For example,

builtins.groupBy (builtins.substring 0 1) ["foo" "bar" "baz"]

evaluates to

{ b = [ "bar" "baz" ]; f = [ "foo" ]; }

builtins.hasAttr

s, set

hasAttr returns true if set has an attribute named s, and false otherwise. This is a dynamic version of the ? operator, since s is an expression rather than an identifier.

builtins.hashFile

type, p

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

builtins.hashString

type, s

Return a base-16 representation of the cryptographic hash of string s. The hash algorithm specified by type must be one of "md5", "sha1", "sha256" or "sha512".

builtins.head

list

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

builtins.import

path

Load, parse and return the Nix expression in the file path. If path is a directory, the file default.nix in that directory is loaded. Evaluation aborts if the file doesn’t exist or contains an incorrect Nix expression. import 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.

Note

Unlike some languages, import is a regular function in Nix. Paths using the angle bracket syntax (e.g., import <foo>) are normal path values.

A Nix expression loaded by import must not contain any free variables (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

rec {
  x = 123;
  y = import ./foo.nix;
}

then the following foo.nix will give an error:

x + 456

since x is not in scope in foo.nix. If you want x to be available in foo.nix, you should pass it as a function argument:

rec {
  x = 123;
  y = import ./foo.nix x;
}

and

x: x + 456

(The function argument doesn’t have to be called x in foo.nix; any name would work.)

builtins.intersectAttrs

e1, e2

Return a set consisting of the attributes in the set e2 that also exist in the set e1.

builtins.isAttrs

e

Return true if e evaluates to a set, and false otherwise.

builtins.isBool

e

Return true if e evaluates to a bool, and false otherwise.

builtins.isFloat

e

Return true if e evaluates to a float, and false otherwise.

builtins.isFunction

e

Return true if e evaluates to a function, and false otherwise.

builtins.isInt

e

Return true if e evaluates to an integer, and false otherwise.

builtins.isList

e

Return true if e evaluates to a list, and false otherwise.

builtins.isNull

e

Return true if e evaluates to null, and false otherwise.

Warning

This function is deprecated; just write e == null instead.

builtins.isPath

e

Return true if e evaluates to a path, and false otherwise.

builtins.isString

e

Return true if e evaluates to a string, and false otherwise.

builtins.length

e

Return the length of the list e.

builtins.lessThan

e1, e2

Return true if the number e1 is less than the number e2, and false otherwise. Evaluation aborts if either e1 or e2 does not evaluate to a number.

builtins.listToAttrs

e

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 name specifying the name of the attribute, and an attribute value specifying its value. Example:

builtins.listToAttrs
  [ { name = "foo"; value = 123; }
    { name = "bar"; value = 456; }
  ]

evaluates to

{ foo = 123; bar = 456; }

builtins.map

f, list

Apply the function f to each element in the list list. For example,

map (x: "foo" + x) [ "bar" "bla" "abc" ]

evaluates to [ "foobar" "foobla" "fooabc" ].

builtins.mapAttrs

f, attrset

Apply function f to every element of attrset. For example,

builtins.mapAttrs (name: value: value * 10) { a = 1; b = 2; }

evaluates to { a = 10; b = 20; }.

builtins.match

regex, str

Returns a list if the extended POSIX regular expression regex matches str precisely, otherwise returns null. Each item in the list is a regex group.

builtins.match "ab" "abc"

Evaluates to null.

builtins.match "abc" "abc"

Evaluates to [ ].

builtins.match "a(b)(c)" "abc"

Evaluates to [ "b" "c" ].

builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" "  FOO   "

Evaluates to [ "foo" ].

builtins.mul

e1, e2

Return the product of the numbers e1 and e2.

builtins.parseDrvName

s

Split the string s 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 { name, version }. Thus, builtins.parseDrvName "nix-0.12pre12876" returns { name = "nix"; version = "0.12pre12876"; }.

builtins.partition

pred, list

Given a predicate function pred, this function returns an attrset containing a list named right, containing the elements in list for which pred returned true, and a list named wrong, containing the elements for which it returned false. For example,

builtins.partition (x: x > 10) [1 23 9 3 42]

evaluates to

{ right = [ 23 42 ]; wrong = [ 1 9 3 ]; }

builtins.path

args

An enrichment of the built-in path type, based on the attributes present in args. All are optional except path:

builtins.pathExists

path

Return true if the path path exists at evaluation time, and false otherwise.

builtins.placeholder

output

Return a placeholder string for the specified output that will be substituted by the corresponding output path at build time. Typical outputs would be "out", "bin" or "dev".

builtins.readDir

path

Return the contents of the directory path as a set mapping directory entries to the corresponding file type. For instance, if directory A contains a regular file B and another directory C, then builtins.readDir ./A will return the set

{ B = "regular"; C = "directory"; }

The possible values for the file type are "regular", "directory", "symlink" and "unknown".

builtins.readFile

path

Return the contents of the file path as a string.

builtins.removeAttrs

set, list

Remove the attributes listed in list from set. The attributes don’t have to exist in set. For instance,

removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]

evaluates to { y = 2; }.

builtins.replaceStrings

from, to, s

Given string s, replace every occurrence of the strings in from with the corresponding string in to. For example,

builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar"

evaluates to "fabir".

builtins.seq

e1, e2

Evaluate e1, then evaluate and return e2. This ensures that a computation is strict in the value of e1.

builtins.sort

comparator, list

Return list in sorted order. It repeatedly calls the function comparator with two elements. The comparator should return true if the first element is less than the second, and false otherwise. For example,

builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ]

produces the list [ 42 77 147 249 483 526 ].

This is a stable sort: it preserves the relative order of elements deemed equal by the comparator.

builtins.split

regex, str

Returns a list composed of non matched strings interleaved with the lists of the extended POSIX regular expression regex matches of str. Each item in the lists of matched sequences is a regex group.

builtins.split "(a)b" "abc"

Evaluates to [ "" [ "a" ] "c" ].

builtins.split "([ac])" "abc"

Evaluates to [ "" [ "a" ] "b" [ "c" ] "" ].

builtins.split "(a)|(c)" "abc"

Evaluates to [ "" [ "a" null ] "b" [ null "c" ] "" ].

builtins.split "([[:upper:]]+)" "  FOO   "

Evaluates to [ " " [ "FOO" ] " " ].

builtins.splitVersion

s

Split a string representing a version into its components, by the same version splitting logic underlying the version comparison in nix-env -u.

builtins.storePath

path

This function allows you to define a dependency on an already existing store path. For example, the derivation attribute src = builtins.storePath /nix/store/f1d18v1y…-source causes the derivation to depend on the specified path, which must exist or be substitutable. Note that this differs from a plain path (e.g. src = /nix/store/f1d18v1y…-source) in that the latter causes the path to be copied again to the Nix store, resulting in a new path (e.g. /nix/store/ld01dnzc…-source-source).

This function is not available in pure evaluation mode.

builtins.stringLength

e

Return the length of the string e. If e is not a string, evaluation is aborted.

builtins.sub

e1, e2

Return the difference between the numbers e1 and e2.

builtins.substring

start, len, s

Return the substring of s from character position start (zero-based) up to but not including start + len. If start is greater than the length of the string, an empty string is returned, and if start + len lies beyond the end of the string, only the substring up to the end of the string is returned. start must be non-negative. For example,

builtins.substring 0 3 "nixos"

evaluates to "nix".

builtins.tail

list

Return the second to last elements of a list; abort evaluation if the argument isn’t a list or is an empty list.

Warning

This function should generally be avoided since it’s inefficient: unlike Haskell’s tail, it takes O(n) time, so recursing over a list by repeatedly calling tail takes O(n^2) time.

builtins.throw

s

Throw an error message s. This usually aborts Nix expression evaluation, but in nix-env -qa 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 abort).

builtins.toFile

name, s

Store the string s in a file in the Nix store and return its path. The file has suffix name. This file can be used as an input to derivations. One application is to write builders “inline”. For instance, the following Nix expression combines the Nix expression for GNU Hello and its build script into one file:

{ 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;
}

It is even possible for one file to refer to another, e.g.,

builder = let
  configFile = builtins.toFile "foo.conf" "
    # This is some dummy configuration file.
    ...
  ";
in builtins.toFile "builder.sh" "
  source $stdenv/setup
  ...
  cp ${configFile} $out/etc/foo.conf
";

Note that ${configFile} is an antiquotation, so the result of the expression configFile (i.e., a path like /nix/store/m7p7jfny445k...-foo.conf) will be spliced into the resulting string.

It is however not allowed to have files mutually referring to each other, like so:

let
  foo = builtins.toFile "foo" "...${bar}...";
  bar = builtins.toFile "bar" "...${foo}...";
in foo

This is not allowed because it would cause a cyclic dependency in the computation of the cryptographic hashes for foo and bar.

It is also not possible to reference the result of a derivation. If you are using Nixpkgs, the writeTextFile function is able to do that.

builtins.toJSON

e

Return a string containing a JSON representation of e. 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.

builtins.toPath

s

DEPRECATED. Use /. + "/path" to convert a string into an absolute path. For relative paths, use ./. + "/path".

builtins.toString

e

Convert the expression e to a string. e can be:

builtins.toXML

e

Return a string containing an XML representation of e. The main application for toXML is to communicate information with the builder in a more structured format than plain environment variables.

Here is an example where this is the case:

{ 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 ①
  ";

  stylesheet = builtins.toFile "stylesheet.xsl"
   "<?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 [
    { path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; }
    { path = "/wiki"; war = uberwiki + "/uberwiki.war"; }
  ];
})

The builder is supposed to generate the configuration file for a Jetty servlet container. A servlet container contains a number of servlets (*.war files) each exported under a specific URI prefix. So the servlet configuration is a list of sets containing the path and war of the servlet (①). 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 toXML, which is unambiguous and can easily be processed with the appropriate tools. For instance, in the example an XSLT stylesheet (at point ②) is applied to it (at point ①) to generate the XML configuration file for the Jetty server. The XML representation produced at point ③ by toXML is as follows:

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

Note that we used the toFile built-in to write the builder and the stylesheet “inline” in the Nix expression. The path of the stylesheet is spliced into the builder using the syntax xsltproc ${stylesheet}.

builtins.trace

e1, e2

Evaluate e1 and print its abstract syntax representation on standard error. Then return e2. This function is useful for debugging.

builtins.tryEval

e

Try to shallowly evaluate e. Return a set containing the attributes success (true if e evaluated successfully, false if an error was thrown) and value, equalling e if successful and false otherwise. tryEval will only prevent errors created by throw or assert from being thrown. Errors tryEval will not catch are for example those created by abort and type errors generated by builtins. Also note that this doesn’t evaluate e deeply, so let e = { x = throw ""; }; in (builtins.tryEval e).success will be true. Using builtins.deepSeq one can get the expected result: let e = { x = throw ""; }; in (builtins.tryEval (builtins.deepSeq e e)).success will be false.

builtins.typeOf

e

Return a string representing the type of the value e, namely "int", "bool", "string", "path", "null", "set", "list", "lambda" or "float".

builtins.zipAttrsWith

f, list

Transpose a list of attribute sets into an attribute set of lists, then apply mapAttrs.

f receives two arguments: the attribute name and a non-empty list of all values encountered for that attribute name.

The result is an attribute set where the attribute names are the union of the attribute names in each element of list. The attribute values are the return values of f.

builtins.zipAttrsWith
  (name: values: { inherit name values; })
  [ { a = "x"; } { a = "y"; b = "z"; } ]

evaluates to

{
  a = { name = "a"; values = [ "x" "y" ]; };
  b = { name = "b"; values = [ "z" ]; };
}

Nixpkgs Library Functions

Assert functions

lib.asserts.assertMsg

pred, msg

assertMsg :: Bool -> String -> Bool

Print a trace message if pred is false.

Printing when the predicate is false:

assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly"
stderr> trace: foo is not bar, silly
stderr> assert failed

lib.asserts.assertOneOf

name, val, xs

assertOneOf :: String -> String -> StringList -> Bool

Specialized asserts.assertMsg for checking if val is one of the elements of xs. Useful for checking enums.

Ensuring a user provided a possible value:

let sslLibrary = "bearssl";
in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "libressl" ];
=> false
stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"

Attribute-Set Functions

lib.attrset.attrByPath

attrPath, default, set

attrByPath :: [String] -> Any -> AttrSet -> Any

Return an attribute from within nested attribute sets.

Extracting a value from a nested attribute set:

let set = { a = { b = 3; }; };
in lib.attrsets.attrByPath [ "a" "b" ] 0 set
=> 3

No value at the path, instead using the default:

lib.attrsets.attrByPath [ "a" "b" ] 0 {}
=> 0

lib.attrsets.attrVals

nameList, set

attrVals :: [String] -> AttrSet -> [Any]

Return the specified attributes from a set. All values must exist.

Getting several values from an attribute set:

lib.attrsets.attrVals [ "a" "b" "c" ] { a = 1; b = 2; c = 3; }
=> [ 1 2 3 ]

Getting missing values from an attribute set:

lib.attrsets.attrVals [ "d" ] { }
error: attribute 'd' missing

lib.attrsets.attrValues

attrs

attrValues :: AttrSet -> [Any]

Get all the attribute values from an attribute set.

:

lib.attrsets.attrValues { a = 1; b = 2; c = 3; }
=> [ 1 2 3 ]

lib.attrsets.cartesianProductOfSets

set

cartesianProductOfSets :: AttrSet -> [ AttrSet ]

Return the cartesian product of attribute set value combinations.

Creating the cartesian product of a list of attribute values:

cartesianProductOfSets { a = [ 1 2 ]; b = [ 10 20 ]; }
=> [
     { a = 1; b = 10; }
     { a = 1; b = 20; }
     { a = 2; b = 10; }
     { a = 2; b = 20; }
   ]

lib.attrsets.catAttrs

attr, sets

catAttrs :: String -> [AttrSet] -> [Any]

Collect each attribute named `attr’ from the list of attribute sets, sets. Sets that don’t contain the named attribute are ignored.

Collect an attribute from a list of attribute sets.:

catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
=> [ 1 2 ]

lib.attrsets.collect

pred, value, attrs, value

collect :: (Any -> Bool) -> AttrSet -> [Any]

Recursively collect sets that verify a given predicate named pred from the set attrs. The recursion stops when pred returns true.

Collecting all lists from an attribute set:

lib.attrsets.collect isList { a = { b = ["b"]; }; c = [1]; }
=> [["b"] [1]]

Collecting all attribute-sets which contain the outPath attribute name.:

collect (x: x ? outPath)
  { a = { outPath = "a/"; }; b = { outPath = "b/"; }; }
=> [{ outPath = "a/"; } { outPath = "b/"; }]

lib.attrsets.filterAttrs

pred, name, value, set, name, value

filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet

Filter an attribute set by removing all attributes for which the given predicate return false.

Filtering an attributeset:

filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; }
=> { foo = 1; }

lib.attrsets.filterAttrsRecursive

pred, name, value, set, name, value

filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet

Filter an attribute set recursively by removing all attributes for which the given predicate return false.

Recursively filtering an attribute set:

lib.attrsets.filterAttrsRecursive
  (n: v: v != null)
  {
    levelA = {
      example = "hi";
      levelB = {
        hello = "there";
        this-one-is-present = {
          this-is-excluded = null;
        };
      };
      this-one-is-also-excluded = null;
    };
    also-excluded = null;
  }
=> {
     levelA = {
       example = "hi";
       levelB = {
         hello = "there";
         this-one-is-present = { };
       };
     };
   }

lib.attrsets.foldAttrs

op, val, col, nul, list_of_attrs, val, col

foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any

Apply fold function to values grouped by key.

Combining an attribute of lists in to one attribute set:

lib.attrsets.foldAttrs
  (n: a: [n] ++ a) []
  [
    { a = 2; b = 7; }
    { a = 3; }
    { b = 6; }
  ]
=> { a = [ 2 3 ]; b = [ 7 6 ]; }

lib.attrsets.genAttrs

names, f, name, name

genAttrs :: [ String ] -> (String -> Any) -> AttrSet

Generate an attribute set by mapping a function over a list of attribute names.

Generate an attrset based on names only:

lib.attrsets.genAttrs [ "foo" "bar" ] (name: "x_${name}")
=> { foo = "x_foo"; bar = "x_bar"; }

lib.attrsets.getAttrFromPath

attrPath, set

getAttrFromPath :: [String] -> AttrSet -> Value

Like except without a default, and it will throw if the value doesn’t exist.

Succesfully getting a value from an attribute set:

lib.attrsets.getAttrFromPath [ "a" "b" ] { a = { b = 3; }; }
=> 3

Throwing after failing to get a value from an attribute set:

lib.attrsets.getAttrFromPath [ "x" "y" ] { }
=> error: cannot find attribute `x.y'

lib.attrsets.hasAttrByPath

attrPath, set

hasAttrByPath :: [String] -> AttrSet -> Bool

Determine if an attribute exists within a nested attribute set.

A nested value does exist inside a set:

lib.attrsets.hasAttrByPath
  [ "a" "b" "c" "d" ]
  { a = { b = { c = { d = 123; }; }; }; }
=> true

lib.attrsets.isDerivation

value

isDerivation :: Any -> Bool

Check whether the argument is a derivation. Any set with { type = “derivation”; } counts as a derivation.

A package is a derivation:

lib.attrsets.isDerivation (import <nixpkgs> {}).ruby
=> true

Anything else is not a derivation:

lib.attrsets.isDerivation "foobar"
=> false

lib.attrsets.mapAttrs

fn, name, value, name, value

``

Apply a function to each element in an attribute set, creating a new attribute set.

Modifying each value of an attribute set:

lib.attrsets.mapAttrs
  (name: value: name + "-" + value)
  { x = "foo"; y = "bar"; }
=> { x = "x-foo"; y = "y-bar"; }

lib.attrsets.mapAttrs’

fn, name, value, set, name, value

mapAttrs' :: (String -> Any -> { name = String; value = Any }) -> AttrSet -> AttrSet

Like mapAttrs, but allows the name of each attribute to be changed in addition to the value. The applied function should return both the new name and value as a nameValuePair.

Change the name and value of each attribute of an attribute set:

lib.attrsets.mapAttrs' (name: value: lib.attrsets.nameValuePair ("foo_" + name) ("bar-" + value))
   { x = "a"; y = "b"; }
=> { foo_x = "bar-a"; foo_y = "bar-b"; }

lib.attrsets.mapAttrsRecursive

f, name_path, value, set, name_path, value

mapAttrsRecursive :: ([String] > Any -> Any) -> AttrSet -> AttrSet

Like mapAttrs, except that it recursively applies itself to attribute sets. Also, the first argument of the argument function is a list of the names of the containing attributes.

A contrived example of using lib.attrsets.mapAttrsRecursive:

mapAttrsRecursive
  (path: value: concatStringsSep "-" (path ++ [value]))
  {
    n = {
      a = "A";
      m = {
        b = "B";
        c = "C";
      };
    };
    d = "D";
  }
=> {
     n = {
       a = "n-a-A";
       m = {
         b = "n-m-b-B";
         c = "n-m-c-C";
       };
     };
     d = "d-D";
   }

lib.attrsets.mapAttrsRecursiveCond

cond, attributeset, f, name_path, value, set, attributeset, name_path, value

mapAttrsRecursiveCond :: (AttrSet -> Bool) -> ([ String ] -> Any -> Any) -> AttrSet -> AttrSet

Like mapAttrsRecursive, but it takes an additional predicate function that tells it whether to recursive into an attribute set. If it returns false, mapAttrsRecursiveCond does not recurse, but does apply the map function. It is returns true, it does recurse, and does not apply the map function.

Only convert attribute values to JSON if the containing attribute set is marked for recursion:

lib.attrsets.mapAttrsRecursiveCond
  ({ recurse ? false, ... }: recurse)
  (name: value: builtins.toJSON value)
  {
    dorecur = {
      recurse = true;
      hello = "there";
    };
    dontrecur = {
      converted-to- = "json";
    };
  }
=> {
     dorecur = {
       hello = "\"there\"";
       recurse = "true";
     };
     dontrecur = "{\"converted-to\":\"json\"}";
   }

lib.attrsets.mapAttrsToList

fn, name, value, set, name, value

mapAttrsToList :: (String -> Any -> Any) -> AttrSet -> [Any]

Call fn for each attribute in the given set and return the result in a list.

Combine attribute values and names in to a list:

lib.attrsets.mapAttrsToList (name: value: "${name}=${value}")
   { x = "a"; y = "b"; }
=> [ "x=a" "y=b" ]

lib.attrsets.nameValuePair

name, value

nameValuePair :: String -> Any -> AttrSet

Utility function that creates a {name, value} pair as expected by builtins.listToAttrs.

Creating a name value pair:

nameValuePair "some" 6
=> { name = "some"; value = 6; }

lib.attrsets.optionalAttrs

cond, as

optionalAttrs :: Bool -> AttrSet

Conditionally return an attribute set or an empty attribute set.

Return the provided attribute set when cond is true:

lib.attrsets.optionalAttrs true { my = "set"; }
=> { my = "set"; }

Return an empty attribute set when cond is false:

lib.attrsets.optionalAttrs false { my = "set"; }
=> { }

lib.attrsets.recurseIntoAttrs

attrs

recurseIntoAttrs :: AttrSet -> AttrSet

Make various Nix tools consider the contents of the resulting attribute set when looking for what to build, find, etc.

Making Nix look inside an attribute set:

{ pkgs ? import <nixpkgs> {} }:
{
  myTools = pkgs.lib.recurseIntoAttrs {
    inherit (pkgs) hello figlet;
  };
}

lib.attrsets.recursiveUpdate

lhs, rhs

recursiveUpdate :: AttrSet -> AttrSet -> AttrSet

A recursive variant of the update operator //. The recursion stops when one of the attribute values is not an attribute set, in which case the right hand side value takes precedence over the left hand side value.

Recursively merging two attribute sets:

recursiveUpdate
  {
    boot.loader.grub.enable = true;
    boot.loader.grub.device = "/dev/hda";
  }
  {
    boot.loader.grub.device = "";
  }
=> {
  boot.loader.grub.enable = true;
  boot.loader.grub.device = "";
}

lib.attrsets.recursiveUpdateUntil

pred, path, l, r, lhs, rhs, path, l, r

recursiveUpdateUntil :: ( [ String ] -> AttrSet -> AttrSet -> Bool ) -> AttrSet -> AttrSet -> AttrSet

Does the same as the update operator // except that attributes are merged until the given predicate is verified. The predicate should accept 3 arguments which are the path to reach the attribute, a part of the first attribute set and a part of the second attribute set. When the predicate is verified, the value of the first attribute set is replaced by the value of the second attribute set.

Recursively merging two attribute sets:

lib.attrsets.recursiveUpdateUntil (path: l: r: path == ["foo"])
  {
    # first attribute set
    foo.bar = 1;
    foo.baz = 2;
    bar = 3;
  }
  {
    #second attribute set
    foo.bar = 1;
    foo.quz = 2;
    baz = 4;
  }
=> {
  foo.bar = 1; # 'foo.*' from the second set
  foo.quz = 2; #
  bar = 3;     # 'bar' from the first set
  baz = 4;     # 'baz' from the second set
}

lib.attrsets.setAttrByPath

attrPath, value

setAttrByPath :: [String] -> Any -> AttrSet

Create a new attribute set with value set at the nested attribute location specified in attrPath.

Creating a new nested attribute set:

lib.attrsets.setAttrByPath [ "a" "b" ] 3
=> { a = { b = 3; }; }

lib.attrsets.toDerivation

path

toDerivation :: Path -> Derivation

Converts a store path to a fake derivation.

lib.attrsets.zipAttrs

sets

zipAttrs :: [ AttrSet ] -> AttrSet

Merge sets of attributes and combine each attribute value in to a list. Similar to where the merge function returns a list of all values.

Combining a list of attribute sets:

lib.attrsets.zipAttrs
  [
    { a = 1; b = 1; c = 1; }
    { a = 10; }
    { b = 100; }
    { c = 1000; }
  ]
=> { a = [ 1 10 ]; b = [ 1 100 ]; c = [ 1 1000 ]; }

lib.attrsets.zipAttrsWith

f, name, vs, sets, name, vs

zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet

Merge sets of attributes and use the function f to merge attribute values. Similar to where all key names are passed for names.

Summing a list of attribute sets of numbers:

lib.attrsets.zipAttrsWith
  (name: vals: "${name} ${toString (builtins.foldl' (a: b: a + b) 0 vals)}")
  [
    { a = 1; b = 1; c = 1; }
    { a = 10; }
    { b = 100; }
    { c = 1000; }
  ]
=> { a = "a 11"; b = "b 101"; c = "c 1001"; }

lib.attrsets.zipAttrsWithNames

names, f, name, vs, sets, name, vs

zipAttrsWithNames :: [ String ] -> (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet

Merge sets of attributes and use the function f to merge attribute values where the attribute name is in names.

Summing a list of attribute sets of numbers:

lib.attrsets.zipAttrsWithNames
  [ "a" "b" ]
  (name: vals: "${name} ${toString (builtins.foldl' (a: b: a + b) 0 vals)}")
  [
    { a = 1; b = 1; c = 1; }
    { a = 10; }
    { b = 100; }
    { c = 1000; }
  ]
=> { a = "a 11"; b = "b 101"; }

Debugging functions

lib.debug.runTests

tests

Evaluate a set of tests. A test is an attribute set {expr, expected}, denoting an expression and its expected result. The result is a list of failed tests, each represented as {name, expected, actual}, denoting the attribute name of the failing test and its expected and actual results.

lib.debug.testAllTrue

expr

Create a test assuming that list elements are true.

lib.debug.testAllTrue usage example:

{ testX = allTrue [ true ]; }

lib.debug.traceFnSeqN

depth, name, f, v

Trace the input and output of a function f named name, both down to depth.

lib.debug.traceFnSeqN usage example:

traceFnSeqN 2 "id" (x: x) { a.b.c = 3; }
trace: { fn = "id"; from = { a.b = {}; }; to = { a.b = {}; }; }
=> { a.b.c = 3; }

lib.debug.traceIf

pred, msg, x

traceIf :: bool -> string -> a -> a

Conditionally trace the supplied message, based on a predicate.

lib.debug.traceIf usage example:

traceIf true "hello" 3
trace: hello
=> 3

lib.debug.traceSeq

x, y

traceSeq :: a -> b -> b

builtins.trace, but the value is builtins.deepSeqed first.

lib.debug.traceSeq usage example:

trace { a.b.c = 3; } null
trace: { a = <CODE>; }
=> null
traceSeq { a.b.c = 3; } null
trace: { a = { b = { c = 3; }; }; }
=> null

lib.debug.traceSeqN

depth, x, y

Like traceSeq, but only evaluate down to depth n. This is very useful because lots of traceSeq usages lead to an infinite recursion.

lib.debug.traceSeqN usage example:

traceSeqN 2 { a.b.c = 3; } null
trace: { a = { b = {}; }; }
=> null

lib.debug.traceVal

__

traceVal :: a -> a

Trace the supplied value and return it.

lib.debug.traceVal usage example:

traceVal 42
# trace: 42
=> 42

lib.debug.traceValFn

f, x

traceValFn :: (a -> b) -> a -> a

Trace the supplied value after applying a function to it, and return the original value.

lib.debug.traceValFn usage example:

traceValFn (v: "mystring ${v}") "foo"
trace: mystring foo
=> "foo"

lib.debug.traceValSeq

__

A combination of traceVal and traceSeq.

lib.debug.traceValSeqFn

f, v

A combination of traceVal and traceSeq that applies a provided function to the value to be traced after deepSeqing it.

lib.debug.traceValSeqN

__

A combination of traceVal and traceSeqN.

lib.debug.traceValSeqNFn

f, depth, v

A combination of traceVal and traceSeqN that applies a provided function to the value to be traced.

List manipulation functions

lib.lists.all

__

all :: (a -> bool) -> [a] -> bool

Return true if function pred returns true for all elements of list.

lib.lists.all usage example:

all (x: x < 3) [ 1 2 ]
=> true
all (x: x < 3) [ 1 2 3 ]
=> false

lib.lists.any

__

any :: (a -> bool) -> [a] -> bool

Return true if function pred returns true for at least one element of list.

lib.lists.any usage example:

any isString [ 1 "a" { } ]
=> true
any isString [ 1 { } ]
=> false

lib.lists.compareLists

cmp, a, b

Compare two lists element-by-element.

lib.lists.compareLists usage example:

compareLists compare [] []
=> 0
compareLists compare [] [ "a" ]
=> -1
compareLists compare [ "a" ] []
=> 1
compareLists compare [ "a" "b" ] [ "a" "c" ]
=> -1

lib.lists.concatMap

__

concatMap :: (a -> [b]) -> [a] -> [b]

Map and concatenate the result.

lib.lists.concatMap usage example:

concatMap (x: [x] ++ ["z"]) ["a" "b"]
=> [ "a" "z" "b" "z" ]

lib.lists.count

pred

count :: (a -> bool) -> [a] -> int

Count how many elements of list match the supplied predicate function.

lib.lists.count usage example:

count (x: x == 3) [ 3 2 3 4 6 ]
=> 2

lib.lists.crossLists

__

Return the image of the cross product of some lists by a function.

lib.lists.crossLists usage example:

crossLists (x:y: "${toString x}${toString y}") [[1 2] [3 4]]
=> [ "13" "14" "23" "24" ]

lib.lists.drop

count, list

drop :: int -> [a] -> [a]

Remove the first (at most) N elements of a list.

lib.lists.drop usage example:

drop 2 [ "a" "b" "c" "d" ]
=> [ "c" "d" ]
drop 2 [ ]
=> [ ]

lib.lists.findFirst

pred, default, list

findFirst :: (a -> bool) -> a -> [a] -> a

Find the first element in the list matching the specified predicate or return default if no such element exists.

lib.lists.findFirst usage example:

findFirst (x: x > 3) 7 [ 1 6 4 ]
=> 6
findFirst (x: x > 9) 7 [ 1 6 4 ]
=> 7

lib.lists.findSingle

pred, default, multiple, list

findSingle :: (a -> bool) -> a -> a -> [a] -> a

Find the sole element in the list matching the specified predicate, returns default if no such element exists, or multiple if there are multiple matching elements.

lib.lists.findSingle usage example:

findSingle (x: x == 3) "none" "multiple" [ 1 3 3 ]
=> "multiple"
findSingle (x: x == 3) "none" "multiple" [ 1 3 ]
=> 3
findSingle (x: x == 3) "none" "multiple" [ 1 9 ]
=> "none"

lib.lists.flatten

x

Flatten the argument into a single list; that is, nested lists are spliced into the top-level lists.

lib.lists.flatten usage example:

flatten [1 [2 [3] 4] 5]
=> [1 2 3 4 5]
flatten 1
=> [1]

lib.lists.fold

__

fold is an alias of foldr for historic reasons

lib.lists.foldl

op, nul, list

foldl :: (b -> a -> b) -> b -> [a] -> b

“left fold”, like foldr, but from the left: foldl op nul [x_1 x_2 ... x_n] == op (... (op (op nul x_1) x_2) ... x_n).

lib.lists.foldl usage example:

lconcat = foldl (a: b: a + b) "z"
lconcat [ "a" "b" "c" ]
=> "zabc"
# different types
lstrange = foldl (str: int: str + toString (int + 1)) "a"
lstrange [ 1 2 3 4 ]
=> "a2345"

lib.lists.foldl’

__

foldl' :: (b -> a -> b) -> b -> [a] -> b

Strict version of foldl.

lib.lists.foldr

op, nul, list

foldr :: (a -> b -> b) -> b -> [a] -> b

“right fold” a binary function op between successive elements of list with nul' as the starting value, i.e.,foldr op nul [x_1 x_2 … x_n] == op x_1 (op x_2 … (op x_n nul))`.

lib.lists.foldr usage example:

concat = foldr (a: b: a + b) "z"
concat [ "a" "b" "c" ]
=> "abcz"
# different types
strange = foldr (int: str: toString (int + 1) + str) "a"
strange [ 1 2 3 4 ]
=> "2345a"

lib.lists.forEach

xs, f

forEach :: [a] -> (a -> b) -> [b]

Apply the function to each element in the list. Same as map, but arguments flipped.

lib.lists.forEach usage example:

forEach [ 1 2 ] (x:
toString x
)
=> [ "1" "2" ]

lib.lists.groupBy’

op, nul, pred, lst

Splits the elements of a list into many lists, using the return value of a predicate. Predicate should return a string which becomes keys of attrset `groupBy’ returns.

lib.lists.groupBy’ usage example:

groupBy (x: boolToString (x > 2)) [ 5 1 2 3 4 ]
=> { true = [ 5 3 4 ]; false = [ 1 2 ]; }
groupBy (x: x.name) [ {name = "icewm"; script = "icewm &";}
{name = "xfce";  script = "xfce4-session &";}
{name = "icewm"; script = "icewmbg &";}
{name = "mate";  script = "gnome-session &";}
]
=> { icewm = [ { name = "icewm"; script = "icewm &"; }
{ name = "icewm"; script = "icewmbg &"; } ];
mate  = [ { name = "mate";  script = "gnome-session &"; } ];
xfce  = [ { name = "xfce";  script = "xfce4-session &"; } ];
}

groupBy' builtins.add 0 (x: boolToString (x > 2)) [ 5 1 2 3 4 ]
=> { true = 12; false = 3; }

lib.lists.imap0

f, list

imap0 :: (int -> a -> b) -> [a] -> [b]

Map with index starting from 0

lib.lists.imap0 usage example:

imap0 (i: v: "${v}-${toString i}") ["a" "b"]
=> [ "a-0" "b-1" ]

lib.lists.imap1

f, list

imap1 :: (int -> a -> b) -> [a] -> [b]

Map with index starting from 1

lib.lists.imap1 usage example:

imap1 (i: v: "${v}-${toString i}") ["a" "b"]
=> [ "a-1" "b-2" ]

lib.lists.init

list

init :: [a] -> [a]

Return all elements but the last.

lib.lists.init usage example:

init [ 1 2 3 ]
=> [ 1 2 ]

lib.lists.intersectLists

e

Intersects list ‘e’ and another list. O(nm) complexity.

lib.lists.intersectLists usage example:

intersectLists [ 1 2 3 ] [ 6 3 2 ]
=> [ 3 2 ]

lib.lists.last

list

last :: [a] -> a

Return the last element of a list.

lib.lists.last usage example:

last [ 1 2 3 ]
=> 3

lib.lists.listDfs

stopOnCycles, before, list

Depth-First Search (DFS) for lists list != [].

lib.lists.listDfs usage example:

listDfs true hasPrefix [ "/home/user" "other" "/" "/home" ]
== { minimal = "/";                  # minimal element
visited = [ "/home/user" ];     # seen elements (in reverse order)
rest    = [ "/home" "other" ];  # everything else
}

listDfs true hasPrefix [ "/home/user" "other" "/" "/home" "/" ]
== { cycle   = "/";                  # cycle encountered at this element
loops   = [ "/" ];              # and continues to these elements
visited = [ "/" "/home/user" ]; # elements leading to the cycle (in reverse order)
rest    = [ "/home" "other" ];  # everything else

lib.lists.mutuallyExclusive

a, b

Test if two lists have no common element. It should be slightly more efficient than (intersectLists a b == [])

lib.lists.naturalSort

lst

Sort list using “Natural sorting”. Numeric portions of strings are sorted in numeric order.

lib.lists.naturalSort usage example:

naturalSort ["disk11" "disk8" "disk100" "disk9"]
=> ["disk8" "disk9" "disk11" "disk100"]
naturalSort ["10.46.133.149" "10.5.16.62" "10.54.16.25"]
=> ["10.5.16.62" "10.46.133.149" "10.54.16.25"]
naturalSort ["v0.2" "v0.15" "v0.0.9"]
=> [ "v0.0.9" "v0.2" "v0.15" ]

lib.lists.optional

cond, elem

optional :: bool -> a -> [a]

Return a singleton list or an empty list, depending on a boolean value. Useful when building lists with optional elements (e.g. `++ optional (system == “i686-linux”) firefox’).

lib.lists.optional usage example:

optional true "foo"
=> [ "foo" ]
optional false "foo"
=> [ ]

lib.lists.optionals

cond, elems

optionals :: bool -> [a] -> [a]

Return a list or an empty list, depending on a boolean value.

lib.lists.optionals usage example:

optionals true [ 2 3 ]
=> [ 2 3 ]
optionals false [ 2 3 ]
=> [ ]

lib.lists.partition

__

(a -> bool) -> [a] -> { right :: [a], wrong :: [a] }

Splits the elements of a list in two lists, right and wrong, depending on the evaluation of a predicate.

lib.lists.partition usage example:

partition (x: x > 2) [ 5 1 2 3 4 ]
=> { right = [ 5 3 4 ]; wrong = [ 1 2 ]; }

lib.lists.range

first, last

range :: int -> int -> [int]

Return a list of integers from first' up to and includinglast’.

lib.lists.range usage example:

range 2 4
=> [ 2 3 4 ]
range 3 2
=> [ ]

lib.lists.remove

e

remove :: a -> [a] -> [a]

Remove elements equal to ‘e’ from a list. Useful for buildInputs.

lib.lists.remove usage example:

remove 3 [ 1 3 4 3 ]
=> [ 1 4 ]

lib.lists.reverseList

xs

reverseList :: [a] -> [a]

Reverse the order of the elements of a list.

lib.lists.reverseList usage example:

reverseList [ "b" "o" "j" ]
=> [ "j" "o" "b" ]

lib.lists.singleton

x

singleton :: a -> [a]

Create a list consisting of a single element. singleton x is sometimes more convenient with respect to indentation than [x] when x spans multiple lines.

lib.lists.singleton usage example:

singleton "foo"
=> [ "foo" ]

lib.lists.sort

__

Sort a list based on a comparator function which compares two elements and returns true if the first argument is strictly below the second argument. The returned list is sorted in an increasing order. The implementation does a quick-sort.

lib.lists.sort usage example:

sort (a: b: a < b) [ 5 3 7 ]
=> [ 3 5 7 ]

lib.lists.sublist

start, count, list

sublist :: int -> int -> [a] -> [a]

Return a list consisting of at most count elements of list, starting at index start.

lib.lists.sublist usage example:

sublist 1 3 [ "a" "b" "c" "d" "e" ]
=> [ "b" "c" "d" ]
sublist 1 3 [ ]
=> [ ]

lib.lists.subtractLists

e

Subtracts list ‘e’ from another list. O(nm) complexity.

lib.lists.subtractLists usage example:

subtractLists [ 3 2 ] [ 1 2 3 4 5 3 ]
=> [ 1 4 5 ]

lib.lists.take

count

take :: int -> [a] -> [a]

Return the first (at most) N elements of a list.

lib.lists.take usage example:

take 2 [ "a" "b" "c" "d" ]
=> [ "a" "b" ]
take 2 [ ]
=> [ ]

lib.lists.toList

x

If argument is a list, return it; else, wrap it in a singleton list. If you’re using this, you should almost certainly reconsider if there isn’t a more “well-typed” approach.

lib.lists.toList usage example:

toList [ 1 2 ]
=> [ 1 2 ]
toList "hi"
=> [ "hi "]

lib.lists.toposort

before, list

Sort a list based on a partial ordering using DFS. This implementation is O(N^2), if your ordering is linear, use sort instead.

lib.lists.toposort usage example:

toposort hasPrefix [ "/home/user" "other" "/" "/home" ]
== { result = [ "/" "/home" "/home/user" "other" ]; }

toposort hasPrefix [ "/home/user" "other" "/" "/home" "/" ]
== { cycle = [ "/home/user" "/" "/" ]; # path leading to a cycle
loops = [ "/" ]; }                # loops back to these elements

toposort hasPrefix [ "other" "/home/user" "/home" "/" ]
== { result = [ "other" "/" "/home" "/home/user" ]; }

toposort (a: b: a < b) [ 3 2 1 ] == { result = [ 1 2 3 ]; }

lib.lists.unique

__

unique :: [a] -> [a]

Remove duplicate elements from the list. O(n^2) complexity.

lib.lists.unique usage example:

unique [ 3 2 3 4 ]
=> [ 3 2 4 ]

lib.lists.zipLists

__

zipLists :: [a] -> [b] -> [{ fst :: a, snd :: b}]

Merges two lists of the same size together. If the sizes aren’t the same the merging stops at the shortest.

lib.lists.zipLists usage example:

zipLists [ 1 2 ] [ "a" "b" ]
=> [ { fst = 1; snd = "a"; } { fst = 2; snd = "b"; } ]

lib.lists.zipListsWith

f, fst, snd

zipListsWith :: (a -> b -> c) -> [a] -> [b] -> [c]

Merges two lists of the same size together. If the sizes aren’t the same the merging stops at the shortest. How both lists are merged is defined by the first argument.

lib.lists.zipListsWith usage example:

zipListsWith (a: b: a + b) ["h" "l"] ["e" "o"]
=> ["he" "lo"]

NixOS / nixpkgs option handling

lib.options.getFiles

__

getFiles :: [ { file :: a } ] -> [a]

Extracts values of all “file” keys of the given list

lib.options.getFiles usage example:

getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
getFiles [ ]                                         // => [ ]

lib.options.getValues

__

getValues :: [ { value :: a } ] -> [a]

Extracts values of all “value” keys of the given list.

lib.options.getValues usage example:

getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
getValues [ ]                               // => [ ]

lib.options.isOption

__

isOption :: a -> bool

Returns true when the given argument is an option

lib.options.isOption usage example:

isOption 1             // => false
isOption (mkOption {}) // => true

lib.options.literalDocBook

text

For use in the defaultText and example option attributes. Causes the given DocBook text to be inserted verbatim in the documentation, for when a literalExpression would be too hard to read.

lib.options.literalExpression

text

For use in the defaultText and example option attributes. Causes the given string to be rendered verbatim in the documentation as Nix code. This is necessary for complex values, e.g. functions, or values that depend on other values or packages.

lib.options.mergeEqualOption

loc, defs

“Merge” option definitions by checking that they all have the same value.

lib.options.mkEnableOption

name

Creates an Option attribute set for a boolean value option i.e an option to be toggled on or off:

lib.options.mkEnableOption usage example:

mkEnableOption "foo"
=> { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }

lib.options.mkOption

pattern, default, defaultText, example, description, relatedPackages, type, apply, internal, visible, readOnly, default, defaultText, example, description, relatedPackages, type, apply, internal, visible, readOnly

Creates an Option attribute set. mkOption accepts an attribute set with the following keys:

lib.options.mkOption usage example:

mkOption { }  // => { _type = "option"; }
mkOption { default = "foo"; } // => { _type = "option"; default = "foo"; }

lib.options.mkPackageOption

pkgs, name, pattern, default, example, default, example

mkPackageOption :: pkgs -> string -> { default :: [string], example :: null | string | [string] } -> optionThe package is specified as a list of strings representing its attribute path in nixpkgs.Because of this, you need to pass nixpkgs itself as the first argument.The second argument is the name of the option, used in the description "The <name> package to use.".You can also pass an example value, either a literal string or a package's attribute path.You can omit the default path if the name of the option is also attribute path in nixpkgs.

Creates an Option attribute set for an option that specifies the package a module should use for some purpose.

lib.options.mkPackageOption usage example:

mkPackageOption pkgs "hello" { }
=> { _type = "option"; default = «derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv»; defaultText = { ... }; description = "The hello package to use."; type = { ... }; }


mkPackageOption pkgs "GHC" {
default = [ "ghc" ];
example = "pkgs.haskell.package.ghc923.ghc.withPackages (hkgs: [ hkgs.primes ])";
}
=> { _type = "option"; default = «derivation /nix/store/jxx55cxsjrf8kyh3fp2ya17q99w7541r-ghc-8.10.7.drv»; defaultText = { ... }; description = "The GHC package to use."; example = { ... }; type = { ... }; }

lib.options.mkSinkUndeclaredOptions

attrs

This option accepts anything, but it does not produce any result.

lib.options.scrubOptionValue

x

This function recursively removes all derivation attributes from x except for the name attribute.

lib.options.showOption

parts

Convert an option, described as a list of the option parts in to a safe, human readable version.

lib.options.showOption usage example:

(showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
(showOption ["foo" "bar.baz" "tux"]) == "foo.bar.baz.tux"

Placeholders will not be quoted as they are not actual values:
(showOption ["foo" "*" "bar"]) == "foo.*.bar"
(showOption ["foo" "<name>" "bar"]) == "foo.<name>.bar"

Unlike attributes, options can also start with numbers:
(showOption ["windowManager" "2bwm" "enable"]) == "windowManager.2bwm.enable"

String manipulation functions

lib.strings.addContextFrom

a, b

Appends string context from another string. This is an implementation detail of Nix.

lib.strings.addContextFrom usage example:

pkgs = import <nixpkgs> { };
addContextFrom pkgs.coreutils "bar"
=> "bar"

lib.strings.commonPrefixLength

a, b

Returns the length of the prefix common to both strings.

lib.strings.commonSuffixLength

a, b

Returns the length of the suffix common to both strings.

lib.strings.concatImapStrings

f, list

concatImapStrings :: (int -> a -> string) -> [a] -> string

Like concatMapStrings except that the f functions also gets the position as a parameter.

lib.strings.concatImapStrings usage example:

concatImapStrings (pos: x: "${toString pos}-${x}") ["foo" "bar"]
=> "1-foo2-bar"

lib.strings.concatImapStringsSep

sep, f, list

concatIMapStringsSep :: string -> (int -> a -> string) -> [a] -> string

Same as concatMapStringsSep, but the mapping function additionally receives the position of its argument.

lib.strings.concatImapStringsSep usage example:

concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ]
=> "6-3-2"

lib.strings.concatMapStrings

f, list

concatMapStrings :: (a -> string) -> [a] -> string

Map a function over a list and concatenate the resulting strings.

lib.strings.concatMapStrings usage example:

concatMapStrings (x: "a" + x) ["foo" "bar"]
=> "afooabar"

lib.strings.concatMapStringsSep

sep, f, list

concatMapStringsSep :: string -> (a -> string) -> [a] -> string

Maps a function over a list of strings and then concatenates the result with the specified separator interspersed between elements.

lib.strings.concatMapStringsSep usage example:

concatMapStringsSep "-" (x: toUpper x)  ["foo" "bar" "baz"]
=> "FOO-BAR-BAZ"

lib.strings.concatStrings

__

concatStrings :: [string] -> string

Concatenate a list of strings.

lib.strings.concatStrings usage example:

concatStrings ["foo" "bar"]
=> "foobar"

lib.strings.concatStringsSep

__

concatStringsSep :: string -> [string] -> string

Concatenate a list of strings with a separator between each element

lib.strings.concatStringsSep usage example:

concatStringsSep "/" ["usr" "local" "bin"]
=> "usr/local/bin"

lib.strings.enableFeature

enable, feat

Create an –{enable,disable}- string that can be passed to standard GNU Autoconf scripts.

lib.strings.enableFeature usage example:

enableFeature true "shared"
=> "--enable-shared"
enableFeature false "shared"
=> "--disable-shared"

lib.strings.enableFeatureAs

enable, feat, value

Create an –{enable-=,disable-} string that can be passed to standard GNU Autoconf scripts.

lib.strings.enableFeatureAs usage example:

enableFeatureAs true "shared" "foo"
=> "--enable-shared=foo"
enableFeatureAs false "shared" (throw "ignored")
=> "--disable-shared"

lib.strings.escape

list

escape :: [string] -> string -> string

Escape occurrence of the elements of list in string by prefixing it with a backslash.

lib.strings.escape usage example:

escape ["(" ")"] "(foo)"
=> "\\(foo\\)"

lib.strings.escapeNixIdentifier

s

string -> string

Quotes a string if it can’t be used as an identifier directly.

lib.strings.escapeNixIdentifier usage example:

escapeNixIdentifier "hello"
=> "hello"
escapeNixIdentifier "0abc"
=> "\"0abc\""

lib.strings.escapeNixString

s

string -> string

Turn a string into a Nix expression representing that string

lib.strings.escapeNixString usage example:

escapeNixString "hello\${}\n"
=> "\"hello\\\${}\\n\""

lib.strings.escapeRegex

__

string -> string

Turn a string into an exact regular expression

lib.strings.escapeRegex usage example:

escapeRegex "[^a-z]*"
=> "\\[\\^a-z]\\*"

lib.strings.escapeShellArg

arg

escapeShellArg :: string -> string

Quote string to be used safely within the Bourne shell.

lib.strings.escapeShellArg usage example:

escapeShellArg "esc'ape\nme"
=> "'esc'\\''ape\nme'"

lib.strings.escapeShellArgs

__

escapeShellArgs :: [string] -> string

Quote all arguments to be safely passed to the Bourne shell.

lib.strings.escapeShellArgs usage example:

escapeShellArgs ["one" "two three" "four'five"]
=> "'one' 'two three' 'four'\\''five'"

lib.strings.escapeXML

__

string -> string

Escapes a string such that it is safe to include verbatim in an XML document.

lib.strings.escapeXML usage example:

escapeXML ''"test" 'test' < & >''
=> "&quot;test&quot; &apos;test&apos; &lt; &amp; &gt;"

lib.strings.fileContents

file

fileContents :: path -> string

Read the contents of a file removing the trailing

lib.strings.fileContents usage example:

$ echo "1.0" > ./version

fileContents ./version
=> "1.0"

lib.strings.fixedWidthNumber

width, n

Format a number adding leading zeroes up to fixed width.

lib.strings.fixedWidthNumber usage example:

fixedWidthNumber 5 15
=> "00015"

lib.strings.fixedWidthString

width, filler, str

fixedWidthString :: int -> string -> string -> string

Create a fixed width string with additional prefix to match required width.

lib.strings.fixedWidthString usage example:

fixedWidthString 5 "0" (toString 15)
=> "00015"

lib.strings.floatToString

float

Convert a float to a string, but emit a warning when precision is lost during the conversion

lib.strings.floatToString usage example:

floatToString 0.000001
=> "0.000001"
floatToString 0.0000001
=> trace: warning: Imprecise conversion from float to string 0.000000
"0.000000"

lib.strings.getName

x

This function takes an argument that’s either a derivation or a derivation’s “name” attribute and extracts the name part from that argument.

lib.strings.getName usage example:

getName "youtube-dl-2016.01.01"
=> "youtube-dl"
getName pkgs.youtube-dl
=> "youtube-dl"

lib.strings.getVersion

x

This function takes an argument that’s either a derivation or a derivation’s “name” attribute and extracts the version part from that argument.

lib.strings.getVersion usage example:

getVersion "youtube-dl-2016.01.01"
=> "2016.01.01"
getVersion pkgs.youtube-dl
=> "2016.01.01"

lib.strings.hasInfix

infix, content

hasInfix :: string -> string -> bool

Determine whether a string contains the given infix

lib.strings.hasInfix usage example:

hasInfix "bc" "abcd"
=> true
hasInfix "ab" "abcd"
=> true
hasInfix "cd" "abcd"
=> true
hasInfix "foo" "abcd"
=> false

lib.strings.hasPrefix

pref, str

hasPrefix :: string -> string -> bool

Determine whether a string has given prefix.

lib.strings.hasPrefix usage example:

hasPrefix "foo" "foobar"
=> true
hasPrefix "foo" "barfoo"
=> false

lib.strings.hasSuffix

suffix, content

hasSuffix :: string -> string -> bool

Determine whether a string has given suffix.

lib.strings.hasSuffix usage example:

hasSuffix "foo" "foobar"
=> false
hasSuffix "foo" "barfoo"
=> true

lib.strings.intersperse

separator, list

intersperse :: a -> [a] -> [a]

Place an element between each element of a list

lib.strings.intersperse usage example:

intersperse "/" ["usr" "local" "bin"]
=> ["usr" "/" "local" "/" "bin"].

lib.strings.isCoercibleToString

x

Check whether a value can be coerced to a string

lib.strings.isStorePath

x

Check whether a value is a store path.

lib.strings.isStorePath usage example:

isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11/bin/python"
=> false
isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11"
=> true
isStorePath pkgs.python
=> true
isStorePath [] || isStorePath 42 || isStorePath {} ||
=> false

lib.strings.isValidPosixName

name

string -> bool

Test whether the given name is a valid POSIX shell variable name.

lib.strings.isValidPosixName usage example:

isValidPosixName "foo_bar000"
=> true
isValidPosixName "0-bad.jpg"
=> false

lib.strings.levenshtein

a, b

levenshtein :: string -> string -> int

Computes the Levenshtein distance between two strings. Complexity O(n*m) where n and m are the lengths of the strings. Algorithm adjusted from https://stackoverflow.com/a/9750974/6605742

lib.strings.levenshtein usage example:

levenshtein "foo" "foo"
=> 0
levenshtein "book" "hook"
=> 1
levenshtein "hello" "Heyo"
=> 3

lib.strings.levenshteinAtMost

__

levenshteinAtMost :: int -> string -> string -> bool

Returns whether the levenshtein distance between two strings is at most some value Complexity is O(min(n,m)) for k <= 2 and O(n*m) otherwise

lib.strings.levenshteinAtMost usage example:

levenshteinAtMost 0 "foo" "foo"
=> true
levenshteinAtMost 1 "foo" "boa"
=> false
levenshteinAtMost 2 "foo" "boa"
=> true
levenshteinAtMost 2 "This is a sentence" "this is a sentense."
=> false
levenshteinAtMost 3 "This is a sentence" "this is a sentense."
=> true

lib.strings.makeBinPath

__

Construct a binary search path (such as $PATH) containing the binaries for a set of packages.

lib.strings.makeBinPath usage example:

makeBinPath ["/root" "/usr" "/usr/local"]
=> "/root/bin:/usr/bin:/usr/local/bin"

lib.strings.makeLibraryPath

__

Construct a library search path (such as RPATH) containing the libraries for a set of packages

lib.strings.makeLibraryPath usage example:

makeLibraryPath [ "/usr" "/usr/local" ]
=> "/usr/lib:/usr/local/lib"
pkgs = import <nixpkgs> { }
makeLibraryPath [ pkgs.openssl pkgs.zlib ]
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r/lib:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/lib"

lib.strings.makeSearchPath

subDir, paths

makeSearchPath :: string -> [string] -> string

Construct a Unix-style, colon-separated search path consisting of the given subDir appended to each of the given paths.

lib.strings.makeSearchPath usage example:

makeSearchPath "bin" ["/root" "/usr" "/usr/local"]
=> "/root/bin:/usr/bin:/usr/local/bin"
makeSearchPath "bin" [""]
=> "/bin"

lib.strings.makeSearchPathOutput

output, subDir, pkgs

string -> string -> [package] -> string

Construct a Unix-style search path by appending the given subDir to the specified output of each of the packages. If no output by the given name is found, fallback to .out and then to the default.

lib.strings.makeSearchPathOutput usage example:

makeSearchPathOutput "dev" "bin" [ pkgs.openssl pkgs.zlib ]
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev/bin:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/bin"

lib.strings.nameFromURL

url, sep

Extract name with version from URL. Ask for separator which is supposed to start extension.

lib.strings.nameFromURL usage example:

nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "-"
=> "nix"
nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "_"
=> "nix-1.7-x86"

lib.strings.optionalString

cond, string

optionalString :: bool -> string -> string

Depending on the boolean `cond’, return either the given string or the empty string. Useful to concatenate against a bigger string.

lib.strings.optionalString usage example:

optionalString true "some-string"
=> "some-string"
optionalString false "some-string"
=> ""

lib.strings.readPathsFromFile

__

Read a list of paths from file, relative to the rootPath. Lines beginning with # are treated as comments and ignored. Whitespace is significant.

lib.strings.readPathsFromFile usage example:

readPathsFromFile /prefix
./pkgs/development/libraries/qt-5/5.4/qtbase/series
=> [ "/prefix/dlopen-resolv.patch" "/prefix/tzdir.patch"
"/prefix/dlopen-libXcursor.patch" "/prefix/dlopen-openssl.patch"
"/prefix/dlopen-dbus.patch" "/prefix/xdg-config-dirs.patch"
"/prefix/nix-profiles-library-paths.patch"
"/prefix/compose-search-path.patch" ]

lib.strings.removePrefix

prefix, str

string -> string -> string

Return a string without the specified prefix, if the prefix matches.

lib.strings.removePrefix usage example:

removePrefix "foo." "foo.bar.baz"
=> "bar.baz"
removePrefix "xxx" "foo.bar.baz"
=> "foo.bar.baz"

lib.strings.removeSuffix

suffix, str

string -> string -> string

Return a string without the specified suffix, if the suffix matches.

lib.strings.removeSuffix usage example:

removeSuffix "front" "homefront"
=> "home"
removeSuffix "xxx" "homefront"
=> "homefront"

lib.strings.sanitizeDerivationName

__

sanitizeDerivationName :: String -> String

Creates a valid derivation name from a potentially invalid one.

lib.strings.sanitizeDerivationName usage example:

sanitizeDerivationName "../hello.bar # foo"
=> "-hello.bar-foo"
sanitizeDerivationName ""
=> "unknown"
sanitizeDerivationName pkgs.hello
=> "-nix-store-2g75chlbpxlrqn15zlby2dfh8hr9qwbk-hello-2.10"

lib.strings.splitString

__sep, s

Cut a string with a separator and produces a list of strings which were separated by this separator.

lib.strings.splitString usage example:

splitString "." "foo.bar.baz"
=> [ "foo" "bar" "baz" ]
splitString "/" "/usr/local/bin"
=> [ "" "usr" "local" "bin" ]

lib.strings.stringAsChars

f, s

stringAsChars :: (string -> string) -> string -> string

Manipulate a string character by character and replace them by strings before concatenating the results.

lib.strings.stringAsChars usage example:

stringAsChars (x: if x == "a" then "i" else x) "nax"
=> "nix"

lib.strings.stringToCharacters

s

stringToCharacters :: string -> [string]

Convert a string to a list of characters (i.e. singleton strings). This allows you to, e.g., map a function over each character. However, note that this will likely be horribly inefficient; Nix is not a general purpose programming language. Complex string manipulations should, if appropriate, be done in a derivation. Also note that Nix treats strings as a list of bytes and thus doesn’t handle unicode.

lib.strings.stringToCharacters usage example:

stringToCharacters ""
=> [ ]
stringToCharacters "abc"
=> [ "a" "b" "c" ]
stringToCharacters "💩"
=> [ "�" "�" "�" "�" ]

lib.strings.toInt

str

string -> int

Parse a string as an int.

lib.strings.toInt usage example:

toInt "1337"
=> 1337
toInt "-4"
=> -4
toInt "3.14"
=> error: floating point JSON numbers are not supported

lib.strings.toLower

__

toLower :: string -> string

Converts an ASCII string to lower-case.

lib.strings.toLower usage example:

toLower "HOME"
=> "home"

lib.strings.toShellVar

name, value

string -> (string | listOf string | attrsOf string) -> string

Translate a Nix value into a shell variable declaration, with proper escaping.

lib.strings.toShellVar usage example:

''
${toShellVar "foo" "some string"}
[[ "$foo" == "some string" ]]
''

lib.strings.toShellVars

vars

attrsOf (string | listOf string | attrsOf string) -> string

Translate an attribute set into corresponding shell variable declarations using toShellVar.

lib.strings.toShellVars usage example:

let
foo = "value";
bar = foo;
in ''
${toShellVars { inherit foo bar; }}
[[ "$foo" == "$bar" ]]
''

lib.strings.toUpper

__

toUpper :: string -> string

Converts an ASCII string to upper-case.

lib.strings.toUpper usage example:

toUpper "home"
=> "HOME"

lib.strings.versionAtLeast

v1, v2

Return true if string v1 denotes a version equal to or newer than v2.

lib.strings.versionAtLeast usage example:

versionAtLeast "1.1" "1.0"
=> true
versionAtLeast "1.1" "1.1"
=> true
versionAtLeast "1.1" "1.2"
=> false

lib.strings.versionOlder

v1, v2

Return true if string v1 denotes a version older than v2.

lib.strings.versionOlder usage example:

versionOlder "1.1" "1.2"
=> true
versionOlder "1.1" "1.1"
=> false

lib.strings.withFeature

with, feat_

Create an –{with,without}- string that can be passed to standard GNU Autoconf scripts.

lib.strings.withFeature usage example:

withFeature true "shared"
=> "--with-shared"
withFeature false "shared"
=> "--without-shared"

lib.strings.withFeatureAs

with, feat, value_

Create an –{with-=,without-} string that can be passed to standard GNU Autoconf scripts.

lib.strings.withFeatureAs usage example:

withFeatureAs true "shared" "foo"
=> "--with-shared=foo"
withFeatureAs false "shared" (throw "ignored")
=> "--without-shared"

Miscellaneous functions

lib.trivial.and

x, y

boolean “and”

lib.trivial.bitAnd

__

bitwise “and”

lib.trivial.bitNot

__

bitwise “not”

lib.trivial.bitOr

__

bitwise “or”

lib.trivial.bitXor

__

bitwise “xor”

lib.trivial.boolToString

b

boolToString :: bool -> string

Convert a boolean to a string.

lib.trivial.checkListOfEnum

msg, valid, given

String -> List ComparableVal -> List ComparableVal -> a -> a

Check if the elements in a list are valid values from a enum, returning the identity function, or throwing an error message otherwise.

lib.trivial.checkListOfEnum usage example:

let colorVariants = ["bright" "dark" "black"]
in checkListOfEnum "color variants" [ "standard" "light" "dark" ] colorVariants;
=>
error: color variants: bright, black unexpected; valid ones: standard, light, dark

lib.trivial.codeName

__

Returns the current nixpkgs release code name.

lib.trivial.compare

a, b

C-style comparisons

lib.trivial.concat

x, y

concat :: [a] -> [a] -> [a]

Concatenate two lists

lib.trivial.concat usage example:

concat [ 1 2 ] [ 3 4 ]
=> [ 1 2 3 4 ]

lib.trivial.const

x, y

const :: a -> b -> a

The constant function

lib.trivial.const usage example:

let f = const 5; in f 10
=> 5

lib.trivial.flip

f, a, b

flip :: (a -> b -> c) -> (b -> a -> c)

Flip the order of the arguments of a binary function.

lib.trivial.flip usage example:

flip concat [1] [2]
=> [ 2 1 ]

lib.trivial.functionArgs

f

Extract the expected function arguments from a function. This works both with nix-native { a, b ? foo, … }: style functions and functions with args set with ‘setFunctionArgs’. It has the same return type and semantics as builtins.functionArgs. setFunctionArgs : (a → b) → Map String Bool.

lib.trivial.id

x

id :: a -> a

The identity function For when you need a function that does “nothing”.

lib.trivial.importJSON

path

Reads a JSON file.

lib.trivial.importTOML

path

Reads a TOML file.

lib.trivial.inNixShell

__

inNixShell :: bool

Determine whether the function is being called from inside a Nix shell.

lib.trivial.inPureEvalMode

__

inPureEvalMode :: bool

Determine whether the function is being called from inside pure-eval mode by seeing whether builtins contains currentSystem. If not, we must be in pure-eval mode.

lib.trivial.isFunction

f

Check whether something is a function or something annotated with function args.

lib.trivial.isInOldestRelease

release

Whether a feature is supported in all supported releases (at the time of release branch-off, if applicable). See oldestSupportedRelease.

lib.trivial.mapNullable

f, a

Apply function if the supplied argument is non-null.

lib.trivial.mapNullable usage example:

mapNullable (x: x+1) null
=> null
mapNullable (x: x+1) 22
=> 23

lib.trivial.max

x, y

Return maximum of two numbers.

lib.trivial.mergeAttrs

x, y

Merge two attribute sets shallowly, right side trumps left

lib.trivial.mergeAttrs usage example:

mergeAttrs { a = 1; b = 2; } { b = 3; c = 4; }
=> { a = 1; b = 3; c = 4; }

lib.trivial.min

x, y

Return minimum of two numbers.

lib.trivial.mod

base, int

Integer modulus

lib.trivial.mod usage example:

mod 11 10
=> 1
mod 1 10
=> 1

lib.trivial.oldestSupportedRelease

__

The latest release that is supported, at the time of release branch-off, if applicable.

lib.trivial.or

x, y

boolean “or”

lib.trivial.pipe

val, functions

pipe :: a -> [<functions>] -> <return type of last function>

Pipes a value through a list of functions, left to right.

lib.trivial.pipe usage example:

pipe 2 [
(x: x + 2)  # 2 + 2 = 4
(x: x * 2)  # 4 * 2 = 8
]
=> 8

# ideal to do text transformations
pipe [ "a/b" "a/c" ] [

# create the cp command
(map (file: ''cp "${src}/${file}" $out\n''))

# concatenate all commands into one string
lib.concatStrings

# make that string into a nix derivation
(pkgs.runCommand "copy-to-out" {})

]
=> <drv which copies all files to $out>

The output type of each function has to be the input type
of the next function, and the last function returns the
final value.

lib.trivial.release

__

Returns the current nixpkgs release number as string.

lib.trivial.revisionWithDefault

default

revisionWithDefault :: string -> string

Attempts to return the the current revision of nixpkgs and returns the supplied default value otherwise.

lib.trivial.setFunctionArgs

f, args

Add metadata about expected function arguments to a function. The metadata should match the format given by builtins.functionArgs, i.e. a set from expected argument to a bool representing whether that argument has a default or not. setFunctionArgs : (a → b) → Map String Bool → (a → b)

lib.trivial.splitByAndCompare

p, yes, no, a, b

(a -> bool) -> (a -> a -> int) -> (a -> a -> int) -> (a -> a -> int)

Split type into two subtypes by predicate p, take all elements of the first subtype to be less than all the elements of the second subtype, compare elements of a single subtype with yes and no respectively.

lib.trivial.splitByAndCompare usage example:

let cmp = splitByAndCompare (hasPrefix "foo") compare compare; in

cmp "a" "z" => -1
cmp "fooa" "fooz" => -1

cmp "f" "a" => 1
cmp "fooa" "a" => -1
# while
compare "fooa" "a" => 1

lib.trivial.throwIf

cond, msg

bool -> string -> a -> a

Like throwIfNot, but negated (throw if the first argument is true).

lib.trivial.throwIfNot

cond, msg

bool -> string -> a -> a

Like the assert b; e expression, but with a custom error message and without the semicolon.

lib.trivial.throwIfNot usage example:

throwIfNot (lib.isList overlays) "The overlays argument to nixpkgs must be a list."
lib.foldr (x: throwIfNot (lib.isFunction x) "All overlays passed to nixpkgs must be functions.") (r: r) overlays
pkgs

lib.trivial.toBaseDigits

base, i

toBaseDigits base i converts the positive integer i to a list of its digits in the given base. For example:

lib.trivial.toFunction

v

Turns any non-callable values into constant functions. Returns callable values as is.

lib.trivial.toFunction usage example:

nix-repl> lib.toFunction 1 2
1

nix-repl> lib.toFunction (x: x + 1) 2
3

lib.trivial.toHexString

i

Convert the given positive integer to a string of its hexadecimal representation. For example:

lib.trivial.version

__

Returns the current full nixpkgs version number.

lib.trivial.versionSuffix

__

Returns the current nixpkgs version suffix as string.

lib.trivial.warn

__

string -> a -> a

Print a warning before returning the second argument. This function behaves like builtins.trace, but requires a string message and formats it as a warning, including the warning: prefix.

lib.trivial.warnIf

cond, msg

bool -> string -> a -> a

Like warn, but only warn when the first argument is true.

lib.trivial.warnIfNot

cond, msg

bool -> string -> a -> a

Like warnIf, but negated (warn if the first argument is false).

Theme: jez/pandoc-markdown-css-theme