Struct nu_plugin::EngineInterface

pub struct EngineInterface { /* private fields */ }

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

Implementations

impl EngineInterface

pub fn get_config(&self) -> Result<Box<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()] 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 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 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.

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.