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>

crates/nu-std/std/assert/mod.nu

@@ -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: {