Trait nu_plugin::SimplePluginCommand

pub trait SimplePluginCommand: 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: &Value
    ) -> Result<Value, LabeledError>;

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

The API for a simple Nushell plugin command

This trait is an alternative to PluginCommand, and operates on values instead of streams. Note that this may make handling large lists more difficult.

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.

Examples

Basic usage:

struct HelloPlugin;
struct 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 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: &Value ) -> Result<Value, 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 does not support streaming. Consider implementing PluginCommand directly if streaming is desired.

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