Change PluginCommand API to be more like Command (#12279)

# Description

This is something that was discussed in the core team meeting last
Wednesday. @ayax79 is building `nu-plugin-polars` with all of the
dataframe commands into a plugin, and there are a lot of them, so it
would help to make the API more similar. At the same time, I think the
`Command` API is just better anyway. I don't think the difference is
justified, and the types for core commands have the benefit of requiring
less `.into()` because they often don't own their data

- Broke `signature()` up into `name()`, `usage()`, `extra_usage()`,
`search_terms()`, `examples()`
- `signature()` returns `nu_protocol::Signature`
- `examples()` returns `Vec<nu_protocol::Example>`
- `PluginSignature` and `PluginExample` no longer need to be used by
plugin developers

# User-Facing Changes
Breaking API for plugins yet again 😄

crates/nu-plugin-test-support/src/fake_register.rs

@@ -1,6 +1,6 @@
-use std::sync::Arc;
+use std::{ops::Deref, sync::Arc};
 
-use nu_plugin::{Plugin, PluginDeclaration};
+use nu_plugin::{create_plugin_signature, Plugin, PluginDeclaration};
 use nu_protocol::{engine::StateWorkingSet, RegisteredPlugin, ShellError};
 
 use crate::{fake_persistent_plugin::FakePersistentPlugin, spawn_fake_plugin::spawn_fake_plugin};
@@ -15,7 +15,7 @@ pub fn fake_register(
     let reg_plugin_clone = reg_plugin.clone();
 
     for command in plugin.commands() {
-        let signature = command.signature();
+        let signature = create_plugin_signature(command.deref());
         let decl = PluginDeclaration::new(reg_plugin.clone(), signature);
         working_set.add_decl(Box::new(decl));
     }

crates/nu-plugin-test-support/src/lib.rs

@@ -7,8 +7,10 @@
 //!
 //! use nu_plugin::*;
 //! use nu_plugin_test_support::PluginTest;
-//! use nu_protocol::{PluginSignature, PipelineData, Type, Span, Value, LabeledError};
-//! use nu_protocol::IntoInterruptiblePipelineData;
+//! use nu_protocol::{
+//!     Example, IntoInterruptiblePipelineData, LabeledError, PipelineData, ShellError, Signature,
+//!     Span, Type, Value,
+//! };
 //!
 //! struct LowercasePlugin;
 //! struct Lowercase;
@@ -16,26 +18,50 @@
 //! impl PluginCommand for Lowercase {
 //!     type Plugin = LowercasePlugin;
 //!
-//!     fn signature(&self) -> PluginSignature {
-//!         PluginSignature::build("lowercase")
-//!             .usage("Convert each string in a stream to lowercase")
-//!             .input_output_type(Type::List(Type::String.into()), Type::List(Type::String.into()))
+//!     fn name(&self) -> &str {
+//!         "lowercase"
+//!     }
+//!
+//!     fn usage(&self) -> &str {
+//!         "Convert each string in a stream to lowercase"
+//!     }
+//!
+//!     fn signature(&self) -> Signature {
+//!         Signature::build(self.name()).input_output_type(
+//!             Type::List(Type::String.into()),
+//!             Type::List(Type::String.into()),
+//!         )
+//!     }
+//!
+//!     fn examples(&self) -> Vec<Example> {
+//!         vec![Example {
+//!             example: r#"[Hello wORLD] | lowercase"#,
+//!             description: "Lowercase a list of strings",
+//!             result: Some(Value::test_list(vec![
+//!                 Value::test_string("hello"),
+//!                 Value::test_string("world"),
+//!             ])),
+//!         }]
 //!     }
 //!
 //!     fn run(
 //!         &self,
-//!         plugin: &LowercasePlugin,
-//!         engine: &EngineInterface,
+//!         _plugin: &LowercasePlugin,
+//!         _engine: &EngineInterface,
 //!         call: &EvaluatedCall,
 //!         input: PipelineData,
 //!     ) -> Result<PipelineData, LabeledError> {
 //!         let span = call.head;
-//!         Ok(input.map(move |value| {
-//!             value.as_str()
-//!                 .map(|string| Value::string(string.to_lowercase(), span))
-//!                 // Errors in a stream should be returned as values.
-//!                 .unwrap_or_else(|err| Value::error(err, span))
-//!         }, None)?)
+//!         Ok(input.map(
+//!             move |value| {
+//!                 value
+//!                     .as_str()
+//!                     .map(|string| Value::string(string.to_lowercase(), span))
+//!                     // Errors in a stream should be returned as values.
+//!                     .unwrap_or_else(|err| Value::error(err, span))
+//!             },
+//!             None,
+//!         )?)
 //!     }
 //! }
 //!
@@ -45,7 +71,14 @@
 //!     }
 //! }
 //!
-//! fn test_lowercase() -> Result<(), LabeledError> {
+//! // #[test]
+//! fn test_examples() -> Result<(), ShellError> {
+//!     PluginTest::new("lowercase", LowercasePlugin.into())?
+//!         .test_command_examples(&Lowercase)
+//! }
+//!
+//! // #[test]
+//! fn test_lowercase() -> Result<(), ShellError> {
 //!     let input = vec![Value::test_string("FooBar")].into_pipeline_data(None);
 //!     let output = PluginTest::new("lowercase", LowercasePlugin.into())?
 //!         .eval_with("lowercase", input)?
@@ -60,6 +93,7 @@
 //!     Ok(())
 //! }
 //! #
+//! # test_examples().unwrap();
 //! # test_lowercase().unwrap();
 //! ```
 

crates/nu-plugin-test-support/src/plugin_test.rs

@@ -7,7 +7,7 @@ use nu_plugin::{Plugin, PluginCommand, PluginCustomValue, PluginSource};
 use nu_protocol::{
     debugger::WithoutDebug,
     engine::{EngineState, Stack, StateWorkingSet},
-    report_error_new, LabeledError, PipelineData, PluginExample, ShellError, Span, Value,
+    report_error_new, Example, LabeledError, PipelineData, ShellError, Span, Value,
 };
 
 use crate::{diff::diff_by_line, fake_register::fake_register};
@@ -186,20 +186,20 @@ impl PluginTest {
     ///
     /// ```rust,no_run
     /// # use nu_plugin_test_support::PluginTest;
-    /// # use nu_protocol::{ShellError, PluginExample, Value};
+    /// # use nu_protocol::{ShellError, Example, Value};
     /// # use nu_plugin::*;
     /// # fn test(MyPlugin: impl Plugin + Send + 'static) -> Result<(), ShellError> {
     /// PluginTest::new("my_plugin", MyPlugin.into())?
     ///     .test_examples(&[
-    ///         PluginExample {
-    ///             example: "my-command".into(),
-    ///             description: "Run my-command".into(),
+    ///         Example {
+    ///             example: "my-command",
+    ///             description: "Run my-command",
     ///             result: Some(Value::test_string("my-command output")),
     ///         },
     ///     ])
     /// # }
     /// ```
-    pub fn test_examples(&mut self, examples: &[PluginExample]) -> Result<(), ShellError> {
+    pub fn test_examples(&mut self, examples: &[Example]) -> Result<(), ShellError> {
         let mut failed = false;
 
         for example in examples {
@@ -210,7 +210,7 @@ impl PluginTest {
                 eprintln!("{} {}", bold.paint("Description:"), example.description);
             };
             if let Some(expectation) = &example.result {
-                match self.eval(&example.example) {
+                match self.eval(example.example) {
                     Ok(data) => {
                         let mut value = data.into_value(Span::test_data());
 
@@ -270,6 +270,6 @@ impl PluginTest {
         &mut self,
         command: &impl PluginCommand,
     ) -> Result<(), ShellError> {
-        self.test_examples(&command.signature().examples)
+        self.test_examples(&command.examples())
     }
 }