lib.attrsets: attribute set functions

Operations on attribute sets.

lib.attrsets.attrByPath

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

Inputs

attrPath

A list of strings representing the attribute path to return from set

default

Default value if attrPath does not resolve to an existing value

set

The nested attribute set to select values from

Type

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

Examples

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:88 in <nixpkgs>.

lib.attrsets.hasAttrByPath

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:

1. hasAttrByPath [] x == true
   

Inputs

attrPath

A list of strings representing the attribute path to check from set

set

The nested attribute set to check

Type

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

Examples

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

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

lib.attrsets.longestValidPathPrefix

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:

1. attrsets.longestValidPathPrefix [] x == []
   

2. hasAttrByPath (attrsets.longestValidPathPrefix p x) x == true
   

Inputs

attrPath

A list of strings representing the longest possible path that may be returned.

v

The nested attribute set to check.

Type

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

Examples

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:225 in <nixpkgs>.

lib.attrsets.setAttrByPath

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

Inputs

attrPath

A list of strings representing the attribute path to set

value

The value to set at the location described by attrPath

Type

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

Examples

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

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

lib.attrsets.getAttrFromPath

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

Inputs

attrPath

A list of strings representing the attribute path to get from set

set

The nested attribute set to find the value in.

Type

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

Examples

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

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

lib.attrsets.concatMapAttrs

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

Inputs

f

1. Function argument

v

2. Function argument

Type

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

Examples

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:374 in <nixpkgs>.

lib.attrsets.updateManyAttrsByPath

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:

• Updates to deeper attribute paths are applied before updates to more shallow attribute paths

• Multiple updates to the same attribute path are applied in the order they appear in the update list

• If any but the last path element leads into a value that is not an attribute set, an error is thrown

• If there is an update for an attribute path that doesn't exist, accessing the argument in the update function causes an error, but intermediate attribute sets are implicitly created as needed

Type

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

Examples

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:436 in <nixpkgs>.

lib.attrsets.attrVals

Returns the specified attributes from a set.

Inputs

nameList

The list of attributes to fetch from set. Each attribute name must exist on the attribute set

set

The set to get attribute values from

Type

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

Examples

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

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

lib.attrsets.attrValues

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

Type

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

Examples

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

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

lib.attrsets.getAttrs

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

Inputs

names

A list of attribute names to get out of set

set

The set to get the named attributes from

Type

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

Examples

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

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

lib.attrsets.catAttrs

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

Inputs

attr

The attribute name to get out of the sets.

list

The list of attribute sets to go through

Type

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

Examples

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

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

lib.attrsets.filterAttrs

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

Inputs

pred

Predicate taking an attribute name and an attribute value, which returns true to include the attribute, or false to exclude the attribute.

If possible, decide on name first and on value only if necessary. This avoids evaluating the value if the name is already enough, making it possible, potentially, to have the argument reference the return value. (Depending on context, that could still be considered a self reference by users; a common pattern in Nix.)

filterAttrs is occasionally the cause of infinite recursion in configuration systems that allow self-references. To support the widest range of user-provided logic, perform the filterAttrs call as late as possible. Typically that's right before using it in a derivation, as opposed to an implicit conversion whose result is accessible to the user's expressions.

set

The attribute set to filter

Type

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

Examples

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

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

lib.attrsets.filterAttrsRecursive

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

Inputs

pred

Predicate taking an attribute name and an attribute value, which returns true to include the attribute, or false to exclude the attribute.

set

The attribute set to filter

Type

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

Examples

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

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

lib.attrsets.foldlAttrs

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.

Inputs

f

1. Function argument

init

2. Function argument

set

3. Function argument

Type

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

Examples

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:795 in <nixpkgs>.

lib.attrsets.foldAttrs

Apply fold functions to values grouped by key.

Inputs

op

A function, given a value and a collector combines the two.

nul

The starting value.

list_of_attrs

A list of attribute sets to fold together by key.

Type

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

Examples

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

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

lib.attrsets.collect

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

Inputs

pred

Given an attribute's value, determine if recursion should stop.

attrs

The attribute set to recursively collect.

Type

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

Examples

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:875 in <nixpkgs>.

lib.attrsets.cartesianProduct

Return the cartesian product of attribute set value combinations.

