Struct EngineInterface

pub struct EngineInterface { /* private fields */ }

A reference through which the nushell engine can be interacted with during execution.

Implementations

impl EngineInterface

pub fn is_using_stdio(&self) -> bool

Returns true if the plugin is communicating on stdio. When this is the case, stdin and stdout should not be used by the plugin for other purposes.

If the plugin can not be used without access to stdio, an error should be presented to the user instead.

pub fn register_signal_handler( &self, handler: Handler, ) -> Result<HandlerGuard, ShellError>

Register a closure which will be called when the engine receives an interrupt signal. Returns a RAII guard that will keep the closure alive until it is dropped.

pub fn get_config(&self) -> Result<Arc<Config>, ShellError>

Get the full shell configuration from the engine. As this is quite a large object, it is provided on request only.

Example

Format a value in the user’s preferred way:

let config = engine.get_config()?;
eprintln!("{}", value.to_expanded_string(", ", &config));

pub fn get_plugin_config(&self) -> Result<Option<Value>, ShellError>

Get the plugin-specific configuration from the engine. This lives in $env.config.plugins.NAME for a plugin named NAME. If the config is set to a closure, it is automatically evaluated each time.

Example

Print this plugin’s config:

let config = engine.get_plugin_config()?;
eprintln!("{:?}", config);

pub fn get_env_var( &self, name: impl Into<String>, ) -> Result<Option<Value>, ShellError>

Get an environment variable from the engine.

Returns Some(value) if present, and None if not found.

Example

Get $env.PATH:

engine.get_env_var("PATH") // => Ok(Some(Value::List([...])))

pub fn get_current_dir(&self) -> Result<String, ShellError>

Get the current working directory from the engine. The result is always an absolute path.

Example

engine.get_current_dir() // => "/home/user"

pub fn get_env_vars(&self) -> Result<HashMap<String, Value>, ShellError>

Get all environment variables from the engine.

Since this is quite a large map that has to be sent, prefer to use [.get_env_var()] (Self::get_env_var) if the variables needed are known ahead of time and there are only a small number needed.

Example

engine.get_env_vars() // => Ok({"PATH": Value::List([...]), ...})

pub fn add_env_var( &self, name: impl Into<String>, value: Value, ) -> Result<(), ShellError>

Set an environment variable in the caller’s scope.

If called after the plugin response has already been sent (i.e. during a stream), this will only affect the environment for engine calls related to this plugin call, and will not be propagated to the environment of the caller.

Example

engine.add_env_var("FOO", Value::test_string("bar"))

pub fn get_help(&self) -> Result<String, ShellError>

Get the help string for the current command.

This returns the same string as passing --help would, and can be used for the top-level command in a command group that doesn’t do anything on its own (e.g. query).

Example

eprintln!("{}", engine.get_help()?);

pub fn enter_foreground(&self) -> Result<ForegroundGuard, ShellError>

Returns a guard that will keep the plugin in the foreground as long as the guard is alive.

Moving the plugin to the foreground is necessary for plugins that need to receive input and signals directly from the terminal.

The exact implementation is operating system-specific. On Unix, this ensures that the plugin process becomes part of the process group controlling the terminal.

pub fn get_span_contents(&self, span: Span) -> Result<Vec<u8>, ShellError>

Get the contents of a Span from the engine.

This method returns Vec<u8> as it’s possible for the matched span to not be a valid UTF-8 string, perhaps because it sliced through the middle of a UTF-8 byte sequence, as the offsets are byte-indexed. Use String::from_utf8_lossy() for display if necessary.

pub fn eval_closure_with_stream( &self, closure: &Spanned<Closure>, positional: Vec<Value>, input: PipelineData, redirect_stdout: bool, redirect_stderr: bool, ) -> Result<PipelineData, ShellError>

Ask the engine to evaluate a closure. Input to the closure is passed as a stream, and the output is available as a stream.

Set redirect_stdout to true to capture the standard output stream of an external command, if the closure results in an external command.

Set redirect_stderr to true to capture the standard error stream of an external command, if the closure results in an external command.

Example

Invoked as:

my_command { seq 1 $in | each { |n| $"Hello, ($n)" } }

let closure = call.req(0)?;
let input = PipelineData::Value(Value::int(4, call.head), None);
let output = engine.eval_closure_with_stream(
    &closure,
    vec![],
    input,
    true,
    false,
)?;
for value in output {
    eprintln!("Closure says: {}", value.as_str()?);
}

Output:

Closure says: Hello, 1
Closure says: Hello, 2
Closure says: Hello, 3
Closure says: Hello, 4

pub fn eval_closure( &self, closure: &Spanned<Closure>, positional: Vec<Value>, input: Option<Value>, ) -> Result<Value, ShellError>

Ask the engine to evaluate a closure. Input is optionally passed as a Value, and output of the closure is collected to a Value even if it is a stream.

If the closure results in an external command, the return value will be a collected string or binary value of the standard output stream of that command, similar to calling eval_closure_with_stream() with redirect_stdout = true and redirect_stderr = false.

Use eval_closure_with_stream() if more control over the input and output is desired.

Example

Invoked as:

my_command { |number| $number + 1}

let closure = call.req(0)?;
for n in 0..4 {
    let result = engine.eval_closure(&closure, vec![Value::int(n, call.head)], None)?;
    eprintln!("{} => {}", n, result.as_int()?);
}

Output:

0 => 1
1 => 2
2 => 3
3 => 4

pub fn find_decl( &self, name: impl Into<String>, ) -> Result<Option<DeclId>, ShellError>

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 call_decl( &self, decl_id: DeclId, call: EvaluatedCall, input: PipelineData, redirect_stdout: bool, redirect_stderr: bool, ) -> Result<PipelineData, ShellError>

Ask the engine to call an internal command, using the declaration ID previously looked up with .find_decl().

Example

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 set_gc_disabled(&self, disabled: bool) -> Result<(), ShellError>

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 temporarily) as necessary to implement functionality that requires the plugin to stay running for longer than the engine can automatically determine.

The user can still stop the plugin if they want to with the plugin stop command.

pub fn signals(&self) -> &Signals

Trait Implementations

impl Clone for EngineInterface

fn clone(&self) -> EngineInterface

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EngineInterface

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Interface for EngineInterface

type Output = PluginOutput

The output message type, which must be capable of encapsulating a StreamMessage.

type DataContext = ()

Any context required to construct PipelineData. Can be () if not needed.

fn write(&self, output: PluginOutput) -> Result<(), ShellError>

Write an output message.

fn flush(&self) -> Result<(), ShellError>

Flush the output buffer, so messages are visible to the other side.

fn stream_id_sequence(&self) -> &Sequence

Get the sequence for generating new StreamIds.

fn stream_manager_handle(&self) -> &StreamManagerHandle

Get the StreamManagerHandle for doing stream operations.

fn prepare_pipeline_data( &self, data: PipelineData, _context: &(), ) -> Result<PipelineData, ShellError>

Prepare PipelineData to be written. This is called by init_write_pipeline_data() as a hook so that values that need special handling can be taken care of.

fn init_write_pipeline_data( &self, data: PipelineData, context: &Self::DataContext, ) -> Result<(PipelineDataHeader, PipelineDataWriter<Self>), ShellError>

Initialize a write for PipelineData. This returns two parts: the header, which can be embedded in the particular message that references the stream, and a writer, which will write out all of the data in the pipeline when .write() is called.