2
0
Fork 0
mirror of https://github.com/nushell/nushell synced 2025-02-15 21:48:29 +00:00
nushell/crates/nu-protocol/src
Devyn Cairns 9cf2e873b5
Reorganize plugin API around commands ()
[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  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
2024-03-14 16:40:02 -05:00
..
ast IO and redirection overhaul () 2024-03-14 15:51:55 -05:00
config Keep plugins persistently running in the background () 2024-03-09 17:10:22 -06:00
debugger IO and redirection overhaul () 2024-03-14 15:51:55 -05:00
engine IO and redirection overhaul () 2024-03-14 15:51:55 -05:00
errors IO and redirection overhaul () 2024-03-14 15:51:55 -05:00
pipeline_data IO and redirection overhaul () 2024-03-14 15:51:55 -05:00
plugin Keep plugins persistently running in the background () 2024-03-09 17:10:22 -06:00
value Reorganize plugin API around commands () 2024-03-14 16:40:02 -05:00
alias.rs IO and redirection overhaul () 2024-03-14 15:51:55 -05:00
did_you_mean.rs Improve case insensitivity consistency () 2023-11-08 23:58:54 +01:00
eval_base.rs IO and redirection overhaul () 2024-03-14 15:51:55 -05:00
eval_const.rs IO and redirection overhaul () 2024-03-14 15:51:55 -05:00
example.rs Fix ignored clippy lints () 2024-03-11 19:46:04 +01:00
id.rs Add virtual path abstraction layer () 2023-05-23 23:48:50 +03:00
lev_distance.rs Suggest existing variables on not found () 2023-05-02 18:17:14 +03:00
lib.rs Restructure nu-protocol in more meaningful units () 2024-03-10 18:45:45 +01:00
module.rs Error on use path item1 item2, if item1 is not a module () 2023-12-05 11:38:45 +01:00
signature.rs Replace debug_assert! with assert! in Signature::check_names () 2024-02-22 16:17:06 -06:00
span.rs Replace panics with errors in thread spawning () 2024-03-02 11:14:02 -06:00
syntax_shape.rs open, rm, umv, cp, rm and du: Don't globs if inputs are variables or string interpolation () 2024-02-23 09:17:09 +08:00
ty.rs Glob: don't allow implicit casting between glob and string () 2024-02-28 23:05:35 +08:00
util.rs Convert more ShellError variants to named fields () 2023-11-28 06:43:51 -06:00