extern/nushell
1
0
Fork 1
mirror of https://github.com/nushell/nushell.git synced 2025-06-30 22:50:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Change PluginCommand API to be more like Command (#12279)

Browse Source 
# Description

This is something that was discussed in the core team meeting last
Wednesday. @ayax79 is building `nu-plugin-polars` with all of the
dataframe commands into a plugin, and there are a lot of them, so it
would help to make the API more similar. At the same time, I think the
`Command` API is just better anyway. I don't think the difference is
justified, and the types for core commands have the benefit of requiring
less `.into()` because they often don't own their data

- Broke `signature()` up into `name()`, `usage()`, `extra_usage()`,
`search_terms()`, `examples()`
- `signature()` returns `nu_protocol::Signature`
- `examples()` returns `Vec<nu_protocol::Example>`
- `PluginSignature` and `PluginExample` no longer need to be used by
plugin developers

# User-Facing Changes
Breaking API for plugins yet again 😄
This commit is contained in:
Devyn Cairns
2024-03-27 03:59:57 -07:00
committed by GitHub
parent 03b5e9d853
commit 01d30a416b
45 changed files with 962 additions and 674 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
crates/nu-plugin-test-support/src/fake_register.rs
View File

@ -1,6 +1,6 @@
use std::sync::Arc;
use std::{ops::Deref, sync::Arc};
use nu_plugin::{Plugin, PluginDeclaration};
use nu_plugin::{create_plugin_signature, Plugin, PluginDeclaration};
use nu_protocol::{engine::StateWorkingSet, RegisteredPlugin, ShellError};
use crate::{fake_persistent_plugin::FakePersistentPlugin, spawn_fake_plugin::spawn_fake_plugin};
@ -15,7 +15,7 @@ pub fn fake_register(
let reg_plugin_clone = reg_plugin.clone();
for command in plugin.commands() {
let signature = command.signature();
let signature = create_plugin_signature(command.deref());
let decl = PluginDeclaration::new(reg_plugin.clone(), signature);
working_set.add_decl(Box::new(decl));
}

64
crates/nu-plugin-test-support/src/lib.rs
View File

@ -7,8 +7,10 @@
//!
//! use nu_plugin::*;
//! use nu_plugin_test_support::PluginTest;
//! use nu_protocol::{PluginSignature, PipelineData, Type, Span, Value, LabeledError};
//! use nu_protocol::IntoInterruptiblePipelineData;
//! use nu_protocol::{
//! Example, IntoInterruptiblePipelineData, LabeledError, PipelineData, ShellError, Signature,
//! Span, Type, Value,
//! };
//!
//! struct LowercasePlugin;
//! struct Lowercase;
@ -16,26 +18,50 @@
//! impl PluginCommand for Lowercase {
//! type Plugin = LowercasePlugin;
//!
//! fn signature(&self) -> PluginSignature {
//! PluginSignature::build("lowercase")
//! .usage("Convert each string in a stream to lowercase")
//! .input_output_type(Type::List(Type::String.into()), Type::List(Type::String.into()))
//! fn name(&self) -> &str {
//! "lowercase"
//! }
//!
//! fn usage(&self) -> &str {
//! "Convert each string in a stream to lowercase"
//! }
//!
//! fn signature(&self) -> Signature {
//! Signature::build(self.name()).input_output_type(
//! Type::List(Type::String.into()),
//! Type::List(Type::String.into()),
//! )
//! }
//!
//! fn examples(&self) -> Vec<Example> {
//! vec![Example {
//! example: r#"[Hello wORLD] | lowercase"#,
//! description: "Lowercase a list of strings",
//! result: Some(Value::test_list(vec![
//! Value::test_string("hello"),
//! Value::test_string("world"),
//! ])),
//! }]
//! }
//!
//! fn run(
//! &self,
//! plugin: &LowercasePlugin,
//! engine: &EngineInterface,
//! _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)?)
//! 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,
//! )?)
//! }
//! }
//!
@ -45,7 +71,14 @@
//! }
//! }
//!
//! fn test_lowercase() -> Result<(), LabeledError> {
//! // #[test]
//! fn test_examples() -> Result<(), ShellError> {
//! PluginTest::new("lowercase", LowercasePlugin.into())?
//! .test_command_examples(&Lowercase)
//! }
//!
//! // #[test]
//! fn test_lowercase() -> Result<(), ShellError> {
//! let input = vec![Value::test_string("FooBar")].into_pipeline_data(None);
//! let output = PluginTest::new("lowercase", LowercasePlugin.into())?
//! .eval_with("lowercase", input)?
@ -60,6 +93,7 @@
//! Ok(())
//! }
//! #
//! # test_examples().unwrap();
//! # test_lowercase().unwrap();
//! ```

16
crates/nu-plugin-test-support/src/plugin_test.rs
View File

@ -7,7 +7,7 @@ use nu_plugin::{Plugin, PluginCommand, PluginCustomValue, PluginSource};
use nu_protocol::{
debugger::WithoutDebug,
engine::{EngineState, Stack, StateWorkingSet},
report_error_new, LabeledError, PipelineData, PluginExample, ShellError, Span, Value,
report_error_new, Example, LabeledError, PipelineData, ShellError, Span, Value,
};
use crate::{diff::diff_by_line, fake_register::fake_register};
@ -186,20 +186,20 @@ impl PluginTest {
///
/// ```rust,no_run
/// # use nu_plugin_test_support::PluginTest;
/// # use nu_protocol::{ShellError, PluginExample, Value};
/// # use nu_protocol::{ShellError, Example, Value};
/// # use nu_plugin::*;
/// # fn test(MyPlugin: impl Plugin + Send + 'static) -> Result<(), ShellError> {
/// PluginTest::new("my_plugin", MyPlugin.into())?
/// .test_examples(&[
/// PluginExample {
/// example: "my-command".into(),
/// description: "Run my-command".into(),
/// Example {
/// example: "my-command",
/// description: "Run my-command",
/// result: Some(Value::test_string("my-command output")),
/// },
/// ])
/// # }
/// ```
pub fn test_examples(&mut self, examples: &[PluginExample]) -> Result<(), ShellError> {
pub fn test_examples(&mut self, examples: &[Example]) -> Result<(), ShellError> {
let mut failed = false;
for example in examples {
@ -210,7 +210,7 @@ impl PluginTest {
eprintln!("{} {}", bold.paint("Description:"), example.description);
};
if let Some(expectation) = &example.result {
match self.eval(&example.example) {
match self.eval(example.example) {
Ok(data) => {
let mut value = data.into_value(Span::test_data());
@ -270,6 +270,6 @@ impl PluginTest {
&mut self,
command: &impl PluginCommand,
) -> Result<(), ShellError> {
self.test_examples(&command.signature().examples)
self.test_examples(&command.examples())
}
}

42
crates/nu-plugin-test-support/tests/custom_value/mod.rs
View File

@ -3,8 +3,7 @@ use std::cmp::Ordering;
use nu_plugin::{EngineInterface, EvaluatedCall, Plugin, SimplePluginCommand};
use nu_plugin_test_support::PluginTest;
use nu_protocol::{
CustomValue, LabeledError, PipelineData, PluginExample, PluginSignature, ShellError, Span,
Type, Value,
CustomValue, Example, LabeledError, PipelineData, ShellError, Signature, Span, Type, Value,
};
use serde::{Deserialize, Serialize};
@ -58,14 +57,24 @@ impl Plugin for CustomU32Plugin {
impl SimplePluginCommand for IntoU32 {
type Plugin = CustomU32Plugin;
fn signature(&self) -> PluginSignature {
PluginSignature::build("into u32")
.input_output_type(Type::Int, Type::Custom("CustomU32".into()))
.plugin_examples(vec![PluginExample {
example: "340 | into u32".into(),
description: "Make a u32".into(),
result: Some(CustomU32(340).into_value(Span::test_data())),
}])
fn name(&self) -> &str {
"into u32"
}
fn usage(&self) -> &str {
"Convert a number to a 32-bit unsigned integer"
}
fn signature(&self) -> Signature {
Signature::build(self.name()).input_output_type(Type::Int, Type::Custom("CustomU32".into()))
}
fn examples(&self) -> Vec<Example> {
vec![Example {
example: "340 | into u32",
description: "Make a u32",
result: Some(CustomU32(340).into_value(Span::test_data())),
}]
}
fn run(
@ -87,9 +96,16 @@ impl SimplePluginCommand for IntoU32 {
impl SimplePluginCommand for IntoIntFromU32 {
type Plugin = CustomU32Plugin;
fn signature(&self) -> PluginSignature {
PluginSignature::build("into int from u32")
.input_output_type(Type::Custom("CustomU32".into()), Type::Int)
fn name(&self) -> &str {
"into int from u32"
}
fn usage(&self) -> &str {
"Turn a u32 back into a number"
}
fn signature(&self) -> Signature {
Signature::build(self.name()).input_output_type(Type::Custom("CustomU32".into()), Type::Int)
}
fn run(

40
crates/nu-plugin-test-support/tests/hello/mod.rs
View File

@ -2,7 +2,7 @@
use nu_plugin::*;
use nu_plugin_test_support::PluginTest;
use nu_protocol::{LabeledError, PluginExample, PluginSignature, ShellError, Type, Value};
use nu_protocol::{Example, LabeledError, ShellError, Signature, Type, Value};
struct HelloPlugin;
struct Hello;
@ -16,14 +16,24 @@ impl Plugin for HelloPlugin {
impl SimplePluginCommand for Hello {
type Plugin = HelloPlugin;
fn signature(&self) -> PluginSignature {
PluginSignature::build("hello")
.input_output_type(Type::Nothing, Type::String)
.plugin_examples(vec![PluginExample {
example: "hello".into(),
description: "Print a friendly greeting".into(),
result: Some(Value::test_string("Hello, World!")),
}])
fn name(&self) -> &str {
"hello"
}
fn usage(&self) -> &str {
"Print a friendly greeting"
}
fn signature(&self) -> Signature {
Signature::build(PluginCommand::name(self)).input_output_type(Type::Nothing, Type::String)
}
fn examples(&self) -> Vec<Example> {
vec![Example {
example: "hello",
description: "Print a friendly greeting",
result: Some(Value::test_string("Hello, World!")),
}]
}
fn run(
@ -44,9 +54,9 @@ fn test_specified_examples() -> Result<(), ShellError> {
#[test]
fn test_an_error_causing_example() -> Result<(), ShellError> {
let result = PluginTest::new("hello", HelloPlugin.into())?.test_examples(&[PluginExample {
example: "hello --unknown-flag".into(),
description: "Run hello with an unknown flag".into(),
let result = PluginTest::new("hello", HelloPlugin.into())?.test_examples(&[Example {
example: "hello --unknown-flag",
description: "Run hello with an unknown flag",
result: Some(Value::test_string("Hello, World!")),
}]);
assert!(result.is_err());
@ -55,9 +65,9 @@ fn test_an_error_causing_example() -> Result<(), ShellError> {
#[test]
fn test_an_example_with_the_wrong_result() -> Result<(), ShellError> {
let result = PluginTest::new("hello", HelloPlugin.into())?.test_examples(&[PluginExample {
example: "hello".into(),
description: "Run hello but the example result is wrong".into(),
let result = PluginTest::new("hello", HelloPlugin.into())?.test_examples(&[Example {
example: "hello",
description: "Run hello but the example result is wrong",
result: Some(Value::test_string("Goodbye, World!")),
}]);
assert!(result.is_err());

43
crates/nu-plugin-test-support/tests/lowercase/mod.rs
View File

@ -1,8 +1,8 @@
use nu_plugin::*;
use nu_plugin_test_support::PluginTest;
use nu_protocol::{
IntoInterruptiblePipelineData, LabeledError, PipelineData, PluginExample, PluginSignature,
ShellError, Span, Type, Value,
Example, IntoInterruptiblePipelineData, LabeledError, PipelineData, ShellError, Signature,
Span, Type, Value,
};
struct LowercasePlugin;
@ -11,21 +11,30 @@ struct Lowercase;
impl PluginCommand for Lowercase {
type Plugin = LowercasePlugin;
fn signature(&self) -> PluginSignature {
PluginSignature::build("lowercase")
.usage("Convert each string in a stream to lowercase")
.input_output_type(
Type::List(Type::String.into()),
Type::List(Type::String.into()),
)
.plugin_examples(vec![PluginExample {
example: r#"[Hello wORLD] | lowercase"#.into(),
description: "Lowercase a list of strings".into(),
result: Some(Value::test_list(vec![
Value::test_string("hello"),
Value::test_string("world"),
])),
}])
fn name(&self) -> &str {
"lowercase"
}
fn usage(&self) -> &str {
"Convert each string in a stream to lowercase"
}
fn signature(&self) -> Signature {
Signature::build(self.name()).input_output_type(
Type::List(Type::String.into()),
Type::List(Type::String.into()),
)
}
fn examples(&self) -> Vec<Example> {
vec![Example {
example: r#"[Hello wORLD] | lowercase"#,
description: "Lowercase a list of strings",
result: Some(Value::test_list(vec![
Value::test_string("hello"),
Value::test_string("world"),
])),
}]
}
fn run(