nushell/tests/plugins/mod.rs

mod call_decl;
mod config;
mod core_inc;
mod custom_values;
mod env;
mod formats;
mod nu_plugin_nu_example;
mod register;
mod registry_file;
mod stream;
mod stress_internals;
Make plugins able to find and call other commands (#13407) # Description Adds functionality to the plugin interface to support calling internal commands from plugins. For example, using `view ir --json`: ```rust let closure: Value = call.req(0)?; let Some(decl_id) = engine.find_decl("view ir")? else { return Err(LabeledError::new("`view ir` not found")); }; let ir_json = engine.call_decl( decl_id, EvaluatedCall::new(call.head) .with_named("json".into_spanned(call.head), Value::bool(true, call.head)) .with_positional(closure), PipelineData::Empty, true, false, )?.into_value()?.into_string()?; let ir = serde_json::from_value(&ir_json); // ... ``` # User-Facing Changes Plugin developers can now use `EngineInterface::find_decl()` and `call_decl()` to call internal commands, which could be handy for formatters like `to csv` or `to nuon`, or for reflection commands that help gain insight into the engine. # Tests + Formatting - :green_circle: `toolkit fmt` - :green_circle: `toolkit clippy` - :green_circle: `toolkit test` - :green_circle: `toolkit test stdlib` # After Submitting - [ ] release notes - [ ] update plugin protocol documentation: `FindDecl`, `CallDecl` engine calls; `Identifier` engine call response 2024-07-19 05:54:21 +00:00			`mod call_decl;`
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 - :green_circle: `toolkit fmt` - :green_circle: `toolkit clippy` - :green_circle: `toolkit test` - :green_circle: `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) 2024-01-15 08:59:47 +00:00			`mod config;`
This commit is the continuing phase of extracting functionality to subcrates. We extract test helpers and begin to change Nu shell's test organization along with it. 2019-12-15 16:15:06 +00:00			`mod core_inc;`
Add CustomValue support to plugins (#6070) * Skeleton implementation Lots and lots of TODOs * Bootstrap simple CustomValue plugin support test * Create nu_plugin_custom_value * Skeleton for nu_plugin_custom_values * Return a custom value from plugin * Encode CustomValues from plugin calls as PluginResponse::PluginData * Add new PluginCall variant CollapseCustomValue * Handle CollapseCustomValue plugin calls * Add CallInput::Data variant to CallInfo inputs * Handle CallInfo with CallInput::Data plugin calls * Send CallInput::Data if Value is PluginCustomValue from plugin calls * Remove unnecessary boxing of plugins CallInfo * Add fields needed to collapse PluginCustomValue to it * Document PluginCustomValue and its purpose * Impl collapsing using plugin calls in PluginCustomValue::to_base_value * Implement proper typetag based deserialization for CoolCustomValue * Test demonstrating that passing back a custom value to plugin works * Added a failing test for describing plugin CustomValues * Support describe for PluginCustomValues - Add name to PluginResponse::PluginData - Also turn it into a struct for clarity - Add name to PluginCustomValue - Return name field from PluginCustomValue * Demonstrate that plugins can create and handle multiple CustomValues * Add bincode to nu-plugin dependencies This is for demonstration purposes, any schemaless binary seralization format will work. I picked bincode since it's the most popular for Rust but there are defintely better options out there for this usecase * serde_json::Value -> Vec<u8> * Update capnp schema for new CallInfo.input field * Move call_input capnp serialization and deserialization into new file * Deserialize Value's span from Value itself instead of passing call.head I am not sure if this was correct and I am breaking it or if it was a bug, I don't fully understand how nu creates and uses Spans. What should reuse spans and what should recreate new ones? But yeah it felt weird that the Value's Span was being ignored since in the json serializer just uses the Value's Span * Add call_info value round trip test * Add capnp CallInput::Data serialization and deserialization support * Add CallInfo::CollapseCustomValue to capnp schema * Add capnp PluginCall::CollapseCustomValue serialization and deserialization support * Add PluginResponse::PluginData to capnp schema * Add capnp PluginResponse::PluginData serialization and deserialization support * Switch plugins::custom_values tests to capnp Both json and capnp would work now! Sadly I can't choose both at the same time :( * Add missing JsonSerializer round trip tests * Handle plugin returning PluginData as a response to CollapseCustomValue * Refactor plugin calling into a reusable function Many less levels of indentation now! * Export PluginData from nu_plugin So plugins can create their very own serve_plugin with whatever CustomValue behavior they may desire * Error if CustomValue cannot be handled by Plugin 2022-07-25 16:32:56 +00:00			`mod custom_values;`
Add environment engine calls for plugins (#12166) # Description This adds three engine calls: `GetEnvVar`, `GetEnvVars`, for getting environment variables from the plugin command context, and `GetCurrentDir` for getting the current working directory. Plugins are now launched in the directory of their executable to try to make improper use of the current directory without first setting it more obvious. Plugins previously launched in whatever the current directory of the engine was at the time the plugin command was run, but switching to persistent plugins broke this, because they stay in whatever directory they launched in initially. This also fixes the `gstat` plugin to use `get_current_dir()` to determine its repo location, which was directly affected by this problem. # User-Facing Changes - Adds new engine calls (`GetEnvVar`, `GetEnvVars`, `GetCurrentDir`) - Runs plugins in a different directory from before, in order to catch bugs - Plugins will have to use the new engine calls if they do filesystem stuff to work properly # Tests + Formatting - :green_circle: `toolkit fmt` - :green_circle: `toolkit clippy` - :green_circle: `toolkit test` - :green_circle: `toolkit test stdlib` # After Submitting - [ ] Document the working directory behavior on plugin launch - [ ] Document the new engine calls + response type (`ValueMap`) 2024-03-12 11:34:32 +00:00			`mod env;`
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. 2023-02-13 12:42:08 +00:00			`mod formats;`
Add an example Nushell plugin written in Nushell itself (#12574) # Description As suggested by @fdncred. It's neat that this is possible, but the particularly useful part of this is that we can actually test it because it doesn't have any external dependencies, unlike the python plugin. Right now this just implements exactly the same behavior as the python plugin, but we could have it exercise a few more things. Also fixes a couple of bugs: - `.nu` plugins were not run with `nu --stdin`, so they couldn't take input. - `register` couldn't be called if `--no-config-file` was set, because it would error on trying to update the plugin file. # User-Facing Changes - `nu_plugin_nu_example` plugin added. - `register` now works in `--no-config-file` mode. # Tests + Formatting Tests added for `nu_plugin_nu_example`. - :green_circle: `toolkit fmt` - :green_circle: `toolkit clippy` - :green_circle: `toolkit test` - :green_circle: `toolkit test stdlib` # After Submitting - [ ] Add the version bump to the release script just like for python 2024-04-19 06:53:30 +00:00			`mod nu_plugin_nu_example;`
Show plugin extra usage and search terms (#10952) # Description The `PluginSignature` type supports extra usage but this was not available in `plugin_name --help`. It also supports search terms but these did not appear in `help commands` New behavior show below is the "Extra usage for nu-example-1" line and the "Search terms:" line ``` ❯ nu-example-1 --help PluginSignature test 1 for plugin. Returns Value::Nothing Extra usage for nu-example-1 Search terms: example 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 opt <int>: Optional number (optional) ...rest <string>: rest value string Examples: running example with an int value and string value > nu-example-1 3 bb ``` Search terms are also available in `help commands`: ``` ❯ help commands \| where name == "nu-example-1" \| select name search_terms ╭──────────────┬──────────────╮ │ name │ search_terms │ ├──────────────┼──────────────┤ │ nu-example-1 │ example │ ╰──────────────┴──────────────╯ ``` # User-Facing Changes Users can now see plugin extra usage and search terms # Tests + Formatting - :green_circle: `toolkit fmt` - :green_circle: `toolkit clippy` - :green_circle: `toolkit test` - :green_circle: `toolkit test stdlib` # After Submitting N/A 2023-11-04 20:12:58 +00:00			`mod register;`
Rename plugin cache file ⇒ plugin registry file (#12634) # Description So far this seems like the winner of my poll on what the name should be. I'll take this off draft once the poll expires, if this is indeed the winner. 2024-04-24 22:40:39 +00:00			`mod registry_file;`
Bidirectional communication and streams for plugins (#11911) 2024-02-25 22:32:50 +00:00			`mod stream;`
Local socket mode and foreground terminal control for plugins (#12448) # Description Adds support for running plugins using local socket communication instead of stdio. This will be an optional thing that not all plugins have to support. This frees up stdio for use to make plugins that use stdio to create terminal UIs, cc @amtoine, @fdncred. This uses the [`interprocess`](https://crates.io/crates/interprocess) crate (298 stars, MIT license, actively maintained), which seems to be the best option for cross-platform local socket support in Rust. On Windows, a local socket name is provided. On Unixes, it's a path. The socket name is kept to a relatively small size because some operating systems have pretty strict limits on the whole path (~100 chars), so on macOS for example we prefer `/tmp/nu.{pid}.{hash64}.sock` where the hash includes the plugin filename and timestamp to be unique enough. This also adds an API for moving plugins in and out of the foreground group, which is relevant for Unixes where direct terminal control depends on that. TODO: - [x] Generate local socket path according to OS conventions - [x] Add support for passing `--local-socket` to the plugin executable instead of `--stdio`, and communicating over that instead - [x] Test plugins that were broken, including [amtoine/nu_plugin_explore](https://github.com/amtoine/nu_plugin_explore) - [x] Automatically upgrade to using local sockets when supported, falling back if it doesn't work, transparently to the user without any visible error messages - Added protocol feature: `LocalSocket` - [x] Reset preferred mode to `None` on `register` - [x] Allow plugins to detect whether they're running on a local socket and can use stdio freely, so that TUI plugins can just produce an error message otherwise - Implemented via `EngineInterface::is_using_stdio()` - [x] Clean up foreground state when plugin command exits on the engine side too, not just whole plugin - [x] Make sure tests for failure cases work as intended - `nu_plugin_stress_internals` added # User-Facing Changes - TUI plugins work - Non-Rust plugins could optionally choose to use this - This might behave differently, so will need to test it carefully across different operating systems # Tests + Formatting - :green_circle: `toolkit fmt` - :green_circle: `toolkit clippy` - :green_circle: `toolkit test` - :green_circle: `toolkit test stdlib` # After Submitting - [ ] Document local socket option in plugin contrib docs - [ ] Document how to do a terminal UI plugin in plugin contrib docs - [ ] Document: `EnterForeground` engine call - [ ] Document: `LeaveForeground` engine call - [ ] Document: `LocalSocket` protocol feature 2024-04-15 18:28:18 +00:00			`mod stress_internals;`