New commands: break, continue, return, and loop (#7230)

# Description

This adds `break`, `continue`, `return`, and `loop`.

* `break` - breaks out a loop
* `continue` - continues a loop at the next iteration
* `return` - early return from a function call
* `loop` - loop forever (until the loop hits a break)

Examples:
```
for i in 1..10 {
    if $i == 5 {
       continue
    } 
    print $i
}
```

```
for i in 1..10 {
    if $i == 5 {
        break
    } 
    print $i
}
```

```
def foo [x] {
    if true {
        return 2
    }
    $x
}
foo 100
```

```
loop { print "hello, forever" }
```

```
[1, 2, 3, 4, 5] | each {|x| 
    if $x > 3 { break }
    $x
}
```

# User-Facing Changes

Adds the above commands.

# Tests + Formatting

Don't forget to add tests that cover your changes.

Make sure you've run and fixed any issues with these commands:

- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass

# After Submitting

If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.

crates/nu-command/src/core_commands/break_.rs

@@ -0,0 +1,49 @@
+use nu_protocol::ast::Call;
+use nu_protocol::engine::{Command, EngineState, Stack};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Type};
+
+#[derive(Clone)]
+pub struct Break;
+
+impl Command for Break {
+    fn name(&self) -> &str {
+        "break"
+    }
+
+    fn usage(&self) -> &str {
+        "Break a loop"
+    }
+
+    fn signature(&self) -> nu_protocol::Signature {
+        Signature::build("break")
+            .input_output_types(vec![(Type::Nothing, Type::Nothing)])
+            .category(Category::Core)
+    }
+
+    fn extra_usage(&self) -> &str {
+        r#"This command is a parser keyword. For details, check:
+  https://www.nushell.sh/book/thinking_in_nu.html"#
+    }
+
+    fn is_parser_keyword(&self) -> bool {
+        true
+    }
+
+    fn run(
+        &self,
+        _engine_state: &EngineState,
+        _stack: &mut Stack,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<nu_protocol::PipelineData, nu_protocol::ShellError> {
+        Err(ShellError::Break(call.head))
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![Example {
+            description: "Break out of a loop",
+            example: r#"loop { break }"#,
+            result: None,
+        }]
+    }
+}

crates/nu-command/src/core_commands/continue_.rs

@@ -0,0 +1,49 @@
+use nu_protocol::ast::Call;
+use nu_protocol::engine::{Command, EngineState, Stack};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Type};
+
+#[derive(Clone)]
+pub struct Continue;
+
+impl Command for Continue {
+    fn name(&self) -> &str {
+        "continue"
+    }
+
+    fn usage(&self) -> &str {
+        "Continue a loop from the next iteration"
+    }
+
+    fn signature(&self) -> nu_protocol::Signature {
+        Signature::build("continue")
+            .input_output_types(vec![(Type::Nothing, Type::Nothing)])
+            .category(Category::Core)
+    }
+
+    fn extra_usage(&self) -> &str {
+        r#"This command is a parser keyword. For details, check:
+  https://www.nushell.sh/book/thinking_in_nu.html"#
+    }
+
+    fn is_parser_keyword(&self) -> bool {
+        true
+    }
+
+    fn run(
+        &self,
+        _engine_state: &EngineState,
+        _stack: &mut Stack,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<nu_protocol::PipelineData, nu_protocol::ShellError> {
+        Err(ShellError::Continue(call.head))
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![Example {
+            description: "Continue a loop from the next iteration",
+            example: r#"for i in 1..10 { if $i == 5 { continue }; print $i }"#,
+            result: None,
+        }]
+    }
+}

crates/nu-command/src/core_commands/do_.rs

@@ -1,4 +1,4 @@
-use nu_engine::{eval_block, CallExt};
+use nu_engine::{eval_block_with_early_return, CallExt};
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Closure, Command, EngineState, Stack};
 use nu_protocol::{
@@ -100,7 +100,7 @@ impl Command for Do {
                 )
             }
         }
