Type: assertMsg :: Bool -> String -> Bool

Throw if pred is false, else return pred. Intended to be used to augment asserts with helpful error messages.

assertMsg false "nope"
stderr> error: nope

assert assertMsg ("foo" == "bar") "foo is not bar, silly"; ""
stderr> error: foo is not bar, silly

Located at lib/asserts.nix:19 in <nixpkgs>.

Type: assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool

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

let sslLibrary = "libressl";
in assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ]
stderr> error: sslLibrary must be one of [
stderr>   "openssl"
stderr>   "bearssl"
stderr> ], but is: "libressl"

Located at lib/asserts.nix:40 in <nixpkgs>.

Type: assertEachOneOf :: String -> List ComparableVal -> List ComparableVal -> Bool

Specialized assertMsg for checking if every one of vals is one of the elements of the list xs. Useful for checking lists of supported attributes.

let sslLibraries = [ "libressl" "bearssl" ];
in assertEachOneOf "sslLibraries" sslLibraries [ "openssl" "bearssl" ]
stderr> error: each element in sslLibraries must be one of [
stderr>   "openssl"
stderr>   "bearssl"
stderr> ], but is: [
stderr>   "libressl"
stderr>   "bearssl"
stderr> ]

Located at lib/asserts.nix:70 in <nixpkgs>.

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

Return an attribute from nested attribute sets.

x = { a = { b = 3; }; }
# ["a" "b"] is equivalent to x.a.b
# 6 is a default value to return if the path does not exist in attrset
attrByPath ["a" "b"] 6 x
=> 3
attrByPath ["z" "z"] 6 x
=> 6

Located at lib/attrsets.nix:30 in <nixpkgs>.

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

Return if an attribute from nested attribute set exists.

Laws:

x = { a = { b = 3; }; }
hasAttrByPath ["a" "b"] x
=> true
hasAttrByPath ["z" "z"] x
=> false
hasAttrByPath [] (throw "no need")
=> true

Located at lib/attrsets.nix:63 in <nixpkgs>.

Type: attrsets.longestValidPathPrefix :: [String] -> Value -> [String]

Return the longest prefix of an attribute path that refers to an existing attribute in a nesting of attribute sets.

Can be used after mapAttrsRecursiveCond to apply a condition, although this will evaluate the predicate function on sibling attributes as well.

Note that the empty attribute path is valid for all values, so this function only throws an exception if any of its inputs does.

Laws:

x = { a = { b = 3; }; }
attrsets.longestValidPathPrefix ["a" "b" "c"] x
=> ["a" "b"]
attrsets.longestValidPathPrefix ["a"] x
=> ["a"]
attrsets.longestValidPathPrefix ["z" "z"] x
=> []
attrsets.longestValidPathPrefix ["z" "z"] (throw "no need")
=> []

Located at lib/attrsets.nix:107 in <nixpkgs>.

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

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

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

Located at lib/attrsets.nix:150 in <nixpkgs>.

Type: getAttrFromPath :: [String] -> AttrSet -> Any

Like attrByPath, but without a default value. If it doesn’t find the path it will throw an error.

