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-cli/src/completions/attribute_completions.rs

@@ -0,0 +1,97 @@
+use super::{completion_options::NuMatcher, SemanticSuggestion};
+use crate::{
+    completions::{Completer, CompletionOptions},
+    SuggestionKind,
+};
+use nu_protocol::{
+    engine::{Stack, StateWorkingSet},
+    Span,
+};
+use reedline::Suggestion;
+
+pub struct AttributeCompletion;
+pub struct AttributableCompletion;
+
+impl Completer for AttributeCompletion {
+    fn fetch(
+        &mut self,
+        working_set: &StateWorkingSet,
+        _stack: &Stack,
+        _prefix: &[u8],
+        span: Span,
+        offset: usize,
+        _pos: usize,
+        options: &CompletionOptions,
+    ) -> Vec<SemanticSuggestion> {
+        let partial = working_set.get_span_contents(span);
+        let mut matcher = NuMatcher::new(String::from_utf8_lossy(partial), options.clone());
+
+        let attr_commands = working_set.find_commands_by_predicate(
+            |s| {
+                s.strip_prefix(b"attr ")
+                    .map(String::from_utf8_lossy)
+                    .is_some_and(|name| matcher.matches(&name))
+            },
+            true,
+        );
+
+        for (name, desc, ty) in attr_commands {
+            let name = name.strip_prefix(b"attr ").unwrap_or(&name);
+            matcher.add_semantic_suggestion(SemanticSuggestion {
+                suggestion: Suggestion {
+                    value: String::from_utf8_lossy(name).into_owned(),
+                    description: desc,
+                    style: None,
+                    extra: None,
+                    span: reedline::Span {
+                        start: span.start - offset,
+                        end: span.end - offset,
+                    },
+                    append_whitespace: false,
+                },
+                kind: Some(SuggestionKind::Command(ty)),
+            });
+        }
+
+        matcher.results()
+    }
+}
+
+impl Completer for AttributableCompletion {
+    fn fetch(
+        &mut self,
+        working_set: &StateWorkingSet,
+        _stack: &Stack,
+        _prefix: &[u8],
+        span: Span,
+        offset: usize,
+        _pos: usize,
+        options: &CompletionOptions,
+    ) -> Vec<SemanticSuggestion> {
+        let partial = working_set.get_span_contents(span);
+        let mut matcher = NuMatcher::new(String::from_utf8_lossy(partial), options.clone());
+
+        for s in ["def", "extern", "export def", "export extern"] {
+            let decl_id = working_set
+                .find_decl(s.as_bytes())
+                .expect("internal error, builtin declaration not found");
+            let cmd = working_set.get_decl(decl_id);
+            matcher.add_semantic_suggestion(SemanticSuggestion {
+                suggestion: Suggestion {
+                    value: cmd.name().into(),
+                    description: Some(cmd.description().into()),
+                    style: None,
+                    extra: None,
+                    span: reedline::Span {
+                        start: span.start - offset,
+                        end: span.end - offset,
+                    },
+                    append_whitespace: false,
+                },
+                kind: Some(SuggestionKind::Command(cmd.command_type())),
+            });
+        }
+
+        matcher.results()
+    }
+}

crates/nu-cli/src/completions/completer.rs

@@ -1,7 +1,7 @@
 use crate::completions::{
-    CellPathCompletion, CommandCompletion, Completer, CompletionOptions, CustomCompletion,
-    DirectoryCompletion, DotNuCompletion, FileCompletion, FlagCompletion, OperatorCompletion,
-    VariableCompletion,
+    AttributableCompletion, AttributeCompletion, CellPathCompletion, CommandCompletion, Completer,
+    CompletionOptions, CustomCompletion, DirectoryCompletion, DotNuCompletion, FileCompletion,
+    FlagCompletion, OperatorCompletion, VariableCompletion,
 };
 use log::debug;
 use nu_color_config::{color_record_to_nustyle, lookup_ansi_color_style};
@@ -63,6 +63,15 @@ fn find_pipeline_element_by_position<'a>(
             .map(FindMapResult::Found)
             .unwrap_or_default(),
         Expr::Var(_) => FindMapResult::Found(expr),
+        Expr::AttributeBlock(ab) => ab
+            .attributes
+            .iter()
+            .map(|attr| &attr.expr)
+            .chain(Some(ab.item.as_ref()))
+            .find_map(|expr| expr.find_map(working_set, &closure))
+            .or(Some(expr))
+            .map(FindMapResult::Found)
+            .unwrap_or_default(),
         _ => FindMapResult::Continue,
     }
 }
