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_query/src/lib.rs

@@ -1,4 +1,3 @@
-mod nu;
 mod query;
 mod query_json;
 mod query_web;
@@ -6,7 +5,7 @@ mod query_xml;
 mod web_tables;
 
 pub use query::Query;
-pub use query_json::execute_json_query;
-pub use query_web::parse_selector_params;
-pub use query_xml::execute_xpath_query;
+pub use query_json::{execute_json_query, QueryJson};
+pub use query_web::{parse_selector_params, QueryWeb};
+pub use query_xml::{execute_xpath_query, QueryXml};
 pub use web_tables::WebTable;

crates/nu_plugin_query/src/nu/mod.rs

@@ -1,95 +0,0 @@
-use crate::Query;
-use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, Plugin};
-use nu_protocol::{Category, PluginExample, PluginSignature, Spanned, SyntaxShape, Value};
-
-impl Plugin for Query {
-    fn signature(&self) -> Vec<PluginSignature> {
-        vec![
-            PluginSignature::build("query")
-            .usage("Show all the query commands")
-            .category(Category::Filters),
-
-            PluginSignature::build("query json")
-            .usage("execute json query on json file (open --raw <file> | query json 'query string')")
-            .required("query", SyntaxShape::String, "json query")
-            .category(Category::Filters),
-
-            PluginSignature::build("query xml")
-            .usage("execute xpath query on xml")
-            .required("query", SyntaxShape::String, "xpath query")
-            .category(Category::Filters),
-
-            PluginSignature::build("query web")
-            .usage("execute selector query on html/web")
-            .named("query", SyntaxShape::String, "selector query", Some('q'))
-            .switch("as-html", "return the query output as html", Some('m'))
-            .plugin_examples(web_examples())
-            .named(
-                "attribute",
-                SyntaxShape::String,
-                "downselect based on the given attribute",
-                Some('a'),
-            )
-            .named(
-                "as-table",
-                SyntaxShape::List(Box::new(SyntaxShape::String)),
-                "find table based on column header list",
-                Some('t'),
-            )
-            .switch(
-                "inspect",
-                "run in inspect mode to provide more information for determining column headers",
-                Some('i'),
-            )
-            .category(Category::Network),
-            ]
-    }
-
-    fn run(
-        &self,
-        name: &str,
-        _engine: &EngineInterface,
-        call: &EvaluatedCall,
-        input: &Value,
-    ) -> Result<Value, LabeledError> {
-        // You can use the name to identify what plugin signature was called
-        let path: Option<Spanned<String>> = call.opt(0)?;
-
-        match name {
-            "query" => {
-                self.query(name, call, input, path)
-            }
-            "query json" => self.query_json( name, call, input, path),
-            "query web" => self.query_web(name, call, input, path),
-            "query xml" => self.query_xml(name, call, input, path),
-            _ => 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),
-            }),
-        }
-    }
-}
-
-pub fn web_examples() -> Vec<PluginExample> {
-    vec![PluginExample {
-        example: "http get https://phoronix.com | query web --query 'header' | flatten".into(),
-        description: "Retrieve all `<header>` elements from phoronix.com website".into(),
-        result: None,
-    }, PluginExample {
-        example: "http get https://en.wikipedia.org/wiki/List_of_cities_in_India_by_population |
-    query web --as-table [City 'Population(2011)[3]' 'Population(2001)[3][a]' 'State or unionterritory' 'Ref']".into(),
-        description: "Retrieve a html table from Wikipedia and parse it into a nushell table using table headers as guides".into(),
-        result: None
-    },
-    PluginExample {
-        example: "http get https://www.nushell.sh | query web --query 'h2, h2 + p' | each {str join} | group 2 | each {rotate --ccw tagline description} | flatten".into(),
-        description: "Pass multiple css selectors to extract several elements within single query, group the query results together and rotate them to create a table".into(),
-        result: None,
-    },
-    PluginExample {
-        example: "http get https://example.org | query web --query a --attribute href".into(),
-        description: "Retrieve a specific html attribute instead of the default text".into(),
-        result: None,
-    }]
-}

crates/nu_plugin_query/src/query.rs

@@ -1,9 +1,10 @@
-use crate::query_json::execute_json_query;
-use crate::query_web::parse_selector_params;
-use crate::query_xml::execute_xpath_query;
+use crate::query_json::QueryJson;
+use crate::query_web::QueryWeb;
+use crate::query_xml::QueryXml;
+
 use nu_engine::documentation::get_flags_section;
