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

assertMsg :: Bool -> String -> Bool

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

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

assertOneOf :: String -> ComparableVal -> [ComparableVal] -> Bool

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

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.

assertEachOneOf :: String -> [ComparableVal] -> [ComparableVal] -> Bool

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

Wrap a value with logic that throws an error when assertions fail and emits any warnings.

checkAssertWarn :: [{ assertion :: Bool; message :: String; }] -> [String] -> a -> a

checkAssertWarn
  [ { assertion = false; message = "Will fail"; } ]
  [ ]
  null
stderr>        error:
stderr>        Failed assertions:
stderr>        - Will fail

checkAssertWarn
  [ { assertion = true; message = "Will not fail"; } ]
  [ "Will warn" ]
  null
stderr> evaluation warning: Will warn
null

Returns an attribute from nested attribute sets.

Nix has an attribute selection operator . which is sufficient for such queries, as long as the number of attributes is static. For example:

(x.a.b or 6) == attrByPath ["a" "b"] 6 x
# and
(x.${f p}."example.com" or 6) == attrByPath [ (f p) "example.com" ] 6 x

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

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

Returns if an attribute from nested attribute set exists.

Nix has a has attribute operator ?, which is sufficient for such queries, as long as the number of attributes is static. For example:

(x?a.b) == hasAttrByPath ["a" "b"] x
# and
(x?${f p}."example.com") == hasAttrByPath [ (f p) "example.com" ] x

Laws:

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

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

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

longestValidPathPrefix :: [String] -> AttrSet -> [String]

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")
=> []

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

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

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

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

Nix has an attribute selection operator which is sufficient for such queries, as long as the number of attributes is static. For example:

x.a.b == getAttrFromPath ["a" "b"] x
# and
x.${f p}."example.com" == getAttrFromPath [ (f p) "example.com" ] x

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

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

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

concatMapAttrs :: (String -> Any -> AttrSet) -> AttrSet -> AttrSet

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

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 :: [String]; update :: (Any -> Any); }] -> AttrSet -> AttrSet

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

Returns the specified attributes from a set.

attrVals :: [String] -> { [String] :: a } -> [a]

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

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

attrValues :: { [String] :: a } -> [a]

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

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

getAttrs :: [String] -> { [String] :: a } -> { [String] :: a }

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

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

catAttrs :: String -> [{ [String] :: a }] -> [a]

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

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

filterAttrs :: (String -> a -> Bool) -> { [String] :: a } -> { [String] :: a }

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

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

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

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

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.

foldlAttrs :: ( a -> String -> b -> a ) -> a -> { [String] :: b } -> a

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

Apply fold functions to values grouped by key.

foldAttrs :: (a -> b -> b) -> b -> [{ [String] :: a }] -> { [String] :: b }

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

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

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

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

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

Return the cartesian product of attribute set value combinations.

cartesianProduct :: { [String] :: [a] } -> [{ [String] :: a }]

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

Return the result of function f applied to the cartesian product of attribute set value combinations. Equivalent to using cartesianProduct followed by map.

mapCartesianProduct :: ({ [String] :: a } -> b) -> { [String] :: a } -> [b]

mapCartesianProduct ({a, b}: "${a}-${b}") { a = [ "1" "2" ]; b = [ "3" "4" ]; }
=> [ "1-3" "1-4" "2-3" "2-4" ]

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

nameValuePair :: String -> a -> { name :: String; value :: a; }

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

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

mapAttrs :: (String -> a -> b) -> { [String] :: a } -> { [String] :: b }

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

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' :: (String -> a -> { name :: String; value :: b; }) -> { [String] :: a } -> { [String] :: b }

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

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

mapAttrsToList :: (String -> a -> b) -> { [String] :: a } -> [b]

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

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 :: { [String] :: a } -> [{ name :: String; value :: a; }]

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

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

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

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

mapAttrsRecursiveCond
  (as: !(as ? "type" && as.type == "derivation"))
  (path: x: x.name)
  attrs

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

Apply a function to each leaf (non‐attribute‐set attribute) of a tree of nested attribute sets, returning the results of the function as a list, ordered lexicographically by their attribute paths.

Like mapAttrsRecursive, but concatenates the mapping function results into a list.

mapAttrsToListRecursive :: ([String] -> a -> b) -> AttrSet -> [b]

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

Determine the nodes of a tree of nested attribute sets by applying a predicate, then apply a function to the leaves, returning the results as a list, ordered lexicographically by their attribute paths.

Like mapAttrsToListRecursive, but takes an additional predicate to decide whether to recurse into an attribute set.

Unlike mapAttrsRecursiveCond this predicate receives the attribute path as its first argument, in addition to the attribute set.

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

