clarify wording on args@ default handling (#8596)

* clarify wording on args@ default handling

Most importantly use shorter sentences and emphasize the key point that defaults aren't taken into account

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
Co-authored-by: John Ericson <git@JohnEricson.me>
This commit is contained in:
Valentin Gagarin 2023-07-19 15:07:07 +02:00 committed by GitHub
parent 32494cbb29
commit b0173716f6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -208,30 +208,41 @@ three kinds of patterns:
```nix
{ x, y, z, ... } @ args: z + y + x + args.a
```
Here `args` is bound to the entire argument, which is further
matched against the pattern `{ x, y, z,
... }`. `@`-pattern makes mainly sense with an ellipsis(`...`) as
Here `args` is bound to the argument *as passed*, which is further
matched against the pattern `{ x, y, z, ... }`.
The `@`-pattern makes mainly sense with an ellipsis(`...`) as
you can access attribute names as `a`, using `args.a`, which was
given as an additional attribute to the function.
> **Warning**
>
> The `args@` expression is bound to the argument passed to the
> function which means that attributes with defaults that aren't
> explicitly specified in the function call won't cause an
> evaluation error, but won't exist in `args`.
>
>
> `args@` binds the name `args` to the attribute set that is passed to the function.
> In particular, `args` does *not* include any default values specified with `?` in the function's set pattern.
>
> For instance
>
>
> ```nix
> let
> function = args@{ a ? 23, ... }: args;
> f = args@{ a ? 23, ... }: [ a args ];
> in
> function {}
> ````
>
> will evaluate to an empty attribute set.
> f {}
> ```
>
> is equivalent to
>
> ```nix
> let
> f = args @ { ... }: [ (args.a or 23) args ];
> in
> f {}
> ```
>
> and both expressions will evaluate to:
>
> ```nix
> [ 23 {} ]
> ```
Note that functions do not have names. If you want to give them a name,
you can bind them to an attribute, e.g.,