Attrset functions

lib.attrsets.attrByPath

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

Return an attribute from nested attribute sets.

attrPath

A list of strings representing the path through the nested attribute set set

default

Default value if attrPath does not resolve to an existing value

e

The nested attributeset to select values from

lib.attrsets.attrByPath usage example

x = { a = { b = 3; }; }
attrByPath ["a" "b"] 6 x
=> 3
attrByPath ["z" "z"] 6 x
=> 6

lib.attrsets.hasAttrByPath

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

Return if an attribute from nested attribute set exists.

attrPath

A list of strings representing the path through the nested attribute set set

e

The nested attributeset to check

lib.attrsets.hasAttrByPath usage example

x = { a = { b = 3; }; }
hasAttrByPath ["a" "b"] x
=> true
hasAttrByPath ["z" "z"] x
=> false

lib.attrsets.setAttrByPath

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

Return nested attribute set in which an attribute is set.

attrPath

A list of strings representing the path through the nested attribute set

value

The value to set at the location described by attrPath

lib.attrsets.setAttrByPath usage example

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

lib.attrsets.getAttrFromPath

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

Like attrByPath without a default value. If it doesn't find the path it will throw.

attrPath

A list of strings representing the path through the nested attribute set set

set

The nested attribute set to find the value in

lib.attrsets.getAttrFromPath usage example

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

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

lib.attrsets.updateManyAttrsByPath usage example

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

lib.attrsets.attrVals

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

Return the specified attributes from a set.

nameList

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

set

The set to get attribute values from

lib.attrsets.attrVals usage example

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

lib.attrsets.attrValues

attrValues :: AttrSet -> [Any]

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

lib.attrsets.attrValues usage example

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

lib.attrsets.getAttrs

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

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

names

A list of attribute names to get out of set

attrs

The set to get the named attributes from

lib.attrsets.getAttrs usage example

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

lib.attrsets.catAttrs

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.

lib.attrsets.catAttrs usage example

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

lib.attrsets.filterAttrs

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

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

pred

A predicate function that takes the attribute's name (name) and the attribute's value (value), and returns true to include the attribute or false to exclude the attribute.

set

The attribute set to filter

lib.attrsets.filterAttrs usage example

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

lib.attrsets.filterAttrsRecursive

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

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

pred

A predicate function that takes the attribute's name (name) and the attribute's value (value), and returns true to include the attribute or false to exclude the attribute.

set

The attribute set to filter

lib.attrsets.filterAttrsRecursive usage example

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

lib.attrsets.foldAttrs

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

Apply fold functions to values grouped by key.

op

A function that takes a value and an accumulator, and returns the an updated accumulator.

nul

The starting accumulator value

listOfAttrs

A list of attribute sets to fold together by key

lib.attrsets.foldAttrs usage example

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

lib.attrsets.collect

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

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

pred

A predicate function that takes an attributes value attrs, and returns true if the value should be collected, or false if the recursive descent should continue.

attrs

An attrset

lib.attrsets.collect usage example

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

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

lib.attrsets.cartesianProductOfSets

cartesianProductOfSets :: AttrSet -> [AttrSet]

Return the cartesian product of attribute set value combinations.

attrsOfLists

An attribute set whose values are all lists

lib.attrsets.cartesianProductOfSets usage example

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

lib.attrsets.nameValuePair

nameValuePair :: String -> Any -> AttrSet

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

name

The attribute name

value

The attribute value

lib.attrsets.nameValuePair usage example

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

lib.attrsets.mapAttrs

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

Apply a function to each element in an attribute set. The function takes two arguments --- the attribute name and its value --- and returns the new value for the attribute. The result is a new attribute set.

lib.attrsets.mapAttrs usage example

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

lib.attrsets.mapAttrs'

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.

f

A function when given an attribute's name and value, returns a new name-value pair

set

The attribute set to map over

lib.attrsets.mapAttrs' usage example

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

lib.attrsets.mapAttrsToList

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

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

f

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

attrs

The attribute set to map over

lib.attrsets.mapAttrsToList usage example

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

lib.attrsets.mapAttrsRecursive

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

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