x = { a = { b = 3; }; }
getAttrFromPath ["a" "b"] x
=> 3
getAttrFromPath ["z" "z"] x
=> error: cannot find attribute `z.z'

Located at lib/attrsets.nix:176 in <nixpkgs>.

Type: concatMapAttrs :: (String -> a -> AttrSet) -> AttrSet -> AttrSet

Map each attribute in the given set and merge them into a new attribute set.

concatMapAttrs
  (name: value: {
    ${name} = value;
    ${name + value} = value;
  })
  { x = "a"; y = "b"; }
=> { x = "a"; xa = "a"; y = "b"; yb = "b"; }

Located at lib/attrsets.nix:198 in <nixpkgs>.

Type: updateManyAttrsByPath :: [{ path :: [String]; update :: (Any -> Any); }] -> AttrSet -> AttrSet

Update or set specific paths of an attribute set.

Takes a list of updates to apply and an attribute set to apply them to, and returns the attribute set with the updates applied. Updates are represented as { path = ...; update = ...; } values, where path is a list of strings representing the attribute path that should be updated, and update is a function that takes the old value at that attribute path as an argument and returns the new value it should be.

Properties:

updateManyAttrsByPath [
  {
    path = [ "a" "b" ];
    update = old: { d = old.c; };
  }
  {
    path = [ "a" "b" "c" ];
    update = old: old + 1;
  }
  {
    path = [ "x" "y" ];
    update = old: "xy";
  }
] { a.b.c = 0; }
=> { a = { b = { d = 1; }; }; x = { y = "xy"; }; }

Located at lib/attrsets.nix:249 in <nixpkgs>.

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

Return the specified attributes from a set.

attrVals ["a" "b" "c"] as
=> [as.a as.b as.c]

Located at lib/attrsets.nix:317 in <nixpkgs>.

Type: attrValues :: AttrSet -> [Any]

Return the values of all attributes in the given set, sorted by attribute name.

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

Located at lib/attrsets.nix:334 in <nixpkgs>.

Type: getAttrs :: [String] -> AttrSet -> AttrSet

Given a set of attribute names, return the set of the corresponding attributes from the given set.

getAttrs [ "a" "b" ] { a = 1; b = 2; c = 3; }
=> { a = 1; b = 2; }

Located at lib/attrsets.nix:347 in <nixpkgs>.

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

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

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

Located at lib/attrsets.nix:363 in <nixpkgs>.

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

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

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

Located at lib/attrsets.nix:377 in <nixpkgs>.

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

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

filterAttrsRecursive (n: v: v != null) { foo = { bar = null; }; }
=> { foo = {}; }

Located at lib/attrsets.nix:395 in <nixpkgs>.

Type: foldlAttrs :: ( a -> String -> b -> a ) -> a -> { ... :: b } -> a

Like lib.lists.foldl' but for attribute sets. Iterates over every name-value pair in the given attribute set. The result of the callback function is often called acc for accumulator. It is passed between callbacks from left to right and the final acc is the return value of foldlAttrs.

Attention: There is a completely different function lib.foldAttrs which has nothing to do with this function, despite the similar name.

foldlAttrs
  (acc: name: value: {
    sum = acc.sum + value;
    names = acc.names ++ [name];
  })
  { sum = 0; names = []; }
  {
    foo = 1;
    bar = 10;
  }
->
  {
    sum = 11;
    names = ["bar" "foo"];
  }

foldlAttrs
  (throw "function not needed")
  123
  {};
->
  123

foldlAttrs
  (acc: _: _: acc)
  3
  { z = throw "value not needed"; a = throw "value not needed"; };
->
  3

The accumulator doesn't have to be an attrset.
It can be as simple as a number or string.

foldlAttrs
  (acc: _: v: acc * 10 + v)
  1
  { z = 1; a = 2; };
->
  121

Located at lib/attrsets.nix:466 in <nixpkgs>.

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

Apply fold functions to values grouped by key.

foldAttrs (item: acc: [item] ++ acc) [] [{ a = 2; } { a = 3; }]
=> { a = [ 2 3 ]; }

Located at lib/attrsets.nix:482 in <nixpkgs>.

Type: collect :: (AttrSet -> Bool) -> AttrSet -> [x]

Recursively collect sets that verify a given predicate named pred from the set attrs. The recursion is stopped when the predicate is verified.

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

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

Located at lib/attrsets.nix:511 in <nixpkgs>.

Type: cartesianProductOfSets :: AttrSet -> [AttrSet]

Return the cartesian product of attribute set value combinations.

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

Located at lib/attrsets.nix:536 in <nixpkgs>.

Type: nameValuePair :: String -> Any -> { name :: String; value :: Any; }

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

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

Located at lib/attrsets.nix:555 in <nixpkgs>.

Type: mapAttrs :: (String -> Any -> Any) -> AttrSet -> AttrSet

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

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

Located at lib/attrsets.nix:573 in <nixpkgs>.

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

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

Located at lib/attrsets.nix:590 in <nixpkgs>.

Type: mapAttrsToList :: (String -> a -> b) -> AttrSet -> [b]

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

mapAttrsToList (name: value: name + value)
   { x = "a"; y = "b"; }
=> [ "xa" "yb" ]

Located at lib/attrsets.nix:610 in <nixpkgs>.

Type: attrsToList :: AttrSet -> [ { name :: String; value :: Any; } ]

Deconstruct an attrset to a list of name-value pairs as expected by builtins.listToAttrs. Each element of the resulting list is an attribute set with these attributes:

The following is always true:

builtins.listToAttrs (attrsToList attrs) == attrs

attrsToList (builtins.listToAttrs list) != list

attrsToList { foo = 1; bar = "asdf"; }
=> [ { name = "bar"; value = "asdf"; } { name = "foo"; value = 1; } ]

Located at lib/attrsets.nix:645 in <nixpkgs>.

Type: mapAttrsRecursive :: ([String] -> a -> b) -> AttrSet -> AttrSet

Like mapAttrs, except that it recursively applies itself to the leaf attributes of a potentially-nested attribute set: the second argument of the function will never be an attrset. Also, the first argument of the argument function is a list of the attribute names that form the path to the leaf attribute.

For a function that gives you control over what counts as a leaf, see mapAttrsRecursiveCond.

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

Located at lib/attrsets.nix:665 in <nixpkgs>.

Type: mapAttrsRecursiveCond :: (AttrSet -> Bool) -> ([String] -> a -> b) -> AttrSet -> AttrSet

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

# To prevent recursing into derivations (which are attribute
# sets with the attribute "type" equal to "derivation"):
mapAttrsRecursiveCond
  (as: !(as ? "type" && as.type == "derivation"))
  (x: ... do something ...)
  attrs

Located at lib/attrsets.nix:690 in <nixpkgs>.

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

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

genAttrs [ "foo" "bar" ] (name: "x_" + name)
=> { foo = "x_foo"; bar = "x_bar"; }

Located at lib/attrsets.nix:719 in <nixpkgs>.

Type: isDerivation :: Any -> Bool

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

nixpkgs = import <nixpkgs> {}
isDerivation nixpkgs.ruby
=> true
isDerivation "foobar"
=> false

Located at lib/attrsets.nix:740 in <nixpkgs>.

Type: toDerivation :: Path -> Derivation

Converts a store path to a fake derivation.

Located at lib/attrsets.nix:749 in <nixpkgs>.

Type: optionalAttrs :: Bool -> AttrSet -> AttrSet

If cond is true, return the attribute set as, otherwise an empty attribute set.

optionalAttrs (true) { my = "set"; }
=> { my = "set"; }
optionalAttrs (false) { my = "set"; }
=> { }

Located at lib/attrsets.nix:777 in <nixpkgs>.

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

Merge sets of attributes and use the function f to merge attributes values.

zipAttrsWithNames ["a"] (name: vs: vs) [{a = "x";} {a = "y"; b = "z";}]
=> { a = ["x" "y"]; }

Located at lib/attrsets.nix:795 in <nixpkgs>.

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

Merge sets of attributes and use the function f to merge attribute values. Like lib.attrsets.zipAttrsWithNames with all key names are passed for names.

Implementation note: Common names appear multiple times in the list of names, hopefully this does not affect the system because the maximal laziness avoid computing twice the same expression and listToAttrs does not care about duplicated attribute names.

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

Located at lib/attrsets.nix:823 in <nixpkgs>.

Type: zipAttrs :: [ AttrSet ] -> AttrSet

Merge sets of attributes and combine each attribute value in to a list.

Like lib.attrsets.zipAttrsWith with (name: values: values) as the function.

zipAttrs [{a = "x";} {a = "y"; b = "z";}]
=> { a = ["x" "y"]; b = ["z"]; }

Located at lib/attrsets.nix:838 in <nixpkgs>.

Type: mergeAttrsList :: [ Attrs ] -> Attrs

Merge a list of attribute sets together using the // operator. In case of duplicate attributes, values from later list elements take precedence over earlier ones. The result is the same as foldl mergeAttrs { }, but the performance is better for large inputs. For n list elements, each with an attribute set containing m unique attributes, the complexity of this operation is O(nm log n).

mergeAttrsList [ { a = 0; b = 1; } { c = 2; d = 3; } ]
=> { a = 0; b = 1; c = 2; d = 3; }
mergeAttrsList [ { a = 0; } { a = 1; } ]
=> { a = 1; }

Located at lib/attrsets.nix:858 in <nixpkgs>.

Type: 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 satisfied, the value of the first attribute set is replaced by the value of the second attribute set.

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
}

Located at lib/attrsets.nix:910 in <nixpkgs>.

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

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

returns: {
  boot.loader.grub.enable = true;
  boot.loader.grub.device = "";
}

Located at lib/attrsets.nix:950 in <nixpkgs>.

Type: matchAttrs :: AttrSet -> AttrSet -> Bool

Recurse into every attribute set of the first argument and check that:

matchAttrs { cpu = {}; } { cpu = { bits = 64; }; }
=> true

Located at lib/attrsets.nix:970 in <nixpkgs>.

Type: overrideExisting :: AttrSet -> AttrSet -> AttrSet

Override only the attributes that are already present in the old set useful for deep-overriding.

overrideExisting {} { a = 1; }
=> {}
overrideExisting { b = 2; } { a = 1; }
=> { b = 2; }
overrideExisting { a = 3; b = 2; } { a = 1; }
=> { a = 1; b = 2; }

Located at lib/attrsets.nix:1006 in <nixpkgs>.

Type: showAttrPath :: [String] -> String

Turns a list of strings into a human-readable description of those strings represented as an attribute path. The result of this function is not intended to be machine-readable. Create a new attribute set with value set at the nested attribute location specified in attrPath.

showAttrPath [ "foo" "10" "bar" ]
=> "foo.\"10\".bar"
showAttrPath []
=> "<root attribute path>"

Located at lib/attrsets.nix:1028 in <nixpkgs>.

Type: getOutput :: String -> Derivation -> String

Get a package output. If no output is found, fallback to .out and then to the default.

getOutput "dev" pkgs.openssl
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev"

Located at lib/attrsets.nix:1045 in <nixpkgs>.

Type: getBin :: Derivation -> String

Get a package’s bin output. If the output does not exist, fallback to .out and then to the default.

getBin pkgs.openssl
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r"

Located at lib/attrsets.nix:1060 in <nixpkgs>.

Type: getLib :: Derivation -> String

Get a package’s lib output. If the output does not exist, fallback to .out and then to the default.

getLib pkgs.openssl
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-lib"

Located at lib/attrsets.nix:1073 in <nixpkgs>.

Type: getDev :: Derivation -> String

Get a package’s dev output. If the output does not exist, fallback to .out and then to the default.

getDev pkgs.openssl
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev"

Located at lib/attrsets.nix:1086 in <nixpkgs>.

Type: getMan :: Derivation -> String

Get a package’s man output. If the output does not exist, fallback to .out and then to the default.

getMan pkgs.openssl
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-man"

Located at lib/attrsets.nix:1099 in <nixpkgs>.

Type: chooseDevOutputs :: [Derivation] -> [String]

Pick the outputs of packages to place in buildInputs

Located at lib/attrsets.nix:1106 in <nixpkgs>.

Type: recurseIntoAttrs :: AttrSet -> AttrSet

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

This function only affects a single attribute set; it does not apply itself recursively for nested attribute sets.

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

Located at lib/attrsets.nix:1129 in <nixpkgs>.

Type: dontRecurseIntoAttrs :: AttrSet -> AttrSet

Undo the effect of recurseIntoAttrs.

Located at lib/attrsets.nix:1139 in <nixpkgs>.

Type: unionOfDisjoint :: AttrSet -> AttrSet -> AttrSet

unionOfDisjoint x y is equal to x // y // z where the attrnames in z are the intersection of the attrnames in x and y, and all values assert with an error message. This operator is commutative, unlike (//).

Located at lib/attrsets.nix:1151 in <nixpkgs>.

Type: concatStrings :: [string] -> string

Concatenate a list of strings.

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

Located at lib/strings.nix:50 in <nixpkgs>.

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

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

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

Located at lib/strings.nix:60 in <nixpkgs>.

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

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

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

Located at lib/strings.nix:71 in <nixpkgs>.

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

Place an element between each element of a list

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

Located at lib/strings.nix:81 in <nixpkgs>.

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

Concatenate a list of strings with a separator between each element

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

Located at lib/strings.nix:98 in <nixpkgs>.

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

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

Located at lib/strings.nix:111 in <nixpkgs>.

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

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

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

Located at lib/strings.nix:128 in <nixpkgs>.

Type: concatLines :: [string] -> string

Concatenate a list of strings, adding a newline at the end of each one. Defined as concatMapStrings (s: s + "\n").

concatLines [ "foo" "bar" ]
=> "foo\nbar\n"

Located at lib/strings.nix:145 in <nixpkgs>.

Type: replicate :: int -> string -> string

Replicate a string n times, and concatenate the parts into a new string.

replicate 3 "v"
=> "vvv"
replicate 5 "hello"
=> "hellohellohellohellohello"

Located at lib/strings.nix:159 in <nixpkgs>.

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

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

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

Located at lib/strings.nix:172 in <nixpkgs>.

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

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

Located at lib/strings.nix:190 in <nixpkgs>.

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

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"

Located at lib/strings.nix:208 in <nixpkgs>.

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

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

Located at lib/strings.nix:217 in <nixpkgs>.

Type: normalizePath :: string -> string

Normalize path, removing extraneous /s

normalizePath "/a//b///c/"
=> "/a/b/c/"

Located at lib/strings.nix:227 in <nixpkgs>.

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

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

Located at lib/strings.nix:253 in <nixpkgs>.

Type: hasPrefix :: string -> string -> bool

Determine whether a string has given prefix.

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

Located at lib/strings.nix:269 in <nixpkgs>.

Type: hasSuffix :: string -> string -> bool

Determine whether a string has given suffix.

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

Located at lib/strings.nix:296 in <nixpkgs>.

Type: hasInfix :: string -> string -> bool

Determine whether a string contains the given infix

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

Located at lib/strings.nix:333 in <nixpkgs>.

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

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

Located at lib/strings.nix:363 in <nixpkgs>.

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

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

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

Located at lib/strings.nix:375 in <nixpkgs>.

Type: charToInt :: string -> int

Convert char to ascii value, must be in printable range

charToInt "A"
=> 65
charToInt "("
=> 40

Located at lib/strings.nix:394 in <nixpkgs>.

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

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

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

Located at lib/strings.nix:405 in <nixpkgs>.

Type: escapeC = [string] -> string -> string

Escape occurrence of the element of list in string by converting to its ASCII value and prefixing it with \x. Only works for printable ascii characters.

escapeC [" "] "foo bar"
=> "foo\\x20bar"

Located at lib/strings.nix:418 in <nixpkgs>.

Type: escapeURL :: string -> string

Escape the string so it can be safely placed inside a URL query.

escapeURL "foo/bar baz"
=> "foo%2Fbar%20baz"

Located at lib/strings.nix:429 in <nixpkgs>.

Type: escapeShellArg :: string -> string

Quote string to be used safely within the Bourne shell.

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

Located at lib/strings.nix:443 in <nixpkgs>.

Type: escapeShellArgs :: [string] -> string

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

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

Located at lib/strings.nix:453 in <nixpkgs>.

Type: string -> bool

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

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

Located at lib/strings.nix:465 in <nixpkgs>.

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

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

The value can be a string (mapped to a regular variable), a list of strings (mapped to a Bash-style array) or an attribute set of strings (mapped to a Bash-style associative array). Note that “string” includes string-coercible values like paths or derivations.

Strings are translated into POSIX sh-compatible code; lists and attribute sets assume a shell that understands Bash syntax (e.g. Bash or ZSH).

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

Located at lib/strings.nix:485 in <nixpkgs>.

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

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

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

Located at lib/strings.nix:513 in <nixpkgs>.

Type: string -> string

Turn a string into a Nix expression representing that string

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

Located at lib/strings.nix:523 in <nixpkgs>.

Type: string -> string

Turn a string into an exact regular expression

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

Located at lib/strings.nix:533 in <nixpkgs>.

Type: string -> string

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

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

Located at lib/strings.nix:545 in <nixpkgs>.

Type: string -> string

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

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

Located at lib/strings.nix:559 in <nixpkgs>.

Type: toLower :: string -> string

Converts an ASCII string to lower-case.

toLower "HOME"
=> "home"

Located at lib/strings.nix:578 in <nixpkgs>.

Type: toUpper :: string -> string

Converts an ASCII string to upper-case.

toUpper "home"
=> "HOME"

Located at lib/strings.nix:588 in <nixpkgs>.

Appends string context from another string. This is an implementation detail of Nix and should be used carefully.

Strings in Nix carry an invisible context which is a list of strings representing store paths. If the string is later used in a derivation attribute, the derivation will properly populate the inputDrvs and inputSrcs.

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

Located at lib/strings.nix:603 in <nixpkgs>.

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

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

Located at lib/strings.nix:614 in <nixpkgs>.

Type: string -> string -> string

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

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

Located at lib/strings.nix:630 in <nixpkgs>.

Type: string -> string -> string

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

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

Located at lib/strings.nix:663 in <nixpkgs>.

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

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

Located at lib/strings.nix:694 in <nixpkgs>.

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

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

Located at lib/strings.nix:706 in <nixpkgs>.

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

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

Located at lib/strings.nix:718 in <nixpkgs>.

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

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

Located at lib/strings.nix:735 in <nixpkgs>.

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

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"

Located at lib/strings.nix:751 in <nixpkgs>.

Type:

cmakeOptionType :: string -> string -> string -> string

@param feature The feature to be set
@param type The type of the feature to be set, as described in
            https://cmake.org/cmake/help/latest/command/set.html
            the possible values (case insensitive) are:
            BOOL FILEPATH PATH STRING INTERNAL
@param value The desired value

Create a “-D<feature>:<type>=<value>” string that can be passed to typical CMake invocations.

cmakeOptionType "string" "ENGINE" "sdl2"
=> "-DENGINE:STRING=sdl2"

Located at lib/strings.nix:774 in <nixpkgs>.

Type:

cmakeBool :: string -> bool -> string

@param condition The condition to be made true or false
@param flag The controlling flag of the condition

Create a -D<condition>={TRUE,FALSE} string that can be passed to typical CMake invocations.

cmakeBool "ENABLE_STATIC_LIBS" false
=> "-DENABLESTATIC_LIBS:BOOL=FALSE"

Located at lib/strings.nix:793 in <nixpkgs>.

Type:

cmakeFeature :: string -> string -> string

@param condition The condition to be made true or false
@param flag The controlling flag of the condition

Create a -D<feature>:STRING=<value> string that can be passed to typical CMake invocations. This is the most typical usage, so it deserves a special case.

cmakeFeature "MODULES" "badblock"
=> "-DMODULES:STRING=badblock"

Located at lib/strings.nix:811 in <nixpkgs>.

Type:

mesonOption :: string -> string -> string

@param feature The feature to be set
@param value The desired value

Create a -D<feature>=<value> string that can be passed to typical Meson invocations.

mesonOption "engine" "opengl"
=> "-Dengine=opengl"

Located at lib/strings.nix:828 in <nixpkgs>.

Type:

mesonBool :: string -> bool -> string

@param condition The condition to be made true or false
@param flag The controlling flag of the condition

Create a -D<condition>={true,false} string that can be passed to typical Meson invocations.

mesonBool "hardened" true
=> "-Dhardened=true"
mesonBool "static" false
=> "-Dstatic=false"

Located at lib/strings.nix:847 in <nixpkgs>.

Type:

mesonEnable :: string -> bool -> string

@param feature The feature to be enabled or disabled
@param flag The controlling flag

Create a -D<feature>={enabled,disabled} string that can be passed to typical Meson invocations.

mesonEnable "docs" true
=> "-Ddocs=enabled"
mesonEnable "savage" false
=> "-Dsavage=disabled"

Located at lib/strings.nix:866 in <nixpkgs>.

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

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

Located at lib/strings.nix:880 in <nixpkgs>.

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

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

Located at lib/strings.nix:894 in <nixpkgs>.

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

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

Located at lib/strings.nix:906 in <nixpkgs>.

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

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

Located at lib/strings.nix:919 in <nixpkgs>.

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

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

This function will fail if the input string is longer than the requested length.

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

Located at lib/strings.nix:934 in <nixpkgs>.

Format a number adding leading zeroes up to fixed width.

fixedWidthNumber 5 15
=> "00015"

Located at lib/strings.nix:951 in <nixpkgs>.

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

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

Located at lib/strings.nix:963 in <nixpkgs>.

Soft-deprecated function. While the original implementation is available as isConvertibleWithToString, consider using isStringLike instead, if suitable.

Located at lib/strings.nix:971 in <nixpkgs>.

Check whether a list or other value can be passed to toString.

Many types of value are coercible to string this way, including int, float, null, bool, list of similarly coercible values.

Located at lib/strings.nix:980 in <nixpkgs>.

Check whether a value can be coerced to a string. The value must be a string, path, or attribute set.

String-like values can be used without explicit conversion in string interpolations and in most functions that expect a string.

Located at lib/strings.nix:991 in <nixpkgs>.

Check whether a value is a store path.

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

Located at lib/strings.nix:1009 in <nixpkgs>.

Type: string -> int

Parse a string as an int. Does not support parsing of integers with preceding zero due to ambiguity between zero-padded and octal numbers. See toIntBase10.

toInt "1337"
=> 1337

toInt "-4"
=> -4

toInt " 123 "
=> 123

toInt "00024"
=> error: Ambiguity in interpretation of 00024 between octal and zero padded integer.

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

Located at lib/strings.nix:1039 in <nixpkgs>.

Type: string -> int

Parse a string as a base 10 int. This supports parsing of zero-padded integers.

toIntBase10 "1337"
=> 1337

toIntBase10 "-4"
=> -4

toIntBase10 " 123 "
=> 123

toIntBase10 "00024"
=> 24

toIntBase10 "3.14"
=> error: floating point JSON numbers are not supported

Located at lib/strings.nix:1090 in <nixpkgs>.

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

NOTE: This function is not performant and should be avoided.

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

Located at lib/strings.nix:1133 in <nixpkgs>.

Type: fileContents :: path -> string

Read the contents of a file removing the trailing \n

$ echo "1.0" > ./version

fileContents ./version
=> "1.0"

Located at lib/strings.nix:1153 in <nixpkgs>.

Type: sanitizeDerivationName :: String -> String

Creates a valid derivation name from a potentially invalid one.

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

Located at lib/strings.nix:1168 in <nixpkgs>.

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

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

Located at lib/strings.nix:1207 in <nixpkgs>.

Returns the length of the prefix common to both strings.

Located at lib/strings.nix:1228 in <nixpkgs>.

Returns the length of the suffix common to both strings.

Located at lib/strings.nix:1236 in <nixpkgs>.

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

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

Located at lib/strings.nix:1260 in <nixpkgs>.

Break a version string into its component parts.

splitVersion "1.2.3"
=> ["1" "2" "3"]

Located at lib/versions.nix:12 in <nixpkgs>.

Get the major version string from a string.

major "1.2.3"
=> "1"

Located at lib/versions.nix:20 in <nixpkgs>.

Get the minor version string from a string.

minor "1.2.3"
=> "2"

Located at lib/versions.nix:28 in <nixpkgs>.

Get the patch version string from a string.

patch "1.2.3"
=> "3"

Located at lib/versions.nix:36 in <nixpkgs>.

Get string of the first two parts (major and minor) of a version string.

majorMinor "1.2.3"
=> "1.2"

Located at lib/versions.nix:45 in <nixpkgs>.

Pad a version string with zeros to match the given number of components.

pad 3 "1.2"
=> "1.2.0"
pad 3 "1.3-rc1"
=> "1.3.0-rc1"
pad 3 "1.2.3.4"
=> "1.2.3"

Located at lib/versions.nix:59 in <nixpkgs>.

Type: id :: a -> a

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

Located at lib/trivial.nix:12 in <nixpkgs>.

Type: const :: a -> b -> a

The constant function

Ignores the second argument. If called with only one argument, constructs a function that always returns a static value.

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

Located at lib/trivial.nix:26 in <nixpkgs>.

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

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

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.

Located at lib/trivial.nix:61 in <nixpkgs>.

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

Concatenate two lists

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

Located at lib/trivial.nix:80 in <nixpkgs>.

boolean “or”

Located at lib/trivial.nix:83 in <nixpkgs>.

boolean “and”

Located at lib/trivial.nix:86 in <nixpkgs>.

bitwise “and”

Located at lib/trivial.nix:89 in <nixpkgs>.

bitwise “or”

Located at lib/trivial.nix:94 in <nixpkgs>.

bitwise “xor”

Located at lib/trivial.nix:99 in <nixpkgs>.

bitwise “not”

Located at lib/trivial.nix:104 in <nixpkgs>.

Type: boolToString :: bool -> string

Convert a boolean to a string.

This function uses the strings “true” and “false” to represent boolean values. Calling toString on a bool instead returns “1” and “” (sic!).

Located at lib/trivial.nix:114 in <nixpkgs>.

Merge two attribute sets shallowly, right side trumps left

mergeAttrs :: attrs -> attrs -> attrs

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

Located at lib/trivial.nix:124 in <nixpkgs>.

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

Flip the order of the arguments of a binary function.

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

Located at lib/trivial.nix:138 in <nixpkgs>.

Apply function if the supplied argument is non-null.

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

Located at lib/trivial.nix:148 in <nixpkgs>.

Returns the current full nixpkgs version number.

Located at lib/trivial.nix:164 in <nixpkgs>.

Returns the current nixpkgs release number as string.

Located at lib/trivial.nix:167 in <nixpkgs>.

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

Ideally, out-of-tree modules should be able to evaluate cleanly with all supported Nixpkgs versions (master, release and old release until EOL). So if possible, deprecation warnings should take effect only when all out-of-tree expressions/libs/modules can upgrade to the new way without losing support for supported Nixpkgs versions.

This release number allows deprecation warnings to be implemented such that they take effect as soon as the oldest release reaches end of life.

Located at lib/trivial.nix:180 in <nixpkgs>.

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

Located at lib/trivial.nix:186 in <nixpkgs>.

Returns the current nixpkgs release code name.

On each release the first letter is bumped and a new animal is chosen starting with that new letter.

Located at lib/trivial.nix:198 in <nixpkgs>.

Returns the current nixpkgs version suffix as string.

Located at lib/trivial.nix:201 in <nixpkgs>.

Type: revisionWithDefault :: string -> string

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

Located at lib/trivial.nix:212 in <nixpkgs>.

Type: inNixShell :: bool

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

Located at lib/trivial.nix:230 in <nixpkgs>.

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

Located at lib/trivial.nix:238 in <nixpkgs>.

Return minimum of two numbers.

Located at lib/trivial.nix:243 in <nixpkgs>.

Return maximum of two numbers.

Located at lib/trivial.nix:246 in <nixpkgs>.

Integer modulus

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

Located at lib/trivial.nix:256 in <nixpkgs>.

C-style comparisons

a < b, compare a b => -1 a == b, compare a b => 0 a > b, compare a b => 1

Located at lib/trivial.nix:267 in <nixpkgs>.

Type: (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.

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

Located at lib/trivial.nix:292 in <nixpkgs>.

Type: importJSON :: path -> any

Reads a JSON file.

Located at lib/trivial.nix:312 in <nixpkgs>.

Type: importTOML :: path -> any

Reads a TOML file.

Located at lib/trivial.nix:319 in <nixpkgs>.

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

To get a call stack trace and abort evaluation, set the environment variable NIX_ABORT_ON_WARN=true and set the Nix options --option pure-eval false --show-trace

Located at lib/trivial.nix:347 in <nixpkgs>.

Type: bool -> string -> a -> a

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

Located at lib/trivial.nix:357 in <nixpkgs>.

Type: bool -> string -> a -> a

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

Located at lib/trivial.nix:364 in <nixpkgs>.

Type: bool -> string -> a -> a

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

If true, return the identity function, r: r.

If false, throw the error message.

Calls can be juxtaposed using function application, as (r: r) a = a, so (r: r) (r: r) a = a, and so forth.

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

Located at lib/trivial.nix:386 in <nixpkgs>.

Type: bool -> string -> a -> a

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

Located at lib/trivial.nix:393 in <nixpkgs>.

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

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

Located at lib/trivial.nix:405 in <nixpkgs>.

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)

This function is necessary because you can’t dynamically create a function of the { a, b ? foo, … }: format, but some facilities like callPackage expect to be able to query expected arguments.

Located at lib/trivial.nix:428 in <nixpkgs>.

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.

Located at lib/trivial.nix:440 in <nixpkgs>.

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

Located at lib/trivial.nix:448 in <nixpkgs>.

Type: mirrorFunctionArgs :: (a -> b) -> (a -> c) -> (a -> c)

mirrorFunctionArgs f g creates a new function g' with the same behavior as g (g' x == g x) but its function arguments mirroring f (lib.functionArgs g' == lib.functionArgs f).

addab = {a, b}: a + b
addab { a = 2; b = 4; }
=> 6
lib.functionArgs addab
=> { a = false; b = false; }
addab1 = attrs: addab attrs + 1
addab1 { a = 2; b = 4; }
=> 7
lib.functionArgs addab1
=> { }
addab1' = lib.mirrorFunctionArgs addab addab1
addab1' { a = 2; b = 4; }
=> 7
lib.functionArgs addab1'
=> { a = false; b = false; }

Located at lib/trivial.nix:475 in <nixpkgs>.

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

nix-repl> lib.toFunction 1 2
1

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

Located at lib/trivial.nix:497 in <nixpkgs>.

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

toHexString 0 => “0”

toHexString 16 => “10”

toHexString 250 => “FA”

Located at lib/trivial.nix:513 in <nixpkgs>.

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

toBaseDigits 10 123 => [ 1 2 3 ]

toBaseDigits 2 6 => [ 1 1 0 ]

toBaseDigits 16 250 => [ 15 10 ]

Located at lib/trivial.nix:539 in <nixpkgs>.

Type: fix :: (a -> a) -> a

fix f computes the fixed point of the given function f. In other words, the return value is x in x = f x.

f must be a lazy function. This means that x must be a value that can be partially evaluated, such as an attribute set, a list, or a function. This way, f can use one part of x to compute another part.

Relation to syntactic recursion

This section explains fix by refactoring from syntactic recursion to a call of fix instead.

For context, Nix lets you define attributes in terms of other attributes syntactically using the rec { } syntax.

nix-repl> rec {
  foo = "foo";
  bar = "bar";
  foobar = foo + bar;
}
{ bar = "bar"; foo = "foo"; foobar = "foobar"; }

This is convenient when constructing a value to pass to a function for example, but an equivalent effect can be achieved with the let binding syntax:

nix-repl> let self = {
  foo = "foo";
  bar = "bar";
  foobar = self.foo + self.bar;
}; in self
{ bar = "bar"; foo = "foo"; foobar = "foobar"; }

But in general you can get more reuse out of let bindings by refactoring them to a function.

nix-repl> f = self: {
  foo = "foo";
  bar = "bar";
  foobar = self.foo + self.bar;
}

This is where fix comes in, it contains the syntactic recursion that’s not in f anymore.

nix-repl> fix = f:
  let self = f self; in self;

By applying fix we get the final result.

nix-repl> fix f
{ bar = "bar"; foo = "foo"; foobar = "foobar"; }

Such a refactored f using fix is not useful by itself. See extends for an example use case. There self is also often called final.

fix (self: { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; })
=> { bar = "bar"; foo = "foo"; foobar = "foobar"; }

fix (self: [ 1 2 (elemAt self 0 + elemAt self 1) ])
=> [ 1 2 3 ]

Located at lib/fixed-points.nix:75 in <nixpkgs>.

A variant of fix that records the original recursive attribute set in the result, in an attribute named __unfix__.

This is useful in combination with the extends function to implement deep overriding.

Located at lib/fixed-points.nix:84 in <nixpkgs>.

Type: (a -> a) -> a -> a

Return the fixpoint that f converges to when called iteratively, starting with the input x.

nix-repl> converge (x: x / 2) 16
0

Located at lib/fixed-points.nix:97 in <nixpkgs>.

Modify the contents of an explicitly recursive attribute set in a way that honors self-references. This is accomplished with a function

g = self: super: { foo = super.foo + " + "; }

that has access to the unmodified input (super) as well as the final non-recursive representation of the attribute set (self). extends differs from the native // operator insofar as that it’s applied before references to self are resolved:

nix-repl> fix (extends g f)
{ bar = "bar"; foo = "foo + "; foobar = "foo + bar"; }

The name of the function is inspired by object-oriented inheritance, i.e. think of it as an infix operator g extends f that mimics the syntax from Java. It may seem counter-intuitive to have the “base class” as the second argument, but it’s nice this way if several uses of extends are cascaded.

To get a better understanding how extends turns a function with a fix point (the package set we start with) into a new function with a different fix point (the desired packages set) lets just see, how extends g f unfolds with g and f defined above:

extends g f = self: let super = f self; in super // g self super;
            = self: let super = { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; }; in super // g self super
            = self: { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; } // g self { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; }
            = self: { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; } // { foo = "foo" + " + "; }
            = self: { foo = "foo + "; bar = "bar"; foobar = self.foo + self.bar; }

Located at lib/fixed-points.nix:141 in <nixpkgs>.

Compose two extending functions of the type expected by ‘extends’ into one where changes made in the first are available in the ‘super’ of the second

Located at lib/fixed-points.nix:148 in <nixpkgs>.

Compose several extending functions of the type expected by ‘extends’ into one where changes made in preceding functions are made available to subsequent ones.

composeManyExtensions : [packageSet -> packageSet -> packageSet] -> packageSet -> packageSet -> packageSet
                          ^final        ^prev         ^overrides     ^final        ^prev         ^overrides

Located at lib/fixed-points.nix:164 in <nixpkgs>.

Create an overridable, recursive attribute set. For example:

nix-repl> obj = makeExtensible (self: { })

nix-repl> obj
{ __unfix__ = «lambda»; extend = «lambda»; }

nix-repl> obj = obj.extend (self: super: { foo = "foo"; })

nix-repl> obj
{ __unfix__ = «lambda»; extend = «lambda»; foo = "foo"; }

nix-repl> obj = obj.extend (self: super: { foo = super.foo + " + "; bar = "bar"; foobar = self.foo + self.bar; })

nix-repl> obj
{ __unfix__ = «lambda»; bar = "bar"; extend = «lambda»; foo = "foo + "; foobar = "foo + bar"; }

Located at lib/fixed-points.nix:187 in <nixpkgs>.

Same as makeExtensible but the name of the extending attribute is customized.

Located at lib/fixed-points.nix:193 in <nixpkgs>.

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

singleton "foo"
=> [ "foo" ]

Located at lib/lists.nix:23 in <nixpkgs>.

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

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

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

Located at lib/lists.nix:36 in <nixpkgs>.

Type: 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)).

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"

Located at lib/lists.nix:53 in <nixpkgs>.

fold is an alias of foldr for historic reasons

Located at lib/lists.nix:64 in <nixpkgs>.

Type: 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).

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"