pub trait Plugin: Sync {
// Required method
fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin = Self>>>;
// Provided methods
fn custom_value_to_base_value(
&self,
engine: &EngineInterface,
custom_value: Spanned<Box<dyn CustomValue>>
) -> Result<Value, LabeledError> { ... }
fn custom_value_follow_path_int(
&self,
engine: &EngineInterface,
custom_value: Spanned<Box<dyn CustomValue>>,
index: Spanned<usize>
) -> Result<Value, LabeledError> { ... }
fn custom_value_follow_path_string(
&self,
engine: &EngineInterface,
custom_value: Spanned<Box<dyn CustomValue>>,
column_name: Spanned<String>
) -> Result<Value, LabeledError> { ... }
fn custom_value_partial_cmp(
&self,
engine: &EngineInterface,
custom_value: Box<dyn CustomValue>,
other_value: Value
) -> Result<Option<Ordering>, LabeledError> { ... }
fn custom_value_operation(
&self,
engine: &EngineInterface,
left: Spanned<Box<dyn CustomValue>>,
operator: Spanned<Operator>,
right: Value
) -> Result<Value, LabeledError> { ... }
fn custom_value_dropped(
&self,
engine: &EngineInterface,
custom_value: Box<dyn CustomValue>
) -> Result<(), LabeledError> { ... }
}
Expand description
The API for a Nushell plugin
A plugin defines multiple commands, which are added to the engine when the user calls
register
.
The plugin must be able to be safely shared between threads, so that multiple invocations can be run in parallel. If interior mutability is desired, consider synchronization primitives such as mutexes and channels.
§Examples
Basic usage:
struct HelloPlugin;
struct Hello;
impl Plugin for HelloPlugin {
fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin=Self>>> {
vec![Box::new(Hello)]
}
}
impl SimplePluginCommand for Hello {
type Plugin = HelloPlugin;
fn name(&self) -> &str {
"hello"
}
fn usage(&self) -> &str {
"Every programmer's favorite greeting"
}
fn signature(&self) -> Signature {
Signature::build(PluginCommand::name(self))
.input_output_type(Type::Nothing, Type::String)
}
fn run(
&self,
plugin: &HelloPlugin,
engine: &EngineInterface,
call: &EvaluatedCall,
input: &Value,
) -> Result<Value, LabeledError> {
Ok(Value::string("Hello, World!".to_owned(), call.head))
}
}
Required Methods§
sourcefn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin = Self>>>
fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin = Self>>>
The commands supported by the plugin
Each PluginCommand
contains both the signature of the command and the functionality it
implements.
This is only called once by serve_plugin
at the beginning of your plugin’s execution. It
is not possible to change the defined commands during runtime.
Provided Methods§
sourcefn custom_value_to_base_value(
&self,
engine: &EngineInterface,
custom_value: Spanned<Box<dyn CustomValue>>
) -> Result<Value, LabeledError>
fn custom_value_to_base_value( &self, engine: &EngineInterface, custom_value: Spanned<Box<dyn CustomValue>> ) -> Result<Value, LabeledError>
Collapse a custom value to plain old data.
The default implementation of this method just calls CustomValue::to_base_value
, but
the method can be implemented differently if accessing plugin state is desirable.
sourcefn custom_value_follow_path_int(
&self,
engine: &EngineInterface,
custom_value: Spanned<Box<dyn CustomValue>>,
index: Spanned<usize>
) -> Result<Value, LabeledError>
fn custom_value_follow_path_int( &self, engine: &EngineInterface, custom_value: Spanned<Box<dyn CustomValue>>, index: Spanned<usize> ) -> Result<Value, LabeledError>
Follow a numbered cell path on a custom value - e.g. value.0
.
The default implementation of this method just calls CustomValue::follow_path_int
, but
the method can be implemented differently if accessing plugin state is desirable.
sourcefn custom_value_follow_path_string(
&self,
engine: &EngineInterface,
custom_value: Spanned<Box<dyn CustomValue>>,
column_name: Spanned<String>
) -> Result<Value, LabeledError>
fn custom_value_follow_path_string( &self, engine: &EngineInterface, custom_value: Spanned<Box<dyn CustomValue>>, column_name: Spanned<String> ) -> Result<Value, LabeledError>
Follow a named cell path on a custom value - e.g. value.column
.
The default implementation of this method just calls CustomValue::follow_path_string
,
but the method can be implemented differently if accessing plugin state is desirable.
sourcefn custom_value_partial_cmp(
&self,
engine: &EngineInterface,
custom_value: Box<dyn CustomValue>,
other_value: Value
) -> Result<Option<Ordering>, LabeledError>
fn custom_value_partial_cmp( &self, engine: &EngineInterface, custom_value: Box<dyn CustomValue>, other_value: Value ) -> Result<Option<Ordering>, LabeledError>
Implement comparison logic for custom values.
The default implementation of this method just calls CustomValue::partial_cmp
, but
the method can be implemented differently if accessing plugin state is desirable.
Note that returning an error here is unlikely to produce desired behavior, as partial_cmp
lacks a way to produce an error. At the moment the engine just logs the error, and the
comparison returns None
.
sourcefn custom_value_operation(
&self,
engine: &EngineInterface,
left: Spanned<Box<dyn CustomValue>>,
operator: Spanned<Operator>,
right: Value
) -> Result<Value, LabeledError>
fn custom_value_operation( &self, engine: &EngineInterface, left: Spanned<Box<dyn CustomValue>>, operator: Spanned<Operator>, right: Value ) -> Result<Value, LabeledError>
Implement functionality for an operator on a custom value.
The default implementation of this method just calls CustomValue::operation
, but
the method can be implemented differently if accessing plugin state is desirable.
sourcefn custom_value_dropped(
&self,
engine: &EngineInterface,
custom_value: Box<dyn CustomValue>
) -> Result<(), LabeledError>
fn custom_value_dropped( &self, engine: &EngineInterface, custom_value: Box<dyn CustomValue> ) -> Result<(), LabeledError>
Handle a notification that all copies of a custom value within the engine have been dropped.
This notification is only sent if CustomValue::notify_plugin_on_drop
was true. Unlike
the other custom value handlers, a span is not provided.
Note that a new custom value is created each time it is sent to the engine - if you intend to accept a custom value and send it back, you may need to implement some kind of unique reference counting in your plugin, as you will receive multiple drop notifications even if the data within is identical.
The default implementation does nothing. Any error generated here is unlikely to be visible to the user, and will only show up in the engine’s log output.