mirror of
https://github.com/nushell/nushell.git
synced 2025-08-09 11:45:50 +02:00
Make plugin commands support examples. (#7984)
# Description
As title, we can't provide examples for plugin commands, this pr would
make it possible
# User-Facing Changes
Take plugin `nu-example-1` as example:
```
❯ nu-example-1 -h
PluginSignature test 1 for plugin. Returns Value::Nothing
Usage:
> nu-example-1 {flags} <a> <b> (opt) ...(rest)
Flags:
-h, --help - Display the help message for this command
-f, --flag - a flag for the signature
-n, --named <String> - named string
Parameters:
a <int>: required integer value
b <string>: required string value
(optional) opt <int>: Optional number
...rest <string>: rest value string
Examples:
running example with an int value and string value
> nu-example-1 3 bb
```
The examples session is newly added.
## Basic idea behind these changes
when nushell query plugin signatures, plugin just returns it's signature
without any examples, so nushell have no idea about the examples of
plugin commands.
To adding the feature, we just making plugin returns it's signature with
examples.
Before:
```
1. get signature
---------------->
Nushell ------------------ Plugin
<-----------------
2. returns Vec<Signature>
```
After:
```
1. get signature
---------------->
Nushell ------------------ Plugin
<-----------------
2. returns Vec<PluginSignature>
```
When writing plugin signature to $nu.plugin-path:
Serialize `<PluginSignature>` rather than `<Signature>`, which would
enable us to serialize examples to `$nu.plugin-path`
## Shortcoming
It's a breaking changes because `Plugin::signature` is changed, and it
requires plugin authors to change their code for new signatures.
Fortunally it should be easy to change, for rust based plugin, we just
need to make a global replace from word `Signature` to word
`PluginSignature` in their plugin project.
Our content of plugin-path is really large, if one plugin have many
examples, it'd results to larger body of $nu.plugin-path, which is not
really scale. A solution would be save register information in other
binary formats rather than `json`. But I think it'd be another story.
# Tests + Formatting
Don't forget to add tests that cover your changes.
Make sure you've run and fixed any issues with these commands:
- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass
# After Submitting
If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
This commit is contained in:
WindSoilder
GitHub
@ -7,21 +7,21 @@ use crate::protocol::{
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use nu_protocol::engine::{Command, EngineState, Stack};
|
||||
use nu_protocol::{ast::Call, Signature};
|
||||
use nu_protocol::{PipelineData, ShellError, Value};
|
||||
use nu_protocol::{ast::Call, PluginSignature, Signature};
|
||||
use nu_protocol::{Example, PipelineData, ShellError, Value};
|
||||
|
||||
#[derive(Clone)]
|
||||
pub struct PluginDeclaration {
|
||||
name: String,
|
||||
signature: Signature,
|
||||
signature: PluginSignature,
|
||||
filename: PathBuf,
|
||||
shell: Option<PathBuf>,
|
||||
}
|
||||
|
||||
impl PluginDeclaration {
|
||||
pub fn new(filename: PathBuf, signature: Signature, shell: Option<PathBuf>) -> Self {
|
||||
pub fn new(filename: PathBuf, signature: PluginSignature, shell: Option<PathBuf>) -> Self {
|
||||
Self {
|
||||
name: signature.name.clone(),
|
||||
name: signature.sig.name.clone(),
|
||||
signature,
|
||||
filename,
|
||||
shell,
|
||||
@ -35,11 +35,23 @@ impl Command for PluginDeclaration {
|
||||
}
|
||||
|
||||
fn signature(&self) -> Signature {
|
||||
self.signature.clone()
|
||||
self.signature.sig.clone()
|
||||
}
|
||||
|
||||
fn usage(&self) -> &str {
|
||||
self.signature.usage.as_str()
|
||||
self.signature.sig.usage.as_str()
|
||||
}
|
||||
|
||||
fn examples(&self) -> Vec<Example> {
|
||||
let mut res = vec![];
|
||||
for e in self.signature.examples.iter() {
|
||||
res.push(Example {
|
||||
example: &e.example,
|
||||
description: &e.description,
|
||||
result: e.result.clone(),
|
||||
})
|
||||
}
|
||||
res
|
||||
}
|
||||
|
||||
fn run(
|
||||
|
||||
@ -11,8 +11,7 @@ use std::io::{BufReader, ErrorKind, Read, Write as WriteTrait};
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::process::{Child, ChildStdout, Command as CommandSys, Stdio};
|
||||
|
||||
use nu_protocol::{CustomValue, ShellError, Span};
|
||||
use nu_protocol::{Signature, Value};
|
||||
use nu_protocol::{CustomValue, PluginSignature, ShellError, Span, Value};
|
||||
|
||||
use super::EvaluatedCall;
|
||||
|
||||
@ -118,7 +117,7 @@ pub fn get_signature(
|
||||
path: &Path,
|
||||
shell: &Option<PathBuf>,
|
||||
current_envs: &HashMap<String, String>,
|
||||
) -> Result<Vec<Signature>, ShellError> {
|
||||
) -> Result<Vec<PluginSignature>, ShellError> {
|
||||
let mut plugin_cmd = create_command(path, shell);
|
||||
let program_name = plugin_cmd.get_program().to_os_string().into_string();
|
||||
|
||||
@ -183,7 +182,7 @@ pub fn get_signature(
|
||||
// The next trait and functions are part of the plugin that is being created
|
||||
// The `Plugin` trait defines the API which plugins use to "hook" into nushell.
|
||||
pub trait Plugin {
|
||||
fn signature(&self) -> Vec<Signature>;
|
||||
fn signature(&self) -> Vec<PluginSignature>;
|
||||
fn run(
|
||||
&mut self,
|
||||
name: &str,
|
||||
@ -311,22 +310,23 @@ fn print_help(plugin: &mut impl Plugin, encoder: impl PluginEncoder) {
|
||||
let mut help = String::new();
|
||||
|
||||
plugin.signature().iter().for_each(|signature| {
|
||||
let res = write!(help, "\nCommand: {}", signature.name)
|
||||
.and_then(|_| writeln!(help, "\nUsage:\n > {}", signature.usage))
|
||||
let res = write!(help, "\nCommand: {}", signature.sig.name)
|
||||
.and_then(|_| writeln!(help, "\nUsage:\n > {}", signature.sig.usage))
|
||||
.and_then(|_| {
|
||||
if !signature.extra_usage.is_empty() {
|
||||
writeln!(help, "\nExtra usage:\n > {}", signature.extra_usage)
|
||||
if !signature.sig.extra_usage.is_empty() {
|
||||
writeln!(help, "\nExtra usage:\n > {}", signature.sig.extra_usage)
|
||||
} else {
|
||||
Ok(())
|
||||
}
|
||||
})
|
||||
.and_then(|_| {
|
||||
let flags = get_flags_section(signature);
|
||||
let flags = get_flags_section(&signature.sig);
|
||||
write!(help, "{flags}")
|
||||
})
|
||||
.and_then(|_| writeln!(help, "\nParameters:"))
|
||||
.and_then(|_| {
|
||||
signature
|
||||
.sig
|
||||
.required_positional
|
||||
.iter()
|
||||
.try_for_each(|positional| {
|
||||
@ -339,6 +339,7 @@ fn print_help(plugin: &mut impl Plugin, encoder: impl PluginEncoder) {
|
||||
})
|
||||
.and_then(|_| {
|
||||
signature
|
||||
.sig
|
||||
.optional_positional
|
||||
.iter()
|
||||
.try_for_each(|positional| {
|
||||
@ -350,7 +351,7 @@ fn print_help(plugin: &mut impl Plugin, encoder: impl PluginEncoder) {
|
||||
})
|
||||
})
|
||||
.and_then(|_| {
|
||||
if let Some(rest_positional) = &signature.rest_positional {
|
||||
if let Some(rest_positional) = &signature.sig.rest_positional {
|
||||
writeln!(
|
||||
help,
|
||||
" ...{} <{}>: {}",
|
||||
|
||||
@ -3,7 +3,7 @@ mod plugin_custom_value;
|
||||
mod plugin_data;
|
||||
|
||||
pub use evaluated_call::EvaluatedCall;
|
||||
use nu_protocol::{ShellError, Signature, Span, Value};
|
||||
use nu_protocol::{PluginSignature, ShellError, Span, Value};
|
||||
pub use plugin_custom_value::PluginCustomValue;
|
||||
pub use plugin_data::PluginData;
|
||||
use serde::{Deserialize, Serialize};
|
||||
@ -97,7 +97,7 @@ impl From<ShellError> for LabeledError {
|
||||
#[derive(Serialize, Deserialize)]
|
||||
pub enum PluginResponse {
|
||||
Error(LabeledError),
|
||||
Signature(Vec<Signature>),
|
||||
Signature(Vec<PluginSignature>),
|
||||
Value(Box<Value>),
|
||||
PluginData(String, PluginData),
|
||||
}
|
||||
|
||||
@ -51,7 +51,7 @@ mod tests {
|
||||
use crate::protocol::{
|
||||
CallInfo, CallInput, EvaluatedCall, LabeledError, PluginCall, PluginData, PluginResponse,
|
||||
};
|
||||
use nu_protocol::{Signature, Span, Spanned, SyntaxShape, Value};
|
||||
use nu_protocol::{PluginSignature, Span, Spanned, SyntaxShape, Value};
|
||||
|
||||
#[test]
|
||||
fn callinfo_round_trip_signature() {
|
||||
@ -183,7 +183,7 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn response_round_trip_signature() {
|
||||
let signature = Signature::build("nu-plugin")
|
||||
let signature = PluginSignature::build("nu-plugin")
|
||||
.required("first", SyntaxShape::String, "first required")
|
||||
.required("second", SyntaxShape::Int, "second required")
|
||||
.required_named("first-named", SyntaxShape::String, "first named", Some('f'))
|
||||
@ -212,32 +212,38 @@ mod tests {
|
||||
PluginResponse::PluginData(..) => panic!("returned wrong call type"),
|
||||
PluginResponse::Signature(returned_signature) => {
|
||||
assert_eq!(returned_signature.len(), 1);
|
||||
assert_eq!(signature.name, returned_signature[0].name);
|
||||
assert_eq!(signature.usage, returned_signature[0].usage);
|
||||
assert_eq!(signature.extra_usage, returned_signature[0].extra_usage);
|
||||
assert_eq!(signature.is_filter, returned_signature[0].is_filter);
|
||||
assert_eq!(signature.sig.name, returned_signature[0].sig.name);
|
||||
assert_eq!(signature.sig.usage, returned_signature[0].sig.usage);
|
||||
assert_eq!(
|
||||
signature.sig.extra_usage,
|
||||
returned_signature[0].sig.extra_usage
|
||||
);
|
||||
assert_eq!(signature.sig.is_filter, returned_signature[0].sig.is_filter);
|
||||
|
||||
signature
|
||||
.sig
|
||||
.required_positional
|
||||
.iter()
|
||||
.zip(returned_signature[0].required_positional.iter())
|
||||
.zip(returned_signature[0].sig.required_positional.iter())
|
||||
.for_each(|(lhs, rhs)| assert_eq!(lhs, rhs));
|
||||
|
||||
signature
|
||||
.sig
|
||||
.optional_positional
|
||||
.iter()
|
||||
.zip(returned_signature[0].optional_positional.iter())
|
||||
.zip(returned_signature[0].sig.optional_positional.iter())
|
||||
.for_each(|(lhs, rhs)| assert_eq!(lhs, rhs));
|
||||
|
||||
signature
|
||||
.sig
|
||||
.named
|
||||
.iter()
|
||||
.zip(returned_signature[0].named.iter())
|
||||
.zip(returned_signature[0].sig.named.iter())
|
||||
.for_each(|(lhs, rhs)| assert_eq!(lhs, rhs));
|
||||
|
||||
assert_eq!(
|
||||
signature.rest_positional,
|
||||
returned_signature[0].rest_positional,
|
||||
signature.sig.rest_positional,
|
||||
returned_signature[0].sig.rest_positional,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@ -50,7 +50,7 @@ mod tests {
|
||||
use crate::protocol::{
|
||||
CallInfo, CallInput, EvaluatedCall, LabeledError, PluginCall, PluginData, PluginResponse,
|
||||
};
|
||||
use nu_protocol::{Signature, Span, Spanned, SyntaxShape, Value};
|
||||
use nu_protocol::{PluginSignature, Span, Spanned, SyntaxShape, Value};
|
||||
|
||||
#[test]
|
||||
fn callinfo_round_trip_signature() {
|
||||
@ -182,7 +182,7 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn response_round_trip_signature() {
|
||||
let signature = Signature::build("nu-plugin")
|
||||
let signature = PluginSignature::build("nu-plugin")
|
||||
.required("first", SyntaxShape::String, "first required")
|
||||
.required("second", SyntaxShape::Int, "second required")
|
||||
.required_named("first-named", SyntaxShape::String, "first named", Some('f'))
|
||||
@ -211,32 +211,38 @@ mod tests {
|
||||
PluginResponse::PluginData(..) => panic!("returned wrong call type"),
|
||||
PluginResponse::Signature(returned_signature) => {
|
||||
assert_eq!(returned_signature.len(), 1);
|
||||
assert_eq!(signature.name, returned_signature[0].name);
|
||||
assert_eq!(signature.usage, returned_signature[0].usage);
|
||||
assert_eq!(signature.extra_usage, returned_signature[0].extra_usage);
|
||||
assert_eq!(signature.is_filter, returned_signature[0].is_filter);
|
||||
assert_eq!(signature.sig.name, returned_signature[0].sig.name);
|
||||
assert_eq!(signature.sig.usage, returned_signature[0].sig.usage);
|
||||
assert_eq!(
|
||||
signature.sig.extra_usage,
|
||||
returned_signature[0].sig.extra_usage
|
||||
);
|
||||
assert_eq!(signature.sig.is_filter, returned_signature[0].sig.is_filter);
|
||||
|
||||
signature
|
||||
.sig
|
||||
.required_positional
|
||||
.iter()
|
||||
.zip(returned_signature[0].required_positional.iter())
|
||||
.zip(returned_signature[0].sig.required_positional.iter())
|
||||
.for_each(|(lhs, rhs)| assert_eq!(lhs, rhs));
|
||||
|
||||
signature
|
||||
.sig
|
||||
.optional_positional
|
||||
.iter()
|
||||
.zip(returned_signature[0].optional_positional.iter())
|
||||
.zip(returned_signature[0].sig.optional_positional.iter())
|
||||
.for_each(|(lhs, rhs)| assert_eq!(lhs, rhs));
|
||||
|
||||
signature
|
||||
.sig
|
||||
.named
|
||||
.iter()
|
||||
.zip(returned_signature[0].named.iter())
|
||||
.zip(returned_signature[0].sig.named.iter())
|
||||
.for_each(|(lhs, rhs)| assert_eq!(lhs, rhs));
|
||||
|
||||
assert_eq!(
|
||||
signature.rest_positional,
|
||||
returned_signature[0].rest_positional,
|
||||
signature.sig.rest_positional,
|
||||
returned_signature[0].sig.rest_positional,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user