mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-09-11 15:08:33 +01:00
Merge pull request #242318 from hercules-ci/doc-lib-fix
lib.fix: Improve doc
This commit is contained in:
commit
b597bff1b6
|
@ -1,26 +1,76 @@
|
||||||
{ lib, ... }:
|
{ lib, ... }:
|
||||||
rec {
|
rec {
|
||||||
/*
|
/*
|
||||||
Compute the fixed point of the given function `f`, which is usually an
|
`fix f` computes the fixed point of the given function `f`. In other words, the return value is `x` in `x = f x`.
|
||||||
attribute set that expects its final, non-recursive representation as an
|
|
||||||
argument:
|
|
||||||
|
|
||||||
```
|
`f` must be a lazy function.
|
||||||
f = self: { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; }
|
This means that `x` must be a value that can be partially evaluated,
|
||||||
|
such as an attribute set, a list, or a function.
|
||||||
|
This way, `f` can use one part of `x` to compute another part.
|
||||||
|
|
||||||
|
**Relation to syntactic recursion**
|
||||||
|
|
||||||
|
This section explains `fix` by refactoring from syntactic recursion to a call of `fix` instead.
|
||||||
|
|
||||||
|
For context, Nix lets you define attributes in terms of other attributes syntactically using the [`rec { }` syntax](https://nixos.org/manual/nix/stable/language/constructs.html#recursive-sets).
|
||||||
|
|
||||||
|
```nix
|
||||||
|
nix-repl> rec {
|
||||||
|
foo = "foo";
|
||||||
|
bar = "bar";
|
||||||
|
foobar = foo + bar;
|
||||||
|
}
|
||||||
|
{ bar = "bar"; foo = "foo"; foobar = "foobar"; }
|
||||||
```
|
```
|
||||||
|
|
||||||
Nix evaluates this recursion until all references to `self` have been
|
This is convenient when constructing a value to pass to a function for example,
|
||||||
resolved. At that point, the final result is returned and `f x = x` holds:
|
but an equivalent effect can be achieved with the `let` binding syntax:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
nix-repl> let self = {
|
||||||
|
foo = "foo";
|
||||||
|
bar = "bar";
|
||||||
|
foobar = self.foo + self.bar;
|
||||||
|
}; in self
|
||||||
|
{ bar = "bar"; foo = "foo"; foobar = "foobar"; }
|
||||||
```
|
```
|
||||||
|
|
||||||
|
But in general you can get more reuse out of `let` bindings by refactoring them to a function.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
nix-repl> f = self: {
|
||||||
|
foo = "foo";
|
||||||
|
bar = "bar";
|
||||||
|
foobar = self.foo + self.bar;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This is where `fix` comes in, it contains the syntactic that's not in `f` anymore.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
nix-repl> fix = f:
|
||||||
|
let self = f self; in self;
|
||||||
|
```
|
||||||
|
|
||||||
|
By applying `fix` we get the final result.
|
||||||
|
|
||||||
|
```nix
|
||||||
nix-repl> fix f
|
nix-repl> fix f
|
||||||
{ bar = "bar"; foo = "foo"; foobar = "foobar"; }
|
{ bar = "bar"; foo = "foo"; foobar = "foobar"; }
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Such a refactored `f` using `fix` is not useful by itself.
|
||||||
|
See [`extends`](#function-library-lib.fixedPoints.extends) for an example use case.
|
||||||
|
There `self` is also often called `final`.
|
||||||
|
|
||||||
Type: fix :: (a -> a) -> a
|
Type: fix :: (a -> a) -> a
|
||||||
|
|
||||||
See https://en.wikipedia.org/wiki/Fixed-point_combinator for further
|
Example:
|
||||||
details.
|
fix (self: { foo = "foo"; bar = "bar"; foobar = self.foo + self.bar; })
|
||||||
|
=> { bar = "bar"; foo = "foo"; foobar = "foobar"; }
|
||||||
|
|
||||||
|
fix (self: [ 1 2 (elemAt self 0 + elemAt self 1) ])
|
||||||
|
=> [ 1 2 3 ]
|
||||||
*/
|
*/
|
||||||
fix = f: let x = f x; in x;
|
fix = f: let x = f x; in x;
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue