mirror of
https://github.com/nushell/nushell.git
synced 2025-06-30 22:50:14 +02:00
Custom command attributes (#14906)
# Description Add custom command attributes. - Attributes are placed before a command definition and start with a `@` character. - Attribute invocations consist of const command call. The command's name must start with "attr ", but this prefix is not used in the invocation. - A command named `attr example` is invoked as an attribute as `@example` - Several built-in attribute commands are provided as part of this PR - `attr example`: Attaches an example to the commands help text ```nushell # Double numbers @example "double an int" { 5 | double } --result 10 @example "double a float" { 0.5 | double } --result 1.0 def double []: [number -> number] { $in * 2 } ``` - `attr search-terms`: Adds search terms to a command - ~`attr env`: Equivalent to using `def --env`~ - ~`attr wrapped`: Equivalent to using `def --wrapped`~ shelved for later discussion - several testing related attributes in `std/testing` - If an attribute has no internal/special purpose, it's stored as command metadata that can be obtained with `scope commands`. - This allows having attributes like `@test` which can be used by test runners. - Used the `@example` attribute for `std` examples. - Updated the std tests and test runner to use `@test` attributes - Added completions for attributes # User-Facing Changes Users can add examples to their own command definitions, and add other arbitrary attributes. # Tests + Formatting - 🟢 toolkit fmt - 🟢 toolkit clippy - 🟢 toolkit test - 🟢 toolkit test stdlib # After Submitting - Add documentation about the attribute syntax and built-in attributes - `help attributes` --------- Co-authored-by: 132ikl <132@ikl.sh>
This commit is contained in:
@ -1,29 +1,15 @@
|
||||
# Add the given paths to the PATH.
|
||||
#
|
||||
# # Example
|
||||
# - adding some dummy paths to an empty PATH
|
||||
# ```nushell
|
||||
# >_ with-env { PATH: [] } {
|
||||
# std path add "foo"
|
||||
# std path add "bar" "baz"
|
||||
# std path add "fooo" --append
|
||||
#
|
||||
# assert equal $env.PATH ["bar" "baz" "foo" "fooo"]
|
||||
#
|
||||
# print (std path add "returned" --ret)
|
||||
# }
|
||||
# ╭───┬──────────╮
|
||||
# │ 0 │ returned │
|
||||
# │ 1 │ bar │
|
||||
# │ 2 │ baz │
|
||||
# │ 3 │ foo │
|
||||
# │ 4 │ fooo │
|
||||
# ╰───┴──────────╯
|
||||
# ```
|
||||
# - adding paths based on the operating system
|
||||
# ```nushell
|
||||
# >_ std path add {linux: "foo", windows: "bar", darwin: "baz"}
|
||||
# ```
|
||||
@example "adding some dummy paths to an empty PATH" {
|
||||
with-env { PATH: [] } {
|
||||
path add "foo"
|
||||
path add "bar" "baz"
|
||||
path add "fooo" --append
|
||||
path add "returned" --ret
|
||||
}
|
||||
} --result [returned bar baz foo fooo]
|
||||
@example "adding paths based on the operating system" {
|
||||
path add {linux: "foo", windows: "bar", darwin: "baz"}
|
||||
}
|
||||
export def --env "path add" [
|
||||
--ret (-r) # return $env.PATH, useful in pipelines to avoid scoping.
|
||||
--append (-a) # append to $env.PATH instead of prepending to.
|
||||
@ -82,11 +68,9 @@ export def ellie [] {
|
||||
}
|
||||
|
||||
# repeat anything a bunch of times, yielding a list of *n* times the input
|
||||
#
|
||||
# # Examples
|
||||
# repeat a string
|
||||
# > "foo" | std repeat 3 | str join
|
||||
# "foofoofoo"
|
||||
@example "repeat a string" {
|
||||
"foo" | std repeat 3 | str join
|
||||
} --result "foofoofoo"
|
||||
export def repeat [
|
||||
n: int # the number of repetitions, must be positive
|
||||
]: any -> list<any> {
|
||||
@ -118,10 +102,9 @@ export const null_device = if $nu.os-info.name == "windows" {
|
||||
}
|
||||
|
||||
# return a null device file.
|
||||
#
|
||||
# # Examples
|
||||
# run a command and ignore it's stderr output
|
||||
# > cat xxx.txt e> (null-device)
|
||||
@example "run a command and ignore it's stderr output" {
|
||||
cat xxx.txt e> (null-device)
|
||||
}
|
||||
export def null-device []: nothing -> path {
|
||||
$null_device
|
||||
}
|
||||
|
Reference in New Issue
Block a user