lib.attrsets.mapAttrsRecursive usage example

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

lib.attrsets.mapAttrsRecursiveCond

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.

cond

A function when given an attribute set, returns true if it should recurse deeper and false if the attrset should be applied to f

f

A function given a list of attribute names, name_path and a value, returns a new value

set

The attribute set to recursively map over

lib.attrsets.mapAttrsRecursiveCond usage example

# 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

lib.attrsets.genAttrs

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

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

names

Names of values int he resulting attribute set

f

A function that takes the name of the attribute set and returns the attribute's value

lib.attrsets.genAttrs usage example

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

lib.attrsets.isDerivation

isDerivation :: Any -> Bool

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

x

The value which is possibly a derivation

lib.attrsets.isDerivation usage example

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

lib.attrsets.toDerivation

toDerivation :: Path -> Derivation

Converts a store path to a fake derivation.

path

A store path to convert to a derivation

lib.attrsets.optionalAttrs

optionalAttrs :: Bool -> AttrSet

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

cond

Condition under which the as attribute set is returned

as

The attribute set to return if cond is true

lib.attrsets.optionalAttrs usage example

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

lib.attrsets.zipAttrsWithNames

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

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

names

A list of attribute names to zip

f

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

sets

A list of attribute sets to zip together

lib.attrsets.zipAttrsWithNames usage example

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

lib.attrsets.zipAttrsWith

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

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

lib.attrsets.zipAttrsWith usage example

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

lib.attrsets.zipAttrs

zipAttrs :: [ AttrSet ] -> AttrSet

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

sets

A list of attribute sets to zip together

lib.attrsets.zipAttrs usage example

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

lib.attrsets.recursiveUpdateUntil

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

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

pred

A function when given a list of values on the left and right hand sides (path), a left-hand side value, and a right-hand side value, returns true when the the right-hand side value should no-longer be substituted, and false when the recursive update should recurse

lhs

The left-hand attribute set of the merge

rhs

The right-hand attribute set of the merge

lib.attrsets.recursiveUpdateUntil usage example

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

returns: {
foo.bar = 1; # 'foo.*' from the second set
foo.quz = 2; #
bar = 3;     # 'bar' from the first set
baz = 4;     # 'baz' from the second set
}

lib.attrsets.recursiveUpdate

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.

lhs

The left-hand attribute set of the merge

rhs

The right-hand attribute set of the merge

lib.attrsets.recursiveUpdate usage example

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

lib.attrsets.matchAttrs

AttrSet -> AttrSet -> Bool

Returns true if the pattern is contained in the set. False otherwise.

pattern

An attrset to match

attrs

An attrset in which to look for the pattern

lib.attrsets.matchAttrs usage example

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

lib.attrsets.overrideExisting

AttrSet -> AttrSet -> AttrSet

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

old

An attribute set containing all the keys that will be present in the result set

new

An attribute set containing the keys that might override the old set

lib.attrsets.overrideExisting usage example

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

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.

path

Function argument

lib.attrsets.showAttrPath usage example

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

lib.attrsets.getOutput

String -> Derivation -> Derivation

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

output

A string name of a pkg's output

pkg

A derivation that might have output output

lib.attrsets.getOutput usage example

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

lib.attrsets.getBin

Derivation -> Derivation

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

lib.attrsets.getLib

Derivation -> Derivation

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

lib.attrsets.getDev

Derivation -> Derivation

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

lib.attrsets.getMan

Derivation -> Derivation

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

lib.attrsets.chooseDevOutputs

[Derivation] -> [Derivation]

Pick the "dev" outputs of packages to place in buildInputs If no output is found, fallback to .out and then to the default.

drvs

A list of derivations to get "dev" outputs from

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

attrs

An attribute set to be marked for recursing into for derivations

lib.attrsets.dontRecurseIntoAttrs

AttrSet -> AttrSet

Undo the effect of recurseIntoAttrs.

attrs

An attribute set to un-mark for recursing into for derivations

lib.attrsets.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 (//).

x

Function argument

y

Function argument

lib.attrsets.zipWithNames

** deprecated stuff **