@@ -297,6 +306,29 @@ impl NuCompleter {
                 let index = pos - span.start;
                 let prefix = &current_span[..index];
 
+                if let Expr::AttributeBlock(ab) = &element_expression.expr {
+                    let last_attr = ab.attributes.last().expect("at least one attribute");
+                    if let Expr::Garbage = last_attr.expr.expr {
+                        return self.process_completion(
+                            &mut AttributeCompletion,
+                            &working_set,
+                            prefix,
+                            new_span,
+                            fake_offset,
+                            pos,
+                        );
+                    } else {
+                        return self.process_completion(
+                            &mut AttributableCompletion,
+                            &working_set,
+                            prefix,
+                            new_span,
+                            fake_offset,
+                            pos,
+                        );
+                    }
+                }
+
                 // Flags completion
                 if prefix.starts_with(b"-") {
                     // Try to complete flag internally

crates/nu-cli/src/completions/mod.rs

@@ -1,3 +1,4 @@
+mod attribute_completions;
 mod base;
 mod cell_path_completions;
 mod command_completions;
@@ -12,6 +13,7 @@ mod flag_completions;
 mod operator_completions;
 mod variable_completions;
 
+pub use attribute_completions::{AttributableCompletion, AttributeCompletion};
 pub use base::{Completer, SemanticSuggestion, SuggestionKind};
 pub use cell_path_completions::CellPathCompletion;
 pub use command_completions::CommandCompletion;

crates/nu-cli/src/syntax_highlight.rs

@@ -309,6 +309,7 @@ fn find_matching_block_end_in_expr(
             .unwrap_or(expression.span.start);
 
         return match &expression.expr {
+            // TODO: Can't these be handled with an `_ => None` branch? Refactor
             Expr::Bool(_) => None,
             Expr::Int(_) => None,
             Expr::Float(_) => None,
@@ -335,6 +336,28 @@ fn find_matching_block_end_in_expr(
             Expr::Nothing => None,
             Expr::Garbage => None,
 
+            Expr::AttributeBlock(ab) => ab
+                .attributes
+                .iter()
+                .find_map(|attr| {
+                    find_matching_block_end_in_expr(
+                        line,
+                        working_set,
+                        &attr.expr,
+                        global_span_offset,
+                        global_cursor_offset,
+                    )
+                })
+                .or_else(|| {
+                    find_matching_block_end_in_expr(
+                        line,
+                        working_set,
+                        &ab.item,
+                        global_span_offset,
+                        global_cursor_offset,
+                    )
+                }),
+
             Expr::Table(table) => {
                 if expr_last == global_cursor_offset {
                     // cursor is at table end

crates/nu-cli/tests/completions/mod.rs

@@ -1213,6 +1213,44 @@ fn flag_completions() {
     match_suggestions(&expected, &suggestions);
 }
 
+#[test]
+fn attribute_completions() {
+    // Create a new engine
+    let (_, _, engine, stack) = new_engine();
+
+    // Instantiate a new completer
+    let mut completer = NuCompleter::new(Arc::new(engine), Arc::new(stack));
+    // Test completions for the 'ls' flags
+    let suggestions = completer.complete("@", 1);
+
+    // Only checking for the builtins and not the std attributes
+    let expected: Vec<String> = vec!["example".into(), "search-terms".into()];
+
+    // Match results
+    match_suggestions(&expected, &suggestions);
+}
+
+#[test]
+fn attributable_completions() {
+    // Create a new engine
+    let (_, _, engine, stack) = new_engine();
+
+    // Instantiate a new completer
+    let mut completer = NuCompleter::new(Arc::new(engine), Arc::new(stack));
+    // Test completions for the 'ls' flags
+    let suggestions = completer.complete("@example; ", 10);
+
+    let expected: Vec<String> = vec![
+        "def".into(),
+        "export def".into(),
+        "export extern".into(),
+        "extern".into(),
+    ];
+
+    // Match results
+    match_suggestions(&expected, &suggestions);
+}
+
 #[test]
 fn folder_with_directorycompletions() {
     // Create a new engine

crates/nu-cmd-lang/src/core_commands/attr/example.rs

@@ -0,0 +1,159 @@
+use nu_engine::command_prelude::*;
+
+#[derive(Clone)]
+pub struct AttrExample;
+
+impl Command for AttrExample {
+    fn name(&self) -> &str {
+        "attr example"
+    }
+
+    // TODO: When const closure are available, switch to using them for the `example` argument
+    // rather than a block. That should remove the need for `requires_ast_for_arguments` to be true
+    fn signature(&self) -> Signature {
+        Signature::build("attr example")
+            .input_output_types(vec![(
+                Type::Nothing,
+                Type::Record(
+                    [
+                        ("description".into(), Type::String),
+                        ("example".into(), Type::String),
+                    ]
+                    .into(),
+                ),
+            )])
+            .allow_variants_without_examples(true)
+            .required(
+                "description",
+                SyntaxShape::String,
+                "Description of the example.",
+            )
+            .required(
+                "example",
+                SyntaxShape::OneOf(vec![SyntaxShape::Block, SyntaxShape::String]),
+                "Example code snippet.",
+            )
+            .named(
+                "result",
+                SyntaxShape::Any,
+                "Expected output of example.",
+                None,
+            )
+            .category(Category::Core)
+    }
+
+    fn description(&self) -> &str {
+        "Attribute for adding examples to custom commands."
+    }
+
+    fn run(
+        &self,
+        engine_state: &EngineState,
+        stack: &mut Stack,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<PipelineData, ShellError> {
+        let description: Spanned<String> = call.req(engine_state, stack, 0)?;
+        let result: Option<Value> = call.get_flag(engine_state, stack, "result")?;
+
+        let example_string: Result<String, _> = call.req(engine_state, stack, 1);
+        let example_expr = call
+            .positional_nth(stack, 1)
+            .ok_or(ShellError::MissingParameter {
+                param_name: "example".into(),
+                span: call.head,
+            })?;
+
+        let working_set = StateWorkingSet::new(engine_state);
+
+        attr_example_impl(
+            example_expr,
+            example_string,
+            &working_set,
+            call,
+            description,
+            result,
+        )
+    }
+
+    fn run_const(
+        &self,
+        working_set: &StateWorkingSet,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<PipelineData, ShellError> {
+        let description: Spanned<String> = call.req_const(working_set, 0)?;
+        let result: Option<Value> = call.get_flag_const(working_set, "result")?;
+
+        let example_string: Result<String, _> = call.req_const(working_set, 1);
+        let example_expr =
+            call.assert_ast_call()?
+                .positional_nth(1)
+                .ok_or(ShellError::MissingParameter {
+                    param_name: "example".into(),
+                    span: call.head,
+                })?;
+
+        attr_example_impl(
+            example_expr,
+            example_string,
+            working_set,
+            call,
+            description,
+            result,
+        )
+    }
+
+    fn is_const(&self) -> bool {
+        true
+    }
+
+    fn requires_ast_for_arguments(&self) -> bool {
+        true
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![Example {
+            description: "Add examples to custom command",
+            example: r###"# Double numbers
+    @example "double an int" { 2 | double } --result 4
+    @example "double a float" { 0.25 | double } --result 0.5
+    def double []: [number -> number] { $in * 2 }"###,
+            result: None,
+        }]
+    }
+}
+
+fn attr_example_impl(
+    example_expr: &nu_protocol::ast::Expression,
+    example_string: Result<String, ShellError>,
+    working_set: &StateWorkingSet<'_>,
+    call: &Call<'_>,
+    description: Spanned<String>,
+    result: Option<Value>,
+) -> Result<PipelineData, ShellError> {
+    let example_content = match example_expr.as_block() {
+        Some(block_id) => {
+            let block = working_set.get_block(block_id);
+            let contents =
+                working_set.get_span_contents(block.span.expect("a block must have a span"));
+            let contents = contents
+                .strip_prefix(b"{")
+                .and_then(|x| x.strip_suffix(b"}"))
+                .unwrap_or(contents)
+                .trim_ascii();
+            String::from_utf8_lossy(contents).into_owned()
+        }
+        None => example_string?,
+    };
+
+    let mut rec = record! {
+        "description" => Value::string(description.item, description.span),
+        "example" => Value::string(example_content, example_expr.span),
+    };
+    if let Some(result) = result {
+        rec.push("result", result);
+    }
+
+    Ok(Value::record(rec, call.head).into_pipeline_data())
+}

crates/nu-cmd-lang/src/core_commands/attr/mod.rs

@@ -0,0 +1,5 @@
+mod example;
+mod search_terms;
+
+pub use example::AttrExample;
+pub use search_terms::AttrSearchTerms;

crates/nu-cmd-lang/src/core_commands/attr/search_terms.rs

@@ -0,0 +1,57 @@
+use nu_engine::command_prelude::*;
+
+#[derive(Clone)]
+pub struct AttrSearchTerms;
+
+impl Command for AttrSearchTerms {
+    fn name(&self) -> &str {
+        "attr search-terms"
+    }
+
+    fn signature(&self) -> Signature {
+        Signature::build("attr search-terms")
+            .input_output_type(Type::Nothing, Type::list(Type::String))
+            .allow_variants_without_examples(true)
+            .rest("terms", SyntaxShape::String, "Search terms.")
+            .category(Category::Core)
+    }
+
+    fn description(&self) -> &str {
+        "Attribute for adding search terms to custom commands."
+    }
+
+    fn run(
+        &self,
+        engine_state: &EngineState,
+        stack: &mut Stack,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<PipelineData, ShellError> {
+        let args = call.rest(engine_state, stack, 0)?;
+        Ok(Value::list(args, call.head).into_pipeline_data())
+    }
+
+    fn run_const(
+        &self,
+        working_set: &StateWorkingSet,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<PipelineData, ShellError> {
+        let args = call.rest_const(working_set, 0)?;
+        Ok(Value::list(args, call.head).into_pipeline_data())
+    }
+
+    fn is_const(&self) -> bool {
+        true
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![Example {
+            description: "Add search terms to a custom command",
+            example: r###"# Double numbers
+    @search-terms multiply times
+    def double []: [number -> number] { $in * 2 }"###,
+            result: None,
+        }]
+    }
+}

crates/nu-cmd-lang/src/core_commands/mod.rs

@@ -1,4 +1,5 @@
 mod alias;
+mod attr;
 mod break_;
 mod collect;
 mod const_;
@@ -35,6 +36,7 @@ mod version;
 mod while_;
 
 pub use alias::Alias;
+pub use attr::*;
 pub use break_::Break;
 pub use collect::Collect;
 pub use const_::Const;

crates/nu-cmd-lang/src/default_context.rs

@@ -16,6 +16,8 @@ pub fn create_default_context() -> EngineState {
         // Core
         bind_command! {
             Alias,
+            AttrExample,
+            AttrSearchTerms,
             Break,
             Collect,
             Const,

crates/nu-engine/src/compile/expression.rs

@@ -72,6 +72,14 @@ pub(crate) fn compile_expression(
     };
 
     match &expr.expr {
+        Expr::AttributeBlock(ab) => compile_expression(
+            working_set,
+            builder,
+            &ab.item,
+            redirect_modes,
+            in_reg,
+            out_reg,
+        ),
         Expr::Bool(b) => lit(builder, Literal::Bool(*b)),
         Expr::Int(i) => lit(builder, Literal::Int(*i)),
         Expr::Float(f) => lit(builder, Literal::Float(*f)),

crates/nu-engine/src/scope.rs

@@ -106,12 +106,27 @@ impl<'e, 's> ScopeData<'e, 's> {
                     })
                     .collect();
 
+                let attributes = decl
+                    .attributes()
+                    .into_iter()
+                    .map(|(name, value)| {
+                        Value::record(
+                            record! {
+                                "name" => Value::string(name, span),
+                                "value" => value,
+                            },
+                            span,
+                        )
+                    })
+                    .collect();
+
                 let record = record! {
                     "name" => Value::string(String::from_utf8_lossy(command_name), span),
                     "category" => Value::string(signature.category.to_string(), span),
                     "signatures" => self.collect_signatures(&signature, span),
                     "description" => Value::string(decl.description(), span),
                     "examples" => Value::list(examples, span),
+                    "attributes" => Value::list(attributes, span),
                     "type" => Value::string(decl.command_type().to_string(), span),
                     "is_sub" => Value::bool(decl.is_sub(), span),
                     "is_const" => Value::bool(decl.is_const(), span),

crates/nu-parser/src/flatten.rs

@@ -189,6 +189,12 @@ fn flatten_expression_into(
     }
 
     match &expr.expr {
+        Expr::AttributeBlock(ab) => {
+            for attr in &ab.attributes {
+                flatten_expression_into(working_set, &attr.expr, output);
+            }
+            flatten_expression_into(working_set, &ab.item, output);
+        }
         Expr::BinaryOp(lhs, op, rhs) => {
             flatten_expression_into(working_set, lhs, output);
             flatten_expression_into(working_set, op, output);

crates/nu-parser/src/known_external.rs

@@ -3,11 +3,14 @@ use nu_protocol::{
     ast::{self, Expr, Expression},
     engine::{self, CallImpl, CommandType, UNKNOWN_SPAN_ID},
     ir::{self, DataSlice},
+    CustomExample,
 };
 
 #[derive(Clone)]
 pub struct KnownExternal {
     pub signature: Box<Signature>,
+    pub attributes: Vec<(String, Value)>,
+    pub examples: Vec<CustomExample>,
 }
 
 impl Command for KnownExternal {
@@ -84,6 +87,17 @@ impl Command for KnownExternal {
             }
         }
     }
+
+    fn attributes(&self) -> Vec<(String, Value)> {
+        self.attributes.clone()
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        self.examples
+            .iter()
+            .map(CustomExample::to_example)
+            .collect()
+    }
 }
 
 /// Transform the args from an `ast::Call` onto a `run-external` call

crates/nu-parser/src/lite_parser.rs

@@ -3,7 +3,7 @@
 
 use crate::{Token, TokenContents};
 use itertools::{Either, Itertools};
-use nu_protocol::{ast::RedirectionSource, ParseError, Span};
+use nu_protocol::{ast::RedirectionSource, engine::StateWorkingSet, ParseError, Span};
 use std::mem;
 
 #[derive(Debug, Clone, Copy)]
@@ -65,6 +65,8 @@ pub struct LiteCommand {
     pub comments: Vec<Span>,
     pub parts: Vec<Span>,
     pub redirection: Option<LiteRedirection>,
+    /// one past the end indices of attributes
+    pub attribute_idx: Vec<usize>,
 }
 
 impl LiteCommand {
@@ -146,6 +148,25 @@ impl LiteCommand {
             )
             .sorted_unstable_by_key(|a| (a.start, a.end))
     }
+
+    pub fn command_parts(&self) -> &[Span] {
+        let command_start = self.attribute_idx.last().copied().unwrap_or(0);
+        &self.parts[command_start..]
+    }
+
+    pub fn has_attributes(&self) -> bool {
+        !self.attribute_idx.is_empty()
+    }
+
+    pub fn attribute_commands(&'_ self) -> impl Iterator<Item = LiteCommand> + '_ {
+        std::iter::once(0)
+            .chain(self.attribute_idx.iter().copied())
+            .tuple_windows()
+            .map(|(s, e)| LiteCommand {
+                parts: self.parts[s..e].to_owned(),
+                ..Default::default()
+            })
+    }
 }
 
 #[derive(Debug, Clone, Default)]
@@ -188,7 +209,17 @@ fn last_non_comment_token(tokens: &[Token], cur_idx: usize) -> Option<TokenConte
     None
 }
 
-pub fn lite_parse(tokens: &[Token]) -> (LiteBlock, Option<ParseError>) {
+#[derive(PartialEq, Eq)]
+enum Mode {
+    Assignment,
+    Attribute,
+    Normal,
+}
+
+pub fn lite_parse(
+    tokens: &[Token],
+    working_set: &StateWorkingSet,
+) -> (LiteBlock, Option<ParseError>) {
     if tokens.is_empty() {
         return (LiteBlock::default(), None);
     }
@@ -200,220 +231,263 @@ pub fn lite_parse(tokens: &[Token]) -> (LiteBlock, Option<ParseError>) {
     let mut last_token = TokenContents::Eol;
     let mut file_redirection = None;
     let mut curr_comment: Option<Vec<Span>> = None;
-    let mut is_assignment = false;
+    let mut mode = Mode::Normal;
     let mut error = None;
 
     for (idx, token) in tokens.iter().enumerate() {
-        if is_assignment {
-            match &token.contents {
-                // Consume until semicolon or terminating EOL. Assignments absorb pipelines and
-                // redirections.
-                TokenContents::Eol => {
-                    // Handle `[Command] [Pipe] ([Comment] | [Eol])+ [Command]`
-                    //
-                    // `[Eol]` branch checks if previous token is `[Pipe]` to construct pipeline
-                    // and so `[Comment] | [Eol]` should be ignore to make it work
-                    let actual_token = last_non_comment_token(tokens, idx);
-                    if actual_token != Some(TokenContents::Pipe) {
-                        is_assignment = false;
-                        pipeline.push(&mut command);
-                        block.push(&mut pipeline);
+        match mode {
+            Mode::Attribute => {
+                match &token.contents {
+                    // Consume until semicolon or terminating EOL. Attributes can't contain pipelines or redirections.
+                    TokenContents::Eol | TokenContents::Semicolon => {
+                        command.attribute_idx.push(command.parts.len());
+                        mode = Mode::Normal;
+                        if matches!(last_token, TokenContents::Eol | TokenContents::Semicolon) {
+                            // Clear out the comment as we're entering a new comment
+                            curr_comment = None;
+                            pipeline.push(&mut command);
+                            block.push(&mut pipeline);
+                        }
                     }
-
-                    if last_token == TokenContents::Eol {
-                        // Clear out the comment as we're entering a new comment
-                        curr_comment = None;
-                    }
-                }
-                TokenContents::Semicolon => {
-                    is_assignment = false;
-                    pipeline.push(&mut command);
-                    block.push(&mut pipeline);
-                }
-                TokenContents::Comment => {
-                    command.comments.push(token.span);
-                    curr_comment = None;
-                }
-                _ => command.push(token.span),
-            }
-        } else if let Some((source, append, span)) = file_redirection.take() {
-            match &token.contents {
-                TokenContents::PipePipe => {
-                    error = error.or(Some(ParseError::ShellOrOr(token.span)));
-                    command.push(span);
-                    command.push(token.span);
-                }
-                TokenContents::Item => {
-                    let target = LiteRedirectionTarget::File {
-                        connector: span,
-                        file: token.span,
-                        append,
-                    };
-                    if let Err(err) = command.try_add_redirection(source, target) {
-                        error = error.or(Some(err));
-                        command.push(span);
-                        command.push(token.span)
-                    }
-                }
-                TokenContents::AssignmentOperator => {
-                    error = error.or(Some(ParseError::Expected("redirection target", token.span)));
-                    command.push(span);
-                    command.push(token.span);
-                }
-                TokenContents::OutGreaterThan
-                | TokenContents::OutGreaterGreaterThan
-                | TokenContents::ErrGreaterThan
-                | TokenContents::ErrGreaterGreaterThan
-                | TokenContents::OutErrGreaterThan
-                | TokenContents::OutErrGreaterGreaterThan => {
-                    error = error.or(Some(ParseError::Expected("redirection target", token.span)));
-                    command.push(span);
-                    command.push(token.span);
-                }
-                TokenContents::Pipe
-                | TokenContents::ErrGreaterPipe
-                | TokenContents::OutErrGreaterPipe => {
-                    error = error.or(Some(ParseError::Expected("redirection target", token.span)));
-                    command.push(span);
-                    pipeline.push(&mut command);
-                    command.pipe = Some(token.span);
-                }
-                TokenContents::Eol => {
-                    error = error.or(Some(ParseError::Expected("redirection target", token.span)));
-                    command.push(span);
-                    pipeline.push(&mut command);
-                }
-                TokenContents::Semicolon => {
-                    error = error.or(Some(ParseError::Expected("redirection target", token.span)));
-                    command.push(span);
-                    pipeline.push(&mut command);
-                    block.push(&mut pipeline);
-                }
-                TokenContents::Comment => {
-                    error = error.or(Some(ParseError::Expected("redirection target", span)));
-                    command.push(span);
-                    command.comments.push(token.span);
-                    curr_comment = None;
-                }
-            }
-        } else {
-            match &token.contents {
-                TokenContents::PipePipe => {
-                    error = error.or(Some(ParseError::ShellOrOr(token.span)));
-                    command.push(token.span);
-                }
-                TokenContents::Item => {
-                    // This is commented out to preserve old parser behavior,
-                    // but we should probably error here.
-                    //
-                    // if element.redirection.is_some() {
-                    //     error = error.or(Some(ParseError::LabeledError(
-                    //         "Unexpected positional".into(),
-                    //         "cannot add positional arguments after output redirection".into(),
-                    //         token.span,
-                    //     )));
-                    // }
-                    //
-                    // For example, this is currently allowed: ^echo thing o> out.txt extra_arg
-
-                    // If we have a comment, go ahead and attach it
-                    if let Some(curr_comment) = curr_comment.take() {
-                        command.comments = curr_comment;
-                    }
-                    command.push(token.span);
-                }
-                TokenContents::AssignmentOperator => {
-                    // When in assignment mode, we'll just consume pipes or redirections as part of
-                    // the command.
-                    is_assignment = true;
-                    if let Some(curr_comment) = curr_comment.take() {
-                        command.comments = curr_comment;
-                    }
-                    command.push(token.span);
-                }
-                TokenContents::OutGreaterThan => {
-                    error = error.or(command.check_accepts_redirection(token.span));
-                    file_redirection = Some((RedirectionSource::Stdout, false, token.span));
-                }
-                TokenContents::OutGreaterGreaterThan => {
-                    error = error.or(command.check_accepts_redirection(token.span));
-                    file_redirection = Some((RedirectionSource::Stdout, true, token.span));
-                }
-                TokenContents::ErrGreaterThan => {
-                    error = error.or(command.check_accepts_redirection(token.span));
-                    file_redirection = Some((RedirectionSource::Stderr, false, token.span));
-                }
-                TokenContents::ErrGreaterGreaterThan => {
-                    error = error.or(command.check_accepts_redirection(token.span));
-                    file_redirection = Some((RedirectionSource::Stderr, true, token.span));
-                }
-                TokenContents::OutErrGreaterThan => {
-                    error = error.or(command.check_accepts_redirection(token.span));
-                    file_redirection =
-                        Some((RedirectionSource::StdoutAndStderr, false, token.span));
-                }
-                TokenContents::OutErrGreaterGreaterThan => {
-                    error = error.or(command.check_accepts_redirection(token.span));
-                    file_redirection = Some((RedirectionSource::StdoutAndStderr, true, token.span));
-                }
-                TokenContents::ErrGreaterPipe => {
-                    let target = LiteRedirectionTarget::Pipe {
-                        connector: token.span,
-                    };
-                    if let Err(err) = command.try_add_redirection(RedirectionSource::Stderr, target)
-                    {
-                        error = error.or(Some(err));
-                    }
-                    pipeline.push(&mut command);
-                    command.pipe = Some(token.span);
-                }
-                TokenContents::OutErrGreaterPipe => {
-                    let target = LiteRedirectionTarget::Pipe {
-                        connector: token.span,
-                    };
-                    if let Err(err) =
-                        command.try_add_redirection(RedirectionSource::StdoutAndStderr, target)
-                    {
-                        error = error.or(Some(err));
-                    }
-                    pipeline.push(&mut command);
-                    command.pipe = Some(token.span);
-                }
-                TokenContents::Pipe => {
-                    pipeline.push(&mut command);
-                    command.pipe = Some(token.span);
-                }
-                TokenContents::Eol => {
-                    // Handle `[Command] [Pipe] ([Comment] | [Eol])+ [Command]`
-                    //
-                    // `[Eol]` branch checks if previous token is `[Pipe]` to construct pipeline
-                    // and so `[Comment] | [Eol]` should be ignore to make it work
-                    let actual_token = last_non_comment_token(tokens, idx);
-                    if actual_token != Some(TokenContents::Pipe) {
-                        pipeline.push(&mut command);
-                        block.push(&mut pipeline);
-                    }
-
-                    if last_token == TokenContents::Eol {
-                        // Clear out the comment as we're entering a new comment
-                        curr_comment = None;
-                    }
-                }
-                TokenContents::Semicolon => {
-                    pipeline.push(&mut command);
-                    block.push(&mut pipeline);
-                }
-                TokenContents::Comment => {
-                    // Comment is beside something
-                    if last_token != TokenContents::Eol {
+                    TokenContents::Comment => {
                         command.comments.push(token.span);
                         curr_comment = None;
-                    } else {
-                        // Comment precedes something
-                        if let Some(curr_comment) = &mut curr_comment {
-                            curr_comment.push(token.span);
-                        } else {
-                            curr_comment = Some(vec![token.span]);
+                    }
+                    _ => command.push(token.span),
+                }
+            }
+            Mode::Assignment => {
+                match &token.contents {
+                    // Consume until semicolon or terminating EOL. Assignments absorb pipelines and
+                    // redirections.
+                    TokenContents::Eol => {
+                        // Handle `[Command] [Pipe] ([Comment] | [Eol])+ [Command]`
+                        //
+                        // `[Eol]` branch checks if previous token is `[Pipe]` to construct pipeline
+                        // and so `[Comment] | [Eol]` should be ignore to make it work
+                        let actual_token = last_non_comment_token(tokens, idx);
+                        if actual_token != Some(TokenContents::Pipe) {
+                            mode = Mode::Normal;
+                            pipeline.push(&mut command);
+                            block.push(&mut pipeline);
+                        }
+
+                        if last_token == TokenContents::Eol {
+                            // Clear out the comment as we're entering a new comment
+                            curr_comment = None;
+                        }
+                    }
+                    TokenContents::Semicolon => {
+                        mode = Mode::Normal;
+                        pipeline.push(&mut command);
+                        block.push(&mut pipeline);
+                    }
+                    TokenContents::Comment => {
+                        command.comments.push(token.span);
+                        curr_comment = None;
+                    }
+                    _ => command.push(token.span),
+                }
+            }
+            Mode::Normal => {
+                if let Some((source, append, span)) = file_redirection.take() {
+                    match &token.contents {
+                        TokenContents::PipePipe => {
+                            error = error.or(Some(ParseError::ShellOrOr(token.span)));
+                            command.push(span);
+                            command.push(token.span);
+                        }
+                        TokenContents::Item => {
+                            let target = LiteRedirectionTarget::File {
+                                connector: span,
+                                file: token.span,
+                                append,
+                            };
+                            if let Err(err) = command.try_add_redirection(source, target) {
+                                error = error.or(Some(err));
+                                command.push(span);
+                                command.push(token.span)
+                            }
+                        }
+                        TokenContents::AssignmentOperator => {
+                            error = error
+                                .or(Some(ParseError::Expected("redirection target", token.span)));
+                            command.push(span);
+                            command.push(token.span);
+                        }
+                        TokenContents::OutGreaterThan
+                        | TokenContents::OutGreaterGreaterThan
+                        | TokenContents::ErrGreaterThan
+                        | TokenContents::ErrGreaterGreaterThan
+                        | TokenContents::OutErrGreaterThan
+                        | TokenContents::OutErrGreaterGreaterThan => {
+                            error = error
+                                .or(Some(ParseError::Expected("redirection target", token.span)));
+                            command.push(span);
+                            command.push(token.span);
+                        }
+                        TokenContents::Pipe
+                        | TokenContents::ErrGreaterPipe
+                        | TokenContents::OutErrGreaterPipe => {
+                            error = error
+                                .or(Some(ParseError::Expected("redirection target", token.span)));
+                            command.push(span);
+                            pipeline.push(&mut command);
+                            command.pipe = Some(token.span);
+                        }
+                        TokenContents::Eol => {
+                            error = error
+                                .or(Some(ParseError::Expected("redirection target", token.span)));
+                            command.push(span);
+                            pipeline.push(&mut command);
+                        }
+                        TokenContents::Semicolon => {
+                            error = error
+                                .or(Some(ParseError::Expected("redirection target", token.span)));
+                            command.push(span);
+                            pipeline.push(&mut command);
+                            block.push(&mut pipeline);
+                        }
+                        TokenContents::Comment => {
+                            error =
+                                error.or(Some(ParseError::Expected("redirection target", span)));
+                            command.push(span);
+                            command.comments.push(token.span);
+                            curr_comment = None;
+                        }
+                    }
+                } else {
+                    match &token.contents {
+                        TokenContents::PipePipe => {
+                            error = error.or(Some(ParseError::ShellOrOr(token.span)));
+                            command.push(token.span);
+                        }
+                        TokenContents::Item => {
+                            // FIXME: This is commented out to preserve old parser behavior,
+                            // but we should probably error here.
+                            //
+                            // if element.redirection.is_some() {
+                            //     error = error.or(Some(ParseError::LabeledError(
+                            //         "Unexpected positional".into(),
+                            //         "cannot add positional arguments after output redirection".into(),
+                            //         token.span,
+                            //     )));
+                            // }
+                            //
+                            // For example, this is currently allowed: ^echo thing o> out.txt extra_arg
+
+                            if working_set.get_span_contents(token.span).starts_with(b"@") {
+                                if matches!(
+                                    last_token,
+                                    TokenContents::Eol | TokenContents::Semicolon
+                                ) {
+                                    mode = Mode::Attribute;
+                                }
+                                command.push(token.span);
+                            } else {
+                                // If we have a comment, go ahead and attach it
+                                if let Some(curr_comment) = curr_comment.take() {
+                                    command.comments = curr_comment;
+                                }
+                                command.push(token.span);
+                            }
+                        }
+                        TokenContents::AssignmentOperator => {
+                            // When in assignment mode, we'll just consume pipes or redirections as part of
+                            // the command.
+                            mode = Mode::Assignment;
+                            if let Some(curr_comment) = curr_comment.take() {
+                                command.comments = curr_comment;
+                            }
+                            command.push(token.span);
+                        }
+                        TokenContents::OutGreaterThan => {
+                            error = error.or(command.check_accepts_redirection(token.span));
+                            file_redirection = Some((RedirectionSource::Stdout, false, token.span));
+                        }
+                        TokenContents::OutGreaterGreaterThan => {
+                            error = error.or(command.check_accepts_redirection(token.span));
+                            file_redirection = Some((RedirectionSource::Stdout, true, token.span));
+                        }
+                        TokenContents::ErrGreaterThan => {
+                            error = error.or(command.check_accepts_redirection(token.span));
+                            file_redirection = Some((RedirectionSource::Stderr, false, token.span));
+                        }
+                        TokenContents::ErrGreaterGreaterThan => {
+                            error = error.or(command.check_accepts_redirection(token.span));
+                            file_redirection = Some((RedirectionSource::Stderr, true, token.span));
+                        }
+                        TokenContents::OutErrGreaterThan => {
+                            error = error.or(command.check_accepts_redirection(token.span));
+                            file_redirection =
+                                Some((RedirectionSource::StdoutAndStderr, false, token.span));
+                        }
+                        TokenContents::OutErrGreaterGreaterThan => {
+                            error = error.or(command.check_accepts_redirection(token.span));
+                            file_redirection =
+                                Some((RedirectionSource::StdoutAndStderr, true, token.span));
+                        }
+                        TokenContents::ErrGreaterPipe => {
+                            let target = LiteRedirectionTarget::Pipe {
+                                connector: token.span,
+                            };
+                            if let Err(err) =
+                                command.try_add_redirection(RedirectionSource::Stderr, target)
+                            {
+                                error = error.or(Some(err));
+                            }
+                            pipeline.push(&mut command);
+                            command.pipe = Some(token.span);
+                        }
+                        TokenContents::OutErrGreaterPipe => {
+                            let target = LiteRedirectionTarget::Pipe {
+                                connector: token.span,
+                            };
+                            if let Err(err) = command
+                                .try_add_redirection(RedirectionSource::StdoutAndStderr, target)
+                            {
+                                error = error.or(Some(err));
+                            }
+                            pipeline.push(&mut command);
+                            command.pipe = Some(token.span);
+                        }
+                        TokenContents::Pipe => {
+                            pipeline.push(&mut command);
+                            command.pipe = Some(token.span);
+                        }
+                        TokenContents::Eol => {
+                            // Handle `[Command] [Pipe] ([Comment] | [Eol])+ [Command]`
+                            //
+                            // `[Eol]` branch checks if previous token is `[Pipe]` to construct pipeline
+                            // and so `[Comment] | [Eol]` should be ignore to make it work
+                            let actual_token = last_non_comment_token(tokens, idx);
+                            if actual_token != Some(TokenContents::Pipe) {
+                                pipeline.push(&mut command);
+                                block.push(&mut pipeline);
+                            }
+
+                            if last_token == TokenContents::Eol {
+                                // Clear out the comment as we're entering a new comment
+                                curr_comment = None;
+                            }
+                        }
+                        TokenContents::Semicolon => {
+                            pipeline.push(&mut command);
+                            block.push(&mut pipeline);
+                        }
+                        TokenContents::Comment => {
+                            // Comment is beside something
+                            if last_token != TokenContents::Eol {
+                                command.comments.push(token.span);
+                                curr_comment = None;
+                            } else {
+                                // Comment precedes something
+                                if let Some(curr_comment) = &mut curr_comment {
+                                    curr_comment.push(token.span);
+                                } else {
+                                    curr_comment = Some(vec![token.span]);
+                                }
+                            }
                         }
                     }
                 }
@@ -428,6 +502,10 @@ pub fn lite_parse(tokens: &[Token]) -> (LiteBlock, Option<ParseError>) {
         error = error.or(Some(ParseError::Expected("redirection target", span)));
     }
 
+    if let Mode::Attribute = mode {
+        command.attribute_idx.push(command.parts.len());
+    }
+
     pipeline.push(&mut command);
     block.push(&mut pipeline);
 

crates/nu-parser/src/parse_keywords.rs

@@ -1,7 +1,7 @@
 use crate::{
     exportable::Exportable,
     parse_block,
-    parser::{parse_redirection, redirecting_builtin_error},
+    parser::{parse_attribute, parse_redirection, redirecting_builtin_error},
     type_check::{check_block_input_output, type_compatible},
 };
 use itertools::Itertools;
@@ -9,14 +9,14 @@ use log::trace;
 use nu_path::canonicalize_with;
 use nu_protocol::{
     ast::{
-        Argument, Block, Call, Expr, Expression, ImportPattern, ImportPatternHead,
+        Argument, AttributeBlock, Block, Call, Expr, Expression, ImportPattern, ImportPatternHead,
         ImportPatternMember, Pipeline, PipelineElement,
     },
     engine::{StateWorkingSet, DEFAULT_OVERLAY_NAME},
     eval_const::eval_constant,
     parser_path::ParserPath,
-    Alias, BlockId, DeclId, Module, ModuleId, ParseError, PositionalArg, ResolvedImportPattern,
-    Span, Spanned, SyntaxShape, Type, Value, VarId,
+    Alias, BlockId, CustomExample, DeclId, FromValue, Module, ModuleId, ParseError, PositionalArg,
+    ResolvedImportPattern, ShellError, Span, Spanned, SyntaxShape, Type, Value, VarId,
 };
 use std::{
     collections::{HashMap, HashSet},
@@ -363,16 +363,166 @@ fn verify_not_reserved_variable_name(working_set: &mut StateWorkingSet, name: &s
     }
 }
 
+// This is meant for parsing attribute blocks without an accompanying `def` or `extern`. It's
+// necessary to provide consistent syntax highlighting, completions, and helpful errors
+//
+// There is no need to run the const evaluation here
+pub fn parse_attribute_block(
+    working_set: &mut StateWorkingSet,
+    lite_command: &LiteCommand,
+) -> Pipeline {
+    let attributes = lite_command
+        .attribute_commands()
+        .map(|cmd| parse_attribute(working_set, &cmd).0)
+        .collect::<Vec<_>>();
+
+    let last_attr_span = attributes
+        .last()
+        .expect("Attribute block must contain at least one attribute")
+        .expr
+        .span;
+
+    working_set.error(ParseError::AttributeRequiresDefinition(last_attr_span));
+    let cmd_span = if lite_command.command_parts().is_empty() {
+        last_attr_span.past()
+    } else {
+        Span::concat(lite_command.command_parts())
+    };
+    let cmd_expr = garbage(working_set, cmd_span);
+    let ty = cmd_expr.ty.clone();
+
+    let attr_block_span = Span::merge_many(
+        attributes
+            .first()
+            .map(|x| x.expr.span)
+            .into_iter()
+            .chain(Some(cmd_span)),
+    );
+
+    Pipeline::from_vec(vec![Expression::new(
+        working_set,
+        Expr::AttributeBlock(AttributeBlock {
+            attributes,
+            item: Box::new(cmd_expr),
+        }),
+        attr_block_span,
+        ty,
+    )])
+}
+
 // Returns also the parsed command name and ID
 pub fn parse_def(
     working_set: &mut StateWorkingSet,
     lite_command: &LiteCommand,
     module_name: Option<&[u8]>,
 ) -> (Pipeline, Option<(Vec<u8>, DeclId)>) {
-    let spans = &lite_command.parts[..];
+    let mut attributes = vec![];
+    let mut attribute_vals = vec![];
+
+    for attr_cmd in lite_command.attribute_commands() {
+        let (attr, name) = parse_attribute(working_set, &attr_cmd);
+        if let Some(name) = name {
+            let val = eval_constant(working_set, &attr.expr);
+            match val {
+                Ok(val) => attribute_vals.push((name, val)),
+                Err(e) => working_set.error(e.wrap(working_set, attr.expr.span)),
+            }
+        }
+        attributes.push(attr);
+    }
+
+    let (expr, decl) = parse_def_inner(working_set, attribute_vals, lite_command, module_name);
+
+    let ty = expr.ty.clone();
+
+    let attr_block_span = Span::merge_many(
+        attributes
+            .first()
+            .map(|x| x.expr.span)
+            .into_iter()
+            .chain(Some(expr.span)),
+    );
+
+    let expr = if attributes.is_empty() {
+        expr
+    } else {
+        Expression::new(
+            working_set,
+            Expr::AttributeBlock(AttributeBlock {
+                attributes,
+                item: Box::new(expr),
+            }),
+            attr_block_span,
+            ty,
+        )
+    };
+
+    (Pipeline::from_vec(vec![expr]), decl)
+}
+
+pub fn parse_extern(
+    working_set: &mut StateWorkingSet,
+    lite_command: &LiteCommand,
+    module_name: Option<&[u8]>,
+) -> Pipeline {
+    let mut attributes = vec![];
+    let mut attribute_vals = vec![];
+
+    for attr_cmd in lite_command.attribute_commands() {
+        let (attr, name) = parse_attribute(working_set, &attr_cmd);
+        if let Some(name) = name {
+            let val = eval_constant(working_set, &attr.expr);
+            match val {
+                Ok(val) => attribute_vals.push((name, val)),
+                Err(e) => working_set.error(e.wrap(working_set, attr.expr.span)),
+            }
+        }
+        attributes.push(attr);
+    }
+
+    let expr = parse_extern_inner(working_set, attribute_vals, lite_command, module_name);
+
+    let ty = expr.ty.clone();
+
+    let attr_block_span = Span::merge_many(
+        attributes
+            .first()
+            .map(|x| x.expr.span)
+            .into_iter()
+            .chain(Some(expr.span)),
+    );
+
+    let expr = if attributes.is_empty() {
+        expr
+    } else {
+        Expression::new(
+            working_set,
+            Expr::AttributeBlock(AttributeBlock {
+                attributes,
+                item: Box::new(expr),
+            }),
+            attr_block_span,
+            ty,
+        )
+    };
+
+    Pipeline::from_vec(vec![expr])
+}
+
+// Returns also the parsed command name and ID
+fn parse_def_inner(
+    working_set: &mut StateWorkingSet,
+    attributes: Vec<(String, Value)>,
+    lite_command: &LiteCommand,
+    module_name: Option<&[u8]>,
+) -> (Expression, Option<(Vec<u8>, DeclId)>) {
+    let spans = lite_command.command_parts();
 
     let (desc, extra_desc) = working_set.build_desc(&lite_command.comments);
 
+    let (attribute_vals, examples, search_terms) =
+        handle_special_attributes(attributes, working_set);
+
     // Checking that the function is used with the correct name
     // Maybe this is not necessary but it is a sanity check
     // Note: "export def" is treated the same as "def"
@@ -390,11 +540,11 @@ pub fn parse_def(
             "internal error: Wrong call name for def function".into(),
             Span::concat(spans),
         ));
-        return (garbage_pipeline(working_set, spans), None);
+        return (garbage(working_set, Span::concat(spans)), None);
     }
     if let Some(redirection) = lite_command.redirection.as_ref() {
         working_set.error(redirecting_builtin_error("def", redirection));
-        return (garbage_pipeline(working_set, spans), None);
+        return (garbage(working_set, Span::concat(spans)), None);
     }
 
     // Parsing the spans and checking that they match the register signature
@@ -406,7 +556,7 @@ pub fn parse_def(
                 "internal error: def declaration not found".into(),
                 Span::concat(spans),
             ));
-            return (garbage_pipeline(working_set, spans), None);
+            return (garbage(working_set, Span::concat(spans)), None);
         }
         Some(decl_id) => {
             working_set.enter_scope();
@@ -430,7 +580,7 @@ pub fn parse_def(
                     String::from_utf8_lossy(&def_call).as_ref(),
                 ) {
                     working_set.error(err);
-                    return (garbage_pipeline(working_set, spans), None);
+                    return (garbage(working_set, Span::concat(spans)), None);
                 }
             }
 
@@ -474,17 +624,12 @@ pub fn parse_def(
             working_set.parse_errors.append(&mut new_errors);
 
             let Ok(is_help) = has_flag_const(working_set, &call, "help") else {
-                return (garbage_pipeline(working_set, spans), None);
+                return (garbage(working_set, Span::concat(spans)), None);
             };
 
             if starting_error_count != working_set.parse_errors.len() || is_help {
                 return (
-                    Pipeline::from_vec(vec![Expression::new(
-                        working_set,
-                        Expr::Call(call),
-                        call_span,
-                        output,
-                    )]),
+                    Expression::new(working_set, Expr::Call(call), call_span, output),
                     None,
                 );
             }
@@ -494,10 +639,10 @@ pub fn parse_def(
     };
 
     let Ok(has_env) = has_flag_const(working_set, &call, "env") else {
-        return (garbage_pipeline(working_set, spans), None);
+        return (garbage(working_set, Span::concat(spans)), None);
     };
     let Ok(has_wrapped) = has_flag_const(working_set, &call, "wrapped") else {
-        return (garbage_pipeline(working_set, spans), None);
+        return (garbage(working_set, Span::concat(spans)), None);
     };
 
     // All positional arguments must be in the call positional vector by this point
@@ -517,12 +662,7 @@ pub fn parse_def(
                     name_expr_span,
                 ));
                 return (
-                    Pipeline::from_vec(vec![Expression::new(
-                        working_set,
-                        Expr::Call(call),
-                        call_span,
-                        Type::Any,
-                    )]),
+                    Expression::new(working_set, Expr::Call(call), call_span, Type::Any),
                     None,
                 );
             }
@@ -534,7 +674,7 @@ pub fn parse_def(
             "Could not get string from string expression".into(),
             name_expr.span,
         ));
-        return (garbage_pipeline(working_set, spans), None);
+        return (garbage(working_set, Span::concat(spans)), None);
     };
 
     let mut result = None;
@@ -567,12 +707,7 @@ pub fn parse_def(
                             format!("...rest-like positional argument used in 'def --wrapped' supports only strings. Change the type annotation of ...{} to 'string'.", &rest.name)));
 
                         return (
-                            Pipeline::from_vec(vec![Expression::new(
-                                working_set,
-                                Expr::Call(call),
-                                call_span,
-                                Type::Any,
-                            )]),
+                            Expression::new(working_set, Expr::Call(call), call_span, Type::Any),
                             result,
                         );
                     }
@@ -581,12 +716,7 @@ pub fn parse_def(
                 working_set.error(ParseError::MissingPositional("...rest-like positional argument".to_string(), name_expr.span, "def --wrapped must have a ...rest-like positional argument. Add '...rest: string' to the command's signature.".to_string()));
 
                 return (
-                    Pipeline::from_vec(vec![Expression::new(
-                        working_set,
-                        Expr::Call(call),
-                        call_span,
-                        Type::Any,
-                    )]),
+                    Expression::new(working_set, Expr::Call(call), call_span, Type::Any),
                     result,
                 );
             }
@@ -602,8 +732,11 @@ pub fn parse_def(
             signature.description = desc;
             signature.extra_description = extra_desc;
             signature.allows_unknown_args = has_wrapped;
+            signature.search_terms = search_terms;
 
-            *declaration = signature.clone().into_block_command(block_id);
+            *declaration = signature
+                .clone()
+                .into_block_command(block_id, attribute_vals, examples);
 
             let block = working_set.get_block_mut(block_id);
             block.signature = signature;
@@ -637,25 +770,25 @@ pub fn parse_def(
     working_set.merge_predecl(name.as_bytes());
 
     (
-        Pipeline::from_vec(vec![Expression::new(
-            working_set,
-            Expr::Call(call),
-            call_span,
-            Type::Any,
-        )]),
+        Expression::new(working_set, Expr::Call(call), call_span, Type::Any),
         result,
     )
 }
 
-pub fn parse_extern(
+fn parse_extern_inner(
     working_set: &mut StateWorkingSet,
+    attributes: Vec<(String, Value)>,
     lite_command: &LiteCommand,
     module_name: Option<&[u8]>,
-) -> Pipeline {
-    let spans = &lite_command.parts;
+) -> Expression {
+    let spans = lite_command.command_parts();
+    let concat_span = Span::concat(spans);
 
     let (description, extra_description) = working_set.build_desc(&lite_command.comments);
 
+    let (attribute_vals, examples, search_terms) =
+        handle_special_attributes(attributes, working_set);
+
     // Checking that the function is used with the correct name
     // Maybe this is not necessary but it is a sanity check
 
@@ -672,11 +805,11 @@ pub fn parse_extern(
             "internal error: Wrong call name for extern command".into(),
             Span::concat(spans),
         ));
-        return garbage_pipeline(working_set, spans);
+        return garbage(working_set, concat_span);
     }
     if let Some(redirection) = lite_command.redirection.as_ref() {
         working_set.error(redirecting_builtin_error("extern", redirection));
-        return garbage_pipeline(working_set, spans);
+        return garbage(working_set, concat_span);
     }
 
     // Parsing the spans and checking that they match the register signature
@@ -688,7 +821,7 @@ pub fn parse_extern(
                 "internal error: def declaration not found".into(),
                 Span::concat(spans),
             ));
-            return garbage_pipeline(working_set, spans);
+            return garbage(working_set, concat_span);
         }
         Some(decl_id) => {
             working_set.enter_scope();
@@ -702,7 +835,7 @@ pub fn parse_extern(
                     String::from_utf8_lossy(&extern_call).as_ref(),
                 ) {
                     working_set.error(err);
-                    return garbage_pipeline(working_set, spans);
+                    return garbage(working_set, concat_span);
                 }
             }
 
@@ -736,12 +869,7 @@ pub fn parse_extern(
                         "main".to_string(),
                         name_expr_span,
                     ));
-                    return Pipeline::from_vec(vec![Expression::new(
-                        working_set,
-                        Expr::Call(call),
-                        call_span,
-                        Type::Any,
-                    )]);
+                    return Expression::new(working_set, Expr::Call(call), call_span, Type::Any);
                 }
             }
 
@@ -761,6 +889,7 @@ pub fn parse_extern(
                 signature.name = external_name;
                 signature.description = description;
                 signature.extra_description = extra_description;
+                signature.search_terms = search_terms;
                 signature.allows_unknown_args = true;
 
                 if let Some(block_id) = body.and_then(|x| x.as_block()) {
@@ -770,7 +899,11 @@ pub fn parse_extern(
                             name_expr.span,
                         ));
                     } else {
-                        *declaration = signature.clone().into_block_command(block_id);
+                        *declaration = signature.clone().into_block_command(
+                            block_id,
+                            attribute_vals,
+                            examples,
+                        );
 
                         working_set.get_block_mut(block_id).signature = signature;
                     }
@@ -785,7 +918,11 @@ pub fn parse_extern(
                         );
                     }
 
-                    let decl = KnownExternal { signature };
+                    let decl = KnownExternal {
+                        signature,
+                        attributes: attribute_vals,
+                        examples,
+                    };
 
                     *declaration = Box::new(decl);
                 }
@@ -807,12 +944,54 @@ pub fn parse_extern(
         }
     }
 
-    Pipeline::from_vec(vec![Expression::new(
-        working_set,
-        Expr::Call(call),
-        call_span,
-        Type::Any,
-    )])
+    Expression::new(working_set, Expr::Call(call), call_span, Type::Any)
+}
+
+fn handle_special_attributes(
+    attributes: Vec<(String, Value)>,
+    working_set: &mut StateWorkingSet<'_>,
+) -> (Vec<(String, Value)>, Vec<CustomExample>, Vec<String>) {
+    let mut attribute_vals = vec![];
+    let mut examples = vec![];
+    let mut search_terms = vec![];
+
+    for (name, value) in attributes {
+        let val_span = value.span();
+        match name.as_str() {
+            "example" => match CustomExample::from_value(value) {
+                Ok(example) => examples.push(example),
+                Err(_) => {
+                    let e = ShellError::GenericError {
+                        error: "nu::shell::invalid_example".into(),
+                        msg: "Value couldn't be converted to an example".into(),
+                        span: Some(val_span),
+                        help: Some("Is `attr example` shadowed?".into()),
+                        inner: vec![],
+                    };
+                    working_set.error(e.wrap(working_set, val_span));
+                }
+            },
+            "search-terms" => match <Vec<String>>::from_value(value) {
+                Ok(mut terms) => {
+                    search_terms.append(&mut terms);
+                }
+                Err(_) => {
+                    let e = ShellError::GenericError {
+                        error: "nu::shell::invalid_search_terms".into(),
+                        msg: "Value couldn't be converted to search-terms".into(),
+                        span: Some(val_span),
+                        help: Some("Is `attr search-terms` shadowed?".into()),
+                        inner: vec![],
+                    };
+                    working_set.error(e.wrap(working_set, val_span));
+                }
+            },
+            _ => {
+                attribute_vals.push((name, value));
+            }
+        }
+    }
+    (attribute_vals, examples, search_terms)
 }
 
 fn check_alias_name<'a>(working_set: &mut StateWorkingSet, spans: &'a [Span]) -> Option<&'a Span> {
@@ -1126,8 +1305,9 @@ pub fn parse_export_in_block(
 ) -> Pipeline {
     let call_span = Span::concat(&lite_command.parts);
 
-    let full_name = if lite_command.parts.len() > 1 {
-        let sub = working_set.get_span_contents(lite_command.parts[1]);
+    let parts = lite_command.command_parts();
+    let full_name = if parts.len() > 1 {
+        let sub = working_set.get_span_contents(parts[1]);
         match sub {
             b"alias" => "export alias",
             b"def" => "export def",
@@ -1146,64 +1326,62 @@ pub fn parse_export_in_block(
         return garbage_pipeline(working_set, &lite_command.parts);
     }
 
-    if let Some(decl_id) = working_set.find_decl(full_name.as_bytes()) {
-        let starting_error_count = working_set.parse_errors.len();
-        let ParsedInternalCall { call, output, .. } = parse_internal_call(
-            working_set,
-            if full_name == "export" {
-                lite_command.parts[0]
-            } else {
-                Span::concat(&lite_command.parts[0..2])
-            },
-            if full_name == "export" {
-                &lite_command.parts[1..]
-            } else {
-                &lite_command.parts[2..]
-            },
-            decl_id,
-        );
-        // don't need errors generated by parse_internal_call
-        // further error will be generated by detail `parse_xxx` function.
-        working_set.parse_errors.truncate(starting_error_count);
+    // No need to care for this when attributes are present, parse_attribute_block will throw the
+    // necessary error
+    if !lite_command.has_attributes() {
+        if let Some(decl_id) = working_set.find_decl(full_name.as_bytes()) {
+            let starting_error_count = working_set.parse_errors.len();
+            let ParsedInternalCall { call, output, .. } = parse_internal_call(
+                working_set,
+                if full_name == "export" {
+                    parts[0]
+                } else {
+                    Span::concat(&parts[0..2])
+                },
+                if full_name == "export" {
+                    &parts[1..]
+                } else {
+                    &parts[2..]
+                },
+                decl_id,
+            );
+            // don't need errors generated by parse_internal_call
+            // further error will be generated by detail `parse_xxx` function.
+            working_set.parse_errors.truncate(starting_error_count);
 
-        let decl = working_set.get_decl(decl_id);
-        check_call(working_set, call_span, &decl.signature(), &call);
-        let Ok(is_help) = has_flag_const(working_set, &call, "help") else {
+            let decl = working_set.get_decl(decl_id);
+            check_call(working_set, call_span, &decl.signature(), &call);
+            let Ok(is_help) = has_flag_const(working_set, &call, "help") else {
+                return garbage_pipeline(working_set, &lite_command.parts);
+            };
+
+            if starting_error_count != working_set.parse_errors.len() || is_help {
+                return Pipeline::from_vec(vec![Expression::new(
+                    working_set,
+                    Expr::Call(call),
+                    call_span,
+                    output,
+                )]);
+            }
+        } else {
+            working_set.error(ParseError::UnknownState(
+                format!("internal error: '{full_name}' declaration not found",),
+                Span::concat(&lite_command.parts),
+            ));
             return garbage_pipeline(working_set, &lite_command.parts);
         };
-
-        if starting_error_count != working_set.parse_errors.len() || is_help {
-            return Pipeline::from_vec(vec![Expression::new(
-                working_set,
-                Expr::Call(call),
-                call_span,
-                output,
-            )]);
-        }
-    } else {
-        working_set.error(ParseError::UnknownState(
-            format!("internal error: '{full_name}' declaration not found",),
-            Span::concat(&lite_command.parts),
-        ));
-        return garbage_pipeline(working_set, &lite_command.parts);
-    };
-
-    if full_name == "export" {
-        // export by itself is meaningless
-        working_set.error(ParseError::UnexpectedKeyword(
-            "export".into(),
-            lite_command.parts[0],
-        ));
-        return garbage_pipeline(working_set, &lite_command.parts);
     }
 
     match full_name {
-        "export alias" => parse_alias(working_set, lite_command, None),
+        // `parse_def` and `parse_extern` work both with and without attributes
         "export def" => parse_def(working_set, lite_command, None).0,
+        "export extern" => parse_extern(working_set, lite_command, None),
+        // Other definitions can't have attributes, so we handle attributes here with parse_attribute_block
+        _ if lite_command.has_attributes() => parse_attribute_block(working_set, lite_command),
+        "export alias" => parse_alias(working_set, lite_command, None),
         "export const" => parse_const(working_set, &lite_command.parts[1..]).0,
         "export use" => parse_use(working_set, lite_command, None).0,
         "export module" => parse_module(working_set, lite_command, None).0,
-        "export extern" => parse_extern(working_set, lite_command, None),
         _ => {
             working_set.error(ParseError::UnexpectedKeyword(
                 full_name.into(),
@@ -1222,7 +1400,7 @@ pub fn parse_export_in_module(
     module_name: &[u8],
     parent_module: &mut Module,
 ) -> (Pipeline, Vec<Exportable>) {
-    let spans = &lite_command.parts[..];
+    let spans = lite_command.command_parts();
 
     let export_span = if let Some(sp) = spans.first() {
         if working_set.get_span_contents(*sp) != b"export" {
@@ -1259,18 +1437,15 @@ pub fn parse_export_in_module(
         parser_info: HashMap::new(),
     });
 
+    let mut out_pipeline = None;
+
     let exportables = if let Some(kw_span) = spans.get(1) {
         let kw_name = working_set.get_span_contents(*kw_span);
         match kw_name {
+            // `parse_def` and `parse_extern` work both with and without attributes
             b"def" => {
-                let lite_command = LiteCommand {
-                    comments: lite_command.comments.clone(),
-                    parts: spans[1..].to_vec(),
-                    pipe: lite_command.pipe,
-                    redirection: lite_command.redirection.clone(),
-                };
-                let (pipeline, cmd_result) =
-                    parse_def(working_set, &lite_command, Some(module_name));
+                let (mut pipeline, cmd_result) =
+                    parse_def(working_set, lite_command, Some(module_name));
 
                 let mut result = vec![];
 
@@ -1292,30 +1467,37 @@ pub fn parse_export_in_module(
                 };
 
                 // Trying to warp the 'def' call into the 'export def' in a very clumsy way
-                if let Some(Expr::Call(def_call)) = pipeline.elements.first().map(|e| &e.expr.expr)
-                {
-                    call.clone_from(def_call);
-                    call.head = Span::concat(&spans[0..=1]);
-                    call.decl_id = export_def_decl_id;
-                } else {
+                // TODO: Rather than this, handle `export def` correctly in `parse_def`
+                'warp: {
+                    match pipeline.elements.first_mut().map(|e| &mut e.expr.expr) {
+                        Some(Expr::Call(def_call)) => {
+                            def_call.head = Span::concat(&spans[0..=1]);
+                            def_call.decl_id = export_def_decl_id;
+                            break 'warp;
+                        }
+                        Some(Expr::AttributeBlock(ab)) => {
+                            if let Expr::Call(def_call) = &mut ab.item.expr {
+                                def_call.head = Span::concat(&spans[0..=1]);
+                                def_call.decl_id = export_def_decl_id;
+                                break 'warp;
+                            }
+                        }
+                        _ => {}
+                    };
+
                     working_set.error(ParseError::InternalError(
                         "unexpected output from parsing a definition".into(),
                         Span::concat(&spans[1..]),
                     ));
-                };
+                }
 
+                out_pipeline = Some(pipeline);
                 result
             }
             b"extern" => {
-                let lite_command = LiteCommand {
-                    comments: lite_command.comments.clone(),
-                    parts: spans[1..].to_vec(),
-                    pipe: lite_command.pipe,
-                    redirection: lite_command.redirection.clone(),
-                };
                 let extern_name = [b"export ", kw_name].concat();
 
-                let pipeline = parse_extern(working_set, &lite_command, Some(module_name));
+                let mut pipeline = parse_extern(working_set, lite_command, Some(module_name));
 
                 let export_def_decl_id = if let Some(id) = working_set.find_decl(&extern_name) {
                     id
@@ -1327,18 +1509,30 @@ pub fn parse_export_in_module(
                     return (garbage_pipeline(working_set, spans), vec![]);
                 };
 
-                // Trying to warp the 'def' call into the 'export def' in a very clumsy way
-                if let Some(Expr::Call(def_call)) = pipeline.elements.first().map(|e| &e.expr.expr)
-                {
-                    call.clone_from(def_call);
-                    call.head = Span::concat(&spans[0..=1]);
-                    call.decl_id = export_def_decl_id;
-                } else {
+                // Trying to warp the 'extern' call into the 'export extern' in a very clumsy way
+                // TODO: Rather than this, handle `export extern` correctly in `parse_extern`
+                'warp: {
+                    match pipeline.elements.first_mut().map(|e| &mut e.expr.expr) {
+                        Some(Expr::Call(def_call)) => {
+                            def_call.head = Span::concat(&spans[0..=1]);
+                            def_call.decl_id = export_def_decl_id;
+                            break 'warp;
+                        }
+                        Some(Expr::AttributeBlock(ab)) => {
+                            if let Expr::Call(def_call) = &mut ab.item.expr {
+                                def_call.head = Span::concat(&spans[0..=1]);
+                                def_call.decl_id = export_def_decl_id;
+                                break 'warp;
+                            }
+                        }
+                        _ => {}
+                    };
+
                     working_set.error(ParseError::InternalError(
                         "unexpected output from parsing a definition".into(),
                         Span::concat(&spans[1..]),
                     ));
-                };
+                }
 
                 let mut result = vec![];
 
@@ -1360,14 +1554,21 @@ pub fn parse_export_in_module(
                     ));
                 }
 
+                out_pipeline = Some(pipeline);
                 result
             }
+            // Other definitions can't have attributes, so we handle attributes here with parse_attribute_block
+            _ if lite_command.has_attributes() => {
+                out_pipeline = Some(parse_attribute_block(working_set, lite_command));
+                vec![]
+            }
             b"alias" => {
                 let lite_command = LiteCommand {
                     comments: lite_command.comments.clone(),
                     parts: spans[1..].to_vec(),
                     pipe: lite_command.pipe,
                     redirection: lite_command.redirection.clone(),
+                    attribute_idx: vec![],
                 };
                 let pipeline = parse_alias(working_set, &lite_command, Some(module_name));
 
@@ -1425,6 +1626,7 @@ pub fn parse_export_in_module(
                     parts: spans[1..].to_vec(),
                     pipe: lite_command.pipe,
                     redirection: lite_command.redirection.clone(),
+                    attribute_idx: vec![],
                 };
                 let (pipeline, exportables) =
                     parse_use(working_set, &lite_command, Some(parent_module));
@@ -1580,15 +1782,13 @@ pub fn parse_export_in_module(
         vec![]
     };
 
-    (
-        Pipeline::from_vec(vec![Expression::new(
-            working_set,
-            Expr::Call(call),
-            Span::concat(spans),
-            Type::Any,
-        )]),
-        exportables,
-    )
+    let out_pipeline = out_pipeline.unwrap_or(Pipeline::from_vec(vec![Expression::new(
+        working_set,
+        Expr::Call(call),
+        Span::concat(spans),
+        Type::Any,
+    )]));
+    (out_pipeline, exportables)
 }
 
 pub fn parse_export_env(
@@ -1724,14 +1924,14 @@ pub fn parse_module_block(
 
     let module_comments = collect_first_comments(&output);
 
-    let (output, err) = lite_parse(&output);
+    let (output, err) = lite_parse(&output, working_set);
     if let Some(err) = err {
         working_set.error(err)
     }
 
     for pipeline in &output.block {
         if pipeline.commands.len() == 1 {
-            parse_def_predecl(working_set, &pipeline.commands[0].parts);
+            parse_def_predecl(working_set, pipeline.commands[0].command_parts());
         }
     }
 
@@ -1744,9 +1944,14 @@ pub fn parse_module_block(
         if pipeline.commands.len() == 1 {
             let command = &pipeline.commands[0];
 
-            let name = working_set.get_span_contents(command.parts[0]);
+            let name = command
+                .command_parts()
+                .first()
+                .map(|s| working_set.get_span_contents(*s))
+                .unwrap_or(b"");
 
             match name {
+                // `parse_def` and `parse_extern` work both with and without attributes
                 b"def" => {
                     block.pipelines.push(
                         parse_def(
@@ -1757,33 +1962,10 @@ pub fn parse_module_block(
                         .0,
                     )
                 }
-                b"const" => block
-                    .pipelines
-                    .push(parse_const(working_set, &command.parts).0),
                 b"extern" => block
                     .pipelines
                     .push(parse_extern(working_set, command, None)),
-                b"alias" => {
-                    block.pipelines.push(parse_alias(
-                        working_set,
-                        command,
-                        None, // using aliases named as the module locally is OK
-                    ))
-                }
-                b"use" => {
-                    let (pipeline, _) = parse_use(working_set, command, Some(&mut module));
-
-                    block.pipelines.push(pipeline)
-                }
-                b"module" => {
-                    let (pipeline, _) = parse_module(
-                        working_set,
-                        command,
-                        None, // using modules named as the module locally is OK
-                    );
-
-                    block.pipelines.push(pipeline)
-                }
+                // `parse_export_in_module` also handles attributes by itself
                 b"export" => {
                     let (pipe, exportables) =
                         parse_export_in_module(working_set, command, module_name, &mut module);
@@ -1864,6 +2046,34 @@ pub fn parse_module_block(
 
                     block.pipelines.push(pipe)
                 }
+                // Other definitions can't have attributes, so we handle attributes here with parse_attribute_block
+                _ if command.has_attributes() => block
+                    .pipelines
+                    .push(parse_attribute_block(working_set, command)),
+                b"const" => block
+                    .pipelines
+                    .push(parse_const(working_set, &command.parts).0),
+                b"alias" => {
+                    block.pipelines.push(parse_alias(
+                        working_set,
+                        command,
+                        None, // using aliases named as the module locally is OK
+                    ))
+                }
+                b"use" => {
+                    let (pipeline, _) = parse_use(working_set, command, Some(&mut module));
+
+                    block.pipelines.push(pipeline)
+                }
+                b"module" => {
+                    let (pipeline, _) = parse_module(
+                        working_set,
+                        command,
+                        None, // using modules named as the module locally is OK
+                    );
+
+                    block.pipelines.push(pipeline)
+                }
                 b"export-env" => {
                     let (pipe, maybe_env_block) = parse_export_env(working_set, &command.parts);
 

crates/nu-parser/src/parse_patterns.rs

@@ -99,7 +99,7 @@ pub fn parse_list_pattern(working_set: &mut StateWorkingSet, span: Span) -> Matc
         working_set.error(err);
     }
 
-    let (output, err) = lite_parse(&output);
+    let (output, err) = lite_parse(&output, working_set);
     if let Some(err) = err {
         working_set.error(err);
     }

crates/nu-parser/src/parser.rs

@@ -14,8 +14,8 @@ use log::trace;
 use nu_engine::DIR_VAR_PARSER_INFO;
 use nu_protocol::{
     ast::*, engine::StateWorkingSet, eval_const::eval_constant, BlockId, DeclId, DidYouMean,
-    FilesizeUnit, Flag, ParseError, PositionalArg, Signature, Span, Spanned, SyntaxShape, Type,
-    Value, VarId, ENV_VARIABLE_ID, IN_VARIABLE_ID,
+    FilesizeUnit, Flag, ParseError, PositionalArg, ShellError, Signature, Span, Spanned,
+    SyntaxShape, Type, Value, VarId, ENV_VARIABLE_ID, IN_VARIABLE_ID,
 };
 use std::{
     collections::{HashMap, HashSet},
@@ -1283,51 +1283,7 @@ pub fn parse_call(working_set: &mut StateWorkingSet, spans: &[Span], head: Span)
         return garbage(working_set, head);
     }
 
-    let mut pos = 0;
-    let cmd_start = pos;
-    let mut name_spans = vec![];
-    let mut name = vec![];
-
-    for word_span in spans[cmd_start..].iter() {
-        // Find the longest group of words that could form a command
-
-        name_spans.push(*word_span);
-
-        let name_part = working_set.get_span_contents(*word_span);
-        if name.is_empty() {
-            name.extend(name_part);
-        } else {
-            name.push(b' ');
-            name.extend(name_part);
-        }
-
-        pos += 1;
-    }
-
-    let mut maybe_decl_id = working_set.find_decl(&name);
-
-    while maybe_decl_id.is_none() {
-        // Find the longest command match
-        if name_spans.len() <= 1 {
-            // Keep the first word even if it does not match -- could be external command
-            break;
-        }
-
-        name_spans.pop();
-        pos -= 1;
-
-        let mut name = vec![];
-        for name_span in &name_spans {
-            let name_part = working_set.get_span_contents(*name_span);
-            if name.is_empty() {
-                name.extend(name_part);
-            } else {
-                name.push(b' ');
-                name.extend(name_part);
-            }
-        }
-        maybe_decl_id = working_set.find_decl(&name);
-    }
+    let (cmd_start, pos, _name, maybe_decl_id) = find_longest_decl(working_set, spans);
 
     if let Some(decl_id) = maybe_decl_id {
         // Before the internal parsing we check if there is no let or alias declarations
@@ -1424,6 +1380,172 @@ pub fn parse_call(working_set: &mut StateWorkingSet, spans: &[Span], head: Span)
     }
 }
 
+pub fn find_longest_decl(
+    working_set: &mut StateWorkingSet<'_>,
+    spans: &[Span],
+) -> (
+    usize,
+    usize,
+    Vec<u8>,
+    Option<nu_protocol::Id<nu_protocol::marker::Decl>>,
+) {
+    find_longest_decl_with_prefix(working_set, spans, b"")
+}
+
+pub fn find_longest_decl_with_prefix(
+    working_set: &mut StateWorkingSet<'_>,
+    spans: &[Span],
+    prefix: &[u8],
+) -> (
+    usize,
+    usize,
+    Vec<u8>,
+    Option<nu_protocol::Id<nu_protocol::marker::Decl>>,
+) {
+    let mut pos = 0;
+    let cmd_start = pos;
+    let mut name_spans = vec![];
+    let mut name = vec![];
+    name.extend(prefix);
+
+    for word_span in spans[cmd_start..].iter() {
+        // Find the longest group of words that could form a command
+
+        name_spans.push(*word_span);
+
+        let name_part = working_set.get_span_contents(*word_span);
+        if name.is_empty() {
+            name.extend(name_part);
+        } else {
+            name.push(b' ');
+            name.extend(name_part);
+        }
+
+        pos += 1;
+    }
+
+    let mut maybe_decl_id = working_set.find_decl(&name);
+
+    while maybe_decl_id.is_none() {
+        // Find the longest command match
+        if name_spans.len() <= 1 {
+            // Keep the first word even if it does not match -- could be external command
+            break;
+        }
+
+        name_spans.pop();
+        pos -= 1;
+
+        // TODO: Refactor to avoid recreating name with an inner loop.
+        name.clear();
+        name.extend(prefix);
+        for name_span in &name_spans {
+            let name_part = working_set.get_span_contents(*name_span);
+            if name.is_empty() {
+                name.extend(name_part);
+            } else {
+                name.push(b' ');
+                name.extend(name_part);
+            }
+        }
+        maybe_decl_id = working_set.find_decl(&name);
+    }
+    (cmd_start, pos, name, maybe_decl_id)
+}
+
+pub fn parse_attribute(
+    working_set: &mut StateWorkingSet,
+    lite_command: &LiteCommand,
+) -> (Attribute, Option<String>) {
+    let _ = lite_command
+        .parts
+        .first()
+        .filter(|s| working_set.get_span_contents(**s).starts_with(b"@"))
+        .expect("Attributes always start with an `@`");
+
+    assert!(
+        lite_command.attribute_idx.is_empty(),
+        "attributes can't have attributes"
+    );
+
+    let mut spans = lite_command.parts.clone();
+    if let Some(first) = spans.first_mut() {
+        first.start += 1;
+    }
+    let spans = spans.as_slice();
+    let attr_span = Span::concat(spans);
+
+    let (cmd_start, cmd_end, mut name, decl_id) =
+        find_longest_decl_with_prefix(working_set, spans, b"attr");
+
+    debug_assert!(name.starts_with(b"attr "));
+    let _ = name.drain(..(b"attr ".len()));
+
+    let name_span = Span::concat(&spans[cmd_start..cmd_end]);
+
+    let Ok(name) = String::from_utf8(name) else {
+        working_set.error(ParseError::NonUtf8(name_span));
+        return (
+            Attribute {
+                expr: garbage(working_set, attr_span),
+            },
+            None,
+        );
+    };
+
+    let Some(decl_id) = decl_id else {
+        working_set.error(ParseError::UnknownCommand(name_span));
+        return (
+            Attribute {
+                expr: garbage(working_set, attr_span),
+            },
+            None,
+        );
+    };
+
+    let decl = working_set.get_decl(decl_id);
+
+    let parsed_call = match decl.as_alias() {
+        // TODO: Once `const def` is available, we should either disallow aliases as attributes OR
+        // allow them but rather than using the aliases' name, use the name of the aliased command
+        Some(alias) => match &alias.clone().wrapped_call {
+            Expression {
+                expr: Expr::ExternalCall(..),
+                ..
+            } => {
+                let shell_error = ShellError::NotAConstCommand { span: name_span };
+                working_set.error(shell_error.wrap(working_set, attr_span));
+                return (
+                    Attribute {
+                        expr: garbage(working_set, Span::concat(spans)),
+                    },
+                    None,
+                );
+            }
+            _ => {
+                trace!("parsing: alias of internal call");
+                parse_internal_call(working_set, name_span, &spans[cmd_end..], decl_id)
+            }
+        },
+        None => {
+            trace!("parsing: internal call");
+            parse_internal_call(working_set, name_span, &spans[cmd_end..], decl_id)
+        }
+    };
+
+    (
+        Attribute {
+            expr: Expression::new(
+                working_set,
+                Expr::Call(parsed_call.call),
+                Span::concat(spans),
+                parsed_call.output,
+            ),
+        },
+        Some(name),
+    )
+}
+
 pub fn parse_binary(working_set: &mut StateWorkingSet, span: Span) -> Expression {
     trace!("parsing: binary");
     let contents = working_set.get_span_contents(span);
@@ -4166,7 +4288,7 @@ pub fn parse_list_expression(
         working_set.error(err)
     }
 
-    let (mut output, err) = lite_parse(&output);
+    let (mut output, err) = lite_parse(&output, working_set);
     if let Some(err) = err {
         working_set.error(err)
     }
@@ -5728,11 +5850,20 @@ pub fn parse_builtin_commands(
     }
 
     trace!("parsing: checking for keywords");
-    let name = working_set.get_span_contents(lite_command.parts[0]);
+    let name = lite_command
+        .command_parts()
+        .first()
+        .map(|s| working_set.get_span_contents(*s))
+        .unwrap_or(b"");
 
     match name {
+        // `parse_def` and `parse_extern` work both with and without attributes
         b"def" => parse_def(working_set, lite_command, None).0,
         b"extern" => parse_extern(working_set, lite_command, None),
+        // `parse_export_in_block` also handles attributes by itself
+        b"export" => parse_export_in_block(working_set, lite_command),
+        // Other definitions can't have attributes, so we handle attributes here with parse_attribute_block
+        _ if lite_command.has_attributes() => parse_attribute_block(working_set, lite_command),
         b"let" => parse_let(
             working_set,
             &lite_command
@@ -5761,7 +5892,6 @@ pub fn parse_builtin_commands(
             parse_keyword(working_set, lite_command)
         }
         b"source" | b"source-env" => parse_source(working_set, lite_command),
-        b"export" => parse_export_in_block(working_set, lite_command),
         b"hide" => parse_hide(working_set, lite_command),
         b"where" => parse_where(working_set, lite_command),
         // Only "plugin use" is a keyword
@@ -6154,7 +6284,7 @@ pub fn parse_block(
     scoped: bool,
     is_subexpression: bool,
 ) -> Block {
-    let (lite_block, err) = lite_parse(tokens);
+    let (lite_block, err) = lite_parse(tokens, working_set);
     if let Some(err) = err {
         working_set.error(err);
     }
@@ -6169,7 +6299,7 @@ pub fn parse_block(
     // that share the same block can see each other
     for pipeline in &lite_block.block {
         if pipeline.commands.len() == 1 {
-            parse_def_predecl(working_set, &pipeline.commands[0].parts)
+            parse_def_predecl(working_set, pipeline.commands[0].command_parts())
         }
     }
 
@@ -6354,6 +6484,9 @@ pub fn discover_captures_in_expr(
     output: &mut Vec<(VarId, Span)>,
 ) -> Result<(), ParseError> {
     match &expr.expr {
+        Expr::AttributeBlock(ab) => {
+            discover_captures_in_expr(working_set, &ab.item, seen, seen_blocks, output)?;
+        }
         Expr::BinaryOp(lhs, _, rhs) => {
             discover_captures_in_expr(working_set, lhs, seen, seen_blocks, output)?;
             discover_captures_in_expr(working_set, rhs, seen, seen_blocks, output)?;

crates/nu-parser/tests/test_parser.rs

@@ -1,109 +1,12 @@
 use nu_parser::*;
 use nu_protocol::{
     ast::{Argument, Expr, Expression, ExternalArgument, PathMember, Range},
-    engine::{Call, Command, EngineState, Stack, StateWorkingSet},
-    Category, DeclId, ParseError, PipelineData, ShellError, Signature, Span, SyntaxShape, Type,
+    engine::{Command, EngineState, Stack, StateWorkingSet},
+    DeclId, ParseError, Signature, Span, SyntaxShape, Type,
 };
 use rstest::rstest;
 
-#[cfg(test)]
-#[derive(Clone)]
-pub struct Let;
-
-#[cfg(test)]
-impl Command for Let {
-    fn name(&self) -> &str {
-        "let"
-    }
-
-    fn description(&self) -> &str {
-        "Create a variable and give it a value."
-    }
-
-    fn signature(&self) -> nu_protocol::Signature {
-        Signature::build("let")
-            .required("var_name", SyntaxShape::VarWithOptType, "variable name")
-            .required(
-                "initial_value",
-                SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::MathExpression)),
-                "equals sign followed by value",
-            )
-    }
-
-    fn run(
-        &self,
-        _engine_state: &EngineState,
-        _stack: &mut Stack,
-        _call: &Call,
-        _input: PipelineData,
-    ) -> Result<PipelineData, ShellError> {
-        todo!()
-    }
-}
-
-#[cfg(test)]
-#[derive(Clone)]
-pub struct Mut;
-
-#[cfg(test)]
-impl Command for Mut {
-    fn name(&self) -> &str {
-        "mut"
-    }
-
-    fn description(&self) -> &str {
-        "Mock mut command."
-    }
-
-    fn signature(&self) -> nu_protocol::Signature {
-        Signature::build("mut")
-            .required("var_name", SyntaxShape::VarWithOptType, "variable name")
-            .required(
-                "initial_value",
-                SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::MathExpression)),
-                "equals sign followed by value",
-            )
-    }
-
-    fn run(
-        &self,
-        _engine_state: &EngineState,
-        _stack: &mut Stack,
-        _call: &Call,
-        _input: PipelineData,
-    ) -> Result<PipelineData, ShellError> {
-        todo!()
-    }
-}
-
-#[derive(Clone)]
-pub struct ToCustom;
-
-impl Command for ToCustom {
-    fn name(&self) -> &str {
-        "to-custom"
-    }
-
-    fn description(&self) -> &str {
-        "Mock converter command."
-    }
-
-    fn signature(&self) -> nu_protocol::Signature {
-        Signature::build(self.name())
-            .input_output_type(Type::Any, Type::Custom("custom".into()))
-            .category(Category::Custom("custom".into()))
-    }
-
-    fn run(
-        &self,
-        _engine_state: &EngineState,
-        _stack: &mut Stack,
-        _call: &Call,
-        _input: PipelineData,
-    ) -> Result<PipelineData, ShellError> {
-        todo!()
-    }
-}
+use mock::{Alias, AttrEcho, Def, Let, Mut, ToCustom};
 
 fn test_int(
     test_tag: &str,     // name of sub-test
@@ -758,6 +661,129 @@ pub fn parse_call_missing_req_flag() {
     ));
 }
 
+#[test]
+pub fn parse_attribute_block_check_spans() {
+    let engine_state = EngineState::new();
+    let mut working_set = StateWorkingSet::new(&engine_state);
+
+    let source = br#"
+    @foo a 1 2
+    @bar b 3 4
+    echo baz
+    "#;
+    let block = parse(&mut working_set, None, source, true);
+
+    // There SHOULD be errors here, we're using nonexistent commands
+    assert!(!working_set.parse_errors.is_empty());
+
+    assert_eq!(block.len(), 1);
+
+    let pipeline = &block.pipelines[0];
+    assert_eq!(pipeline.len(), 1);
+    let element = &pipeline.elements[0];
+    assert!(element.redirection.is_none());
+
+    let Expr::AttributeBlock(ab) = &element.expr.expr else {
+        panic!("Couldn't parse attribute block");
+    };
+
+    assert_eq!(
+        working_set.get_span_contents(ab.attributes[0].expr.span),
+        b"foo a 1 2"
+    );
+    assert_eq!(
+        working_set.get_span_contents(ab.attributes[1].expr.span),
+        b"bar b 3 4"
+    );
+    assert_eq!(working_set.get_span_contents(ab.item.span), b"echo baz");
+}
+
+#[test]
+pub fn parse_attributes_check_values() {
+    let engine_state = EngineState::new();
+    let mut working_set = StateWorkingSet::new(&engine_state);
+
+    working_set.add_decl(Box::new(Def));
+    working_set.add_decl(Box::new(AttrEcho));
+
+    let source = br#"
+    @echo "hello world"
+    @echo 42
+    def foo [] {}
+    "#;
+    let _ = parse(&mut working_set, None, source, false);
+
+    assert!(working_set.parse_errors.is_empty());
+
+    let decl_id = working_set.find_decl(b"foo").unwrap();
+    let cmd = working_set.get_decl(decl_id);
+    let attributes = cmd.attributes();
+
+    let (name, val) = &attributes[0];
+    assert_eq!(name, "echo");
+    assert_eq!(val.as_str(), Ok("hello world"));
+
+    let (name, val) = &attributes[1];
+    assert_eq!(name, "echo");
+    assert_eq!(val.as_int(), Ok(42));
+}
+
+#[test]
+pub fn parse_attributes_alias() {
+    let engine_state = EngineState::new();
+    let mut working_set = StateWorkingSet::new(&engine_state);
+
+    working_set.add_decl(Box::new(Def));
+    working_set.add_decl(Box::new(Alias));
+    working_set.add_decl(Box::new(AttrEcho));
+
+    let source = br#"
+    alias "attr test" = attr echo
+
+    @test null
+    def foo [] {}
+    "#;
+    let _ = parse(&mut working_set, None, source, false);
+
+    assert!(working_set.parse_errors.is_empty());
+
+    let decl_id = working_set.find_decl(b"foo").unwrap();
+    let cmd = working_set.get_decl(decl_id);
+    let attributes = cmd.attributes();
+
+    let (name, val) = &attributes[0];
+    assert_eq!(name, "test");
+    assert!(val.is_nothing());
+}
+
+#[test]
+pub fn parse_attributes_external_alias() {
+    let engine_state = EngineState::new();
+    let mut working_set = StateWorkingSet::new(&engine_state);
+
+    working_set.add_decl(Box::new(Def));
+    working_set.add_decl(Box::new(Alias));
+    working_set.add_decl(Box::new(AttrEcho));
+
+    let source = br#"
+    alias "attr test" = ^echo
+
+    @test null
+    def foo [] {}
+    "#;
+    let _ = parse(&mut working_set, None, source, false);
+
+    assert!(!working_set.parse_errors.is_empty());
+
+    let ParseError::LabeledError(shell_error, parse_error, _span) = &working_set.parse_errors[0]
+    else {
+        panic!("Expected LabeledError");
+    };
+
+    assert!(shell_error.contains("nu::shell::not_a_const_command"));
+    assert!(parse_error.contains("Encountered error during parse-time evaluation"));
+}
+
 fn test_external_call(input: &str, tag: &str, f: impl FnOnce(&Expression, &[ExternalArgument])) {
     let engine_state = EngineState::new();
     let mut working_set = StateWorkingSet::new(&engine_state);
@@ -1943,10 +1969,78 @@ mod range {
 }
 
 #[cfg(test)]
-mod input_types {
+mod mock {
     use super::*;
-    use nu_protocol::{ast::Argument, engine::Call, Category, PipelineData, ShellError, Type};
+    use nu_engine::CallExt;
+    use nu_protocol::{
+        engine::Call, Category, IntoPipelineData, PipelineData, ShellError, Type, Value,
+    };
 
+    #[derive(Clone)]
+    pub struct Let;
+
+    impl Command for Let {
+        fn name(&self) -> &str {
+            "let"
+        }
+
+        fn description(&self) -> &str {
+            "Create a variable and give it a value."
+        }
+
+        fn signature(&self) -> nu_protocol::Signature {
+            Signature::build("let")
+                .required("var_name", SyntaxShape::VarWithOptType, "variable name")
+                .required(
+                    "initial_value",
+                    SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::MathExpression)),
+                    "equals sign followed by value",
+                )
+        }
+
+        fn run(
+            &self,
+            _engine_state: &EngineState,
+            _stack: &mut Stack,
+            _call: &Call,
+            _input: PipelineData,
+        ) -> Result<PipelineData, ShellError> {
+            todo!()
+        }
+    }
+
+    #[derive(Clone)]
+    pub struct Mut;
+
+    impl Command for Mut {
+        fn name(&self) -> &str {
+            "mut"
+        }
+
+        fn description(&self) -> &str {
+            "Mock mut command."
+        }
+
+        fn signature(&self) -> nu_protocol::Signature {
+            Signature::build("mut")
+                .required("var_name", SyntaxShape::VarWithOptType, "variable name")
+                .required(
+                    "initial_value",
+                    SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::MathExpression)),
+                    "equals sign followed by value",
+                )
+        }
+
+        fn run(
+            &self,
+            _engine_state: &EngineState,
+            _stack: &mut Stack,
+            _call: &Call,
+            _input: PipelineData,
+        ) -> Result<PipelineData, ShellError> {
+            todo!()
+        }
+    }
     #[derive(Clone)]
     pub struct LsTest;
 
@@ -2006,6 +2100,87 @@ mod input_types {
         }
     }
 
+    #[derive(Clone)]
+    pub struct Alias;
+
+    impl Command for Alias {
+        fn name(&self) -> &str {
+            "alias"
+        }
+
+        fn description(&self) -> &str {
+            "Mock alias command."
+        }
+
+        fn signature(&self) -> nu_protocol::Signature {
+            Signature::build("alias")
+                .input_output_types(vec![(Type::Nothing, Type::Nothing)])
+                .required("name", SyntaxShape::String, "Name of the alias.")
+                .required(
+                    "initial_value",
+                    SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::Expression)),
+                    "Equals sign followed by value.",
+                )
+                .category(Category::Core)
+        }
+
+        fn run(
+            &self,
+            _engine_state: &EngineState,
+            _stack: &mut Stack,
+            _call: &Call,
+            _input: PipelineData,
+        ) -> Result<PipelineData, ShellError> {
+            todo!()
+        }
+    }
+
+    #[derive(Clone)]
+    pub struct AttrEcho;
+
+    impl Command for AttrEcho {
+        fn name(&self) -> &str {
+            "attr echo"
+        }
+
+        fn signature(&self) -> Signature {
+            Signature::build("attr echo").required(
+                "value",
+                SyntaxShape::Any,
+                "Value to store as an attribute",
+            )
+        }
+
+        fn description(&self) -> &str {
+            "Add an arbitrary value as an attribute to a command"
+        }
+
+        fn run(
+            &self,
+            engine_state: &EngineState,
+            stack: &mut Stack,
+            call: &Call,
+            _input: PipelineData,
+        ) -> Result<PipelineData, ShellError> {
+            let value: Value = call.req(engine_state, stack, 0)?;
+            Ok(value.into_pipeline_data())
+        }
+
+        fn is_const(&self) -> bool {
+            true
+        }
+
+        fn run_const(
+            &self,
+            working_set: &StateWorkingSet,
+            call: &Call,
+            _input: PipelineData,
+        ) -> Result<PipelineData, ShellError> {
+            let value: Value = call.req_const(working_set, 0)?;
+            Ok(value.into_pipeline_data())
+        }
+    }
+
     #[derive(Clone)]
     pub struct GroupBy;
 
@@ -2255,6 +2430,13 @@ mod input_types {
             todo!()
         }
     }
+}
+
+#[cfg(test)]
+mod input_types {
+    use super::*;
+    use mock::*;
+    use nu_protocol::ast::Argument;
 
     fn add_declarations(engine_state: &mut EngineState) {
         let delta = {

crates/nu-protocol/src/ast/attribute.rs

@@ -0,0 +1,13 @@
+use super::Expression;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Attribute {
+    pub expr: Expression,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct AttributeBlock {
+    pub attributes: Vec<Attribute>,
+    pub item: Box<Expression>,
+}

crates/nu-protocol/src/ast/expr.rs

@@ -2,8 +2,8 @@ use chrono::FixedOffset;
 use serde::{Deserialize, Serialize};
 
 use super::{
-    Call, CellPath, Expression, ExternalArgument, FullCellPath, Keyword, MatchPattern, Operator,
-    Range, Table, ValueWithUnit,
+    AttributeBlock, Call, CellPath, Expression, ExternalArgument, FullCellPath, Keyword,
+    MatchPattern, Operator, Range, Table, ValueWithUnit,
 };
 use crate::{
     ast::ImportPattern, engine::StateWorkingSet, BlockId, ModuleId, OutDest, Signature, Span, VarId,
@@ -12,6 +12,7 @@ use crate::{
 /// An [`Expression`] AST node
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub enum Expr {
+    AttributeBlock(AttributeBlock),
     Bool(bool),
     Int(i64),
     Float(f64),
@@ -67,6 +68,7 @@ impl Expr {
         working_set: &StateWorkingSet,
     ) -> (Option<OutDest>, Option<OutDest>) {
         match self {
+            Expr::AttributeBlock(ab) => ab.item.expr.pipe_redirection(working_set),
             Expr::Call(call) => working_set.get_decl(call.decl_id).pipe_redirection(),
             Expr::Collect(_, _) => {
                 // A collect expression always has default redirection, it's just going to collect

crates/nu-protocol/src/ast/expression.rs

@@ -104,6 +104,7 @@ impl Expression {
 
     pub fn has_in_variable(&self, working_set: &StateWorkingSet) -> bool {
         match &self.expr {
+            Expr::AttributeBlock(ab) => ab.item.has_in_variable(working_set),
             Expr::BinaryOp(left, _, right) => {
                 left.has_in_variable(working_set) || right.has_in_variable(working_set)
             }
@@ -280,6 +281,7 @@ impl Expression {
             self.span = new_span;
         }
         match &mut self.expr {
+            Expr::AttributeBlock(ab) => ab.item.replace_span(working_set, replaced, new_span),
             Expr::BinaryOp(left, _, right) => {
                 left.replace_span(working_set, replaced, new_span);
                 right.replace_span(working_set, replaced, new_span);
@@ -428,6 +430,7 @@ impl Expression {
 
     pub fn replace_in_variable(&mut self, working_set: &mut StateWorkingSet, new_var_id: VarId) {
         match &mut self.expr {
+            Expr::AttributeBlock(ab) => ab.item.replace_in_variable(working_set, new_var_id),
             Expr::Bool(_) => {}
             Expr::Int(_) => {}
             Expr::Float(_) => {}

crates/nu-protocol/src/ast/mod.rs

@@ -1,4 +1,5 @@
 //! Types representing parsed Nushell code (the Abstract Syntax Tree)
+mod attribute;
 mod block;
 mod call;
 mod cell_path;
@@ -15,6 +16,7 @@ mod traverse;
 mod unit;
 mod value_with_unit;
 
+pub use attribute::*;
 pub use block::*;
 pub use call::*;
 pub use cell_path::*;

crates/nu-protocol/src/ast/traverse.rs

@@ -177,6 +177,12 @@ impl Traverse for Expression {
             Expr::StringInterpolation(vec) | Expr::GlobInterpolation(vec, _) => {
                 vec.iter().flat_map(recur).collect()
             }
+            Expr::AttributeBlock(ab) => ab
+                .attributes
+                .iter()
+                .flat_map(|attr| recur(&attr.expr))
+                .chain(recur(&ab.item))
+                .collect(),
 
             _ => Vec::new(),
         }
@@ -233,6 +239,11 @@ impl Traverse for Expression {
                     Expr::StringInterpolation(vec) | Expr::GlobInterpolation(vec, _) => {
                         vec.iter().find_map(recur)
                     }
+                    Expr::AttributeBlock(ab) => ab
+                        .attributes
+                        .iter()
+                        .find_map(|attr| recur(&attr.expr))
+                        .or_else(|| recur(&ab.item)),
 
                     _ => None,
                 }

crates/nu-protocol/src/debugger/profiler.rs

@@ -310,6 +310,7 @@ fn profiler_error(msg: impl Into<String>, span: Span) -> ShellError {
 
 fn expr_to_string(engine_state: &EngineState, expr: &Expr) -> String {
     match expr {
+        Expr::AttributeBlock(ab) => expr_to_string(engine_state, &ab.item.expr),
         Expr::Binary(_) => "binary".to_string(),
         Expr::BinaryOp(_, _, _) => "binary operation".to_string(),
         Expr::Block(_) => "block".to_string(),

crates/nu-protocol/src/engine/command.rs

@@ -1,5 +1,7 @@
 use super::{EngineState, Stack, StateWorkingSet};
-use crate::{engine::Call, Alias, BlockId, Example, OutDest, PipelineData, ShellError, Signature};
+use crate::{
+    engine::Call, Alias, BlockId, Example, OutDest, PipelineData, ShellError, Signature, Value,
+};
 use std::fmt::Display;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -73,6 +75,10 @@ pub trait Command: Send + Sync + CommandClone {
         vec![]
     }
 
+    fn attributes(&self) -> Vec<(String, Value)> {
+        vec![]
+    }
+
     // Whether can run in const evaluation in the parser
     fn is_const(&self) -> bool {
         false

crates/nu-protocol/src/errors/parse_error.rs

@@ -543,6 +543,13 @@ pub enum ParseError {
         help("try assigning to a variable or a cell path of a variable")
     )]
     AssignmentRequiresVar(#[label("needs to be a variable")] Span),
+
+    #[error("Attributes must be followed by a definition.")]
+    #[diagnostic(
+        code(nu::parser::attribute_requires_definition),
+        help("try following this line with a `def` or `extern` definition")
+    )]
+    AttributeRequiresDefinition(#[label("must be followed by a definition")] Span),
 }
 
 impl ParseError {
@@ -634,6 +641,7 @@ impl ParseError {
             ParseError::ExtraTokensAfterClosingDelimiter(s) => *s,
             ParseError::AssignmentRequiresVar(s) => *s,
             ParseError::AssignmentRequiresMutableVar(s) => *s,
+            ParseError::AttributeRequiresDefinition(s) => *s,
         }
     }
 }

crates/nu-protocol/src/eval_base.rs

@@ -27,6 +27,7 @@ pub trait Eval {
         let expr_span = expr.span(&state);
 
         match &expr.expr {
+            Expr::AttributeBlock(ab) => Self::eval::<D>(state, mut_state, &ab.item),
             Expr::Bool(b) => Ok(Value::bool(*b, expr_span)),
             Expr::Int(i) => Ok(Value::int(*i, expr_span)),
             Expr::Float(f) => Ok(Value::float(*f, expr_span)),

crates/nu-protocol/src/signature.rs

@@ -1,10 +1,16 @@
 use crate::{
     engine::{Call, Command, CommandType, EngineState, Stack},
-    BlockId, PipelineData, ShellError, SyntaxShape, Type, Value, VarId,
+    BlockId, Example, PipelineData, ShellError, SyntaxShape, Type, Value, VarId,
 };
+use nu_derive_value::FromValue;
 use serde::{Deserialize, Serialize};
 use std::fmt::Write;
 
+// Make nu_protocol available in this namespace, consumers of this crate will
+// have this without such an export.
+// The `FromValue` derive macro fully qualifies paths to "nu_protocol".
+use crate as nu_protocol;
+
 /// The signature definition of a named flag that either accepts a value or acts as a toggle flag
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct Flag {
@@ -560,10 +566,17 @@ impl Signature {
     }
 
     /// Combines a signature and a block into a runnable block
-    pub fn into_block_command(self, block_id: BlockId) -> Box<dyn Command> {
+    pub fn into_block_command(
+        self,
+        block_id: BlockId,
+        attributes: Vec<(String, Value)>,
+        examples: Vec<CustomExample>,
+    ) -> Box<dyn Command> {
         Box::new(BlockCommand {
             signature: self,
             block_id,
+            attributes,
+            examples,
         })
     }
 
@@ -651,10 +664,29 @@ fn get_positional_short_name(arg: &PositionalArg, is_required: bool) -> String {
     }
 }
 
+#[derive(Clone, FromValue)]
+pub struct CustomExample {
+    pub example: String,
+    pub description: String,
+    pub result: Option<Value>,
+}
+
+impl CustomExample {
+    pub fn to_example(&self) -> Example<'_> {
+        Example {
+            example: self.example.as_str(),
+            description: self.description.as_str(),
+            result: self.result.clone(),
+        }
+    }
+}
+
 #[derive(Clone)]
 struct BlockCommand {
     signature: Signature,
     block_id: BlockId,
+    attributes: Vec<(String, Value)>,
+    examples: Vec<CustomExample>,
 }
 
 impl Command for BlockCommand {
@@ -697,4 +729,23 @@ impl Command for BlockCommand {
     fn block_id(&self) -> Option<BlockId> {
         Some(self.block_id)
     }
+
+    fn attributes(&self) -> Vec<(String, Value)> {
+        self.attributes.clone()
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        self.examples
+            .iter()
+            .map(CustomExample::to_example)
+            .collect()
+    }
+
+    fn search_terms(&self) -> Vec<&str> {
+        self.signature
+            .search_terms
+            .iter()
+            .map(String::as_str)
+            .collect()
+    }
 }

crates/nu-std/src/lib.rs

@@ -58,6 +58,11 @@ pub fn load_standard_library(
         ("mod.nu", "std/util", include_str!("../std/util/mod.nu")),
         ("mod.nu", "std/xml", include_str!("../std/xml/mod.nu")),
         ("mod.nu", "std/config", include_str!("../std/config/mod.nu")),
+        (
+            "mod.nu",
+            "std/testing",
+            include_str!("../std/testing/mod.nu"),
+        ),
     ];
 
     for (filename, std_subdir_name, content) in std_submodules.drain(..) {

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

crates/nu-std/std/bench/mod.nu

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

crates/nu-std/std/dt/mod.nu

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

crates/nu-std/std/iter/mod.nu

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

crates/nu-std/std/mod.nu

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

crates/nu-std/std/testing/mod.nu

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

crates/nu-std/std/util/mod.nu

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

crates/nu-std/testing.nu

@@ -14,43 +14,29 @@ def "nu-complete threads" [] {
 # test and test-skip annotations may be used multiple times throughout the module as the function names are stored in a list
 # Other annotations should only be used once within a module file
 # If you find yourself in need of multiple before- or after- functions it's a sign your test suite probably needs redesign
-def valid-annotations [] {
-    {
-        "#[test]": "test",
-        "#[ignore]": "test-skip",
-        "#[before-each]": "before-each"
-        "#[before-all]": "before-all"
-        "#[after-each]": "after-each"
-        "#[after-all]": "after-all"
-    }
+const valid_annotations = {
+    "test": "test",
+    "ignore": "test-skip",
+    "before-each": "before-each"
+    "before-all": "before-all"
+    "after-each": "after-each"
+    "after-all": "after-all"
 }
 
 # Returns a table containing the list of function names together with their annotations (comments above the declaration)
 def get-annotated [
     file: path
 ]: nothing -> table<function_name: string, annotation: string> {
-    let raw_file = (
-        open $file
-        | lines
-        | enumerate
-        | flatten
-    )
-
-    $raw_file
-    | where item starts-with def and index > 0
-    | insert annotation {|x|
-        $raw_file
-        | get ($x.index - 1)
-        | get item
-        | str trim
-    }
-    | where annotation in (valid-annotations|columns)
-    | reject index
-    | update item {
-        split column --collapse-empty ' '
-        | get column2.0
-    }
-    | rename function_name
+    ^$nu.current-exe -c $'
+        source `($file)`
+        scope commands
+        | select name attributes
+        | where attributes != []
+        | to nuon
+    '
+    | from nuon
+    | update attributes { get name | each {|x| $valid_annotations | get -i $x } | first }
+    | rename function_name annotation
 }
 
 # Takes table of function names and their annotations such as the one returned by get-annotated
@@ -72,10 +58,6 @@ def create-test-record []: nothing -> record<before-each: string, after-each: st
 
     let test_record = (
         $input
-        | update annotation {|x|
-            valid-annotations
-            | get $x.annotation
-        }
         | group-by --to-table annotation
         | update items {|x|
             $x.items.function_name

crates/nu-std/tests/logger_tests/test_basic_commands.nu

@@ -1,3 +1,4 @@
+use std/testing *
 use std/assert
 
 def run [
@@ -41,57 +42,57 @@ def "assert message short" [
     assert str contains $output "test message"
 }
 
-#[test]
+@test
 def critical [] {
     assert no message 99 critical
     assert message CRITICAL critical CRT
 }
 
-#[test]
+@test
 def critical_short [] {
     assert message short CRITICAL critical C
 }
 
-#[test]
+@test
 def error [] {
     assert no message CRITICAL error
     assert message ERROR error ERR
 }
 
-#[test]
+@test
 def error_short [] {
     assert message short ERROR error E
 }
 
-#[test]
+@test
 def warning [] {
     assert no message ERROR warning
     assert message WARNING warning WRN
 }
 
-#[test]
+@test
 def warning_short [] {
     assert message short WARNING warning W
 }
 
-#[test]
+@test
 def info [] {
     assert no message WARNING info
     assert message INFO info "INF" # INF has to be quoted, otherwise it is the `inf` float
 }
 
-#[test]
+@test
 def info_short [] {
     assert message short INFO info I
 }
 
-#[test]
+@test
 def debug [] {
     assert no message INFO debug
     assert message DEBUG debug DBG
 }
 
-#[test]
+@test
 def debug_short [] {
     assert message short DEBUG debug D
 }

crates/nu-std/tests/logger_tests/test_log_custom.nu

@@ -1,3 +1,4 @@
+use std/testing *
 use std/assert
 use commons.nu *
 
@@ -21,14 +22,14 @@ def run-command [
     | complete | get --ignore-errors stderr
 }
 
-#[test]
+@test
 def errors_during_deduction [] {
     assert str contains (run-command "DEBUG" "msg" "%MSG%" 25) "Cannot deduce log level prefix for given log level"
     assert str contains (run-command "DEBUG" "msg" "%MSG%" 25 --ansi (ansi red)) "Cannot deduce log level prefix for given log level"
     assert str contains (run-command "DEBUG" "msg" "%MSG%" 25 --level-prefix "abc") "Cannot deduce ansi for given log level"
 }
 
-#[test]
+@test
 def valid_calls [] {
     use std/log *
     assert equal (run-command "DEBUG" "msg" "%MSG%" 25 --level-prefix "abc" --ansi (ansi default) | str trim --right) "msg"
@@ -37,7 +38,7 @@ def valid_calls [] {
     assert equal (run-command "INFO" "msg" "%ANSI_START%%LEVEL% %MSG%%ANSI_STOP%" ((log-level).CRITICAL) | str trim --right) $"((log-ansi).CRITICAL)CRT msg(ansi reset)"
 }
 
-#[test]
+@test
 def log-level_handling [] {
     use std/log *
     assert equal (run-command "DEBUG" "msg" "%LEVEL% %MSG%" 20 | str trim --right) $"((log-prefix).INFO) msg"

crates/nu-std/tests/logger_tests/test_log_format_flag.nu

@@ -1,3 +1,4 @@
+use std/testing *
 use std *
 use std/log *
 use std/assert
@@ -40,7 +41,7 @@ def "assert formatted" [
     assert equal ($output | str trim --right) (format-message $message $format $prefix $ansi)
 }
 
-#[test]
+@test
 def format_flag [] {
     assert formatted "test" "25 %MSG% %ANSI_START% %LEVEL%%ANSI_STOP%" critical
     assert formatted "test" "25 %MSG% %ANSI_START% %LEVEL%%ANSI_STOP%" error

crates/nu-std/tests/logger_tests/test_logger_env.nu

@@ -1,8 +1,9 @@
+use std/testing *
 use std/assert
 use std/log
 use std/log *
 
-#[test]
+@test
 def env_log-ansi [] {
     assert equal (log-ansi).CRITICAL (ansi red_bold)
     assert equal (log-ansi).ERROR (ansi red)
@@ -11,7 +12,7 @@ def env_log-ansi [] {
     assert equal (log-ansi).DEBUG (ansi default_dimmed)
 }
 
-#[test]
+@test
 def env_log-level [] {
     assert equal (log-level).CRITICAL 50
     assert equal (log-level).ERROR 40
@@ -20,7 +21,7 @@ def env_log-level [] {
     assert equal (log-level).DEBUG 10
 }
 
-#[test]
+@test
 def env_log-prefix [] {
     assert equal (log-prefix).CRITICAL "CRT"
     assert equal (log-prefix).ERROR "ERR"
@@ -29,7 +30,7 @@ def env_log-prefix [] {
     assert equal (log-prefix).DEBUG "DBG"
 }
 
-#[test]
+@test
 def env_log-short-prefix [] {
     assert equal (log-short-prefix).CRITICAL "C"
     assert equal (log-short-prefix).ERROR "E"
@@ -38,7 +39,7 @@ def env_log-short-prefix [] {
     assert equal (log-short-prefix).DEBUG "D"
 }
 
-#[test]
+@test
 def env_log_format [] {
     assert equal $env.NU_LOG_FORMAT $"%ANSI_START%%DATE%|%LEVEL%|%MSG%%ANSI_STOP%"
 }

crates/nu-std/tests/test_asserts.nu

@@ -1,7 +1,8 @@
+use std/testing *
 use std *
 use std/assert
 
-#[test]
+@test
 def assert_basic [] {
     assert true
     assert (1 + 2 == 3)
@@ -9,7 +10,7 @@ def assert_basic [] {
     assert error { assert (1 + 2 == 4) }
 }
 
-#[test]
+@test
 def assert_not [] {
     assert not false
     assert not (1 + 2 == 4)
@@ -17,7 +18,7 @@ def assert_not [] {
     assert error { assert not (1 + 2 == 3) }
 }
 
-#[test]
+@test
 def assert_equal [] {
     assert equal (1 + 2) 3
     assert equal (0.1 + 0.2 | into string | into float) 0.3 # 0.30000000000000004 == 0.3
@@ -25,7 +26,7 @@ def assert_equal [] {
     assert error { assert equal (1 + 2) 4 }
 }
 
-#[test]
+@test
 def assert_not_equal [] {
     assert not equal (1 + 2) 4
     assert not equal 1 "foo"
@@ -33,7 +34,7 @@ def assert_not_equal [] {
     assert error { assert not equal 1 1 }
 }
 
-#[test]
+@test
 def assert_error [] {
     let failing_code = {|| missing_code_to_run}
     assert error $failing_code
@@ -43,39 +44,39 @@ def assert_error [] {
     assert $assert_error_raised "The assert error should be false if there is no error in the executed code."
 }
 
-#[test]
+@test
 def assert_less [] {
     assert less 1 2
     assert error { assert less 1 1 }
 }
 
-#[test]
+@test
 def assert_less_or_equal [] {
     assert less or equal 1 2
     assert less or equal 1 1
     assert error { assert less or equal 1 0 }
 }
 
-#[test]
+@test
 def assert_greater [] {
     assert greater 2 1
     assert error { assert greater 2 2 }
 }
 
-#[test]
+@test
 def assert_greater_or_equal [] {
     assert greater or equal 1 1
     assert greater or equal 2 1
     assert error { assert greater or equal 0 1 }
 }
 
-#[test]
+@test
 def assert_length [] {
     assert length [0, 0, 0]  3
     assert error { assert length [0, 0] 3 }
 }
 
-#[ignore]
+@ignore
 def assert_skip [] {
     assert true # This test case is skipped on purpose
 }

crates/nu-std/tests/test_dirs.nu

@@ -1,3 +1,4 @@
+use std/testing *
 use std/assert
 use std/log
 
@@ -5,7 +6,7 @@ use std/log
 # Each 'use' for that module in the test script will execute the def --env block.
 # PWD at the time of the `use` will be what the export def --env block will see.
 
-#[before-each]
+@before-each
 def before-each [] {
     # need some directories to play with
     let base_path = ($nu.temp-path | path join $"test_dirs_(random uuid)")
@@ -17,7 +18,7 @@ def before-each [] {
     {base_path: $base_path, path_a: $path_a, path_b: $path_b}
 }
 
-#[after-each]
+@after-each
 def after-each [] {
     let base_path = $in.base_path
     cd $base_path
@@ -36,7 +37,7 @@ def cur_ring_check [expect_dir:string, expect_position: int scenario:string] {
     assert equal $expect_position $env.DIRS_POSITION $"position in ring after ($scenario)"
 }
 
-#[test]
+@test
 def dirs_command [] {
     # careful with order of these statements!
     # must capture value of $in before executing `use`s
@@ -87,7 +88,7 @@ def dirs_command [] {
     assert equal $env.PWD $c.base_path "drop changes PWD (regression test for #9449)"
 }
 
-#[test]
+@test
 def dirs_next [] {
     # must capture value of $in before executing `use`s
     let $c = $in
@@ -109,7 +110,7 @@ def dirs_next [] {
 
 }
 
-#[test]
+@test
 def dirs_cd [] {
     # must capture value of $in before executing `use`s
     let $c = $in
@@ -134,7 +135,7 @@ def dirs_cd [] {
     assert equal [$c.path_b $c.path_b] $env.DIRS_LIST "cd updated both positions in ring"
 }
 
-#[test]
+@test
 def dirs_goto_bug10696 [] {
     let $c = $in
     cd $c.base_path
@@ -148,7 +149,7 @@ def dirs_goto_bug10696 [] {
     assert equal $env.PWD $c.path_b "goto other, then goto to come back returns to same directory"
 }
 
-#[test]
+@test
 def dirs_goto [] {
     let $c = $in
     cd $c.base_path

crates/nu-std/tests/test_dt.nu

@@ -1,44 +1,45 @@
+use std/testing *
 use std/assert
 use std/dt *
 
-#[test]
+@test
 def equal_times [] {
     let t1 = (date now)
     assert equal (datetime-diff $t1 $t1) ({year:0, month:0, day:0, hour:0, minute:0, second:0, millisecond:0, microsecond:0 nanosecond:0})
 }
 
-#[test]
+@test
 def one_ns_later [] {
     let t1 = (date now)
     assert equal (datetime-diff ($t1 + 1ns) $t1) ({year:0, month:0, day:0, hour:0, minute:0, second:0, millisecond:0, microsecond:0 nanosecond:1})
 }
 
-#[test]
+@test
 def one_yr_later [] {
     let t1 = ('2022-10-1T0:1:2z' | into datetime)   # a date for which one year later is 365 days, since duration doesn't support year or month
     assert equal (datetime-diff ($t1 + 365day) $t1) ({year:1, month:0, day:0, hour:0, minute:0, second:0, millisecond:0, microsecond:0 nanosecond:0})
 }
 
-#[test]
+@test
 def carry_ripples [] {
     let t1 = ('2023-10-9T0:0:0z' | into datetime)
     let t2 = ('2022-10-9T0:0:0.000000001z' | into datetime)
     assert equal (datetime-diff $t1 $t2) ({year:0, month:11, day:30, hour:23, minute:59, second:59, millisecond:999, microsecond:999 nanosecond:999})
 }
 
-#[test]
+@test
 def earlier_arg_must_be_less_or_equal_later [] {
     let t1 = ('2022-10-9T0:0:0.000000001z' | into datetime)
     let t2 = ('2023-10-9T0:0:0z' | into datetime)
     assert error {|| (datetime-diff $t1 $t2)} 
 }
 
-#[test]
+@test
 def pp_skips_zeros [] {
     assert equal (pretty-print-duration {year:1, month:0, day:0, hour:0, minute:0, second:0, millisecond:0, microsecond:0 nanosecond:0}) "1yr "
 }
 
-#[test]
+@test
 def pp_doesnt_skip_neg [] { # datetime-diff can't return negative units, but prettyprint shouldn't skip them (if passed handcrafted record)
     assert equal (pretty-print-duration {year:-1, month:0, day:0, hour:0, minute:0, second:0, millisecond:0, microsecond:0 nanosecond:0}) "-1yr "
-}
+}

crates/nu-std/tests/test_formats.nu

@@ -1,4 +1,5 @@
 # Test std/formats when importing module-only
+use std/testing *
 use std/assert
 use std/formats *
 
@@ -30,113 +31,113 @@ def test_data_multiline [--nuon] {
   }
 }
 
-#[test]
+@test
 def from_ndjson_multiple_objects [] {
   let result = test_data_multiline | from ndjson
   let expect = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}]
   assert equal $result $expect "could not convert from NDJSON"
 }
 
-#[test]
+@test
 def from_ndjson_single_object [] {
   let result = '{"a": 1}' | from ndjson
   let expect = [{a:1}]
   assert equal $result $expect "could not convert from NDJSON"
 }
 
-#[test]
+@test
 def from_ndjson_invalid_object [] {
   assert error { '{"a":1' | from ndjson }
 }
 
-#[test]
+@test
 def from_jsonl_multiple_objects [] {
   let result = test_data_multiline | from jsonl
   let expect = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}]
   assert equal $result $expect "could not convert from JSONL"
 }
 
-#[test]
+@test
 def from_jsonl_single_object [] {
   let result = '{"a": 1}' | from jsonl
   let expect = [{a:1}]
   assert equal $result $expect "could not convert from JSONL"
 }
 
-#[test]
+@test
 def from_jsonl_invalid_object [] {
   assert error { '{"a":1' | from jsonl }
 }
 
-#[test]
+@test
 def to_ndjson_multiple_objects [] {
   let result = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}] | to ndjson | str trim
   let expect = test_data_multiline
   assert equal $result $expect "could not convert to NDJSON"
 }
 
-#[test]
+@test
 def to_ndjson_single_object [] {
   let result = [{a:1}] | to ndjson | str trim
   let expect = "{\"a\":1}"
   assert equal $result $expect "could not convert to NDJSON"
 }
 
-#[test]
+@test
 def to_jsonl_multiple_objects [] {
   let result = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}] | to jsonl | str trim
   let expect = test_data_multiline
   assert equal $result $expect "could not convert to JSONL"
 }
 
-#[test]
+@test
 def to_jsonl_single_object [] {
   let result = [{a:1}] | to jsonl | str trim
   let expect = "{\"a\":1}"
   assert equal $result $expect "could not convert to JSONL"
 }
 
-#[test]
+@test
 def from_ndnuon_multiple_objects [] {
   let result = test_data_multiline | from ndnuon
   let expect = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}]
   assert equal $result $expect "could not convert from NDNUON"
 }
 
-#[test]
+@test
 def from_ndnuon_single_object [] {
   let result = '{a: 1}' | from ndnuon
   let expect = [{a:1}]
   assert equal $result $expect "could not convert from NDNUON"
 }
 
-#[test]
+@test
 def from_ndnuon_invalid_object [] {
   assert error { '{"a":1' | formats from ndnuon }
 }
 
-#[test]
+@test
 def to_ndnuon_multiple_objects [] {
   let result = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}] | to ndnuon | str trim
   let expect = test_data_multiline --nuon
   assert equal $result $expect "could not convert to NDNUON"
 }
 
-#[test]
+@test
 def to_ndnuon_single_object [] {
   let result = [{a:1}] | to ndnuon | str trim
   let expect = "{a: 1}"
   assert equal $result $expect "could not convert to NDNUON"
 }
 
-#[test]
+@test
 def to_ndnuon_multiline_strings [] {
   let result = "foo\n\\n\nbar" | to ndnuon
   let expect = '"foo\n\\n\nbar"'
   assert equal $result $expect "could not convert multiline string to NDNUON"
 }
 
-#[test]
+@test
 def from_ndnuon_multiline_strings [] {
   let result = '"foo\n\\n\nbar"' | from ndnuon
   let expect = ["foo\n\\n\nbar"]

crates/nu-std/tests/test_help.nu

@@ -1,13 +1,14 @@
+use std/testing *
 use std/assert
 use std/help
 
-#[test]
+@test
 def show_help_on_commands [] {
     let help_result = (help alias)
     assert ("item not found" not-in $help_result)
 }
 
-#[test]
+@test
 def show_help_on_error_make [] {
     let help_result = (help error make)
     assert ("Error: nu::shell::eval_block_with_input" not-in $help_result)

crates/nu-std/tests/test_iter.nu

@@ -1,7 +1,8 @@
+use std/testing *
 use std *
 use std/assert
 
-#[test]
+@test
 def iter_find [] {
     let hastack1 = [1 2 3 4 5 6 7]
     let hastack2 = [nushell rust shell iter std]
@@ -20,7 +21,7 @@ def iter_find [] {
     assert equal $res null
 }
 
-#[test]
+@test
 def iter_intersperse [] {
     let res = ([1 2 3 4] | iter intersperse 0)
     assert equal $res [1 0 2 0 3 0 4]
@@ -41,7 +42,7 @@ def iter_intersperse [] {
     assert equal $res [4]
 }
 
-#[test]
+@test
 def iter_scan [] {
     let scanned = ([1 2 3] | iter scan 0 {|x, y| $x + $y} -n)
     assert equal $scanned [1, 3, 6]
@@ -56,7 +57,7 @@ def iter_scan [] {
     assert equal $scanned ["a" "ab" "abc" "abcd"]
 }
 
-#[test]
+@test
 def iter_filter_map [] {
     let res = ([2 5 "4" 7] | iter filter-map {|it| $it ** 2})
     assert equal $res [4 25 49]
@@ -68,7 +69,7 @@ def iter_filter_map [] {
     assert equal $res [3 42 69]
 }
 
-#[test]
+@test
 def iter_find_index [] {
     let res = (
          ["iter", "abc", "shell", "around", "nushell", "std"]
@@ -84,7 +85,7 @@ def iter_find_index [] {
     assert equal $res 0
 }
 
-#[test]
+@test
 def iter_zip_with [] {
     let res = (
         [1 2 3] | iter zip-with [2 3 4] {|a, b| $a + $b }
@@ -111,7 +112,7 @@ def iter_zip_with [] {
     ]
 }
 
-#[test]
+@test
 def iter_flat_map [] {
     let res = (
         [[1 2 3] [2 3 4] [5 6 7]] | iter flat-map {|it| $it | math sum}
@@ -122,7 +123,7 @@ def iter_flat_map [] {
     assert equal $res [11 22 33]
 }
 
-#[test]
+@test
 def iter_zip_into_record [] {
     let headers = [name repo position]
     let values = [rust github 1]

crates/nu-std/tests/test_prelude.nu

@@ -1,6 +1,7 @@
+use std/testing *
 use std/assert
 
-#[test]
+@test
 def banner [] {
     use std/prelude
     assert ((prelude banner | lines | length) == 16)

crates/nu-std/tests/test_setup_teardown.nu

@@ -1,28 +1,29 @@
+use std/testing *
 use std/log
 use std/assert
 
-#[before-each]
+@before-each
 def before-each [] {
     log debug "Setup is running"
     {msg: "This is the context"}
 }
 
-#[after-each]
+@after-each
 def after-each [] {
     log debug $"Teardown is running. Context: ($in)"
 }
 
-#[test]
+@test
 def assert_pass [] {
     log debug $"Assert is running. Context: ($in)"
 }
 
-#[ignore]
+@ignore
 def assert_skip [] {
     log debug $"Assert is running. Context: ($in)"
 }
 
-#[ignore]
+@ignore
 def assert_fail_skipped_by_default [] {
     # Change test-skip to test if you want to see what happens if a test fails
     log debug $"Assert is running. Context: ($in)"

crates/nu-std/tests/test_std_formats.nu

@@ -1,4 +1,5 @@
 # Test std/formats when importing `use std *`
+use std/testing *
 use std *
 
 def test_data_multiline [--nuon] {
@@ -30,113 +31,113 @@ def test_data_multiline [--nuon] {
   }
 }
 
-#[test]
+@test
 def from_ndjson_multiple_objects [] {
   let result = test_data_multiline | formats from ndjson
   let expect = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}]
   assert equal $result $expect "could not convert from NDJSON"
 }
 
-#[test]
+@test
 def from_ndjson_single_object [] {
   let result = '{"a": 1}' | formats from ndjson
   let expect = [{a:1}]
   assert equal $result $expect "could not convert from NDJSON"
 }
 
-#[test]
+@test
 def from_ndjson_invalid_object [] {
   assert error { '{"a":1' | formats from ndjson }
 }
 
-#[test]
+@test
 def from_jsonl_multiple_objects [] {
   let result = test_data_multiline | formats from jsonl
   let expect = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}]
   assert equal $result $expect "could not convert from JSONL"
 }
 
-#[test]
+@test
 def from_jsonl_single_object [] {
   let result = '{"a": 1}' | formats from jsonl
   let expect = [{a:1}]
   assert equal $result $expect "could not convert from JSONL"
 }
 
-#[test]
+@test
 def from_jsonl_invalid_object [] {
   assert error { '{"a":1' | formats from jsonl }
 }
 
-#[test]
+@test
 def to_ndjson_multiple_objects [] {
   let result = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}] | formats to ndjson | str trim
   let expect = test_data_multiline
   assert equal $result $expect "could not convert to NDJSON"
 }
 
-#[test]
+@test
 def to_ndjson_single_object [] {
   let result = [{a:1}] | formats to ndjson | str trim
   let expect = "{\"a\":1}"
   assert equal $result $expect "could not convert to NDJSON"
 }
 
-#[test]
+@test
 def to_jsonl_multiple_objects [] {
   let result = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}] | formats to jsonl | str trim
   let expect = test_data_multiline
   assert equal $result $expect "could not convert to JSONL"
 }
 
-#[test]
+@test
 def to_jsonl_single_object [] {
   let result = [{a:1}] | formats to jsonl | str trim
   let expect = "{\"a\":1}"
   assert equal $result $expect "could not convert to JSONL"
 }
 
-#[test]
+@test
 def from_ndnuon_multiple_objects [] {
   let result = test_data_multiline | formats from ndnuon
   let expect = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}]
   assert equal $result $expect "could not convert from NDNUON"
 }
 
-#[test]
+@test
 def from_ndnuon_single_object [] {
   let result = '{a: 1}' | formats from ndnuon
   let expect = [{a:1}]
   assert equal $result $expect "could not convert from NDNUON"
 }
 
-#[test]
+@test
 def from_ndnuon_invalid_object [] {
   assert error { '{"a":1' | formats from ndnuon }
 }
 
-#[test]
+@test
 def to_ndnuon_multiple_objects [] {
   let result = [{a:1},{a:2},{a:3},{a:4},{a:5},{a:6}] | formats to ndnuon | str trim
   let expect = test_data_multiline --nuon
   assert equal $result $expect "could not convert to NDNUON"
 }
 
-#[test]
+@test
 def to_ndnuon_single_object [] {
   let result = [{a:1}] | formats to ndnuon | str trim
   let expect = "{a: 1}"
   assert equal $result $expect "could not convert to NDNUON"
 }
 
-#[test]
+@test
 def to_ndnuon_multiline_strings [] {
   let result = "foo\n\\n\nbar" | formats to ndnuon
   let expect = '"foo\n\\n\nbar"'
   assert equal $result $expect "could not convert multiline string to NDNUON"
 }
 
-#[test]
+@test
 def from_ndnuon_multiline_strings [] {
   let result = '"foo\n\\n\nbar"' | formats from ndnuon
   let expect = ["foo\n\\n\nbar"]

crates/nu-std/tests/test_std_postload.nu

@@ -1,11 +1,12 @@
+use std/testing *
 use std/assert
 export use std *
 
-#[test]
+@test
 def std_post_import [] {
   assert length (scope commands | where name == "path add") 1
   assert length (scope commands | where name == "ellie") 1
   assert length (scope commands | where name == "repeat") 1
   assert length (scope commands | where name == "formats from jsonl") 1
   assert length (scope commands | where name == "dt datetime-diff") 1
-}
+}

crates/nu-std/tests/test_std_preload.nu

@@ -1,6 +1,7 @@
+use std/testing *
 use std/assert
 
-#[test]
+@test
 def std_pre_import [] {
   # These commands shouldn't exist without an import
   assert length (scope commands | where name == "path add") 0
@@ -8,4 +9,4 @@ def std_pre_import [] {
   assert length (scope commands | where name == "repeat") 0
   assert length (scope commands | where name == "from jsonl") 0
   assert length (scope commands | where name == "datetime-diff") 0
-}
+}

crates/nu-std/tests/test_std_util.nu

@@ -1,6 +1,7 @@
+use std/testing *
 use std *
 
-#[test]
+@test
 def path_add [] {
     use std/assert
 
@@ -44,7 +45,7 @@ def path_add [] {
     }
 }
 
-#[test]
+@test
 def path_add_expand [] {
     use std/assert
 
@@ -70,7 +71,7 @@ def path_add_expand [] {
     rm $real_dir $link_dir
 }
 
-#[test]
+@test
 def repeat_things [] {
     use std/assert
     assert error { "foo" | repeat -1 }

crates/nu-std/tests/test_util.nu

@@ -1,6 +1,7 @@
+use std/testing *
 use std/util *
 
-#[test]
+@test
 def path_add [] {
     use std/assert
 
@@ -44,7 +45,7 @@ def path_add [] {
     }
 }
 
-#[test]
+@test
 def path_add_expand [] {
     use std/assert
 
@@ -70,7 +71,7 @@ def path_add_expand [] {
     rm $real_dir $link_dir
 }
 
-#[test]
+@test
 def repeat_things [] {
     use std/assert
     assert error { "foo" | repeat -1 }

crates/nu-std/tests/test_xml.nu

@@ -1,7 +1,8 @@
+use std/testing *
 use std/xml *
 use std/assert
 
-#[before-each]
+@before-each
 def before-each [] {
     {sample_xml: ('
         <a>
@@ -17,7 +18,7 @@ def before-each [] {
     }
 }
 
-#[test]
+@test
 def xml_xaccess [] {
     let sample_xml = $in.sample_xml
 
@@ -28,7 +29,7 @@ def xml_xaccess [] {
     assert equal ($sample_xml | xaccess [* * * {|e| $e.attributes != {}}]) [[tag, attributes, content]; [c, {a: b}, []]]
 }
 
-#[test]
+@test
 def xml_xupdate [] {
     let sample_xml = $in.sample_xml
 
@@ -37,7 +38,7 @@ def xml_xupdate [] {
     assert equal ($sample_xml | xupdate [* * * {|e| $e.attributes != {}}] {|x| $x | update content ['xml']}) {tag: a, attributes: {}, content: [[tag, attributes, content]; [b, {}, [[tag, attributes, content]; [c, {a: b}, [xml]]]], [c, {}, []], [d, {}, [[tag, attributes, content]; [e, {}, [[tag, attributes, content]; [null, null, z]]], [e, {}, [[tag, attributes, content]; [null, null, x]]]]]]}
 }
 
-#[test]
+@test
 def xml_xinsert [] {
     let sample_xml = $in.sample_xml
 

crates/nuon/src/from.rs

@@ -118,6 +118,12 @@ fn convert_to_value(
     original_text: &str,
 ) -> Result<Value, ShellError> {
     match expr.expr {
+        Expr::AttributeBlock(..) => Err(ShellError::OutsideSpannedLabeledError {
+            src: original_text.to_string(),
+            error: "Error when loading".into(),
+            msg: "attributes not supported in nuon".into(),
+            span: expr.span,
+        }),
         Expr::BinaryOp(..) => Err(ShellError::OutsideSpannedLabeledError {
             src: original_text.to_string(),
             error: "Error when loading".into(),