Trait nu_plugin::PluginCommand

pub trait PluginCommand: Sync {
    type Plugin: Plugin;

    // Required methods
    fn name(&self) -> &str;
    fn signature(&self) -> Signature;
    fn usage(&self) -> &str;
    fn run(
        &self,
        plugin: &Self::Plugin,
        engine: &EngineInterface,
        call: &EvaluatedCall,
        input: PipelineData
    ) -> Result<PipelineData, LabeledError>;

    // Provided methods
    fn extra_usage(&self) -> &str { ... }
    fn search_terms(&self) -> Vec<&str> { ... }
    fn examples(&self) -> Vec<Example<'_>> { ... }
}

The API for a Nushell plugin command

This is the trait that Nushell plugin commands must implement. The methods defined on PluginCommand are invoked by serve_plugin during plugin registration and execution.

The plugin command 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.

This version of the trait expects stream input and output. If you have a simple plugin that just operates on plain values, consider using SimplePluginCommand instead.

Examples

Basic usage:

struct LowercasePlugin;
struct Lowercase;

impl PluginCommand for Lowercase {
    type Plugin = LowercasePlugin;

    fn name(&self) -> &str {
        "lowercase"
    }

    fn usage(&self) -> &str {
        "Convert each string in a stream to lowercase"
    }

    fn signature(&self) -> Signature {
        Signature::build(PluginCommand::name(self))
            .input_output_type(Type::List(Type::String.into()), Type::List(Type::String.into()))
    }

    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)?)
    }
}

Required Associated Types

type Plugin: Plugin

The type of plugin this command runs on.

Since [.run()] takes a reference to the plugin, it is necessary to define the type of plugin that the command expects here.

Required Methods

fn name(&self) -> &str

The name of the command from within Nu.

In case this contains spaces, it will be treated as a subcommand.

fn signature(&self) -> Signature

The signature of the command.

This defines the arguments and input/output types of the command.

fn usage(&self) -> &str

A brief description of usage for the command.

This should be short enough to fit in completion menus.

fn run( &self, plugin: &Self::Plugin, engine: &EngineInterface, call: &EvaluatedCall, input: PipelineData ) -> Result<PipelineData, LabeledError>

Perform the actual behavior of the plugin command.

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.

engine provides an interface back to the Nushell engine. See EngineInterface docs for details on what methods are available.

The call contains metadata describing how the plugin command was invoked, including arguments, and input contains the structured data piped into the command.

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 SimplePluginCommand is recommended instead if this is not a concern.

Provided Methods

fn extra_usage(&self) -> &str

Additional documentation for usage of the command.

This is optional - any arguments documented by [.signature()] will be shown in the help page automatically. However, this can be useful for explaining things that would be too brief to include in [.usage()] and may span multiple lines.

fn search_terms(&self) -> Vec<&str>

Search terms to help users find the command.

A search query matching any of these search keywords, e.g. on help --find, will also show this command as a result. This may be used to suggest this command as a replacement for common system commands, or based alternate names for the functionality this command provides.

For example, a fold command might mention reduce in its search terms.

fn examples(&self) -> Vec<Example<'_>>

Examples, in Nu, of how the command might be used.

The examples are not restricted to only including this command, and may demonstrate pipelines using the command. A result may optionally be provided to show users what the command would return.

PluginTest::test_command_examples() from the nu-plugin-test-support crate can be used in plugin tests to automatically test that examples produce the results as specified.

Implementors

impl<T> PluginCommand for T

where T: SimplePluginCommand,

All SimplePluginCommands can be used as PluginCommands, but input streams will be fully consumed before the plugin command runs.

type Plugin = <T as SimplePluginCommand>::Plugin