mirror of
https://codeberg.org/mhwombat/nix-book.git
synced 2026-01-02 19:45:12 +08:00
115 lines
3.3 KiB
Text
115 lines
3.3 KiB
Text
[#argument-sets]
|
|
|
|
= Argument sets
|
|
|
|
An attribute set that is used as a function parameter is often called an _argument set_.
|
|
|
|
== Set patterns
|
|
|
|
To specify an attribute set as a function parameter, we use a _set pattern_,
|
|
which has the form
|
|
|
|
[source,subs=quotes]
|
|
----
|
|
{ _name1_, _name2_, ... }
|
|
----
|
|
|
|
Note that while the key-value associations in attribute sets are separated by semi-colons,
|
|
the key names in the attribute set _pattern are separated by commas.
|
|
Here's an example of a function that has an attribute set as an input parameter.
|
|
|
|
[source]
|
|
.Example
|
|
....
|
|
nix-repl> greet = { first, last }: "Hello ${first} ${last}! May I call you ${first}?"
|
|
|
|
nix-repl> greet { first="Amy"; last="de Buitléir"; }
|
|
"Hello Amy de Buitléir! May I call you Amy?"
|
|
....
|
|
|
|
|
|
// TODO Review my use of "we" vs "I".
|
|
|
|
== Optional parameters
|
|
|
|
We can make some values in an argument set optional by providing default values,
|
|
using the syntax `_name_ ? _value_`.
|
|
This is illustrated below.
|
|
|
|
[source]
|
|
.Example
|
|
....
|
|
nix-repl> greet = { first, last ? "whatever-your-lastname-is", topic ? "Nix" }: "Hello ${first} ${last}! May I call you ${first}? Are you enjoying learning ${topic}?"
|
|
|
|
nix-repl> greet { first="Amy"; }
|
|
"Hello Amy whatever-your-lastname-is! May I call you Amy? Are you enjoying learning Nix?"
|
|
|
|
nix-repl> greet { first="Amy"; topic="Mathematics";}
|
|
"Hello Amy whatever-your-lastname-is! May I call you Amy? Are you enjoying learning Mathematics?"
|
|
....
|
|
|
|
== Variadic attributes
|
|
|
|
A function can allow the caller to supply argument sets that contain "extra" values.
|
|
This is done with the special parameter `...`.
|
|
|
|
[source]
|
|
.Example
|
|
....
|
|
nix-repl> formatName = { first, last, ... }: "${first} ${last}"
|
|
....
|
|
|
|
One reason for doing this is to allow the caller to pass the same argument set to multiple functions,
|
|
even though each function may not need all of the values.
|
|
|
|
[source]
|
|
.Example
|
|
....
|
|
nix-repl> person = { first="Joe"; last="Bloggs"; address="123 Main Street"; }
|
|
|
|
nix-repl> formatName person
|
|
"Joe Bloggs"
|
|
....
|
|
|
|
Another reason for allowing variadic arguments is when a function calls another function,
|
|
supplying the same argument set.
|
|
An example is shown in <<at-patterns>>.
|
|
|
|
[#at-patterns]
|
|
== @-patterns
|
|
|
|
It can be convenient for a function to be able to reference the argument set as a whole.
|
|
This is done using an _@-pattern_.
|
|
|
|
[source]
|
|
.Example
|
|
....
|
|
nix-repl> formatPoint = p@{ x, y, ... }: builtins.toXML p
|
|
|
|
nix-repl> formatPoint { x=5; y=3; z=2; }
|
|
"<?xml version='1.0' encoding='utf-8'?>\n<expr>\n <attrs>\n <attr name=\"x\">\n <int value=\"5\" />\n </attr>\n <attr name=\"y\">\n <int value=\"3\" />\n </attr>\n <attr name=\"z\">\n <int value=\"2\" />\n </attr>\n </attrs>\n</expr>\n"
|
|
....
|
|
|
|
Alternatively, the @-pattern can appear _after_ the argument set, as in the example below.
|
|
|
|
[source]
|
|
.Example
|
|
....
|
|
nix-repl> formatPoint = { x, y, ... } @ p: builtins.toXML p
|
|
....
|
|
|
|
An @-pattern is the only way a function can access variadic attributes,
|
|
so they are often used together.
|
|
In the example below, the function `greet` passes its argument set, including the variadic arguments,
|
|
to the function `confirmAddress`.
|
|
|
|
[source]
|
|
.Example
|
|
....
|
|
nix-repl> confirmAddress = { address, ... }: "Do you still live at ${address}?"
|
|
|
|
nix-repl> greet = args@{ first, last, ... }: "Hello ${first}. " + confirmAddress args
|
|
|
|
nix-repl> greet person
|
|
"Hello Joe. Do you still live at 123 Main Street?"
|
|
....
|