Reorganize plugin API around commands (#12170)

[Context on
Discord](https://discord.com/channels/601130461678272522/855947301380947968/1216517833312309419)

# Description
This is a significant breaking change to the plugin API, but one I think
is worthwhile. @ayax79 mentioned on Discord that while trying to start
on a dataframes plugin, he was a little disappointed that more wasn't
provided in terms of code organization for commands, particularly since
there are *a lot* of `dfr` commands.

This change treats plugins more like miniatures of the engine, with
dispatch of the command name being handled inherently, each command
being its own type, and each having their own signature within the trait
impl for the command type rather than having to find a way to centralize
it all into one `Vec`.

For the example plugins that have multiple commands, I definitely like
how this looks a lot better. This encourages doing code organization the
right way and feels very good.

For the plugins that have only one command, it's just a little bit more
boilerplate - but still worth it, in my opinion.

The `Box<dyn PluginCommand<Plugin = Self>>` type in `commands()` is a
little bit hairy, particularly for Rust beginners, but ultimately not so
bad, and it gives the desired flexibility for shared state for a whole
plugin + the individual commands.

# User-Facing Changes
Pretty big breaking change to plugin API, but probably one that's worth
making.

```rust
use nu_plugin::*;
use nu_protocol::{PluginSignature, PipelineData, Type, Value};

struct LowercasePlugin;
struct Lowercase;

// Plugins can now have multiple commands
impl PluginCommand for Lowercase {
    type Plugin = LowercasePlugin;

    // The signature lives with the command
    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()))
    }

    // We also provide SimplePluginCommand which operates on Value like before
    fn run(
        &self,
        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)?)
    }
}

// Plugin now just has a list of commands, and the custom value op stuff still goes here
impl Plugin for LowercasePlugin {
    fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin=Self>>> {
        vec![Box::new(Lowercase)]
    }
}

fn main() {
    serve_plugin(&LowercasePlugin{}, MsgPackSerializer)
}
```

Time this however you like - we're already breaking stuff for 0.92, so
it might be good to do it now, but if it feels like a lot all at once,
it could wait.

# Tests + Formatting
- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`

# After Submitting
- [ ] Update examples in the book
- [x] Fix #12088 to match - this change would actually simplify it a
lot, because the methods are currently just duplicated between `Plugin`
and `StreamingPlugin`, but they only need to be on `Plugin` with this
change

crates/nu_plugin_formats/src/from/eml.rs

@@ -1,18 +1,48 @@
 use eml_parser::eml::*;
 use eml_parser::EmlParser;
 use indexmap::map::IndexMap;
-use nu_plugin::{EvaluatedCall, LabeledError};
-use nu_protocol::{record, PluginExample, ShellError, Span, Value};
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{
+    record, Category, PluginExample, PluginSignature, ShellError, Span, SyntaxShape, Type, Value,
+};
+
+use crate::FromCmds;
 
 const DEFAULT_BODY_PREVIEW: usize = 50;
 pub const CMD_NAME: &str = "from eml";
 
-pub fn from_eml_call(call: &EvaluatedCall, input: &Value) -> Result<Value, LabeledError> {
-    let preview_body: usize = call
-        .get_flag::<i64>("preview-body")?
-        .map(|l| if l < 0 { 0 } else { l as usize })
-        .unwrap_or(DEFAULT_BODY_PREVIEW);
-    from_eml(input, preview_body, call.head)
+pub struct FromEml;
+
+impl SimplePluginCommand for FromEml {
+    type Plugin = FromCmds;
+
+    fn signature(&self) -> nu_protocol::PluginSignature {
+        PluginSignature::build(CMD_NAME)
+            .input_output_types(vec![(Type::String, Type::Record(vec![]))])
+            .named(
+                "preview-body",
+                SyntaxShape::Int,
+                "How many bytes of the body to preview",
+                Some('b'),
+            )
+            .usage("Parse text as .eml and create record.")
+            .plugin_examples(examples())
+            .category(Category::Formats)
+    }
+
+    fn run(
+        &self,
+        _plugin: &FromCmds,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: &Value,
+    ) -> Result<Value, LabeledError> {
+        let preview_body: usize = call
+            .get_flag::<i64>("preview-body")?
+            .map(|l| if l < 0 { 0 } else { l as usize })
+            .unwrap_or(DEFAULT_BODY_PREVIEW);
+        from_eml(input, preview_body, call.head)
+    }
 }
 
 pub fn examples() -> Vec<PluginExample> {

crates/nu_plugin_formats/src/from/ics.rs

@@ -1,52 +1,76 @@
 use ical::parser::ical::component::*;
 use ical::property::Property;
 use indexmap::map::IndexMap;
-use nu_plugin::{EvaluatedCall, LabeledError};
-use nu_protocol::{record, PluginExample, ShellError, Span, Value};
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{
+    record, Category, PluginExample, PluginSignature, ShellError, Span, Type, Value,
+};
 use std::io::BufReader;
 
+use crate::FromCmds;
+
 pub const CMD_NAME: &str = "from ics";
 
-pub fn from_ics_call(call: &EvaluatedCall, input: &Value) -> Result<Value, LabeledError> {
-    let span = input.span();
-    let input_string = input.coerce_str()?;
-    let head = call.head;
+pub struct FromIcs;
 
-    let input_string = input_string
-        .lines()
-        .enumerate()
-        .map(|(i, x)| {
-            if i == 0 {
-                x.trim().to_string()
-            } else if x.len() > 1 && (x.starts_with(' ') || x.starts_with('\t')) {
-                x[1..].trim_end().to_string()
-            } else {
-                format!("\n{}", x.trim())
-            }
-        })
-        .collect::<String>();
+impl SimplePluginCommand for FromIcs {
+    type Plugin = FromCmds;
 
-    let input_bytes = input_string.as_bytes();
-    let buf_reader = BufReader::new(input_bytes);
-    let parser = ical::IcalParser::new(buf_reader);
-
-    let mut output = vec![];
-
-    for calendar in parser {
-        match calendar {
-            Ok(c) => output.push(calendar_to_value(c, head)),
-            Err(e) => output.push(Value::error(
-                ShellError::UnsupportedInput {
-                    msg: format!("input cannot be parsed as .ics ({e})"),
-                    input: "value originates from here".into(),
-                    msg_span: head,
-                    input_span: span,
-                },
-                span,
-            )),
-        }
+    fn signature(&self) -> nu_protocol::PluginSignature {
+        PluginSignature::build(CMD_NAME)
+            .input_output_types(vec![(Type::String, Type::Table(vec![]))])
+            .usage("Parse text as .ics and create table.")
+            .plugin_examples(examples())
+            .category(Category::Formats)
+    }
+
+    fn run(
+        &self,
+        _plugin: &FromCmds,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: &Value,
+    ) -> Result<Value, LabeledError> {
+        let span = input.span();
+        let input_string = input.coerce_str()?;
+        let head = call.head;
+
+        let input_string = input_string
+            .lines()
+            .enumerate()
+            .map(|(i, x)| {
+                if i == 0 {
+                    x.trim().to_string()
+                } else if x.len() > 1 && (x.starts_with(' ') || x.starts_with('\t')) {
+                    x[1..].trim_end().to_string()
+                } else {
+                    format!("\n{}", x.trim())
+                }
+            })
+            .collect::<String>();
+
+        let input_bytes = input_string.as_bytes();
+        let buf_reader = BufReader::new(input_bytes);
+        let parser = ical::IcalParser::new(buf_reader);
+
+        let mut output = vec![];
+
+        for calendar in parser {
+            match calendar {
+                Ok(c) => output.push(calendar_to_value(c, head)),
+                Err(e) => output.push(Value::error(
+                    ShellError::UnsupportedInput {
+                        msg: format!("input cannot be parsed as .ics ({e})"),
+                        input: "value originates from here".into(),
+                        msg_span: head,
+                        input_span: span,
+                    },
+                    span,
+                )),
+            }
+        }
+        Ok(Value::list(output, head))
     }
-    Ok(Value::list(output, head))
 }
 
 pub fn examples() -> Vec<PluginExample> {

crates/nu_plugin_formats/src/from/ini.rs

@@ -1,52 +1,76 @@
-use nu_plugin::{EvaluatedCall, LabeledError};
-use nu_protocol::{record, PluginExample, Record, ShellError, Value};
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{
+    record, Category, PluginExample, PluginSignature, Record, ShellError, Type, Value,
+};
+
+use crate::FromCmds;
 
 pub const CMD_NAME: &str = "from ini";
 
-pub fn from_ini_call(call: &EvaluatedCall, input: &Value) -> Result<Value, LabeledError> {
-    let span = input.span();
-    let input_string = input.coerce_str()?;
-    let head = call.head;
+pub struct FromIni;
 
-    let ini_config: Result<ini::Ini, ini::ParseError> = ini::Ini::load_from_str(&input_string);
-    match ini_config {
-        Ok(config) => {
-            let mut sections = Record::new();
+impl SimplePluginCommand for FromIni {
+    type Plugin = FromCmds;
 
-            for (section, properties) in config.iter() {
-                let mut section_record = Record::new();
+    fn signature(&self) -> PluginSignature {
+        PluginSignature::build(CMD_NAME)
+            .input_output_types(vec![(Type::String, Type::Record(vec![]))])
+            .usage("Parse text as .ini and create table.")
+            .plugin_examples(examples())
+            .category(Category::Formats)
+    }
 
-                // section's key value pairs
-                for (key, value) in properties.iter() {
-                    section_record.push(key, Value::string(value, span));
-                }
+    fn run(
+        &self,
+        _plugin: &FromCmds,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: &Value,
+    ) -> Result<Value, LabeledError> {
+        let span = input.span();
+        let input_string = input.coerce_str()?;
+        let head = call.head;
 
-                let section_record = Value::record(section_record, span);
+        let ini_config: Result<ini::Ini, ini::ParseError> = ini::Ini::load_from_str(&input_string);
+        match ini_config {
+            Ok(config) => {
+                let mut sections = Record::new();
 
-                // section
-                match section {
-                    Some(section_name) => {
-                        sections.push(section_name, section_record);
+                for (section, properties) in config.iter() {
+                    let mut section_record = Record::new();
+
+                    // section's key value pairs
+                    for (key, value) in properties.iter() {
+                        section_record.push(key, Value::string(value, span));
                     }
-                    None => {
-                        // Section (None) allows for key value pairs without a section
-                        if !properties.is_empty() {
-                            sections.push(String::new(), section_record);
+
+                    let section_record = Value::record(section_record, span);
+
+                    // section
+                    match section {
+                        Some(section_name) => {
+                            sections.push(section_name, section_record);
+                        }
+                        None => {
+                            // Section (None) allows for key value pairs without a section
+                            if !properties.is_empty() {
+                                sections.push(String::new(), section_record);
+                            }
                         }
                     }
                 }
-            }
 
-            // all sections with all its key value pairs
-            Ok(Value::record(sections, span))
+                // all sections with all its key value pairs
+                Ok(Value::record(sections, span))
+            }
+            Err(err) => Err(ShellError::UnsupportedInput {
+                msg: format!("Could not load ini: {err}"),
+                input: "value originates from here".into(),
+                msg_span: head,
+                input_span: span,
+            }
+            .into()),
         }
-        Err(err) => Err(ShellError::UnsupportedInput {
-            msg: format!("Could not load ini: {err}"),
-            input: "value originates from here".into(),
-            msg_span: head,
-            input_span: span,
-        }
-        .into()),
     }
 }
 

crates/nu_plugin_formats/src/from/vcf.rs

@@ -1,49 +1,73 @@
 use ical::parser::vcard::component::*;
 use ical::property::Property;
 use indexmap::map::IndexMap;
-use nu_plugin::{EvaluatedCall, LabeledError};
-use nu_protocol::{record, PluginExample, ShellError, Span, Value};
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{
+    record, Category, PluginExample, PluginSignature, ShellError, Span, Type, Value,
+};
+
+use crate::FromCmds;
 
 pub const CMD_NAME: &str = "from vcf";
 
-pub fn from_vcf_call(call: &EvaluatedCall, input: &Value) -> Result<Value, LabeledError> {
-    let span = input.span();
-    let input_string = input.coerce_str()?;
-    let head = call.head;
+pub struct FromVcf;
 
-    let input_string = input_string
-        .lines()
-        .enumerate()
-        .map(|(i, x)| {
-            if i == 0 {
-                x.trim().to_string()
-            } else if x.len() > 1 && (x.starts_with(' ') || x.starts_with('\t')) {
-                x[1..].trim_end().to_string()
-            } else {
-                format!("\n{}", x.trim())
-            }
-        })
-        .collect::<String>();
+impl SimplePluginCommand for FromVcf {
+    type Plugin = FromCmds;
 
-    let input_bytes = input_string.as_bytes();
-    let cursor = std::io::Cursor::new(input_bytes);
-    let parser = ical::VcardParser::new(cursor);
+    fn signature(&self) -> PluginSignature {
+        PluginSignature::build(CMD_NAME)
+            .input_output_types(vec![(Type::String, Type::Table(vec![]))])
+            .usage("Parse text as .vcf and create table.")
+            .plugin_examples(examples())
+            .category(Category::Formats)
+    }
 
-    let iter = parser.map(move |contact| match contact {
-        Ok(c) => contact_to_value(c, head),
-        Err(e) => Value::error(
-            ShellError::UnsupportedInput {
-                msg: format!("input cannot be parsed as .vcf ({e})"),
-                input: "value originates from here".into(),
-                msg_span: head,
-                input_span: span,
-            },
-            span,
-        ),
-    });
+    fn run(
+        &self,
+        _plugin: &FromCmds,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: &Value,
+    ) -> Result<Value, LabeledError> {
+        let span = input.span();
+        let input_string = input.coerce_str()?;
+        let head = call.head;
 
-    let collected: Vec<_> = iter.collect();
-    Ok(Value::list(collected, head))
+        let input_string = input_string
+            .lines()
+            .enumerate()
+            .map(|(i, x)| {
+                if i == 0 {
+                    x.trim().to_string()
+                } else if x.len() > 1 && (x.starts_with(' ') || x.starts_with('\t')) {
+                    x[1..].trim_end().to_string()
+                } else {
+                    format!("\n{}", x.trim())
+                }
+            })
+            .collect::<String>();
+
+        let input_bytes = input_string.as_bytes();
+        let cursor = std::io::Cursor::new(input_bytes);
+        let parser = ical::VcardParser::new(cursor);
+
+        let iter = parser.map(move |contact| match contact {
+            Ok(c) => contact_to_value(c, head),
+            Err(e) => Value::error(
+                ShellError::UnsupportedInput {
+                    msg: format!("input cannot be parsed as .vcf ({e})"),
+                    input: "value originates from here".into(),
+                    msg_span: head,
+                    input_span: span,
+                },
+                span,
+            ),
+        });
+
+        let collected: Vec<_> = iter.collect();
+        Ok(Value::list(collected, head))
+    }
 }
 
 pub fn examples() -> Vec<PluginExample> {

crates/nu_plugin_formats/src/lib.rs

@@ -1,60 +1,21 @@
 mod from;
 
-use from::{eml, ics, ini, vcf};
-use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, Plugin};
-use nu_protocol::{Category, PluginSignature, SyntaxShape, Type, Value};
+use nu_plugin::{Plugin, PluginCommand};
+
+pub use from::eml::FromEml;
+pub use from::ics::FromIcs;
+pub use from::ini::FromIni;
+pub use from::vcf::FromVcf;
 
 pub struct FromCmds;
 
 impl Plugin for FromCmds {
-    fn signature(&self) -> Vec<PluginSignature> {
+    fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin = Self>>> {
         vec![
-            PluginSignature::build(eml::CMD_NAME)
-                .input_output_types(vec![(Type::String, Type::Record(vec![]))])
-                .named(
-                    "preview-body",
-                    SyntaxShape::Int,
-                    "How many bytes of the body to preview",
-                    Some('b'),
-                )
-                .usage("Parse text as .eml and create record.")
-                .plugin_examples(eml::examples())
-                .category(Category::Formats),
-            PluginSignature::build(ics::CMD_NAME)
-                .input_output_types(vec![(Type::String, Type::Table(vec![]))])
-                .usage("Parse text as .ics and create table.")
-                .plugin_examples(ics::examples())
-                .category(Category::Formats),
-            PluginSignature::build(vcf::CMD_NAME)
-                .input_output_types(vec![(Type::String, Type::Table(vec![]))])
-                .usage("Parse text as .vcf and create table.")
-                .plugin_examples(vcf::examples())
-                .category(Category::Formats),
-            PluginSignature::build(ini::CMD_NAME)
-                .input_output_types(vec![(Type::String, Type::Record(vec![]))])
-                .usage("Parse text as .ini and create table.")
-                .plugin_examples(ini::examples())
-                .category(Category::Formats),
+            Box::new(FromEml),
+            Box::new(FromIcs),
+            Box::new(FromIni),
+            Box::new(FromVcf),
         ]
     }
-
-    fn run(
-        &self,
-        name: &str,
-        _engine: &EngineInterface,
-        call: &EvaluatedCall,
-        input: &Value,
-    ) -> Result<Value, LabeledError> {
-        match name {
-            eml::CMD_NAME => eml::from_eml_call(call, input),
-            ics::CMD_NAME => ics::from_ics_call(call, input),
-            vcf::CMD_NAME => vcf::from_vcf_call(call, input),
-            ini::CMD_NAME => ini::from_ini_call(call, input),
-            _ => Err(LabeledError {
-                label: "Plugin call with wrong name signature".into(),
-                msg: "the signature used to call the plugin does not match any name in the plugin signature vector".into(),
-                span: Some(call.head),
-            }),
-        }
-    }
 }