Crate nu_plugin

Nu Plugin: Plugin library for Nushell

This crate contains the interface necessary to build Nushell plugins in Rust. Additionally, it contains public, but undocumented, items used by Nushell itself to interface with Nushell plugins. This documentation focuses on the interface needed to write an independent plugin.

Nushell plugins are stand-alone applications that communicate with Nushell over stdin and stdout using a standardizes serialization framework to exchange the typed data that Nushell commands utilize natively.

A typical plugin application will define a struct that implements the Plugin trait and then, in its main method, pass that Plugin to the serve_plugin() function, which will handle all of the input and output serialization when invoked by Nushell.

use nu_plugin::{EvaluatedCall, MsgPackSerializer, serve_plugin};
use nu_plugin::{EngineInterface, Plugin, PluginCommand, SimplePluginCommand};
use nu_protocol::{LabeledError, Signature, Value};

struct MyPlugin;
struct MyCommand;

impl Plugin for MyPlugin {
    fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin = Self>>> {
        vec![Box::new(MyCommand)]
    }
}

impl SimplePluginCommand for MyCommand {
    type Plugin = MyPlugin;

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

    fn usage(&self) -> &str {
        todo!();
    }

    fn signature(&self) -> Signature {
        todo!();
    }

    fn run(
        &self,
        plugin: &MyPlugin,
        engine: &EngineInterface,
        call: &EvaluatedCall,
        input: &Value
    ) -> Result<Value, LabeledError> {
        todo!();
    }
}

fn main() {
   serve_plugin(&MyPlugin{}, MsgPackSerializer)
}

Nushell’s source tree contains a Plugin Example that demonstrates the full range of plugin capabilities.

Re-exports

• pub use plugin::PluginRead;
• pub use plugin::PluginWrite;

Structs

• EngineInterface
  A reference through which the nushell engine can be interacted with during execution.
• EvaluatedCall
  A representation of the plugin’s invocation command including command line args
• JsonSerializer
  A PluginEncoder that enables the plugin to communicate with Nushell with JSON serialized data.
• MsgPackSerializer
  A PluginEncoder that enables the plugin to communicate with Nushell with MsgPack serialized data.

Traits

• Plugin
  The API for a Nushell plugin
• PluginCommand
  The API for a Nushell plugin command
• PluginEncoder
  Encoding scheme that defines a plugin’s communication protocol with Nu
• SimplePluginCommand
  The API for a simple Nushell plugin command

Functions

• serve_plugin
  Function used to implement the communication protocol between nushell and an external plugin.