mirror of
https://github.com/nushell/nushell.git
synced 2025-04-25 21:58:18 +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>
56 lines
1.7 KiB
Plaintext
56 lines
1.7 KiB
Plaintext
# run a piece of `nushell` code multiple times and measure the time of execution.
|
|
#
|
|
# this command returns a benchmark report of the following form:
|
|
#
|
|
# > **Note**
|
|
# > `std bench --pretty` will return a `string`.
|
|
@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|
|
|
if $verbose { print -n $"($i) / ($rounds)\r" }
|
|
timeit { do $code }
|
|
}
|
|
)
|
|
|
|
if $verbose { print $"($rounds) / ($rounds)" }
|
|
|
|
let report = {
|
|
mean: ($times | math avg)
|
|
min: ($times | math min)
|
|
max: ($times | math max)
|
|
std: ($times | into int | math stddev | into int | into duration)
|
|
times: ($times)
|
|
}
|
|
|
|
if $pretty {
|
|
$"($report.mean) +/- ($report.std)"
|
|
} else {
|
|
$report
|
|
}
|
|
}
|