Trait nu_plugin::Plugin

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> { ... }
}

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

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

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.

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.

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.

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.

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.

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.

Object Safety

This trait is not object safe.

Implementors