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

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