about summary refs log tree commit diff
path: root/doc
diff options
context:
space:
mode:
authorMaximilian Bosch <maximilian@mbosch.me>2019-05-20T17·17+0200
committerMaximilian Bosch <maximilian@mbosch.me>2019-05-21T16·08+0200
commitb502b6682b9c73ae5760967eaf7161b3e8523e9e (patch)
treeb198cb186e80e049ed63e6852038e5df87a7de49 /doc
parent14c877b4ab097667734b050a79b45658dcf2695d (diff)
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@`.
Diffstat (limited to 'doc')
-rw-r--r--doc/manual/expressions/language-constructs.xml20
1 files changed, 19 insertions, 1 deletions
diff --git a/doc/manual/expressions/language-constructs.xml b/doc/manual/expressions/language-constructs.xml
index f961ed921bca..923b5d8c4011 100644
--- a/doc/manual/expressions/language-constructs.xml
+++ b/doc/manual/expressions/language-constructs.xml
@@ -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>