holm/nushell
1
1
Fork 0
forked from extern/nushell
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Custom command attributes (#14906)

Browse Source 
# 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:
Bahex
2025-02-11 15:34:51 +03:00
committed by GitHub
parent a58d9b0b3a
commit 442df9e39c
57 changed files with 2028 additions and 987 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
crates/nu-std/std/assert/mod.nu
View File

@ -7,32 +7,16 @@
# Universal assert command
#
# If the condition is not true, it generates an error.
#
# # Example
#
# ```nushell
# >_ assert (3 == 3)
# >_ assert (42 == 3)
# Error:
# × Assertion failed:
# ╭─[myscript.nu:11:1]
# 11 │ assert (3 == 3)
# 12 │ assert (42 == 3)
# · ───┬────
# · ╰── It is not true.
# 13 │
# ╰────
# ```
#
# The --error-label flag can be used if you want to create a custom assert command:
# ```
# def "assert even" [number: int] {
# assert ($number mod 2 == 0) --error-label {
# text: $"($number) is not an even number",
# span: (metadata $number).span,
# }
# }
# ```
@example "This assert passes" { assert (3 == 3) }
@example "This assert fails" { assert (42 == 3) }
@example "The --error-label flag can be used if you want to create a custom assert command:" {
def "assert even" [number: int] {
assert ($number mod 2 == 0) --error-label {
text: $"($number) is not an even number",
span: (metadata $number).span,
}
}
}
export def main [
condition: bool, # Condition, which should be true
message?: string, # Optional error message
@ -52,32 +36,16 @@ export def main [
# Negative assertion
#
# If the condition is not false, it generates an error.
#
# # Examples
#
# >_ assert (42 == 3)
# >_ assert (3 == 3)
# Error:
# × Assertion failed:
# ╭─[myscript.nu:11:1]
# 11 │ assert (42 == 3)
# 12 │ assert (3 == 3)
# · ───┬────
# · ╰── It is not false.
# 13 │
# ╰────
#
#
# The --error-label flag can be used if you want to create a custom assert command:
# ```
# def "assert not even" [number: int] {
# assert not ($number mod 2 == 0) --error-label {
# span: (metadata $number).span,
# text: $"($number) is an even number",
# }
# }
# ```
#
@example "This assert passes" { assert (42 == 3) }
@example "This assert fails" { assert (3 == 3) }
@example "The --error-label flag can be used if you want to create a custom assert command:" {
def "assert not even" [number: int] {
assert not ($number mod 2 == 0) --error-label {
span: (metadata $number).span,
text: $"($number) is an even number",
}
}
}
export def not [
condition: bool, # Condition, which should be false
message?: string, # Optional error message
@ -95,14 +63,12 @@ export def not [
}
}
# Assert that executing the code generates an error
#
# For more documentation see the assert command
#
# # Examples
#
# > assert error {|| missing_command} # passes
# > assert error {|| 12} # fails
@example "This assert passes" { assert error {|| missing_command} }
@example "This assert fails" { assert error {|| 12} }
export def error [
code: closure,
message?: string
@ -120,12 +86,9 @@ export def error [
# Assert $left == $right
#
# For more documentation see the assert command
#
# # Examples
#
# > assert equal 1 1 # passes
# > assert equal (0.1 + 0.2) 0.3
# > assert equal 1 2 # fails
@example "This assert passes" { assert equal 1 1 }
@example "This assert passes" { assert equal (0.1 + 0.2) 0.3 }
@example "This assert fails" { assert equal 1 2 }
export def equal [left: any, right: any, message?: string] {
main ($left == $right) $message --error-label {
span: {
@ -143,12 +106,9 @@ export def equal [left: any, right: any, message?: string] {
# Assert $left != $right
#
# For more documentation see the assert command
#
# # Examples
#
# > assert not equal 1 2 # passes
# > assert not equal 1 "apple" # passes
# > assert not equal 7 7 # fails
@example "This assert passes" { assert not equal 1 2 }
@example "This assert passes" { assert not equal 1 "apple" }
@example "This assert fails" { assert not equal 7 7 }
export def "not equal" [left: any, right: any, message?: string] {
main ($left != $right) $message --error-label {
span: {
@ -162,12 +122,9 @@ export def "not equal" [left: any, right: any, message?: string] {
# Assert $left <= $right
#
# For more documentation see the assert command
#
# # Examples
#
# > assert less or equal 1 2 # passes
# > assert less or equal 1 1 # passes
# > assert less or equal 1 0 # fails
@example "This assert passes" { assert less or equal 1 2 }
@example "This assert passes" { assert less or equal 1 1 }
@example "This assert fails" { assert less or equal 1 0 }
export def "less or equal" [left: any, right: any, message?: string] {
main ($left <= $right) $message --error-label {
span: {
@ -185,11 +142,8 @@ export def "less or equal" [left: any, right: any, message?: string] {
# Assert $left < $right
#
# For more documentation see the assert command
#
# # Examples
#
# > assert less 1 2 # passes
# > assert less 1 1 # fails
@example "This assert passes" { assert less 1 2 }
@example "This assert fails" { assert less 1 1 }
export def less [left: any, right: any, message?: string] {
main ($left < $right) $message --error-label {
span: {
@ -207,11 +161,8 @@ export def less [left: any, right: any, message?: string] {
# Assert $left > $right
#
# For more documentation see the assert command
#
# # Examples
#
# > assert greater 2 1 # passes
# > assert greater 2 2 # fails
@example "This assert passes" { assert greater 2 1 }
@example "This assert fails" { assert greater 2 2 }
export def greater [left: any, right: any, message?: string] {
main ($left > $right) $message --error-label {
span: {
@ -229,12 +180,9 @@ export def greater [left: any, right: any, message?: string] {
# Assert $left >= $right
#
# For more documentation see the assert command
#
# # Examples
#
# > assert greater or equal 2 1 # passes
# > assert greater or equal 2 2 # passes
# > assert greater or equal 1 2 # fails
@example "This assert passes" { assert greater or equal 2 1 }
@example "This assert passes" { assert greater or equal 2 2 }
@example "This assert fails" { assert greater or equal 1 2 }
export def "greater or equal" [left: any, right: any, message?: string] {
main ($left >= $right) $message --error-label {
span: {
@ -253,11 +201,8 @@ alias "core length" = length
# Assert length of $left is $right
#
# For more documentation see the assert command
#
# # Examples
#
# > assert length [0, 0] 2 # passes
# > assert length [0] 3 # fails
@example "This assert passes" { assert length [0, 0] 2 }
@example "This assert fails" { assert length [0] 3 }
export def length [left: list, right: int, message?: string] {
main (($left | core length) == $right) $message --error-label {
span: {
@ -277,11 +222,8 @@ alias "core str contains" = str contains
# Assert that ($left | str contains $right)
#
# For more documentation see the assert command
#
# # Examples
#
# > assert str contains "arst" "rs" # passes
# > assert str contains "arst" "k" # fails
@example "This assert passes" { assert str contains "arst" "rs" }
@example "This assert fails" { assert str contains "arst" "k" }
export def "str contains" [left: string, right: string, message?: string] {
main ($left | core str contains $right) $message --error-label {
span: {

51
crates/nu-std/std/bench/mod.nu
View File

@ -1,45 +1,34 @@
# run a piece of `nushell` code multiple times and measure the time of execution.
#
# this command returns a benchmark report of the following form:
# ```
# record<
# mean: duration
# std: duration
# times: list<duration>
# >
# ```
#
# > **Note**
# > `std bench --pretty` will return a `string`.
#
# # Examples
# measure the performance of simple addition
# > std bench { 1 + 2 } -n 10 | table -e
# ╭───────┬────────────────────╮
# │ mean │ 4µs 956ns │
# │ std │ 4µs 831ns │
# │ │ ╭───┬────────────╮ │
# │ times │ │ 0 │ 19µs 402ns │ │
# │ │ │ 1 │ 4µs 322ns │ │
# │ │ │ 2 │ 3µs 352ns │ │
# │ │ │ 3 │ 2µs 966ns │ │
# │ │ │ 4 │ 3µs │ │
# │ │ │ 5 │ 3µs 86ns │ │
# │ │ │ 6 │ 3µs 84ns │ │
# │ │ │ 7 │ 3µs 604ns │ │
# │ │ │ 8 │ 3µs 98ns │ │
# │ │ │ 9 │ 3µs 653ns │ │
# │ │ ╰───┴────────────╯ │
# ╰───────┴────────────────────╯
#
# get a pretty benchmark report
# > std bench { 1 + 2 } --pretty
# 3µs 125ns +/- 2µs 408ns
@example "measure the performance of simple addition" { bench { 1 + 2 } -n 10 } --result {
mean: (4µs + 956ns)
std: (4µs + 831ns)
times: [
(19µs + 402ns)
( 4µs + 322ns)
( 3µs + 352ns)
( 2µs + 966ns)
( 3µs )
( 3µs + 86ns)
( 3µs + 84ns)
( 3µs + 604ns)
( 3µs + 98ns)
( 3µs + 653ns)
]
}
@example "get a pretty benchmark report" { bench { 1 + 2 } --pretty } --result "3µs 125ns +/- 2µs 408ns"
export def main [
code: closure # the piece of `nushell` code to measure the performance of
--rounds (-n): int = 50 # the number of benchmark rounds (hopefully the more rounds the less variance)
--verbose (-v) # be more verbose (namely prints the progress)
--pretty # shows the results in human-readable format: "<mean> +/- <stddev>"
]: [
nothing -> record<mean: duration, std: duration, times: list<duration>>
nothing -> string
] {
let times: list<duration> = (
seq 1 $rounds | each {|i|

40
crates/nu-std/std/dt/mod.nu
View File

@ -89,23 +89,23 @@ def borrow-second [from: record, current: record] {
}
# Subtract later from earlier datetime and return the unit differences as a record
# Example:
# > dt datetime-diff 2023-05-07T04:08:45+12:00 2019-05-10T09:59:12-07:00
# ╭─────────────┬────╮
# │ year │ 3 │
# │ month │ 11 │
# │ day │ 26 │
# │ hour │ 23 │
# │ minute │ 9 │
# │ second │ 33 │
# │ millisecond │ 0 │
# │ microsecond │ 0 │
# │ nanosecond │ 0 │
# ╰─────────────┴────╯
@example "Get the difference between two dates" {
dt datetime-diff 2023-05-07T04:08:45+12:00 2019-05-10T09:59:12-07:00
} --result {
year: 3,
month: 11,
day: 26,
hour: 23,
minute: 9,
second: 33,
millisecond: 0,
microsecond: 0,
nanosecond: 0,
}
export def datetime-diff [
later: datetime, # a later datetime
earlier: datetime # earlier (starting) datetime
] {
later: datetime, # a later datetime
earlier: datetime # earlier (starting) datetime
]: [nothing -> record] {
if $earlier > $later {
let start = (metadata $later).span.start
let end = (metadata $earlier).span.end
@ -162,10 +162,10 @@ export def datetime-diff [
}
# Convert record from datetime-diff into humanized string
# Example:
# > dt pretty-print-duration (dt datetime-diff 2023-05-07T04:08:45+12:00 2019-05-10T09:59:12+12:00)
# 3yrs 11months 27days 18hrs 9mins 33secs
export def pretty-print-duration [dur: record] {
@example "Format the difference between two dates into a human readable string" {
dt pretty-print-duration (dt datetime-diff 2023-05-07T04:08:45+12:00 2019-05-10T09:59:12+12:00)
} --result "3yrs 11months 27days 18hrs 9mins 33secs"
export def pretty-print-duration [dur: record]: [nothing -> string] {
mut result = ""
if $dur.year != 0 {
if $dur.year > 1 {

141
crates/nu-std/std/iter/mod.nu
View File

@ -14,21 +14,12 @@
# > The closure also has to be valid for the types it receives
# > These will be flagged as errors later as closure annotations
# > are implemented
#
# # Example
# ```
# use std ["assert equal" "iter find"]
#
# let haystack = ["shell", "abc", "around", "nushell", "std"]
#
# let found = ($haystack | iter find {|e| $e starts-with "a" })
# let not_found = ($haystack | iter find {|e| $e mod 2 == 0})
#
# assert equal $found "abc"
# assert equal $not_found null
# ```
export def find [ # -> any | null
fn: closure # the closure used to perform the search
@example "Find an element starting with 'a'" {
["shell", "abc", "around", "nushell", "std"] | iter find {|e| $e starts-with "a" }
} --result "abc"
@example "Try to find an element starting with 'a'" { ["shell", "abc", "around", "nushell", "std"] | iter find {|e| $e mod 2 == 0} } --result null
export def find [
fn: closure # the closure used to perform the search
] {
filter {|e| try {do $fn $e} } | try { first }
}
@ -38,23 +29,14 @@ export def find [ # -> any | null
#
# # Invariant
# > The closure has to return a bool
#
# # Example
# ```nu
# use std ["assert equal" "iter find-index"]
#
# let res = (
# ["iter", "abc", "shell", "around", "nushell", "std"]
# | iter find-index {|x| $x starts-with 's'}
# )
# assert equal $res 2
#
# let is_even = {|x| $x mod 2 == 0}
# let res = ([3 5 13 91] | iter find-index $is_even)
# assert equal $res -1
# ```
export def find-index [ # -> int
fn: closure # the closure used to perform the search
@example "Find the index of an element starting with 's'" {
["iter", "abc", "shell", "around", "nushell", "std"] | iter find-index {|x| $x starts-with 's'}
} --result 2
@example "Try to find the index of an element starting with 's'" {
[3 5 13 91] | iter find-index {|x| $x mod 2 == 0}
} --result -1
export def find-index [
fn: closure # the closure used to perform the search
] {
enumerate
| find {|e| $e.item | do $fn $e.item }
@ -63,16 +45,11 @@ export def find-index [ # -> int
# Returns a new list with the separator between adjacent
# items of the original list
#
# # Example
# ```
# use std ["assert equal" "iter intersperse"]
#
# let res = ([1 2 3 4] | iter intersperse 0)
# assert equal $res [1 0 2 0 3 0 4]
# ```
export def intersperse [ # -> list<any>
separator: any # the separator to be used
@example "Intersperse the list with `0`" {
[1 2 3 4] | iter intersperse 0
} --result [1 0 2 0 3 0 4]
export def intersperse [
separator: any # the separator to be used
] {
reduce --fold [] {|e, acc|
$acc ++ [$e, $separator]
@ -89,20 +66,12 @@ export def intersperse [ # -> list<any>
# being the list element in the current iteration and the second
# the internal state.
# The internal state is also provided as pipeline input.
#
# # Example
# ```
# use std ["assert equal" "iter scan"]
# let scanned = ([1 2 3] | iter scan 0 {|x, y| $x + $y})
#
# assert equal $scanned [0, 1, 3, 6]
#
# # use the --noinit(-n) flag to remove the initial value from
# # the final result
# let scanned = ([1 2 3] | iter scan 0 {|x, y| $x + $y} -n)
#
# assert equal $scanned [1, 3, 6]
# ```
@example "Get a running sum of the input list" {
[1 2 3] | iter scan 0 {|x, y| $x + $y}
} --result [0, 1, 3, 6]
@example "use the `--noinit(-n)` flag to remove the initial value from the final result" {
[1 2 3] | iter scan 0 {|x, y| $x + $y} -n
} --result [1, 3, 6]
export def scan [ # -> list<any>
init: any # initial value to seed the initial state
fn: closure # the closure to perform the scan
@ -118,16 +87,10 @@ export def scan [ # -> list<any>
# Returns a list of values for which the supplied closure does not
# return `null` or an error. It is equivalent to
# `$in | each $fn | filter $fn`
#
# # Example
# ```nu
# use std ["assert equal" "iter filter-map"]
#
# let res = ([2 5 "4" 7] | iter filter-map {|e| $e ** 2})
#
# assert equal $res [4 25 49]
# ```
export def filter-map [ # -> list<any>
@example "Get the squares of elements that can be squared" {
[2 5 "4" 7] | iter filter-map {|e| $e ** 2}
} --result [4, 25, 49]
export def filter-map [
fn: closure # the closure to apply to the input
] {
each {|$e|
@ -143,16 +106,9 @@ export def filter-map [ # -> list<any>
}
# Maps a closure to each nested structure and flattens the result
#
# # Example
# ```nu
# use std ["assert equal" "iter flat-map"]
#
# let res = (
# [[1 2 3] [2 3 4] [5 6 7]] | iter flat-map {|e| $e | math sum}
# )
# assert equal $res [6 9 18]
# ```
@example "Get the sums of list elements" {
[[1 2 3] [2 3 4] [5 6 7]] | iter flat-map {|e| $e | math sum}
} --result [6, 9, 18]
export def flat-map [ # -> list<any>
fn: closure # the closure to map to the nested structures
] {
@ -160,18 +116,10 @@ export def flat-map [ # -> list<any>
}
# Zips two structures and applies a closure to each of the zips
#
# # Example
# ```nu
# use std ["assert equal" "iter iter zip-with"]
#
# let res = (
# [1 2 3] | iter zip-with [2 3 4] {|a, b| $a + $b }
# )
#
# assert equal $res [3 5 7]
# ```
export def zip-with [ # -> list<any>
@example "Add two lists element-wise" {
[1 2 3] | iter zip-with [2 3 4] {|a, b| $a + $b }
} --result [3, 5, 7]
export def zip-with [ # -> list<any>
other: any # the structure to zip with
fn: closure # the closure to apply to the zips
] {
@ -182,20 +130,9 @@ export def zip-with [ # -> list<any>
}
# Zips two lists and returns a record with the first list as headers
#
# # Example
# ```nu
# use std ["assert equal" "iter iter zip-into-record"]
#
# let res = (
# [1 2 3] | iter zip-into-record [2 3 4]
# )
#
# assert equal $res [
# [1 2 3];
# [2 3 4]
# ]
# ```
@example "Create record from two lists" {
[1 2 3] | iter zip-into-record [2 3 4]
} --result [{1: 2, 2: 3, 3: 4}]
export def zip-into-record [ # -> table<any>
other: list # the values to zip with
] {

1
crates/nu-std/std/mod.nu
View File

@ -15,6 +15,7 @@ export module std/log
export module std/math
export module std/xml
export module std/config
export module std/testing
# Load main dirs command and all subcommands
export use std/dirs main

17
crates/nu-std/std/testing/mod.nu Normal file
View File

@ -0,0 +1,17 @@
# Mark command as a test
export alias "attr test" = echo
# Mark a test command to be ignored
export alias "attr ignore" = echo
# Mark a command to be run before each test
export alias "attr before-each" = echo
# Mark a command to be run once before all tests
export alias "attr before-all" = echo
# Mark a command to be run after each test
export alias "attr after-each" = echo
# Mark a command to be run once after all tests
export alias "attr after-all" = echo

51
crates/nu-std/std/util/mod.nu
View File

@ -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
}