nu_plugin/
lib.rs

1#![allow(clippy::needless_doctest_main)]
2//! # Nu Plugin: Plugin library for Nushell
3//!
4//! This crate contains the interface necessary to build Nushell plugins in Rust.
5//! Additionally, it contains public, but undocumented, items used by Nushell itself
6//! to interface with Nushell plugins. This documentation focuses on the interface
7//! needed to write an independent plugin.
8//!
9//! Nushell plugins are stand-alone applications that communicate with Nushell
10//! over stdin and stdout using a standardizes serialization framework to exchange
11//! the typed data that Nushell commands utilize natively.
12//!
13//! A typical plugin application will define a struct that implements the [`Plugin`]
14//! trait and then, in its main method, pass that [`Plugin`] to the [`serve_plugin()`]
15//! function, which will handle all of the input and output serialization when
16//! invoked by Nushell.
17//!
18//! ```rust,no_run
19//! use nu_plugin::{EvaluatedCall, MsgPackSerializer, serve_plugin};
20//! use nu_plugin::{EngineInterface, Plugin, PluginCommand, SimplePluginCommand};
21//! use nu_protocol::{LabeledError, Signature, Value};
22//!
23//! struct MyPlugin;
24//! struct MyCommand;
25//!
26//! impl Plugin for MyPlugin {
27//!     fn version(&self) -> String {
28//!         env!("CARGO_PKG_VERSION").into()
29//!     }
30//!
31//!     fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin = Self>>> {
32//!         vec![Box::new(MyCommand)]
33//!     }
34//! }
35//!
36//! impl SimplePluginCommand for MyCommand {
37//!     type Plugin = MyPlugin;
38//!
39//!     fn name(&self) -> &str {
40//!         "my-command"
41//!     }
42//!
43//!     fn description(&self) -> &str {
44//!         todo!();
45//!     }
46//!
47//!     fn signature(&self) -> Signature {
48//!         todo!();
49//!     }
50//!
51//!     fn run(
52//!         &self,
53//!         plugin: &MyPlugin,
54//!         engine: &EngineInterface,
55//!         call: &EvaluatedCall,
56//!         input: &Value
57//!     ) -> Result<Value, LabeledError> {
58//!         todo!();
59//!     }
60//! }
61//!
62//! fn main() {
63//!    serve_plugin(&MyPlugin{}, MsgPackSerializer)
64//! }
65//! ```
66//!
67//! Nushell's source tree contains a
68//! [Plugin Example](https://github.com/nushell/nushell/tree/main/crates/nu_plugin_example)
69//! that demonstrates the full range of plugin capabilities.
70mod plugin;
71
72#[cfg(test)]
73mod test_util;
74
75pub use plugin::{EngineInterface, Plugin, PluginCommand, SimplePluginCommand, serve_plugin};
76
77// Re-exports. Consider semver implications carefully.
78pub use nu_plugin_core::{JsonSerializer, MsgPackSerializer, PluginEncoder};
79pub use nu_plugin_protocol::EvaluatedCall;
80
81// Required by other internal crates.
82#[doc(hidden)]
83pub use plugin::{create_plugin_signature, serve_plugin_io};
nu_plugin/lib.rs

nu_plugin/
lib.rs
