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
- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`

# After Submitting
- [ ] release notes
- [ ] update plugin protocol documentation: `FindDecl`, `CallDecl`
engine calls; `Identifier` engine call response
This commit is contained in:
Devyn Cairns
2024-07-18 22:54:21 -07:00
committed by GitHub
parent c19944f291
commit f3843a6176
11 changed files with 418 additions and 21 deletions

View File

@ -6,12 +6,12 @@ use nu_plugin_core::{
StreamManagerHandle,
};
use nu_plugin_protocol::{
CallInfo, CustomValueOp, EngineCall, EngineCallId, EngineCallResponse, Ordering, PluginCall,
PluginCallId, PluginCallResponse, PluginCustomValue, PluginInput, PluginOption, PluginOutput,
ProtocolInfo,
CallInfo, CustomValueOp, EngineCall, EngineCallId, EngineCallResponse, EvaluatedCall, Ordering,
PluginCall, PluginCallId, PluginCallResponse, PluginCustomValue, PluginInput, PluginOption,
PluginOutput, ProtocolInfo,
};
use nu_protocol::{
engine::Closure, Config, LabeledError, PipelineData, PluginMetadata, PluginSignature,
engine::Closure, Config, DeclId, LabeledError, PipelineData, PluginMetadata, PluginSignature,
ShellError, Signals, Span, Spanned, Value,
};
use nu_utils::SharedCow;
@ -872,6 +872,71 @@ impl EngineInterface {
}
}
/// Ask the engine for the identifier for a declaration. If found, the result can then be passed
/// to [`.call_decl()`] to call other internal commands.
///
/// See [`.call_decl()`] for an example.
pub fn find_decl(&self, name: impl Into<String>) -> Result<Option<DeclId>, ShellError> {
let call = EngineCall::FindDecl(name.into());
match self.engine_call(call)? {
EngineCallResponse::Error(err) => Err(err),
EngineCallResponse::Identifier(id) => Ok(Some(id)),
EngineCallResponse::PipelineData(PipelineData::Empty) => Ok(None),
_ => Err(ShellError::PluginFailedToDecode {
msg: "Received unexpected response type for EngineCall::FindDecl".into(),
}),
}
}
/// Ask the engine to call an internal command, using the declaration ID previously looked up
/// with [`.find_decl()`].
///
/// # Example
///
/// ```rust,no_run
/// # use nu_protocol::{Value, ShellError, PipelineData};
/// # use nu_plugin::{EngineInterface, EvaluatedCall};
/// # fn example(engine: &EngineInterface, call: &EvaluatedCall) -> Result<Value, ShellError> {
/// if let Some(decl_id) = engine.find_decl("scope commands")? {
/// let commands = engine.call_decl(
/// decl_id,
/// EvaluatedCall::new(call.head),
/// PipelineData::Empty,
/// true,
/// false,
/// )?;
/// commands.into_value(call.head)
/// } else {
/// Ok(Value::list(vec![], call.head))
/// }
/// # }
/// ```
pub fn call_decl(
&self,
decl_id: DeclId,
call: EvaluatedCall,
input: PipelineData,
redirect_stdout: bool,
redirect_stderr: bool,
) -> Result<PipelineData, ShellError> {
let call = EngineCall::CallDecl {
decl_id,
call,
input,
redirect_stdout,
redirect_stderr,
};
match self.engine_call(call)? {
EngineCallResponse::Error(err) => Err(err),
EngineCallResponse::PipelineData(data) => Ok(data),
_ => Err(ShellError::PluginFailedToDecode {
msg: "Received unexpected response type for EngineCall::CallDecl".into(),
}),
}
}
/// Tell the engine whether to disable garbage collection for this plugin.
///
/// The garbage collector is enabled by default, but plugins can turn it off (ideally