Inputs

attrsOfLists

Attribute set with attributes that are lists of values

Type

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

Examples

cartesianProduct { 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:915 in <nixpkgs>.

lib.attrsets.mapCartesianProduct

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

Inputs

f

A function, given an attribute set, it returns a new value.

attrsOfLists

Attribute set with attributes that are lists of values

Type

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

Examples

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

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

lib.attrsets.nameValuePair

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

Inputs

name

Attribute name

value

Attribute value

Type

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

Examples

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

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

lib.attrsets.mapAttrs

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

Inputs

f

A function that takes an attribute name and its value, and returns the new value for the attribute.

attrset

The attribute set to iterate through.

Type

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

Examples

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

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

lib.attrsets.mapAttrs'

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.

Inputs

f

A function, given an attribute's name and value, returns a new nameValuePair.

set

Attribute set to map over.

Type

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

Examples

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:1055 in <nixpkgs>.

lib.attrsets.mapAttrsToList

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

Inputs

f

A function, given an attribute's name and value, returns a new value.

attrs

Attribute set to map over.

Type

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

Examples

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

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

lib.attrsets.attrsToList

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:

• name (string): The name of the attribute
• value (any): The value of the attribute

The following is always true:

builtins.listToAttrs (attrsToList attrs) == attrs

attrsToList (builtins.listToAttrs list) != list

Inputs

set

The attribute set to deconstruct.

Type

attrsToList :: { [String] :: a } -> [{ name :: String; value :: a; }]

Examples

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

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

lib.attrsets.mapAttrsRecursive

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

Type

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

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

lib.attrsets.mapAttrsRecursiveCond

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

Type

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

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

lib.attrsets.mapAttrsToListRecursive

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.

Inputs

f

Mapping function which, given an attribute’s path and value, returns a new value.

This value will be an element of the list returned by mapAttrsToListRecursive.

The first argument to the mapping function is a list of attribute names forming the path to the leaf attribute. The second argument is the leaf attribute value, which will never be an attribute set.

set

Attribute set to map over.

Type

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

Examples

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

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

lib.attrsets.mapAttrsToListRecursiveCond

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.

Inputs

pred

Predicate to decide whether to recurse into an attribute set.

If the predicate returns true, mapAttrsToListRecursiveCond recurses into the attribute set. If the predicate returns false, it does not recurse but instead applies the mapping function, treating the attribute set as a leaf.

The first argument to the predicate is a list of attribute names forming the path to the attribute set. The second argument is the attribute set.

f

Mapping function which, given an attribute’s path and value, returns a new value.

This value will be an element of the list returned by mapAttrsToListRecursiveCond.

The first argument to the mapping function is a list of attribute names forming the path to the leaf attribute. The second argument is the leaf attribute value, which may be an attribute set if the predicate returned false.

set

Attribute set to map over.

Type

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

Examples

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

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

lib.attrsets.genAttrs

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

Inputs

names

Names of values in the resulting attribute set.

f

A function, given the name of the attribute, returns the attribute's value.

Type

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

Examples

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

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

lib.attrsets.genAttrs'

Inputs

xs

A list of strings s used as generator.

f

A function, given a string s from the list xs, returns a new nameValuePair.

Type

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

Examples

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

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

lib.attrsets.isDerivation

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

Inputs

value

Value to check.

Type

isDerivation :: Any -> Bool

Examples

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

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

lib.attrsets.toDerivation

Converts a store path to a fake derivation.

Inputs

path

A store path to convert to a derivation.

Type

toDerivation :: Path -> Derivation

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

lib.attrsets.optionalAttrs

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

Inputs

cond

Condition under which the as attribute set is returned.

as

The attribute set to return if cond is true.

Type

optionalAttrs :: Bool -> AttrSet -> AttrSet

Examples

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

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

lib.attrsets.zipAttrsWithNames

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

Inputs

names

List of attribute names to zip.

f

A function, accepts an attribute name, all the values, and returns a combined value.

sets

List of values from the list of attribute sets.

Type

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

Examples

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

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

lib.attrsets.zipAttrsWith

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.

Type

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

Examples

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

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

lib.attrsets.zipAttrs

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

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

Type

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

Examples

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

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

lib.attrsets.mergeAttrsList

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

Inputs

list

1. Function argument

Type

mergeAttrsList :: [AttrSet] -> AttrSet

Examples

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:1612 in <nixpkgs>.

lib.attrsets.recursiveUpdateUntil

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:

• true: a value in the mapping
• false: an attribute set whose purpose is to create the nesting structure.

Inputs

pred

Predicate function (of type List String -> Any -> Any -> Bool)

Inputs:

• path : List String: the path to the current attribute as a list of strings for attribute names
• lhsAtPath : Any: the value at that path in lhs; same as getAttrFromPath path lhs
• rhsAtPath : Any: the value at that path in rhs; same as getAttrFromPath path rhs

Output:

• true: path points to a value in the mapping, and rhsAtPath will appear in the return value of recursiveUpdateUntil
• false: path is part of the nesting structure and will be an attrset in the return value of recursiveUpdateUntil

pred is only called for paths that extend prefixes for which pred returned false.

lhs

Left attribute set of the update.

rhs

Right attribute set of the update.

Type

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

Examples

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
}

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