-        let result = eval_block(
+        let result = eval_block_with_early_return(
             engine_state,
             &mut stack,
             block,

crates/nu-command/src/core_commands/for_.rs

@@ -1,7 +1,9 @@
 use nu_engine::{eval_block, eval_expression, CallExt};
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Block, Command, EngineState, Stack};
-use nu_protocol::{Category, Example, ListStream, PipelineData, Signature, SyntaxShape, Value};
+use nu_protocol::{
+    Category, Example, ListStream, PipelineData, ShellError, Signature, SyntaxShape, Value,
+};
 
 #[derive(Clone)]
 pub struct For;
@@ -104,15 +106,27 @@ impl Command for For {
                     );
 
                     //let block = engine_state.get_block(block_id);
-                    eval_block(
+                    match eval_block(
                         &engine_state,
                         stack,
                         &block,
                         PipelineData::new(head),
                         redirect_stdout,
                         redirect_stderr,
-                    )?
-                    .into_value(head);
+                    ) {
+                        Err(ShellError::Break(_)) => {
+                            break;
+                        }
+                        Err(ShellError::Continue(_)) => {
+                            continue;
+                        }
+                        Err(err) => {
+                            return Err(err);
+                        }
+                        Ok(pipeline) => {
+                            pipeline.into_value(head);
+                        }
+                    }
                 }
             }
             Value::Range { val, .. } => {
@@ -137,15 +151,27 @@ impl Command for For {
                     );
 
                     //let block = engine_state.get_block(block_id);
-                    eval_block(
+                    match eval_block(
                         &engine_state,
                         stack,
                         &block,
                         PipelineData::new(head),
                         redirect_stdout,
                         redirect_stderr,
-                    )?
-                    .into_value(head);
+                    ) {
+                        Err(ShellError::Break(_)) => {
+                            break;
+                        }
+                        Err(ShellError::Continue(_)) => {
+                            continue;
+                        }
+                        Err(err) => {
+                            return Err(err);
+                        }
+                        Ok(pipeline) => {
+                            pipeline.into_value(head);
+                        }
+                    }
                 }
             }
             x => {

crates/nu-command/src/core_commands/loop_.rs

@@ -0,0 +1,101 @@
+use std::sync::atomic::Ordering;
+
+use nu_engine::{eval_block, CallExt};
+use nu_protocol::ast::Call;
+use nu_protocol::engine::{Block, Command, EngineState, Stack};
+use nu_protocol::{
+    Category, Example, PipelineData, ShellError, Signature, Span, SyntaxShape, Value,
+};
+
+#[derive(Clone)]
+pub struct Loop;
+
+impl Command for Loop {
+    fn name(&self) -> &str {
+        "loop"
+    }
+
+    fn usage(&self) -> &str {
+        "Run a block in a loop."
+    }
+
+    fn signature(&self) -> nu_protocol::Signature {
+        Signature::build("loop")
+            .required("block", SyntaxShape::Block, "block to loop")
+            .category(Category::Core)
+    }
+
+    fn extra_usage(&self) -> &str {
+        r#"This command is a parser keyword. For details, check:
+  https://www.nushell.sh/book/thinking_in_nu.html"#
+    }
+
+    fn is_parser_keyword(&self) -> bool {
+        true
+    }
+
+    fn run(
+        &self,
+        engine_state: &EngineState,
+        stack: &mut Stack,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<nu_protocol::PipelineData, nu_protocol::ShellError> {
+        let block: Block = call.req(engine_state, stack, 0)?;
+
+        loop {
+            if let Some(ctrlc) = &engine_state.ctrlc {
+                if ctrlc.load(Ordering::SeqCst) {
+                    break;
+                }
+            }
+
+            let block = engine_state.get_block(block.block_id);
+            match eval_block(
+                engine_state,
+                stack,
+                block,
+                PipelineData::new(call.head),
+                call.redirect_stdout,
+                call.redirect_stderr,
+            ) {
+                Err(ShellError::Break(_)) => {
+                    break;
+                }
+                Err(ShellError::Continue(_)) => {
+                    continue;
+                }
+                Err(err) => {
+                    return Err(err);
+                }
+                Ok(pipeline) => {
+                    pipeline.into_value(call.head);
+                }
+            }
+        }
+        Ok(PipelineData::new(call.head))
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![Example {
+            description: "Loop while a condition is true",
+            example: "mut x = 0; loop { if $x > 10 { break }; $x = $x + 1 }; $x",
+            result: Some(Value::Int {
+                val: 11,
+                span: Span::test_data(),
+            }),
+        }]
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn test_examples() {
+        use crate::test_examples;
+
+        test_examples(Loop {})
+    }
+}

crates/nu-command/src/core_commands/mod.rs

@@ -1,6 +1,8 @@
 mod alias;
 mod ast;
+mod break_;
 mod commandline;
+mod continue_;
 mod debug;
 mod def;
 mod def_env;
@@ -22,10 +24,12 @@ mod hide_env;
 mod if_;
 mod ignore;
 mod let_;
+mod loop_;
 mod metadata;
 mod module;
 mod mut_;
 pub(crate) mod overlay;
+mod return_;
 mod try_;
 mod use_;
 mod version;
@@ -33,7 +37,9 @@ mod while_;
 
 pub use alias::Alias;
 pub use ast::Ast;
+pub use break_::Break;
 pub use commandline::Commandline;
+pub use continue_::Continue;
 pub use debug::Debug;
 pub use def::Def;
 pub use def_env::DefEnv;
@@ -55,10 +61,12 @@ pub use hide_env::HideEnv;
 pub use if_::If;
 pub use ignore::Ignore;
 pub use let_::Let;
+pub use loop_::Loop;
 pub use metadata::Metadata;
 pub use module::Module;
 pub use mut_::Mut;
 pub use overlay::*;
+pub use return_::Return;
 pub use try_::Try;
 pub use use_::Use;
 pub use version::Version;

crates/nu-command/src/core_commands/return_.rs

@@ -0,0 +1,61 @@
+use nu_engine::CallExt;
+use nu_protocol::ast::Call;
+use nu_protocol::engine::{Command, EngineState, Stack};
+use nu_protocol::{
+    Category, Example, PipelineData, ShellError, Signature, SyntaxShape, Type, Value,
+};
+
+#[derive(Clone)]
+pub struct Return;
+
+impl Command for Return {
+    fn name(&self) -> &str {
+        "return"
+    }
+
+    fn usage(&self) -> &str {
+        "Return early from a function"
+    }
+
+    fn signature(&self) -> nu_protocol::Signature {
+        Signature::build("return")
+            .input_output_types(vec![(Type::Nothing, Type::Nothing)])
+            .optional("return_value", SyntaxShape::Any, "optional value to return")
+            .category(Category::Core)
+    }
+
+    fn extra_usage(&self) -> &str {
+        r#"This command is a parser keyword. For details, check:
+  https://www.nushell.sh/book/thinking_in_nu.html"#
+    }
+
+    fn is_parser_keyword(&self) -> bool {
+        true
+    }
+
+    fn run(
+        &self,
+        engine_state: &EngineState,
+        stack: &mut Stack,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<nu_protocol::PipelineData, nu_protocol::ShellError> {
+        let return_value: Option<Value> = call.opt(engine_state, stack, 0)?;
+        if let Some(value) = return_value {
+            Err(ShellError::Return(call.head, Box::new(value)))
+        } else {
+            Err(ShellError::Return(
+                call.head,
+                Box::new(Value::nothing(call.head)),
+            ))
+        }
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![Example {
+            description: "Return early",
+            example: r#"def foo [] { return }"#,
+            result: None,
+        }]
+    }
+}

crates/nu-command/src/core_commands/while_.rs

@@ -59,15 +59,27 @@ impl Command for While {
                 Value::Bool { val, .. } => {
                     if *val {
                         let block = engine_state.get_block(block.block_id);
-                        eval_block(
+                        match eval_block(
                             engine_state,
                             stack,
                             block,
                             PipelineData::new(call.head),
                             call.redirect_stdout,
                             call.redirect_stderr,
-                        )?
-                        .into_value(call.head);
+                        ) {
+                            Err(ShellError::Break(_)) => {
+                                break;
+                            }
+                            Err(ShellError::Continue(_)) => {
+                                continue;
+                            }
+                            Err(err) => {
+                                return Err(err);
+                            }
+                            Ok(pipeline) => {
+                                pipeline.into_value(call.head);
+                            }
+                        }
                     } else {
                         break;
                     }