doc: clarify that optional attrs in a function argument will be ignored unless specified

In `args@{ a ? 1 }: /* ... */` the value `a` won't be a part of `args`
unless it's specified when calling the function, the default value will
be ignored in this case.

My personal point of view is that this behavior is a matter of taste, at
least I was pretty sure that unmatched arguments will be a part of
`args@` while debugging some Nix code last week.

I decided to add a warning to the docs which hopefully reduces the
confusion of further Nix developers who thought the same about `args@`.
This commit is contained in:
Maximilian Bosch 2019-05-20 19:17:18 +02:00
parent 14c877b4ab
commit b502b6682b
No known key found for this signature in database
GPG key ID: 091DBF4D1FC46B8E

View file

@ -217,7 +217,25 @@ but can also be written as:
ellipsis(<literal>...</literal>) as you can access attribute names as
<literal>a</literal>, using <literal>args.a</literal>, which was given as an
additional attribute to the function.
</para></listitem>
</para>
<warning>
<para>
The <literal>args@</literal> 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 <literal>args</literal>.
</para>
<para>
For instance
<programlisting>
let
function = args@{ a ? 23, ... }: args;
in
function {}
</programlisting>
will evaluate to an empty attribute set.
</para>
</warning></listitem>
</itemizedlist>