mirror of
https://github.com/nushell/nushell.git
synced 2025-06-30 14:40:06 +02:00
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
This commit is contained in:
@ -1,14 +1,19 @@
|
||||
use nu_protocol::{record, CustomValue, ShellError, Span, Value};
|
||||
use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
|
||||
use nu_protocol::{
|
||||
record, Category, CustomValue, PluginSignature, ShellError, Span, SyntaxShape, Value,
|
||||
};
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::CustomValuePlugin;
|
||||
|
||||
#[derive(Clone, Debug, Serialize, Deserialize)]
|
||||
pub struct DropCheck {
|
||||
pub struct DropCheckValue {
|
||||
pub(crate) msg: String,
|
||||
}
|
||||
|
||||
impl DropCheck {
|
||||
pub(crate) fn new(msg: String) -> DropCheck {
|
||||
DropCheck { msg }
|
||||
impl DropCheckValue {
|
||||
pub(crate) fn new(msg: String) -> DropCheckValue {
|
||||
DropCheckValue { msg }
|
||||
}
|
||||
|
||||
pub(crate) fn into_value(self, span: Span) -> Value {
|
||||
@ -16,18 +21,18 @@ impl DropCheck {
|
||||
}
|
||||
|
||||
pub(crate) fn notify(&self) {
|
||||
eprintln!("DropCheck was dropped: {}", self.msg);
|
||||
eprintln!("DropCheckValue was dropped: {}", self.msg);
|
||||
}
|
||||
}
|
||||
|
||||
#[typetag::serde]
|
||||
impl CustomValue for DropCheck {
|
||||
impl CustomValue for DropCheckValue {
|
||||
fn clone_value(&self, span: Span) -> Value {
|
||||
self.clone().into_value(span)
|
||||
}
|
||||
|
||||
fn value_string(&self) -> String {
|
||||
"DropCheck".into()
|
||||
"DropCheckValue".into()
|
||||
}
|
||||
|
||||
fn to_base_value(&self, span: Span) -> Result<Value, ShellError> {
|
||||
@ -48,3 +53,26 @@ impl CustomValue for DropCheck {
|
||||
true
|
||||
}
|
||||
}
|
||||
|
||||
pub struct DropCheck;
|
||||
|
||||
impl SimplePluginCommand for DropCheck {
|
||||
type Plugin = CustomValuePlugin;
|
||||
|
||||
fn signature(&self) -> nu_protocol::PluginSignature {
|
||||
PluginSignature::build("custom-value drop-check")
|
||||
.usage("Generates a custom value that prints a message when dropped")
|
||||
.required("msg", SyntaxShape::String, "the message to print on drop")
|
||||
.category(Category::Experimental)
|
||||
}
|
||||
|
||||
fn run(
|
||||
&self,
|
||||
_plugin: &Self::Plugin,
|
||||
_engine: &EngineInterface,
|
||||
call: &EvaluatedCall,
|
||||
_input: &Value,
|
||||
) -> Result<Value, LabeledError> {
|
||||
Ok(DropCheckValue::new(call.req(0)?).into_value(call.head))
|
||||
}
|
||||
}
|
||||
|
26
crates/nu_plugin_custom_values/src/generate.rs
Normal file
26
crates/nu_plugin_custom_values/src/generate.rs
Normal file
@ -0,0 +1,26 @@
|
||||
use crate::{cool_custom_value::CoolCustomValue, CustomValuePlugin};
|
||||
|
||||
use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
|
||||
use nu_protocol::{Category, PluginSignature, Value};
|
||||
|
||||
pub struct Generate;
|
||||
|
||||
impl SimplePluginCommand for Generate {
|
||||
type Plugin = CustomValuePlugin;
|
||||
|
||||
fn signature(&self) -> PluginSignature {
|
||||
PluginSignature::build("custom-value generate")
|
||||
.usage("PluginSignature for a plugin that generates a custom value")
|
||||
.category(Category::Experimental)
|
||||
}
|
||||
|
||||
fn run(
|
||||
&self,
|
||||
_plugin: &CustomValuePlugin,
|
||||
_engine: &EngineInterface,
|
||||
call: &EvaluatedCall,
|
||||
_input: &Value,
|
||||
) -> Result<Value, LabeledError> {
|
||||
Ok(CoolCustomValue::new("abc").into_value(call.head))
|
||||
}
|
||||
}
|
42
crates/nu_plugin_custom_values/src/generate2.rs
Normal file
42
crates/nu_plugin_custom_values/src/generate2.rs
Normal file
@ -0,0 +1,42 @@
|
||||
use crate::{second_custom_value::SecondCustomValue, CustomValuePlugin};
|
||||
|
||||
use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
|
||||
use nu_protocol::{Category, PluginSignature, SyntaxShape, Value};
|
||||
|
||||
pub struct Generate2;
|
||||
|
||||
impl SimplePluginCommand for Generate2 {
|
||||
type Plugin = CustomValuePlugin;
|
||||
|
||||
fn signature(&self) -> PluginSignature {
|
||||
PluginSignature::build("custom-value generate2")
|
||||
.usage("PluginSignature for a plugin that generates a different custom value")
|
||||
.optional(
|
||||
"closure",
|
||||
SyntaxShape::Closure(Some(vec![SyntaxShape::Any])),
|
||||
"An optional closure to pass the custom value to",
|
||||
)
|
||||
.category(Category::Experimental)
|
||||
}
|
||||
|
||||
fn run(
|
||||
&self,
|
||||
_plugin: &CustomValuePlugin,
|
||||
engine: &EngineInterface,
|
||||
call: &EvaluatedCall,
|
||||
_input: &Value,
|
||||
) -> Result<Value, LabeledError> {
|
||||
let second_custom_value = SecondCustomValue::new("xyz").into_value(call.head);
|
||||
// If we were passed a closure, execute that instead
|
||||
if let Some(closure) = call.opt(0)? {
|
||||
let result = engine.eval_closure(
|
||||
&closure,
|
||||
vec![second_custom_value.clone()],
|
||||
Some(second_custom_value),
|
||||
)?;
|
||||
Ok(result)
|
||||
} else {
|
||||
Ok(second_custom_value)
|
||||
}
|
||||
}
|
||||
}
|
@ -1,132 +1,49 @@
|
||||
use nu_plugin::{
|
||||
serve_plugin, EngineInterface, LabeledError, MsgPackSerializer, Plugin, PluginCommand,
|
||||
};
|
||||
|
||||
mod cool_custom_value;
|
||||
mod drop_check;
|
||||
mod second_custom_value;
|
||||
|
||||
use cool_custom_value::CoolCustomValue;
|
||||
use drop_check::DropCheck;
|
||||
use second_custom_value::SecondCustomValue;
|
||||
mod drop_check;
|
||||
mod generate;
|
||||
mod generate2;
|
||||
mod update;
|
||||
mod update_arg;
|
||||
|
||||
use nu_plugin::{serve_plugin, EngineInterface, MsgPackSerializer, Plugin};
|
||||
use nu_plugin::{EvaluatedCall, LabeledError};
|
||||
use nu_protocol::{Category, CustomValue, PluginSignature, ShellError, SyntaxShape, Value};
|
||||
use drop_check::{DropCheck, DropCheckValue};
|
||||
use generate::Generate;
|
||||
use generate2::Generate2;
|
||||
use nu_protocol::CustomValue;
|
||||
use update::Update;
|
||||
use update_arg::UpdateArg;
|
||||
|
||||
struct CustomValuePlugin;
|
||||
pub struct CustomValuePlugin;
|
||||
|
||||
impl Plugin for CustomValuePlugin {
|
||||
fn signature(&self) -> Vec<nu_protocol::PluginSignature> {
|
||||
fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin = Self>>> {
|
||||
vec![
|
||||
PluginSignature::build("custom-value generate")
|
||||
.usage("PluginSignature for a plugin that generates a custom value")
|
||||
.category(Category::Experimental),
|
||||
PluginSignature::build("custom-value generate2")
|
||||
.usage("PluginSignature for a plugin that generates a different custom value")
|
||||
.optional(
|
||||
"closure",
|
||||
SyntaxShape::Closure(Some(vec![SyntaxShape::Any])),
|
||||
"An optional closure to pass the custom value to",
|
||||
)
|
||||
.category(Category::Experimental),
|
||||
PluginSignature::build("custom-value update")
|
||||
.usage("PluginSignature for a plugin that updates a custom value")
|
||||
.category(Category::Experimental),
|
||||
PluginSignature::build("custom-value update-arg")
|
||||
.usage("PluginSignature for a plugin that updates a custom value as an argument")
|
||||
.required(
|
||||
"custom_value",
|
||||
SyntaxShape::Any,
|
||||
"the custom value to update",
|
||||
)
|
||||
.category(Category::Experimental),
|
||||
PluginSignature::build("custom-value drop-check")
|
||||
.usage("Generates a custom value that prints a message when dropped")
|
||||
.required("msg", SyntaxShape::String, "the message to print on drop")
|
||||
.category(Category::Experimental),
|
||||
Box::new(Generate),
|
||||
Box::new(Generate2),
|
||||
Box::new(Update),
|
||||
Box::new(UpdateArg),
|
||||
Box::new(DropCheck),
|
||||
]
|
||||
}
|
||||
|
||||
fn run(
|
||||
&self,
|
||||
name: &str,
|
||||
engine: &EngineInterface,
|
||||
call: &EvaluatedCall,
|
||||
input: &Value,
|
||||
) -> Result<Value, LabeledError> {
|
||||
match name {
|
||||
"custom-value generate" => self.generate(call, input),
|
||||
"custom-value generate2" => self.generate2(engine, call),
|
||||
"custom-value update" => self.update(call, input),
|
||||
"custom-value update-arg" => self.update(call, &call.req(0)?),
|
||||
"custom-value drop-check" => self.drop_check(call),
|
||||
_ => 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),
|
||||
}),
|
||||
}
|
||||
}
|
||||
|
||||
fn custom_value_dropped(
|
||||
&self,
|
||||
_engine: &EngineInterface,
|
||||
custom_value: Box<dyn CustomValue>,
|
||||
) -> Result<(), LabeledError> {
|
||||
// This is how we implement our drop behavior for DropCheck.
|
||||
if let Some(drop_check) = custom_value.as_any().downcast_ref::<DropCheck>() {
|
||||
if let Some(drop_check) = custom_value.as_any().downcast_ref::<DropCheckValue>() {
|
||||
drop_check.notify();
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
impl CustomValuePlugin {
|
||||
fn generate(&self, call: &EvaluatedCall, _input: &Value) -> Result<Value, LabeledError> {
|
||||
Ok(CoolCustomValue::new("abc").into_value(call.head))
|
||||
}
|
||||
|
||||
fn generate2(
|
||||
&self,
|
||||
engine: &EngineInterface,
|
||||
call: &EvaluatedCall,
|
||||
) -> Result<Value, LabeledError> {
|
||||
let second_custom_value = SecondCustomValue::new("xyz").into_value(call.head);
|
||||
// If we were passed a closure, execute that instead
|
||||
if let Some(closure) = call.opt(0)? {
|
||||
let result = engine.eval_closure(
|
||||
&closure,
|
||||
vec![second_custom_value.clone()],
|
||||
Some(second_custom_value),
|
||||
)?;
|
||||
Ok(result)
|
||||
} else {
|
||||
Ok(second_custom_value)
|
||||
}
|
||||
}
|
||||
|
||||
fn update(&self, call: &EvaluatedCall, input: &Value) -> Result<Value, LabeledError> {
|
||||
if let Ok(mut value) = CoolCustomValue::try_from_value(input) {
|
||||
value.cool += "xyz";
|
||||
return Ok(value.into_value(call.head));
|
||||
}
|
||||
|
||||
if let Ok(mut value) = SecondCustomValue::try_from_value(input) {
|
||||
value.something += "abc";
|
||||
return Ok(value.into_value(call.head));
|
||||
}
|
||||
|
||||
Err(ShellError::CantConvert {
|
||||
to_type: "cool or second".into(),
|
||||
from_type: "non-cool and non-second".into(),
|
||||
span: call.head,
|
||||
help: None,
|
||||
}
|
||||
.into())
|
||||
}
|
||||
|
||||
fn drop_check(&self, call: &EvaluatedCall) -> Result<Value, LabeledError> {
|
||||
Ok(DropCheck::new(call.req(0)?).into_value(call.head))
|
||||
}
|
||||
}
|
||||
|
||||
fn main() {
|
||||
serve_plugin(&CustomValuePlugin, MsgPackSerializer {})
|
||||
}
|
||||
|
44
crates/nu_plugin_custom_values/src/update.rs
Normal file
44
crates/nu_plugin_custom_values/src/update.rs
Normal file
@ -0,0 +1,44 @@
|
||||
use crate::{
|
||||
cool_custom_value::CoolCustomValue, second_custom_value::SecondCustomValue, CustomValuePlugin,
|
||||
};
|
||||
|
||||
use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
|
||||
use nu_protocol::{Category, PluginSignature, ShellError, Value};
|
||||
|
||||
pub struct Update;
|
||||
|
||||
impl SimplePluginCommand for Update {
|
||||
type Plugin = CustomValuePlugin;
|
||||
|
||||
fn signature(&self) -> PluginSignature {
|
||||
PluginSignature::build("custom-value update")
|
||||
.usage("PluginSignature for a plugin that updates a custom value")
|
||||
.category(Category::Experimental)
|
||||
}
|
||||
|
||||
fn run(
|
||||
&self,
|
||||
_plugin: &CustomValuePlugin,
|
||||
_engine: &EngineInterface,
|
||||
call: &EvaluatedCall,
|
||||
input: &Value,
|
||||
) -> Result<Value, LabeledError> {
|
||||
if let Ok(mut value) = CoolCustomValue::try_from_value(input) {
|
||||
value.cool += "xyz";
|
||||
return Ok(value.into_value(call.head));
|
||||
}
|
||||
|
||||
if let Ok(mut value) = SecondCustomValue::try_from_value(input) {
|
||||
value.something += "abc";
|
||||
return Ok(value.into_value(call.head));
|
||||
}
|
||||
|
||||
Err(ShellError::CantConvert {
|
||||
to_type: "cool or second".into(),
|
||||
from_type: "non-cool and non-second".into(),
|
||||
span: call.head,
|
||||
help: None,
|
||||
}
|
||||
.into())
|
||||
}
|
||||
}
|
31
crates/nu_plugin_custom_values/src/update_arg.rs
Normal file
31
crates/nu_plugin_custom_values/src/update_arg.rs
Normal file
@ -0,0 +1,31 @@
|
||||
use crate::{update::Update, CustomValuePlugin};
|
||||
|
||||
use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
|
||||
use nu_protocol::{Category, PluginSignature, SyntaxShape, Value};
|
||||
|
||||
pub struct UpdateArg;
|
||||
|
||||
impl SimplePluginCommand for UpdateArg {
|
||||
type Plugin = CustomValuePlugin;
|
||||
|
||||
fn signature(&self) -> PluginSignature {
|
||||
PluginSignature::build("custom-value update-arg")
|
||||
.usage("PluginSignature for a plugin that updates a custom value as an argument")
|
||||
.required(
|
||||
"custom_value",
|
||||
SyntaxShape::Any,
|
||||
"the custom value to update",
|
||||
)
|
||||
.category(Category::Experimental)
|
||||
}
|
||||
|
||||
fn run(
|
||||
&self,
|
||||
plugin: &CustomValuePlugin,
|
||||
engine: &EngineInterface,
|
||||
call: &EvaluatedCall,
|
||||
_input: &Value,
|
||||
) -> Result<Value, LabeledError> {
|
||||
SimplePluginCommand::run(&Update, plugin, engine, call, &call.req(0)?)
|
||||
}
|
||||
}
|
Reference in New Issue
Block a user