forked from extern/nushell
0c4d5330ee
# Description This breaks `nu-plugin` up into four crates: - `nu-plugin-protocol`: just the type definitions for the protocol, no I/O. If someone wanted to wire up something more bare metal, maybe for async I/O, they could use this. - `nu-plugin-core`: the shared stuff between engine/plugin. Less stable interface. - `nu-plugin-engine`: everything required for the engine to talk to plugins. Less stable interface. - `nu-plugin`: everything required for the plugin to talk to the engine, what plugin developers use. Should be the most stable interface. No changes are made to the interface exposed by `nu-plugin` - it should all still be there. Re-exports from `nu-plugin-protocol` or `nu-plugin-core` are used as required. Plugins shouldn't ever have to use those crates directly. This should be somewhat faster to compile as `nu-plugin-engine` and `nu-plugin` can compile in parallel, and the engine doesn't need `nu-plugin` and plugins don't need `nu-plugin-engine` (except for test support), so that should reduce what needs to be compiled too. The only significant change here other than splitting stuff up was to break the `source` out of `PluginCustomValue` and create a new `PluginCustomValueWithSource` type that contains that instead. One bonus of that is we get rid of the option and it's now more type-safe, but it also means that the logic for that stuff (actually running the plugin for custom value ops) can live entirely within the `nu-plugin-engine` crate. # User-Facing Changes - New crates. - Added `local-socket` feature for `nu` to try to make it possible to compile without that support if needed. # Tests + Formatting - 🟢 `toolkit fmt` - 🟢 `toolkit clippy` - 🟢 `toolkit test` - 🟢 `toolkit test stdlib`
80 lines
2.5 KiB
Rust
80 lines
2.5 KiB
Rust
#![allow(clippy::needless_doctest_main)]
|
|
//! # 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.
|
|
//!
|
|
//! ```rust,no_run
|
|
//! 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](https://github.com/nushell/nushell/tree/main/crates/nu_plugin_example)
|
|
//! that demonstrates the full range of plugin capabilities.
|
|
mod plugin;
|
|
|
|
#[cfg(test)]
|
|
mod test_util;
|
|
|
|
pub use plugin::{serve_plugin, EngineInterface, Plugin, PluginCommand, SimplePluginCommand};
|
|
|
|
// Re-exports. Consider semver implications carefully.
|
|
pub use nu_plugin_core::{JsonSerializer, MsgPackSerializer, PluginEncoder};
|
|
pub use nu_plugin_protocol::EvaluatedCall;
|
|
|
|
// Required by other internal crates.
|
|
#[doc(hidden)]
|
|
pub use plugin::{create_plugin_signature, serve_plugin_io};
|