mirror of
https://github.com/nushell/nushell.git
synced 2025-04-26 14:18:19 +02:00
442df9e39c
# 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>
111 lines
2.8 KiB
Plaintext
111 lines
2.8 KiB
Plaintext
# Add the given paths to the PATH.
|
|
@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.
|
|
...paths # the paths to add to $env.PATH.
|
|
] {
|
|
let span = (metadata $paths).span
|
|
let paths = $paths | flatten
|
|
|
|
if ($paths | is-empty) or ($paths | length) == 0 {
|
|
error make {msg: "Empty input", label: {
|
|
text: "Provide at least one string or a record",
|
|
span: $span
|
|
}}
|
|
}
|
|
|
|
let path_name = if "PATH" in $env { "PATH" } else { "Path" }
|
|
|
|
let paths = $paths | each {|p|
|
|
let p = match ($p | describe | str replace --regex '<.*' '') {
|
|
"string" => $p,
|
|
"record" => { $p | get --ignore-errors $nu.os-info.name },
|
|
}
|
|
|
|
$p | path expand --no-symlink
|
|
}
|
|
|
|
if null in $paths or ($paths | is-empty) {
|
|
error make {msg: "Empty input", label: {
|
|
text: $"Received a record, that does not contain a ($nu.os-info.name) key",
|
|
span: $span
|
|
}}
|
|
}
|
|
|
|
load-env {$path_name: (
|
|
$env
|
|
| get $path_name
|
|
| split row (char esep)
|
|
| if $append { append $paths } else { prepend $paths }
|
|
)}
|
|
|
|
if $ret {
|
|
$env | get $path_name
|
|
}
|
|
}
|
|
|
|
# the cute and friendly mascot of Nushell :)
|
|
export def ellie [] {
|
|
let ellie = [
|
|
" __ ,",
|
|
" .--()°'.'",
|
|
"'|, . ,'",
|
|
" !_-(_\\",
|
|
]
|
|
|
|
$ellie | str join "\n" | $"(ansi green)($in)(ansi reset)"
|
|
}
|
|
|
|
# repeat anything a bunch of times, yielding a list of *n* times the input
|
|
@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> {
|
|
let item = $in
|
|
|
|
if $n < 0 {
|
|
let span = metadata $n | get span
|
|
error make {
|
|
msg: $"(ansi red_bold)invalid_argument(ansi reset)"
|
|
label: {
|
|
text: $"n should be a positive integer, found ($n)"
|
|
span: $span
|
|
}
|
|
}
|
|
}
|
|
|
|
if $n == 0 {
|
|
return []
|
|
}
|
|
|
|
1..$n | each { $item }
|
|
}
|
|
|
|
# null device file
|
|
export const null_device = if $nu.os-info.name == "windows" {
|
|
'\\.\NUL'
|
|
} else {
|
|
'/dev/null'
|
|
}
|
|
|
|
# return a null device file.
|
|
@example "run a command and ignore it's stderr output" {
|
|
cat xxx.txt e> (null-device)
|
|
}
|
|
export def null-device []: nothing -> path {
|
|
$null_device
|
|
}
|