nushell/crates/nu-protocol/src
Bahex 442df9e39c
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>
2025-02-11 06:34:51 -06:00
..
ast Custom command attributes (#14906) 2025-02-11 06:34:51 -06:00
config Improve and fix filesize formatting/display (#14397) 2025-01-22 22:24:51 -08:00
debugger Custom command attributes (#14906) 2025-02-11 06:34:51 -06:00
engine Custom command attributes (#14906) 2025-02-11 06:34:51 -06:00
errors Custom command attributes (#14906) 2025-02-11 06:34:51 -06:00
ir fix: clippy warning of rust 1.8.4 (#14984) 2025-02-02 07:56:54 -06:00
pipeline check signals while printing values (#14980) 2025-02-07 06:56:07 -05:00
plugin Change the usage misnomer to "description" (#13598) 2024-08-22 12:02:08 +02:00
process Refactor I/O Errors (#14927) 2025-01-28 16:03:31 -06:00
value fix ranges over zero-length input (#15062) 2025-02-08 19:57:28 -05:00
alias.rs Change the usage misnomer to "description" (#13598) 2024-08-22 12:02:08 +02:00
did_you_mean.rs Improve case insensitivity consistency (#10884) 2023-11-08 23:58:54 +01:00
eval_base.rs Custom command attributes (#14906) 2025-02-11 06:34:51 -06:00
eval_const.rs Refactor I/O Errors (#14927) 2025-01-28 16:03:31 -06:00
example.rs Overhaul the plugin cache file with a new msgpack+brotli format (#12579) 2024-04-21 07:36:26 -05:00
id.rs Make SpanId and RegId also use new ID struct (#13963) 2024-10-01 13:23:27 +02:00
lev_distance.rs Rework for new clippy lints (#12736) 2024-05-02 19:29:03 +02:00
lib.rs Start to Add WASM Support Again (#14418) 2024-11-30 07:57:11 -06:00
module.rs refactor(parser): use var_id for most constants in ResolvedImportPattern (#14920) 2025-01-26 15:43:34 +02:00
parser_path.rs Replace raw usize IDs with new types (#13832) 2024-09-30 13:20:15 +02:00
signature.rs Custom command attributes (#14906) 2025-02-11 06:34:51 -06:00
span.rs Fix cargo doc Warnings (#14948) 2025-01-28 18:09:53 -06:00
syntax_shape.rs Remove unsued types (#14916) 2025-01-26 12:30:58 +08:00
ty.rs Fix cargo doc Warnings (#14948) 2025-01-28 18:09:53 -06:00