From f013539cfb1b8d4e3b1a101d23fd84ebfecd5d88 Mon Sep 17 00:00:00 2001
From: AlOwain <az@alowain.dev>
Date: Tue, 5 Aug 2025 13:46:58 +0300
Subject: [PATCH] Use a record instead of a list to clarify arguments in
 examples.

In Programming in Nu#Operators:262 inferring the arguments from the
list position could introduce some misunderstanding.
---
 book/operators.md | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/book/operators.md b/book/operators.md
index a3b0ef8b5a5..a321eb93c42 100644
--- a/book/operators.md
+++ b/book/operators.md
@@ -247,7 +247,9 @@ external command.
 Here is an example custom command that has a rest parameter:
 
 ```nu
-def foo [ --flag req opt? ...args ] { [$flag, $req, $opt, $args] | to nuon }
+def foo [ --flag req opt? ...args ] {
+  { flag: $flag, req: $req, opt: $opt, args: $args } | to nuon
+}
 ```
 
 It has one flag (`--flag`), one required positional parameter (`req`), one optional positional parameter
@@ -259,9 +261,9 @@ recognized before variables, subexpressions, and list literals, and no whitespac
 
 ```nu
 foo "bar" "baz" ...[1 2 3] # With ..., the numbers are treated as separate arguments
-# => [false, bar, baz, [1, 2, 3]]
+# => { flag: false, req: bar, opt: baz, args: [1, 2, 3] }
 foo "bar" "baz" [1 2 3] # Without ..., [1 2 3] is treated as a single argument
-# => [false, bar, baz, [[1, 2, 3]]]
+# => { flag: false, req: bar, opt: baz, args: [[1, 2, 3]] }
 ```
 
 A more useful way to use the spread operator is if you have another command with a rest parameter
@@ -270,21 +272,21 @@ and you want it to forward its arguments to `foo`:
 ```nu
 def bar [ ...args ] { foo --flag "bar" "baz" ...$args }
 bar 1 2 3
-# => [true, bar, baz, [1, 2, 3]]
+# => { flag: true, req: bar, opt: baz, args: [1, 2, 3] }
 ```
 
 You can spread multiple lists in a single call, and also intersperse individual arguments:
 
 ```nu
 foo "bar" "baz" 1 ...[2 3] 4 5 ...(6..9 | take 2) last
-# => [false, bar, baz, [1, 2, 3, 4, 5, 6, 7, last]]
+# => { flag: false, req: bar, opt: baz, args: [1, 2, 3, 4, 5, 6, 7, last] }
 ```
 
 Flags/named arguments can go after a spread argument, just like they can go after regular rest arguments:
 
 ```nu
 foo "bar" "baz" 1 ...[2 3] --flag 4
-# => [true, bar, baz, [1, 2, 3, 4]]
+# => { flag: true, req: bar, opt: baz, args: [1, 2, 3, 4] }
 ```
 
 If a spread argument comes before an optional positional parameter, that optional parameter is treated
@@ -292,5 +294,5 @@ as being omitted:
 
 ```nu
 foo "bar" ...[1 2] "not opt" # The null means no argument was given for opt
-# => [false, bar, null, [1, 2, "not opt"]]
+# => { flag: false, req: bar, opt: null, args: [1, 2, "not opt"] }
 ```