Trait nu_plugin::PluginCommand
source · 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<'_>> { ... }
}
Expand description
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§
Required Methods§
sourcefn name(&self) -> &str
fn name(&self) -> &str
The name of the command from within Nu.
In case this contains spaces, it will be treated as a subcommand.
sourcefn signature(&self) -> Signature
fn signature(&self) -> Signature
The signature of the command.
This defines the arguments and input/output types of the command.
sourcefn usage(&self) -> &str
fn usage(&self) -> &str
A brief description of usage for the command.
This should be short enough to fit in completion menus.
sourcefn run(
&self,
plugin: &Self::Plugin,
engine: &EngineInterface,
call: &EvaluatedCall,
input: PipelineData
) -> Result<PipelineData, LabeledError>
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§
sourcefn extra_usage(&self) -> &str
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.
sourcefn search_terms(&self) -> Vec<&str>
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.
sourcefn examples(&self) -> Vec<Example<'_>>
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 result
s as specified.
Implementors§
source§impl<T> PluginCommand for Twhere
T: SimplePluginCommand,
impl<T> PluginCommand for Twhere
T: SimplePluginCommand,
All SimplePluginCommand
s can be used as PluginCommand
s, but input streams will be fully
consumed before the plugin command runs.