lib.attrsets.recursiveUpdate

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.

Inputs

lhs

Left attribute set of the merge.

rhs

Right attribute set of the merge.

Type

recursiveUpdate :: AttrSet -> AttrSet -> AttrSet

Examples

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:1768 in <nixpkgs>.

lib.attrsets.matchAttrs

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

• Each attribute path also exists in the second argument.
• If the attribute's value is not a nested attribute set, it must have the same value in the right argument.

Inputs

pattern

Attribute set structure to match

attrs

Attribute set to check

Type

matchAttrs :: AttrSet -> AttrSet -> Bool

Examples

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

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

lib.attrsets.overrideExisting

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

Inputs

old

Original attribute set

new

Attribute set with attributes to override in old.

Type

overrideExisting :: AttrSet -> AttrSet -> AttrSet

Examples

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:1866 in <nixpkgs>.

lib.attrsets.showAttrPath

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.

Inputs

path

Attribute path to render to a string

Type

showAttrPath :: [String] -> String

Examples

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

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

lib.attrsets.getOutput

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.

Inputs

output

1. Function argument

pkg

2. Function argument

Type

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

Examples

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

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

lib.attrsets.getFirstOutput

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.

Inputs

outputs

1. Function argument

pkg

2. Function argument

Type

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

Examples

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

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

lib.attrsets.getBin

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

Inputs

pkg

The package whose bin output will be retrieved.

Type

getBin :: Derivation -> Derivation

Examples

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

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

lib.attrsets.getLib

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

Inputs

pkg

The package whose lib output will be retrieved.

Type

getLib :: Derivation -> Derivation

Examples

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

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

lib.attrsets.getStatic

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

Inputs

pkg

The package whose static output will be retrieved.

Type

getStatic :: Derivation -> Derivation

Examples

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

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

lib.attrsets.getDev

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

Inputs

pkg

The package whose dev output will be retrieved.

Type

getDev :: Derivation -> Derivation

Examples

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

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

lib.attrsets.getInclude

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

Inputs

pkg

The package whose include output will be retrieved.

Type

getInclude :: Derivation -> Derivation

Examples

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

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

lib.attrsets.getMan

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

Inputs

pkg

The package whose man output will be retrieved.

Type

getMan :: Derivation -> Derivation

Examples

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

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

lib.attrsets.chooseDevOutputs

Pick the outputs of packages to place in buildInputs

Inputs

pkgs

List of packages.

Type

chooseDevOutputs :: [Derivation] -> [Derivation]

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

lib.attrsets.recurseIntoAttrs

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.

Inputs

attrs

An attribute set to scan for derivations.

Type

recurseIntoAttrs :: AttrSet -> AttrSet

Examples

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

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

lib.attrsets.dontRecurseIntoAttrs

Undo the effect of recurseIntoAttrs.

Inputs

attrs

An attribute set to not scan for derivations.

Type

dontRecurseIntoAttrs :: AttrSet -> AttrSet

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

lib.attrsets.unionOfDisjoint

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

Inputs

x

1. Function argument

y

2. Function argument

Type

unionOfDisjoint :: AttrSet -> AttrSet -> AttrSet

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