-use nu_plugin::{EvaluatedCall, LabeledError, Plugin};
-use nu_protocol::{PluginSignature, Spanned, Value};
+use nu_plugin::{EvaluatedCall, LabeledError, Plugin, PluginCommand, SimplePluginCommand};
+use nu_protocol::{Category, PluginSignature, Value};
 use std::fmt::Write;
 
 #[derive(Default)]
@@ -17,48 +18,50 @@ impl Query {
     pub fn usage() -> &'static str {
         "Usage: query"
     }
+}
 
-    pub fn query(
-        &self,
-        _name: &str,
-        call: &EvaluatedCall,
-        _value: &Value,
-        _path: Option<Spanned<String>>,
-    ) -> Result<Value, LabeledError> {
-        let help = get_brief_subcommand_help(&Query.signature());
-        Ok(Value::string(help, call.head))
-    }
-
-    pub fn query_json(
-        &self,
-        name: &str,
-        call: &EvaluatedCall,
-        input: &Value,
-        query: Option<Spanned<String>>,
-    ) -> Result<Value, LabeledError> {
-        execute_json_query(name, call, input, query)
-    }
-    pub fn query_web(
-        &self,
-        _name: &str,
-        call: &EvaluatedCall,
-        input: &Value,
-        _rest: Option<Spanned<String>>,
-    ) -> Result<Value, LabeledError> {
-        parse_selector_params(call, input)
-    }
-    pub fn query_xml(
-        &self,
-        name: &str,
-        call: &EvaluatedCall,
-        input: &Value,
-        query: Option<Spanned<String>>,
-    ) -> Result<Value, LabeledError> {
-        execute_xpath_query(name, call, input, query)
+impl Plugin for Query {
+    fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin = Self>>> {
+        vec![
+            Box::new(QueryCommand),
+            Box::new(QueryJson),
+            Box::new(QueryXml),
+            Box::new(QueryWeb),
+        ]
     }
 }
 
-pub fn get_brief_subcommand_help(sigs: &[PluginSignature]) -> String {
+// With no subcommand
+pub struct QueryCommand;
+
+impl SimplePluginCommand for QueryCommand {
+    type Plugin = Query;
+
+    fn signature(&self) -> PluginSignature {
+        PluginSignature::build("query")
+            .usage("Show all the query commands")
+            .category(Category::Filters)
+    }
+
+    fn run(
+        &self,
+        _plugin: &Query,
+        _engine: &nu_plugin::EngineInterface,
+        call: &EvaluatedCall,
+        _input: &Value,
+    ) -> Result<Value, LabeledError> {
+        let help = get_brief_subcommand_help();
+        Ok(Value::string(help, call.head))
+    }
+}
+
+pub fn get_brief_subcommand_help() -> String {
+    let sigs: Vec<_> = Query
+        .commands()
+        .into_iter()
+        .map(|cmd| cmd.signature())
+        .collect();
+
     let mut help = String::new();
     let _ = write!(help, "{}\n\n", sigs[0].sig.usage);
     let _ = write!(help, "Usage:\n  > {}\n\n", sigs[0].sig.name);

crates/nu_plugin_query/src/query_json.rs

@@ -1,9 +1,37 @@
 use gjson::Value as gjValue;
-use nu_plugin::{EvaluatedCall, LabeledError};
-use nu_protocol::{Record, Span, Spanned, Value};
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{Category, PluginSignature, Record, Span, Spanned, SyntaxShape, Value};
+
+use crate::Query;
+
+pub struct QueryJson;
+
+impl SimplePluginCommand for QueryJson {
+    type Plugin = Query;
+
+    fn signature(&self) -> PluginSignature {
+        PluginSignature::build("query json")
+            .usage(
+                "execute json query on json file (open --raw <file> | query json 'query string')",
+            )
+            .required("query", SyntaxShape::String, "json query")
+            .category(Category::Filters)
+    }
+
+    fn run(
+        &self,
+        _plugin: &Query,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: &Value,
+    ) -> Result<Value, LabeledError> {
+        let query: Option<Spanned<String>> = call.opt(0)?;
+
+        execute_json_query(call, input, query)
+    }
+}
 
 pub fn execute_json_query(
-    _name: &str,
     call: &EvaluatedCall,
     input: &Value,
     query: Option<Spanned<String>>,

crates/nu_plugin_query/src/query_web.rs

@@ -1,8 +1,76 @@
-use crate::web_tables::WebTable;
-use nu_plugin::{EvaluatedCall, LabeledError};
-use nu_protocol::{Record, Span, Value};
+use crate::{web_tables::WebTable, Query};
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{Category, PluginExample, PluginSignature, Record, Span, SyntaxShape, Value};
 use scraper::{Html, Selector as ScraperSelector};
 
+pub struct QueryWeb;
+
+impl SimplePluginCommand for QueryWeb {
+    type Plugin = Query;
+
+    fn signature(&self) -> PluginSignature {
+        PluginSignature::build("query web")
+            .usage("execute selector query on html/web")
+            .named("query", SyntaxShape::String, "selector query", Some('q'))
+            .switch("as-html", "return the query output as html", Some('m'))
+            .plugin_examples(web_examples())
+            .named(
+                "attribute",
+                SyntaxShape::String,
+                "downselect based on the given attribute",
+                Some('a'),
+            )
+            .named(
+                "as-table",
+                SyntaxShape::List(Box::new(SyntaxShape::String)),
+                "find table based on column header list",
+                Some('t'),
+            )
+            .switch(
+                "inspect",
+                "run in inspect mode to provide more information for determining column headers",
+                Some('i'),
+            )
+            .category(Category::Network)
+    }
+
+    fn run(
+        &self,
+        _plugin: &Query,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: &Value,
+    ) -> Result<Value, LabeledError> {
+        parse_selector_params(call, input)
+    }
+}
+
+pub fn web_examples() -> Vec<PluginExample> {
+    vec![
+        PluginExample {
+            example: "http get https://phoronix.com | query web --query 'header' | flatten".into(),
+            description: "Retrieve all `<header>` elements from phoronix.com website".into(),
+            result: None,
+        },
+        PluginExample {
+            example: "http get https://en.wikipedia.org/wiki/List_of_cities_in_India_by_population |
+        query web --as-table [City 'Population(2011)[3]' 'Population(2001)[3][a]' 'State or unionterritory' 'Ref']".into(),
+            description: "Retrieve a html table from Wikipedia and parse it into a nushell table using table headers as guides".into(),
+            result: None
+        },
+        PluginExample {
+            example: "http get https://www.nushell.sh | query web --query 'h2, h2 + p' | each {str join} | group 2 | each {rotate --ccw tagline description} | flatten".into(),
+            description: "Pass multiple css selectors to extract several elements within single query, group the query results together and rotate them to create a table".into(),
+            result: None,
+        },
+        PluginExample {
+            example: "http get https://example.org | query web --query a --attribute href".into(),
+            description: "Retrieve a specific html attribute instead of the default text".into(),
+            result: None,
+        }
+    ]
+}
+
 pub struct Selector {
     pub query: String,
     pub as_html: bool,

crates/nu_plugin_query/src/query_xml.rs

@@ -1,10 +1,36 @@
-use nu_plugin::{EvaluatedCall, LabeledError};
-use nu_protocol::{record, Record, Span, Spanned, Value};
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{record, Category, PluginSignature, Record, Span, Spanned, SyntaxShape, Value};
 use sxd_document::parser;
 use sxd_xpath::{Context, Factory};
 
+use crate::Query;
+
+pub struct QueryXml;
+
+impl SimplePluginCommand for QueryXml {
+    type Plugin = Query;
+
+    fn signature(&self) -> PluginSignature {
+        PluginSignature::build("query xml")
+            .usage("execute xpath query on xml")
+            .required("query", SyntaxShape::String, "xpath query")
+            .category(Category::Filters)
+    }
+
+    fn run(
+        &self,
+        _plugin: &Query,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: &Value,
+    ) -> Result<Value, LabeledError> {
+        let query: Option<Spanned<String>> = call.opt(0)?;
+
+        execute_xpath_query(call, input, query)
+    }
+}
+
 pub fn execute_xpath_query(
-    _name: &str,
     call: &EvaluatedCall,
     input: &Value,
     query: Option<Spanned<String>>,
@@ -131,7 +157,7 @@ mod tests {
             span: Span::test_data(),
         };
 
-        let actual = query("", &call, &text, Some(spanned_str)).expect("test should not fail");
+        let actual = query(&call, &text, Some(spanned_str)).expect("test should not fail");
         let expected = Value::list(
             vec![Value::test_record(record! {
                 "count(//a/*[posit..." => Value::test_float(1.0),
@@ -160,7 +186,7 @@ mod tests {
             span: Span::test_data(),
         };
 
-        let actual = query("", &call, &text, Some(spanned_str)).expect("test should not fail");
+        let actual = query(&call, &text, Some(spanned_str)).expect("test should not fail");
         let expected = Value::list(
             vec![Value::test_record(record! {
                 "count(//*[contain..." => Value::test_float(1.0),