mirror of
https://github.com/nushell/nushell.git
synced 2025-04-09 21:28:55 +02:00
b296d6ee3c
5 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Devyn Cairns
|
9cf2e873b5
|
Reorganize plugin API around commands (#12170)
[Context on Discord](https://discord.com/channels/601130461678272522/855947301380947968/1216517833312309419) # Description This is a significant breaking change to the plugin API, but one I think is worthwhile. @ayax79 mentioned on Discord that while trying to start on a dataframes plugin, he was a little disappointed that more wasn't provided in terms of code organization for commands, particularly since there are *a lot* of `dfr` commands. This change treats plugins more like miniatures of the engine, with dispatch of the command name being handled inherently, each command being its own type, and each having their own signature within the trait impl for the command type rather than having to find a way to centralize it all into one `Vec`. For the example plugins that have multiple commands, I definitely like how this looks a lot better. This encourages doing code organization the right way and feels very good. For the plugins that have only one command, it's just a little bit more boilerplate - but still worth it, in my opinion. The `Box<dyn PluginCommand<Plugin = Self>>` type in `commands()` is a little bit hairy, particularly for Rust beginners, but ultimately not so bad, and it gives the desired flexibility for shared state for a whole plugin + the individual commands. # User-Facing Changes Pretty big breaking change to plugin API, but probably one that's worth making. ```rust use nu_plugin::*; use nu_protocol::{PluginSignature, PipelineData, Type, Value}; struct LowercasePlugin; struct Lowercase; // Plugins can now have multiple commands impl PluginCommand for Lowercase { type Plugin = LowercasePlugin; // The signature lives with the command 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())) } // We also provide SimplePluginCommand which operates on Value like before 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)?) } } // Plugin now just has a list of commands, and the custom value op stuff still goes here impl Plugin for LowercasePlugin { fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin=Self>>> { vec![Box::new(Lowercase)] } } fn main() { serve_plugin(&LowercasePlugin{}, MsgPackSerializer) } ``` Time this however you like - we're already breaking stuff for 0.92, so it might be good to do it now, but if it feels like a lot all at once, it could wait. # Tests + Formatting - 🟢 `toolkit fmt` - 🟢 `toolkit clippy` - 🟢 `toolkit test` - 🟢 `toolkit test stdlib` # After Submitting - [ ] Update examples in the book - [x] Fix #12088 to match - this change would actually simplify it a lot, because the methods are currently just duplicated between `Plugin` and `StreamingPlugin`, but they only need to be on `Plugin` with this change |
||
|
Devyn Cairns
|
430fb1fcb6
|
Add support for engine calls from plugins (#12029)
# Description This allows plugins to make calls back to the engine to get config, evaluate closures, and do other things that must be done within the engine process. Engine calls can both produce and consume streams as necessary. Closures passed to plugins can both accept stream input and produce stream output sent back to the plugin. Engine calls referring to a plugin call's context can be processed as long either the response hasn't been received, or the response created streams that haven't ended yet. This is a breaking API change for plugins. There are some pretty major changes to the interface that plugins must implement, including: 1. Plugins now run with `&self` and must be `Sync`. Executing multiple plugin calls in parallel is supported, and there's a chance that a closure passed to a plugin could invoke the same plugin. Supporting state across plugin invocations is left up to the plugin author to do in whichever way they feel best, but the plugin object itself is still shared. Even though the engine doesn't run multiple plugin calls through the same process yet, I still considered it important to break the API in this way at this stage. We might want to consider an optional threadpool feature for performance. 2. Plugins take a reference to `EngineInterface`, which can be cloned. This interface allows plugins to make calls back to the engine, including for getting config and running closures. 3. Plugins no longer take the `config` parameter. This can be accessed from the interface via the `.get_plugin_config()` engine call. # User-Facing Changes <!-- List of all changes that impact the user experience here. This helps us keep track of breaking changes. --> Not only does this have plugin protocol changes, it will require plugins to make some code changes before they will work again. But on the plus side, the engine call feature is extensible, and we can add more things to it as needed. Plugin maintainers will have to change the trait signature at the very least. If they were using `config`, they will have to call `engine.get_plugin_config()` instead. If they were using the mutable reference to the plugin, they will have to come up with some strategy to work around it (for example, for `Inc` I just cloned it). This shouldn't be such a big deal at the moment as it's not like plugins have ever run as daemons with persistent state in the past, and they don't in this PR either. But I thought it was important to make the change before we support plugins as daemons, as an exclusive mutable reference is not compatible with parallel plugin calls. I suggest this gets merged sometime *after* the current pending release, so that we have some time to adjust to the previous plugin protocol changes that don't require code changes before making ones that do. # Tests + Formatting - 🟢 `toolkit fmt` - 🟢 `toolkit clippy` - 🟢 `toolkit test` - 🟢 `toolkit test stdlib` # After Submitting I will document the additional protocol features (`EngineCall`, `EngineCallResponse`), and constraints on plugin call processing if engine calls are used - basically, to be aware that an engine call could result in a nested plugin call, so the plugin should be able to handle that. |
||
Eric Hodel
|
7071617f18
|
Allow plugins to receive configuration from the nushell configuration (#10955)
# Description
When nushell calls a plugin it now sends a configuration `Value` from
the nushell config under `$env.config.plugins.PLUGIN_SHORT_NAME`. This
allows plugin authors to read configuration provided by plugin users.
The `PLUGIN_SHORT_NAME` must match the registered filename after
`nu_plugin_`. If you register `target/debug/nu_plugin_config` the
`PLUGIN_NAME` will be `config` and the nushell config will loook like:
$env.config = {
# ...
plugins: {
config: [
some
values
]
}
}
Configuration may also use a closure which allows passing values from
`$env` to a plugin:
$env.config = {
# ...
plugins: {
config: {||
$env.some_value
}
}
}
This is a breaking change for the plugin API as the `Plugin::run()`
function now accepts a new configuration argument which is an
`&Option<Value>`. If no configuration was supplied the value is `None`.
Plugins compiled after this change should work with older nushell, and
will behave as if the configuration was not set.
Initially discussed in #10867
# User-Facing Changes
* Plugins can read configuration data stored in `$env.config.plugins`
* The plugin `CallInfo` now includes a `config` entry, existing plugins
will require updates
# Tests + Formatting
- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`
# After Submitting
- [ ] Update [Creating a plugin (in
Rust)](https://www.nushell.sh/contributor-book/plugins.html#creating-a-plugin-in-rust)
[source](https://github.com/nushell/nushell.github.io/blob/main/contributor-book/plugins.md)
- [ ] Add "Configuration" section to [Plugins
documentation](https://www.nushell.sh/contributor-book/plugins.html)
|
||
WindSoilder
|
8e84e33638
|
add usage for plugin commands (#8138)
# Description As title # User-Facing Changes _(List of all changes that impact the user experience here. This helps us keep track of breaking changes.)_ # 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. |
||
|
WindSoilder
|
208ffdc1da
|
Move some from xxx commands to plugin (#7942)
# Description From nushell 0.8 philosophy: https://github.com/nushell/nushell.github.io/blob/main/contributor-book/philosophy_0_80.md#core-categories > The following categories should be moved to plugins: Uncommon format support So this pr is trying to move following commands to plugin: - [X] from eml - [x] from ics - [x] from ini - [x] from vcf And we can have a new plugin handles for these formatting, currently it's implemented here: https://github.com/WindSoilder/nu_plugin_format The command usage should be the same to original command. If it's ok, the plugin can support more formats like [parquet](https://github.com/fdncred/nu_plugin_from_parquet), or [EDN format](https://github.com/nushell/nushell/issues/6415), or something else. Just create a draft pr to show what's the blueprint looks like, and is it a good direction to move forward? # User-Facing Changes _(List of all changes that impact the user experience here. This helps us keep track of breaking changes.)_ # 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. |