Skip to content

Commit 24e6385

Browse files
0x4D53520x4D5352
authored
Add attributes documentation for custom commands. (#2118)
* fix: add documentation for `attrs` in custom_commands.md * fix: tweak wording and code block formatting * fix: correct typo
1 parent cef5cff commit 24e6385

1 file changed

Lines changed: 164 additions & 0 deletions

File tree

‎book/custom_commands.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -935,6 +935,170 @@ The comments following the parameters become their description. Only a single-li
935935
A Nushell comment that continues on the same line for argument documentation purposes requires a space before the ` #` pound sign.
936936
:::
937937

938+
## Adding Attributes to Custom Commands via `attr`
939+
940+
As of version 0.103.0, Nushell allows authors of custom commands to enrich their work
941+
with attributes with subcommands of the `attr` builtin, prefixed by the `@` symbol
942+
before the definition of the command. For those coming from Python, Java, or JavaScript, this
943+
will appear similar to decorators or annotations, but serve a slightly different purpose.
944+
945+
Let's improve the documentation for the `vip-greet` custom command. The `example`
946+
attribute adds to the output of `help {command}` or `{command} -h`:
947+
948+
```nu
949+
# Greet guests along with a VIP
950+
#
951+
# Use for birthdays, graduation parties,
952+
# retirements, and any other event which
953+
# celebrates an event # for a particular
954+
# person.
955+
@example "Greet a VIP" {vip-greet "Bob"} --result "And a special welcome to our VIP today, Bob!"
956+
@example "Greet multiple people" {vip-greet "Bob" ["Alice" "Charlie"]} --result "Hello, Alice!
957+
Hello, Charlie!
958+
And a special welcome to our VIP today, Bob!"
959+
def vip-greet [
960+
vip: string # The special guest
961+
...names: string # The other guests
962+
] {
963+
for $name in $names {
964+
print $"Hello, ($name)!"
965+
}
966+
967+
print $"And a special welcome to our VIP today, ($vip)!"
968+
}
969+
```
970+
971+
Now, run `help vip-greet` to see the examples added.
972+
973+
```text
974+
Greet guests along with a VIP
975+
976+
Use for birthdays, graduation parties,
977+
retirements, and any other event which
978+
celebrates an event # for a particular
979+
person.
980+
981+
Usage:
982+
> vip-greet <vip> ...(names)
983+
984+
Flags:
985+
-h, --help: Display the help message for this command
986+
987+
Parameters:
988+
vip <string>: The special guest
989+
...names <string>: The other guests
990+
991+
Input/output types:
992+
╭───┬───────┬────────╮
993+
│ # │ input │ output │
994+
├───┼───────┼────────┤
995+
│ 0 │ any │ any │
996+
╰───┴───────┴────────╯
997+
998+
Examples:
999+
Greet a VIP
1000+
> vip-greet "Bob"
1001+
And a special welcome to our VIP today, Bob!
1002+
1003+
Greet multiple people
1004+
> vip-greet "Bob" ["Alice" "Charlie"]
1005+
Hello, Alice!
1006+
Hello, Charlie!
1007+
And a special welcome to our VIP today, Bob!
1008+
```
1009+
1010+
When maintaining a script, module, plugin, or library written in nu, some custom
1011+
commands may end up being replaced by newer versions or removed completely, but
1012+
remain available temporarily to give users time to transition away from the older
1013+
functionality.
1014+
1015+
The `deprecated` attribute raises a warning to the users upon running
1016+
the custom command.
1017+
1018+
```nu
1019+
@deprecated
1020+
def greet [
1021+
name: string
1022+
--all-caps
1023+
] {
1024+
let greeting = $"Hello, ($name)!"
1025+
if $all_caps {
1026+
$greeting | str upcase
1027+
} else {
1028+
$greeting
1029+
}
1030+
}
1031+
```
1032+
1033+
Run `greet {name}` to see the warning.
1034+
1035+
```bash
1036+
> greet "bob"
1037+
Warning: nu::parser::deprecated
1038+
1039+
⚠ Command deprecated.
1040+
╭─[entry #13:1:1]
1041+
1 │ greet "bob"
1042+
· ─────┬─────
1043+
· ╰── greet is deprecated and will be removed in a future release.
1044+
╰────
1045+
1046+
Hello, bob!
1047+
```
1048+
1049+
If there is a replacement command or additional context that would
1050+
assist the user when updating their workflows, add text after `@deprecated`.
1051+
1052+
The `category` attribute assigns the specified label when using `scope commands`
1053+
or `help` commands.
1054+
1055+
```nu
1056+
@deprecated "Use vip-greet as a replacement."
1057+
@category "deprecated"
1058+
def greet [
1059+
name: string
1060+
--all-caps
1061+
] {
1062+
let greeting = $"Hello, ($name)!"
1063+
if $all_caps {
1064+
$greeting | str upcase
1065+
} else {
1066+
$greeting
1067+
}
1068+
}
1069+
```
1070+
1071+
```bash
1072+
> greet bob
1073+
Warning: nu::parser::deprecated
1074+
1075+
⚠ Command deprecated.
1076+
╭─[entry #15:1:1]
1077+
1 │ greet bob
1078+
· ────┬────
1079+
· ╰── greet is deprecated and will be removed in a future release.
1080+
╰────
1081+
help: Use vip-greet as a replacement.
1082+
1083+
Hello, bob!
1084+
1085+
> help commands | where category == deprecated
1086+
╭───────┬──────────┬───────────────┬─────────────────┬────────────────┬───────────────────────────────────────────────────────────────────────────────────────┬───────────────────┬─────────────────┬─────────────╮
1087+
│ # │ name │ category │ command_type │ description │ params │ input_output │ search_terms │ is_const │
1088+
├───────┼──────────┼───────────────┼─────────────────┼────────────────┼───────────────────────────────────────────────────────────────────────────────────────┼───────────────────┼─────────────────┼─────────────┤
1089+
│ 0 │ greet │ deprecated │ custom │ │ ╭───┬────────────┬────────┬──────────┬───────────────────────────────────────────╮ │ [list 0 items] │ │ false │
1090+
│ │ │ │ │ │ │ # │ name │ type │ required │ description │ │ │ │ │
1091+
│ │ │ │ │ │ ├───┼────────────┼────────┼──────────┼───────────────────────────────────────────┤ │ │ │ │
1092+
│ │ │ │ │ │ │ 0 │ name │ string │ true │ │ │ │ │ │
1093+
│ │ │ │ │ │ │ 1 │ --all-caps │ switch │ false │ │ │ │ │ │
1094+
│ │ │ │ │ │ │ 2 │ --help(-h) │ switch │ false │ Display the help message for this command │ │ │ │ │
1095+
│ │ │ │ │ │ ╰───┴────────────┴────────┴──────────┴───────────────────────────────────────────╯ │ │ │ │
1096+
╰───────┴──────────┴───────────────┴─────────────────┴────────────────┴───────────────────────────────────────────────────────────────────────────────────────┴───────────────────┴─────────────────┴─────────────╯
1097+
```
1098+
1099+
To see other attributes available for use within nushell, check the [command reference](/commands/docs/attr.html)
1100+
or run `help attr` from the nushell REPL.
1101+
9381102
## Changing the Environment in a Custom Command
9391103
9401104
Normally, environment variable definitions and changes are [_scoped_ within a block](./environment.html#scoping). This means that changes to those variables are lost when they go out of scope at the end of the block, including the block of a custom command.

0 commit comments

Comments
 (0)