Merge stream_example into example plugin and clean up names (#12234)

# Description

As suggested by @WindSoilder, since plugins can now contain both simple
commands that produce `Value` and commands that produce `PipelineData`
without having to choose one or the other for the whole plugin, this
change merges `stream_example` into `example`.

# User-Facing Changes

All of the example plugins are renamed.

# Tests + Formatting

- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`

# After Submitting

- [ ] Check nushell/nushell.github.io for any docs that match the
command names changed

crates/nu_plugin_example/README.md

@@ -29,6 +29,6 @@ $env.config = {
 To list plugin values run:
 
 ```nushell
-nu-example-config
+example config
 ```
 

crates/nu_plugin_example/src/commands/collect_external.rs

@@ -1,16 +1,16 @@
 use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, PluginCommand};
 use nu_protocol::{Category, PipelineData, PluginExample, PluginSignature, RawStream, Type, Value};
 
-use crate::StreamExample;
+use crate::Example;
 
-/// `<list<string>> | stream_example collect-external`
+/// `<list<string>> | example collect-external`
 pub struct CollectExternal;
 
 impl PluginCommand for CollectExternal {
-    type Plugin = StreamExample;
+    type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
-        PluginSignature::build("stream_example collect-external")
+        PluginSignature::build("example collect-external")
             .usage("Example transformer to raw external stream")
             .search_terms(vec!["example".into()])
             .input_output_types(vec![
@@ -18,7 +18,7 @@ impl PluginCommand for CollectExternal {
                 (Type::List(Type::Binary.into()), Type::Binary),
             ])
             .plugin_examples(vec![PluginExample {
-                example: "[a b] | stream_example collect-external".into(),
+                example: "[a b] | example collect-external".into(),
                 description: "collect strings into one stream".into(),
                 result: Some(Value::test_string("ab")),
             }])
@@ -27,7 +27,7 @@ impl PluginCommand for CollectExternal {
 
     fn run(
         &self,
-        _plugin: &StreamExample,
+        _plugin: &Example,
         _engine: &EngineInterface,
         call: &EvaluatedCall,
         input: PipelineData,

crates/nu_plugin_example/src/commands/config.rs

@@ -3,13 +3,13 @@ use nu_protocol::{Category, PluginSignature, Type, Value};
 
 use crate::Example;
 
-pub struct NuExampleConfig;
+pub struct Config;
 
-impl SimplePluginCommand for NuExampleConfig {
+impl SimplePluginCommand for Config {
     type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
-        PluginSignature::build("nu-example-config")
+        PluginSignature::build("example config")
             .usage("Show plugin configuration")
             .extra_usage("The configuration is set under $env.config.plugins.example")
             .category(Category::Experimental)

crates/nu_plugin_example/src/commands/disable_gc.rs

@@ -3,13 +3,13 @@ use nu_protocol::{Category, PluginSignature, Value};
 
 use crate::Example;
 
-pub struct NuExampleDisableGc;
+pub struct DisableGc;
 
-impl SimplePluginCommand for NuExampleDisableGc {
+impl SimplePluginCommand for DisableGc {
     type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
-        PluginSignature::build("nu-example-disable-gc")
+        PluginSignature::build("example disable-gc")
             .usage("Disable the plugin garbage collector for `example`")
             .extra_usage(
                 "\

crates/nu_plugin_example/src/commands/env.rs

@@ -3,13 +3,13 @@ use nu_protocol::{Category, PluginSignature, SyntaxShape, Type, Value};
 
 use crate::Example;
 
-pub struct NuExampleEnv;
+pub struct Env;
 
-impl SimplePluginCommand for NuExampleEnv {
+impl SimplePluginCommand for Env {
     type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
-        PluginSignature::build("nu-example-env")
+        PluginSignature::build("example env")
             .usage("Get environment variable(s)")
             .extra_usage("Returns all environment variables if no name provided")
             .category(Category::Experimental)

crates/nu_plugin_example/src/commands/for_each.rs

@@ -1,16 +1,16 @@
 use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, PluginCommand};
 use nu_protocol::{Category, PipelineData, PluginExample, PluginSignature, SyntaxShape, Type};
 
-use crate::StreamExample;
+use crate::Example;
 
-/// `<list> | stream_example for-each { |value| ... }`
+/// `<list> | example for-each { |value| ... }`
 pub struct ForEach;
 
 impl PluginCommand for ForEach {
-    type Plugin = StreamExample;
+    type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
-        PluginSignature::build("stream_example for-each")
+        PluginSignature::build("example for-each")
             .usage("Example execution of a closure with a stream")
             .extra_usage("Prints each value the closure returns to stderr")
             .input_output_type(Type::ListStream, Type::Nothing)
@@ -20,7 +20,7 @@ impl PluginCommand for ForEach {
                 "The closure to run for each input value",
             )
             .plugin_examples(vec![PluginExample {
-                example: "ls | get name | stream_example for-each { |f| ^file $f }".into(),
+                example: "ls | get name | example for-each { |f| ^file $f }".into(),
                 description: "example with an external command".into(),
                 result: None,
             }])
@@ -29,7 +29,7 @@ impl PluginCommand for ForEach {
 
     fn run(
         &self,
-        _plugin: &StreamExample,
+        _plugin: &Example,
         engine: &EngineInterface,
         call: &EvaluatedCall,
         input: PipelineData,

crates/nu_plugin_example/src/commands/generate.rs

@@ -4,16 +4,16 @@ use nu_protocol::{
     SyntaxShape, Type, Value,
 };
 
-use crate::StreamExample;
+use crate::Example;
 
-/// `stream_example generate <initial> { |previous| {out: ..., next: ...} }`
+/// `example generate <initial> { |previous| {out: ..., next: ...} }`
 pub struct Generate;
 
 impl PluginCommand for Generate {
-    type Plugin = StreamExample;
+    type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
-        PluginSignature::build("stream_example generate")
+        PluginSignature::build("example generate")
             .usage("Example execution of a closure to produce a stream")
             .extra_usage("See the builtin `generate` command")
             .input_output_type(Type::Nothing, Type::ListStream)
@@ -28,9 +28,8 @@ impl PluginCommand for Generate {
                 "The closure to run to generate values",
             )
             .plugin_examples(vec![PluginExample {
-                example:
-                    "stream_example generate 0 { |i| if $i <= 10 { {out: $i, next: ($i + 2)} } }"
-                        .into(),
+                example: "example generate 0 { |i| if $i <= 10 { {out: $i, next: ($i + 2)} } }"
+                    .into(),
                 description: "Generate a sequence of numbers".into(),
                 result: Some(Value::test_list(
                     [0, 2, 4, 6, 8, 10]
@@ -44,7 +43,7 @@ impl PluginCommand for Generate {
 
     fn run(
         &self,
-        _plugin: &StreamExample,
+        _plugin: &Example,
         engine: &EngineInterface,
         call: &EvaluatedCall,
         _input: PipelineData,

crates/nu_plugin_example/src/commands/main.rs

@@ -0,0 +1,41 @@
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{Category, PluginSignature, Value};
+
+use crate::Example;
+
+pub struct Main;
+
+impl SimplePluginCommand for Main {
+    type Plugin = Example;
+
+    fn signature(&self) -> PluginSignature {
+        PluginSignature::build("example")
+            .usage("Example commands for Nushell plugins")
+            .extra_usage(
+                r#"
+The `example` plugin demonstrates usage of the Nushell plugin API.
+
+Several commands provided to test and demonstrate different capabilities of
+plugins exposed through the API. None of these commands are intended to be
+particularly useful.
+"#
+                .trim(),
+            )
+            .search_terms(vec!["example".into()])
+            .category(Category::Experimental)
+    }
+
+    fn run(
+        &self,
+        _plugin: &Self::Plugin,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        _input: &Value,
+    ) -> Result<Value, LabeledError> {
+        Err(LabeledError {
+            label: "No subcommand provided".into(),
+            msg: "add --help to see a list of subcommands".into(),
+            span: Some(call.head),
+        })
+    }
+}

crates/nu_plugin_example/src/commands/mod.rs

@@ -1,13 +1,35 @@
-mod nu_example_1;
-mod nu_example_2;
-mod nu_example_3;
-mod nu_example_config;
-mod nu_example_disable_gc;
-mod nu_example_env;
+// `example` command - just suggests to call --help
+mod main;
 
-pub use nu_example_1::NuExample1;
-pub use nu_example_2::NuExample2;
-pub use nu_example_3::NuExample3;
-pub use nu_example_config::NuExampleConfig;
-pub use nu_example_disable_gc::NuExampleDisableGc;
-pub use nu_example_env::NuExampleEnv;
+pub use main::Main;
+
+// Basic demos
+mod one;
+mod three;
+mod two;
+
+pub use one::One;
+pub use three::Three;
+pub use two::Two;
+
+// Engine interface demos
+mod config;
+mod disable_gc;
+mod env;
+
+pub use config::Config;
+pub use disable_gc::DisableGc;
+pub use env::Env;
+
+// Stream demos
+mod collect_external;
+mod for_each;
+mod generate;
+mod seq;
+mod sum;
+
+pub use collect_external::CollectExternal;
+pub use for_each::ForEach;
+pub use generate::Generate;
+pub use seq::Seq;
+pub use sum::Sum;

crates/nu_plugin_example/src/commands/one.rs

@@ -3,17 +3,17 @@ use nu_protocol::{Category, PluginExample, PluginSignature, SyntaxShape, Value};
 
 use crate::Example;
 
-pub struct NuExample1;
+pub struct One;
 
-impl SimplePluginCommand for NuExample1 {
+impl SimplePluginCommand for One {
     type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
         // The signature defines the usage of the command inside Nu, and also automatically
         // generates its help page.
-        PluginSignature::build("nu-example-1")
+        PluginSignature::build("example one")
             .usage("PluginSignature test 1 for plugin. Returns Value::Nothing")
-            .extra_usage("Extra usage for nu-example-1")
+            .extra_usage("Extra usage for example one")
             .search_terms(vec!["example".into()])
             .required("a", SyntaxShape::Int, "required integer value")
             .required("b", SyntaxShape::String, "required string value")
@@ -22,7 +22,7 @@ impl SimplePluginCommand for NuExample1 {
             .named("named", SyntaxShape::String, "named string", Some('n'))
             .rest("rest", SyntaxShape::String, "rest value string")
             .plugin_examples(vec![PluginExample {
-                example: "nu-example-1 3 bb".into(),
+                example: "example one 3 bb".into(),
                 description: "running example with an int value and string value".into(),
                 result: None,
             }])

crates/nu_plugin_example/src/commands/seq.rs

@@ -3,23 +3,23 @@ use nu_protocol::{
     Category, ListStream, PipelineData, PluginExample, PluginSignature, SyntaxShape, Type, Value,
 };
 
-use crate::StreamExample;
+use crate::Example;
 
-/// `stream_example seq <first> <last>`
+/// `example seq <first> <last>`
 pub struct Seq;
 
 impl PluginCommand for Seq {
-    type Plugin = StreamExample;
+    type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
-        PluginSignature::build("stream_example seq")
+        PluginSignature::build("example seq")
             .usage("Example stream generator for a list of values")
             .search_terms(vec!["example".into()])
             .required("first", SyntaxShape::Int, "first number to generate")
             .required("last", SyntaxShape::Int, "last number to generate")
             .input_output_type(Type::Nothing, Type::List(Type::Int.into()))
             .plugin_examples(vec![PluginExample {
-                example: "stream_example seq 1 3".into(),
+                example: "example seq 1 3".into(),
                 description: "generate a sequence from 1 to 3".into(),
                 result: Some(Value::test_list(vec![
                     Value::test_int(1),
@@ -32,7 +32,7 @@ impl PluginCommand for Seq {
 
     fn run(
         &self,
-        _plugin: &StreamExample,
+        _plugin: &Example,
         _engine: &EngineInterface,
         call: &EvaluatedCall,
         _input: PipelineData,

crates/nu_plugin_example/src/commands/sum.rs

@@ -1,16 +1,16 @@
 use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, PluginCommand};
 use nu_protocol::{Category, PipelineData, PluginExample, PluginSignature, Span, Type, Value};
 
-use crate::StreamExample;
+use crate::Example;
 
-/// `<list> | stream_example sum`
+/// `<list> | example sum`
 pub struct Sum;
 
 impl PluginCommand for Sum {
-    type Plugin = StreamExample;
+    type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
-        PluginSignature::build("stream_example sum")
+        PluginSignature::build("example sum")
             .usage("Example stream consumer for a list of values")
             .search_terms(vec!["example".into()])
             .input_output_types(vec![
@@ -18,7 +18,7 @@ impl PluginCommand for Sum {
                 (Type::List(Type::Float.into()), Type::Float),
             ])
             .plugin_examples(vec![PluginExample {
-                example: "seq 1 5 | stream_example sum".into(),
+                example: "seq 1 5 | example sum".into(),
                 description: "sum values from 1 to 5".into(),
                 result: Some(Value::test_int(15)),
             }])
@@ -27,7 +27,7 @@ impl PluginCommand for Sum {
 
     fn run(
         &self,
-        _plugin: &StreamExample,
+        _plugin: &Example,
         _engine: &EngineInterface,
         call: &EvaluatedCall,
         input: PipelineData,

crates/nu_plugin_example/src/commands/three.rs

@@ -3,15 +3,15 @@ use nu_protocol::{Category, PluginSignature, SyntaxShape, Value};
 
 use crate::Example;
 
-pub struct NuExample3;
+pub struct Three;
 
-impl SimplePluginCommand for NuExample3 {
+impl SimplePluginCommand for Three {
     type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
         // The signature defines the usage of the command inside Nu, and also automatically
         // generates its help page.
-        PluginSignature::build("nu-example-3")
+        PluginSignature::build("example three")
             .usage("PluginSignature test 3 for plugin. Returns labeled error")
             .required("a", SyntaxShape::Int, "required integer value")
             .required("b", SyntaxShape::String, "required string value")

crates/nu_plugin_example/src/commands/two.rs

@@ -3,15 +3,15 @@ use nu_protocol::{record, Category, PluginSignature, SyntaxShape, Value};
 
 use crate::Example;
 
-pub struct NuExample2;
+pub struct Two;
 
-impl SimplePluginCommand for NuExample2 {
+impl SimplePluginCommand for Two {
     type Plugin = Example;
 
     fn signature(&self) -> PluginSignature {
         // The signature defines the usage of the command inside Nu, and also automatically
         // generates its help page.
-        PluginSignature::build("nu-example-2")
+        PluginSignature::build("example two")
             .usage("PluginSignature test 2 for plugin. Returns list of records")
             .required("a", SyntaxShape::Int, "required integer value")
             .required("b", SyntaxShape::String, "required string value")

crates/nu_plugin_example/src/lib.rs

@@ -13,12 +13,21 @@ impl Plugin for Example {
         //
         // If it doesn't appear on this list, it won't be added.
         vec![
-            Box::new(NuExample1),
-            Box::new(NuExample2),
-            Box::new(NuExample3),
-            Box::new(NuExampleConfig),
-            Box::new(NuExampleEnv),
-            Box::new(NuExampleDisableGc),
+            Box::new(Main),
+            // Basic demos
+            Box::new(One),
+            Box::new(Two),
+            Box::new(Three),
+            // Engine interface demos
+            Box::new(Config),
+            Box::new(Env),
+            Box::new(DisableGc),
+            // Stream demos
+            Box::new(CollectExternal),
+            Box::new(ForEach),
+            Box::new(Generate),
+            Box::new(Seq),
+            Box::new(Sum),
         ]
     }
 }

crates/nu_plugin_stream_example/Cargo.toml

@@ -1,19 +0,0 @@
-[package]
-authors = ["The Nushell Project Developers"]
-description = "An example of stream handling in nushell plugins"
-repository = "https://github.com/nushell/nushell/tree/main/crates/nu_plugin_stream_example"
-edition = "2021"
-license = "MIT"
-name = "nu_plugin_stream_example"
-version = "0.91.1"
-
-[[bin]]
-name = "nu_plugin_stream_example"
-bench = false
-
-[lib]
-bench = false
-
-[dependencies]
-nu-plugin = { path = "../nu-plugin", version = "0.91.1" }
-nu-protocol = { path = "../nu-protocol", version = "0.91.1", features = ["plugin"] }

crates/nu_plugin_stream_example/README.md

@@ -1,62 +0,0 @@
-# Streaming Plugin Example
-
-Crate with a simple example of a plugin with commands that produce streams
-
-## `stream_example seq`
-
-This command demonstrates generating list streams. It generates numbers from the first argument
-to the second argument just like the builtin `seq` command does.
-
-Examples:
-
-> ```nushell
-> stream_example seq 1 10
-> ```
-
-    [1 2 3 4 5 6 7 8 9 10]
-
-> ```nushell
-> stream_example seq 1 10 | describe
-> ```
-
-    list<int> (stream)
-
-## `stream_example sum`
-
-This command demonstrates consuming list streams. It consumes a stream of numbers and calculates the
-sum just like the builtin `math sum` command does.
-
-Examples:
-
-> ```nushell
-> seq 1 5 | stream_example sum
-> ```
-
-    15
-
-## `stream_example collect-external`
-
-This command demonstrates transforming streams into external streams. The list (or stream) of
-strings on input will be concatenated into an external stream (raw input) on stdout.
-
-> ```nushell
-> [Hello "\n" world how are you] | stream_example collect-external
-> ````
-
-    Hello
-    worldhowareyou
-
-## `stream_example for-each`
-
-This command demonstrates executing closures on values in streams. Each value received on the input
-will be printed to the plugin's stderr. This works even with external commands.
-
-> ```nushell
-> ls | get name | stream_example for-each { |f| ^file $f }
-> ```
-
-    CODE_OF_CONDUCT.md: ASCII text
-
-    CONTRIBUTING.md: ASCII text, with very long lines (303)
-
-    ...

crates/nu_plugin_stream_example/src/commands/mod.rs

@@ -1,11 +0,0 @@
-mod collect_external;
-mod for_each;
-mod generate;
-mod seq;
-mod sum;
-
-pub use collect_external::CollectExternal;
-pub use for_each::ForEach;
-pub use generate::Generate;
-pub use seq::Seq;
-pub use sum::Sum;

crates/nu_plugin_stream_example/src/lib.rs

@@ -1,50 +0,0 @@
-use nu_plugin::{
-    EngineInterface, EvaluatedCall, LabeledError, Plugin, PluginCommand, SimplePluginCommand,
-};
-use nu_protocol::{Category, PluginSignature, Value};
-
-mod commands;
-pub use commands::*;
-
-pub struct StreamExample;
-
-impl Plugin for StreamExample {
-    fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin = Self>>> {
-        vec![
-            Box::new(Main),
-            Box::new(Seq),
-            Box::new(Sum),
-            Box::new(CollectExternal),
-            Box::new(ForEach),
-            Box::new(Generate),
-        ]
-    }
-}
-
-/// `stream_example`
-pub struct Main;
-
-impl SimplePluginCommand for Main {
-    type Plugin = StreamExample;
-
-    fn signature(&self) -> PluginSignature {
-        PluginSignature::build("stream_example")
-            .usage("Examples for streaming plugins")
-            .search_terms(vec!["example".into()])
-            .category(Category::Experimental)
-    }
-
-    fn run(
-        &self,
-        _plugin: &StreamExample,
-        _engine: &EngineInterface,
-        call: &EvaluatedCall,
-        _input: &Value,
-    ) -> Result<Value, LabeledError> {
-        Err(LabeledError {
-            label: "No subcommand provided".into(),
-            msg: "add --help here to see usage".into(),
-            span: Some(call.head.past()),
-        })
-    }
-}

crates/nu_plugin_stream_example/src/main.rs

@@ -1,30 +0,0 @@
-use nu_plugin::{serve_plugin, MsgPackSerializer};
-use nu_plugin_stream_example::StreamExample;
-
-fn main() {
-    // When defining your plugin, you can select the Serializer that could be
-    // used to encode and decode the messages. The available options are
-    // MsgPackSerializer and JsonSerializer. Both are defined in the serializer
-    // folder in nu-plugin.
-    serve_plugin(&StreamExample {}, MsgPackSerializer {})
-
-    // Note
-    // When creating plugins in other languages one needs to consider how a plugin
-    // is added and used in nushell.
-    // The steps are:
-    // - The plugin is register. In this stage nushell calls the binary file of
-    //      the plugin sending information using the encoded PluginCall::PluginSignature object.
-    //      Use this encoded data in your plugin to design the logic that will return
-    //      the encoded signatures.
-    //      Nushell is expecting and encoded PluginResponse::PluginSignature with all the
-    //      plugin signatures
-    // - When calling the plugin, nushell sends to the binary file the encoded
-    //      PluginCall::CallInfo which has all the call information, such as the
-    //      values of the arguments, the name of the signature called and the input
-    //      from the pipeline.
-    //      Use this data to design your plugin login and to create the value that
-    //      will be sent to nushell
-    //      Nushell expects an encoded PluginResponse::Value from the plugin
-    // - If an error needs to be sent back to nushell, one can encode PluginResponse::Error.
-    //      This is a labeled error that nushell can format for pretty printing
-}