Merge pull request #208674 from YoshiRulz/yoshi-lib-docs

        else { ${elemAt attrPath n} = atDepth (n + 1); };

    in atDepth 0;

  /* Like `attrByPath', but without a default value. If it doesn't find the

  /* Like `attrByPath`, but without a default value. If it doesn't find the

     path it will throw an error.

     Example:

    # The set to get the named attributes from

    attrs: genAttrs names (name: attrs.${name});

  /* Collect each attribute named `attr' from a list of attribute

  /* Collect each attribute named `attr` from a list of attribute

     sets.  Sets that don't contain the named attribute are ignored.

     Example:

    ) {} list_of_attrs;

  /* Recursively collect sets that verify a given predicate named `pred'

     from the set `attrs'.  The recursion is stopped when the predicate is

  /* Recursively collect sets that verify a given predicate named `pred`

     from the set `attrs`.  The recursion is stopped when the predicate is

     verified.

     Example:

      listToAttrs (map (attr: { name = attr; value = f attr set.${attr}; }) (attrNames set)));

  /* Like `mapAttrs', but allows the name of each attribute to be

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

     return both the new name and value as a `nameValuePair`.

     Example:

       mapAttrs' (name: value: nameValuePair ("foo_" + name) ("bar-" + value))

    map (name: f name attrs.${name}) (attrNames attrs);

  /* Like `mapAttrs', except that it recursively applies itself to

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

    mapAttrsRecursiveCond (as: true) f set;

  /* Like `mapAttrsRecursive', but it takes an additional predicate

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

     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.

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

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

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

     Example:

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

rec {

  /* `overrideDerivation drv f' takes a derivation (i.e., the result

     of a call to the builtin function `derivation') and returns a new

  /* `overrideDerivation drv f` takes a derivation (i.e., the result

     of a call to the builtin function `derivation`) and returns a new

     derivation in which the attributes of the original are overridden

     according to the function `f'.  The function `f' is called with

     according to the function `f`.  The function `f` is called with

     the original derivation attributes.

     `overrideDerivation' allows certain "ad-hoc" customisation

     `overrideDerivation` allows certain "ad-hoc" customisation

     scenarios (e.g. in ~/.config/nixpkgs/config.nix).  For instance,

     if you want to "patch" the derivation returned by a package

     function in Nixpkgs to build another version than what the

      else result;

  /* Call the package function in the file `fn' with the required

  /* Call the package function in the file `fn` with the required

    arguments automatically.  The function is called with the

    arguments `args', but any missing arguments are obtained from

    `autoArgs'.  This function is intended to be partially

    arguments `args`, but any missing arguments are obtained from

    `autoArgs`.  This function is intended to be partially

    parameterised, e.g.,

      callPackage = callPackageWith pkgs;

        libbar = callPackage ./bar.nix { };

      };

    If the `libbar' function expects an argument named `libfoo', it is

    If the `libbar` function expects an argument named `libfoo`, it is

    automatically passed as an argument.  Overrides or missing

    arguments can be supplied in `args', e.g.

    arguments can be supplied in `args`, e.g.

      libbar = callPackage ./bar.nix {

        libfoo = null;

    in lib.deepSeq drv' drv';

  /* Make a set of packages with a common scope. All packages called

     with the provided `callPackage' will be evaluated with the same

     with the provided `callPackage` will be evaluated with the same

     arguments. Any package in the set may depend on any other. The

     `overrideScope'` function allows subsequent modification of the package

     set in a consistent way, i.e. all packages in the set will be

     called with the overridden packages. The package sets may be

     hierarchical: the packages in the set are called with the scope

     provided by `newScope' and the set provides a `newScope' attribute

     provided by `newScope` and the set provides a `newScope` attribute

     which can form the parent scope for later package sets. */

  makeScope = newScope: f:

    let self = f self // {

/* Library of low-level helper functions for nix expressions.

 *

 * Please implement (mostly) exhaustive unit tests

 * for new functions in `./tests.nix'.

 * for new functions in `./tests.nix`.

 */

let

  /* Return a singleton list or an empty list, depending on a boolean

     value.  Useful when building lists with optional elements

     (e.g. `++ optional (system == "i686-linux") firefox').

     (e.g. `++ optional (system == "i686-linux") firefox`).

     Type: optional :: bool -> a -> [a]

  */

  toList = x: if isList x then x else [x];

  /* Return a list of integers from `first' up to and including `last'.

  /* Return a list of integers from `first` up to and including `last`.

     Type: range :: int -> int -> [int]

    ) { right = []; wrong = []; });

  /* Splits the elements of a list into many lists, using the return value of a predicate.

     Predicate should return a string which becomes keys of attrset `groupBy' returns.

     Predicate should return a string which becomes keys of attrset `groupBy` returns.

     `groupBy'` allows to customise the combining function and initial value

  setName = name: drv: drv // {inherit name;};

  /* Like `setName', but takes the previous name as an argument.

  /* Like `setName`, but takes the previous name as an argument.

     Example:

       updateName (oldName: oldName + "-experimental") somePkg