Trait nu_plugin::StreamingPlugin

pub trait StreamingPlugin {
    // Required methods
    fn signature(&self) -> Vec<PluginSignature>;
    fn run(
        &mut self,
        name: &str,
        config: &Option<Value>,
        call: &EvaluatedCall,
        input: PipelineData
    ) -> Result<PipelineData, LabeledError>;
}

The streaming API for a Nushell plugin

This is a more low-level version of the Plugin trait that supports operating on streams of data. If you don’t need to operate on streams, consider using that trait instead.

The methods defined on StreamingPlugin are invoked by serve_plugin during plugin registration and execution.

Examples

Basic usage:

struct LowercasePlugin;

impl StreamingPlugin for LowercasePlugin {
    fn signature(&self) -> Vec<PluginSignature> {
        let sig = 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()));

        vec![sig]
    }

    fn run(
        &mut self,
        name: &str,
        config: &Option<Value>,
        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)?)
    }
}

Required Methods

fn signature(&self) -> Vec<PluginSignature>

The signature of the plugin

This method returns the PluginSignatures that describe the capabilities of this plugin. Since a single plugin executable can support multiple invocation patterns we return a Vec of signatures.

fn run( &mut self, name: &str, config: &Option<Value>, call: &EvaluatedCall, input: PipelineData ) -> Result<PipelineData, LabeledError>

Perform the actual behavior of the plugin

The behavior of the plugin is defined by the implementation of this method. When Nushell invoked the plugin serve_plugin will call this method and print the serialized returned value or error to stdout, which Nushell will interpret.

The name is only relevant for plugins that implement multiple commands as the invoked command will be passed in via this argument. The call contains metadata describing how the plugin was invoked and input contains the structured data passed to the command implemented by this Plugin.

This variant expects to receive and produce PipelineData, which allows for stream-based handling of I/O. This is recommended if the plugin is expected to transform large lists or potentially large quantities of bytes. The API is more complex however, and Plugin is recommended instead if this is not a concern.

Implementors

impl<T: Plugin> StreamingPlugin for T

All Plugins can be used as StreamingPlugins, but input streams will be fully consumed before the plugin runs.