mapAttrsToListRecursiveCond
  (path: as: !(lib.isDerivation as))
  (path: value: "--set=${lib.concatStringsSep "." path}=${toString value}")
  {
    rust.optimize = 2;
    target = {
      riscv64-unknown-linux-gnu.linker = pkgs.lld;
    };
  }
=> [ "--set=rust.optimize=2" "--set=target.riscv64-unknown-linux-gnu.linker=/nix/store/sjw4h1k…" ]

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

genAttrs :: [String] -> (String -> a) -> { [String] :: a }

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

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

genAttrs' :: [a] -> (a -> { name :: String; value :: b; }) -> { [String] :: b }

genAttrs' [ "foo" "bar" ] (s: nameValuePair ("x_" + s) ("y_" + s))
=> { x_foo = "y_foo"; x_bar = "y_bar"; }

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

isDerivation :: Any -> Bool

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

Converts a store path to a fake derivation.

toDerivation :: Path -> Derivation

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

optionalAttrs :: Bool -> AttrSet -> AttrSet

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

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

zipAttrsWithNames :: [String] -> (String -> [a] -> b) -> [{ [String] :: a }] -> { [String] :: b }

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

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 :: (String -> [a] -> b) -> [{ [String] :: a }] -> { [String] :: b }

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

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 :: [{ [String] :: a }] -> { [String] :: [a] }

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

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 :: [AttrSet] -> AttrSet

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

Update lhs so that rhs wins for any given attribute path that occurs in both.

Unlike the // (update) operator, which operates on a single attribute set, This function views its operands lhs and rhs as a mapping from attribute paths to values.

The caller-provided function pred decides whether any given path is one of the following:

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

recursiveUpdateUntil (path: lhs: rhs: path == ["foo"]) {
  # left attribute set
  foo.bar = 1;
  foo.baz = 2;
  bar = 3;
} {
  # right attribute set
  foo.bar = 1;
  foo.quz = 2;
  baz = 4;
}

=> {
  foo.bar = 1; # 'foo.*' from the 'right' set
  foo.quz = 2; #
  bar = 3;     # 'bar' from the 'left' set
  baz = 4;     # 'baz' from the 'right' set
}

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

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

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

matchAttrs :: AttrSet -> AttrSet -> Bool

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

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

overrideExisting :: AttrSet -> AttrSet -> AttrSet

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

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 :: [String] -> String

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

Get a package output. If no output is found, fallback to .out and then to the default. The function is idempotent: getOutput "b" (getOutput "a" p) == getOutput "a" p.

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

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

Get the first of the outputs provided by the package, or the default. This function is aligned with _overrideFirst() from the multiple-outputs.sh setup hook. Like getOutput, the function is idempotent.

getFirstOutput :: [String] -> Derivation -> Derivation

"${getFirstOutput [ "include" "dev" ] pkgs.openssl}"
=> "/nix/store/00000000000000000000000000000000-openssl-1.0.1r-dev"

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

getBin :: Derivation -> Derivation

"${getBin pkgs.openssl}"
=> "/nix/store/00000000000000000000000000000000-openssl-1.0.1r"

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

getLib :: Derivation -> Derivation

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

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

getStatic :: Derivation -> Derivation

"${lib.getStatic pkgs.glibc}"
=> "/nix/store/00000000000000000000000000000000-glibc-2.39-52-static"

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

getDev :: Derivation -> Derivation

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

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

getInclude :: Derivation -> Derivation

"${getInclude pkgs.openssl}"
=> "/nix/store/00000000000000000000000000000000-openssl-1.0.1r-dev"

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

getMan :: Derivation -> Derivation

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

Pick the outputs of packages to place in buildInputs

chooseDevOutputs :: [Derivation] -> [Derivation]

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.

recurseIntoAttrs :: AttrSet -> AttrSet

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

Undo the effect of recurseIntoAttrs.

dontRecurseIntoAttrs :: AttrSet -> AttrSet

unionOfDisjoint x y is equal to x // y, but accessing attributes present in both x and y will throw an error. This operator is commutative, unlike //.

unionOfDisjoint :: AttrSet -> AttrSet -> AttrSet

Concatenates a list of strings with a separator between each element.

join :: String -> [String] -> String

join ", " ["foo" "bar"]
=> "foo, bar"

Concatenate a list of strings.

concatStrings :: [String] -> String

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

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

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

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

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

concatImapStrings :: (Int -> a -> String) -> [a] -> String

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

Place an element between each element of a list

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

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

Concatenate a list of strings with a separator between each element

concatStringsSep :: String -> [String] -> String

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

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

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

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

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

