lib.attrsets: attribute set functions

lib.attrsets.attrByPath

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

Return an attribute from nested attribute sets.

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

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

lib.attrsets.hasAttrByPath

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

Return if an attribute from nested attribute set exists.

attrPath

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

e

The nested attribute set to check

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

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

lib.attrsets.setAttrByPath

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

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

attrPath

A list of strings representing the attribute path to set

value

The value to set at the location described by attrPath

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

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

lib.attrsets.getAttrFromPath

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

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

attrPath

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

set

The nested attribute set to find the value in.

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

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

lib.attrsets.concatMapAttrs

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

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

f

Function argument

v

Function argument

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

lib.attrsets.updateManyAttrsByPath

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:

• 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

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

lib.attrsets.attrVals

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

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

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

lib.attrsets.attrValues

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

lib.attrsets.getAttrs

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

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

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

lib.attrsets.catAttrs

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

lib.attrsets.filterAttrs

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

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

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

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

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

lib.attrsets.filterAttrsRecursive

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

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

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

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

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

lib.attrsets.foldlAttrs

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

Like builtins.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.

f

Function argument

init

Function argument

set

Function argument

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
  (_: _: v: v)
  (throw "initial accumulator not needed")
  { z = 3; a = 2; };
->
  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:394 in <nixpkgs>.

lib.attrsets.foldAttrs

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

Apply fold functions to values grouped by key.

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.

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

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

lib.attrsets.collect

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.

pred

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

attrs

The attribute set to recursively collect.

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

lib.attrsets.cartesianProductOfSets

Type: cartesianProductOfSets :: AttrSet -> [AttrSet]

Return the cartesian product of attribute set value combinations.

attrsOfLists

Attribute set with attributes that are lists of values

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

lib.attrsets.nameValuePair

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

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

name

Attribute name

value

Attribute value

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

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

lib.attrsets.mapAttrs

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

lib.attrsets.mapAttrs'

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.

f

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

set

Attribute set to map over.

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

lib.attrsets.mapAttrsToList

Type: 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, given an attribute's name and value, returns a new value.

attrs

Attribute set to map over.

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

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

lib.attrsets.mapAttrsRecursive

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.

f

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

set

Set to recursively map over.

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

lib.attrsets.mapAttrsRecursiveCond

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.

cond

A function, given the attribute set the recursion is currently at, determine if to recurse deeper into that attribute set.

f

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

set

Attribute set to recursively map over.

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

lib.attrsets.genAttrs

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

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

names

Names of values in the resulting attribute set.

f

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

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

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

lib.attrsets.isDerivation

Type: isDerivation :: Any -> Bool

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

value

Value to check.

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

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

lib.attrsets.toDerivation

Type: toDerivation :: Path -> Derivation

Converts a store path to a fake derivation.

path

A store path to convert to a derivation.

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

lib.attrsets.optionalAttrs

Type: optionalAttrs :: Bool -> AttrSet -> 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.

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

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

lib.attrsets.zipAttrsWithNames

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

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

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.

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

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

lib.attrsets.zipAttrsWith

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

lib.attrsets.zipAttrs

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.

sets

List of attribute sets to zip together.

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

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

lib.attrsets.mergeAttrsList

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

list

Function argument

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

lib.attrsets.recursiveUpdateUntil

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.

pred

Predicate, taking the path to the current attribute as a list of strings for attribute names, and the two values at that path from the original arguments.

lhs

Left attribute set of the merge.

rhs

Right attribute set of the merge.

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

lib.attrsets.recursiveUpdate

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.

lhs

Left attribute set of the merge.

rhs

Right attribute set of the merge.

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

lib.attrsets.matchAttrs

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

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

pattern

Attribute set structure to match

attrs

Attribute set to find patterns in

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

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

lib.attrsets.overrideExisting

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

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

old

Original attribute set

new

Attribute set with attributes to override in old.

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

lib.attrsets.showAttrPath

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.

path

Attribute path to render to a string

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

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

lib.attrsets.getOutput

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

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

output

Function argument

pkg

Function argument

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

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

lib.attrsets.getBin

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

lib.attrsets.getLib

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

lib.attrsets.getDev

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

lib.attrsets.getMan

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

lib.attrsets.chooseDevOutputs

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

Pick the outputs of packages to place in buildInputs

drvs

List of packages to pick dev outputs from

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

lib.attrsets.recurseIntoAttrs

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.

attrs

An attribute set to scan for derivations.

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

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

lib.attrsets.dontRecurseIntoAttrs

Type: dontRecurseIntoAttrs :: AttrSet -> AttrSet

Undo the effect of recurseIntoAttrs.

attrs

An attribute set to not scan for derivations.

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

lib.attrsets.unionOfDisjoint

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

x

Function argument

y

Function argument

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