concatIMapStringsSep :: String -> (Int -> a -> String) -> [a] -> String

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

Like concatMapStringsSep but takes an attribute set instead of a list.

concatMapAttrsStringSep :: String -> (String -> a -> String) -> { [String] :: a } -> String

concatMapAttrsStringSep "\n" (name: value: "${name}: foo-${value}") { a = "0.1.0"; b = "0.2.0"; }
=> "a: foo-0.1.0\nb: foo-0.2.0"

Concatenate a list of strings, adding a newline at the end of each one.

concatLines :: [String] -> String

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

Given string s, replace every occurrence of the string from with the string to.

replaceString :: String -> String -> String -> String

replaceString "world" "Nix" "Hello, world!"
=> "Hello, Nix!"
replaceString "." "_" "v1.2.3"
=> "v1_2_3"

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

replicate :: Int -> String -> String

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

Remove leading and trailing whitespace from a string s.

Whitespace is defined as any of the following characters: " ", “\t” “\r” “\n”

trim :: String -> String

trim "   hello, world!   "
=> "hello, world!"

Remove leading and/or trailing whitespace from a string s.

To remove both leading and trailing whitespace, you can also use trim

Whitespace is defined as any of the following characters: " ", “\t” “\r” “\n”

trimWith :: { start :: Bool; end :: Bool; } -> String -> String

trimWith { start = true; } "   hello, world!   "}
=> "hello, world!   "

trimWith { end = true; } "   hello, world!   "}
=> "   hello, world!"

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

makeSearchPath :: String -> [String] -> String

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

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 :: String -> String -> [Derivation] -> String

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

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

makeLibraryPath :: [Derivation] -> String

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"

Construct an include search path (such as C_INCLUDE_PATH) containing the header files for a set of packages or paths.

makeIncludePath :: [Derivation] -> String

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

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

makeBinPath :: [Derivation] -> String

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

Normalize path, removing extraneous /s

normalizePath :: String -> String

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

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

optionalString :: Bool -> String -> String

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

Determine whether a string has given prefix.

hasPrefix :: String -> String -> Bool

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

Determine whether a string has given suffix.

hasSuffix :: String -> String -> Bool

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

Determine whether a string contains the given infix

hasInfix :: String -> String -> Bool

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

Convert a string s 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 :: String -> [String]

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

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

stringAsChars :: (String -> String) -> String -> String

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

Convert char to ascii value, must be in printable range

charToInt :: String -> Int

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

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

escape :: [String] -> String -> String

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

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 :: [String] -> String -> String

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

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

escapeURL :: String -> String

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

Quote string to be used safely within the Bourne shell if it has any special characters.

escapeShellArg :: String -> String

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

Quote all arguments that have special characters to be safely passed to the Bourne shell.

escapeShellArgs :: [String] -> String

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

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

isValidPosixName :: String -> Bool

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

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 :: String -> (String | [String] | { [String] :: String }) -> String

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

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

toShellVars :: {
  [String] :: String | [String] | { [String] :: String };
} -> String

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

Turn a string s into a Nix expression representing that string

escapeNixString :: String -> String

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

Turn a string s into an exact regular expression

escapeRegex :: String -> String

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

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

escapeNixIdentifier :: String -> String

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

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

escapeXML :: String -> String

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

Converts an ASCII string s to lower-case.

toLower :: String -> String

toLower "HOME"
=> "home"

Converts an ASCII string s to upper-case.

toUpper :: String -> String

toUpper "home"
=> "HOME"

Converts the first character of a string s to upper-case.

toSentenceCase :: String -> String

toSentenceCase "home"
=> "Home"

Converts a string to camelCase. Handles snake_case, PascalCase, kebab-case strings as well as strings delimited by spaces.

toCamelCase :: String -> String

toCamelCase "hello-world"
=> "helloWorld"
toCamelCase "hello_world"
=> "helloWorld"
toCamelCase "hello world"
=> "helloWorld"
toCamelCase "HelloWorld"
=> "helloWorld"

Appends string context from string like object src to target.

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.

addContextFrom :: String -> String -> String

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

nix-repl> builtins.getContext (lib.strings.addContextFrom pkgs.coreutils "bar")
{
  "/nix/store/m1s1d2dk2dqqlw3j90jl3cjy2cykbdxz-coreutils-9.5.drv" = { ... };
}

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

splitString :: String -> String -> [String]

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

Splits a string into substrings based on a predicate that examines adjacent characters.

This function provides a flexible way to split strings by checking pairs of characters against a custom predicate function. Unlike simpler splitting functions, this allows for context-aware splitting based on character transitions and patterns.