Struct nu_plugin::EngineInterface

source ·
pub struct EngineInterface { /* private fields */ }
Expand description

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

Implementations§

source§

impl EngineInterface

source

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.

source

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));
source

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);
source

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([...])))
source

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"
source

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([...]), ...})
source

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"))
source

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()?);
source

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.

source

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.

source

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
source

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
source

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§

source§

impl Clone for EngineInterface

source§

fn clone(&self) -> EngineInterface

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for EngineInterface

source§

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

Formats the value using the given formatter. Read more
source§

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.
source§

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

Write an output message.
source§

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

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

fn stream_id_sequence(&self) -> &Sequence

Get the sequence for generating new StreamIds.
source§

fn stream_manager_handle(&self) -> &StreamManagerHandle

Get the StreamManagerHandle for doing stream operations.
source§

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.
source§

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. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T> IntoSpanned for T

source§

fn into_spanned(self, span: Span) -> Spanned<T>

Wrap items together with a span into Spanned. Read more
source§

impl<D> OwoColorize for D

source§

fn fg<C>(&self) -> FgColorDisplay<'_, C, Self>
where C: Color,

Set the foreground color generically Read more
source§

fn bg<C>(&self) -> BgColorDisplay<'_, C, Self>
where C: Color,

Set the background color generically. Read more
source§

fn black(&self) -> FgColorDisplay<'_, Black, Self>

Change the foreground color to black
source§

fn on_black(&self) -> BgColorDisplay<'_, Black, Self>

Change the background color to black
source§

fn red(&self) -> FgColorDisplay<'_, Red, Self>

Change the foreground color to red
source§

fn on_red(&self) -> BgColorDisplay<'_, Red, Self>

Change the background color to red
source§

fn green(&self) -> FgColorDisplay<'_, Green, Self>

Change the foreground color to green
source§

fn on_green(&self) -> BgColorDisplay<'_, Green, Self>

Change the background color to green
source§

fn yellow(&self) -> FgColorDisplay<'_, Yellow, Self>

Change the foreground color to yellow
source§

fn on_yellow(&self) -> BgColorDisplay<'_, Yellow, Self>

Change the background color to yellow
source§

fn blue(&self) -> FgColorDisplay<'_, Blue, Self>

Change the foreground color to blue
source§

fn on_blue(&self) -> BgColorDisplay<'_, Blue, Self>

Change the background color to blue
source§

fn magenta(&self) -> FgColorDisplay<'_, Magenta, Self>

Change the foreground color to magenta
source§

fn on_magenta(&self) -> BgColorDisplay<'_, Magenta, Self>

Change the background color to magenta
source§

fn purple(&self) -> FgColorDisplay<'_, Magenta, Self>

Change the foreground color to purple
source§

fn on_purple(&self) -> BgColorDisplay<'_, Magenta, Self>

Change the background color to purple
source§

fn cyan(&self) -> FgColorDisplay<'_, Cyan, Self>

Change the foreground color to cyan
source§

fn on_cyan(&self) -> BgColorDisplay<'_, Cyan, Self>

Change the background color to cyan
source§

fn white(&self) -> FgColorDisplay<'_, White, Self>

Change the foreground color to white
source§

fn on_white(&self) -> BgColorDisplay<'_, White, Self>

Change the background color to white
source§

fn default_color(&self) -> FgColorDisplay<'_, Default, Self>

Change the foreground color to the terminal default
source§

fn on_default_color(&self) -> BgColorDisplay<'_, Default, Self>

Change the background color to the terminal default
source§

fn bright_black(&self) -> FgColorDisplay<'_, BrightBlack, Self>

Change the foreground color to bright black
source§

fn on_bright_black(&self) -> BgColorDisplay<'_, BrightBlack, Self>

Change the background color to bright black
source§

fn bright_red(&self) -> FgColorDisplay<'_, BrightRed, Self>

Change the foreground color to bright red
source§

fn on_bright_red(&self) -> BgColorDisplay<'_, BrightRed, Self>

Change the background color to bright red
source§

fn bright_green(&self) -> FgColorDisplay<'_, BrightGreen, Self>

Change the foreground color to bright green
source§

fn on_bright_green(&self) -> BgColorDisplay<'_, BrightGreen, Self>

Change the background color to bright green
source§

fn bright_yellow(&self) -> FgColorDisplay<'_, BrightYellow, Self>

Change the foreground color to bright yellow
source§

fn on_bright_yellow(&self) -> BgColorDisplay<'_, BrightYellow, Self>

Change the background color to bright yellow
source§

fn bright_blue(&self) -> FgColorDisplay<'_, BrightBlue, Self>

Change the foreground color to bright blue
source§

fn on_bright_blue(&self) -> BgColorDisplay<'_, BrightBlue, Self>

Change the background color to bright blue
source§

fn bright_magenta(&self) -> FgColorDisplay<'_, BrightMagenta, Self>

Change the foreground color to bright magenta
source§

fn on_bright_magenta(&self) -> BgColorDisplay<'_, BrightMagenta, Self>

Change the background color to bright magenta
source§

fn bright_purple(&self) -> FgColorDisplay<'_, BrightMagenta, Self>

Change the foreground color to bright purple
source§

fn on_bright_purple(&self) -> BgColorDisplay<'_, BrightMagenta, Self>

Change the background color to bright purple
source§

fn bright_cyan(&self) -> FgColorDisplay<'_, BrightCyan, Self>

Change the foreground color to bright cyan
source§

fn on_bright_cyan(&self) -> BgColorDisplay<'_, BrightCyan, Self>

Change the background color to bright cyan
source§

fn bright_white(&self) -> FgColorDisplay<'_, BrightWhite, Self>

Change the foreground color to bright white
source§

fn on_bright_white(&self) -> BgColorDisplay<'_, BrightWhite, Self>

Change the background color to bright white
source§

fn bold(&self) -> BoldDisplay<'_, Self>

Make the text bold
source§

fn dimmed(&self) -> DimDisplay<'_, Self>

Make the text dim
source§

fn italic(&self) -> ItalicDisplay<'_, Self>

Make the text italicized
source§

fn underline(&self) -> UnderlineDisplay<'_, Self>

Make the text italicized
Make the text blink
Make the text blink (but fast!)
source§

fn reversed(&self) -> ReversedDisplay<'_, Self>

Swap the foreground and background colors
source§

fn hidden(&self) -> HiddenDisplay<'_, Self>

Hide the text
source§

fn strikethrough(&self) -> StrikeThroughDisplay<'_, Self>

Cross out the text
source§

fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self>
where Color: DynColor,

Set the foreground color at runtime. Only use if you do not know which color will be used at compile-time. If the color is constant, use either OwoColorize::fg or a color-specific method, such as OwoColorize::green, Read more
source§

fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self>
where Color: DynColor,

Set the background color at runtime. Only use if you do not know what color to use at compile-time. If the color is constant, use either OwoColorize::bg or a color-specific method, such as OwoColorize::on_yellow, Read more
source§

fn fg_rgb<const R: u8, const G: u8, const B: u8>( &self, ) -> FgColorDisplay<'_, CustomColor<R, G, B>, Self>

Set the foreground color to a specific RGB value.
source§

fn bg_rgb<const R: u8, const G: u8, const B: u8>( &self, ) -> BgColorDisplay<'_, CustomColor<R, G, B>, Self>

Set the background color to a specific RGB value.
source§

fn truecolor(&self, r: u8, g: u8, b: u8) -> FgDynColorDisplay<'_, Rgb, Self>

Sets the foreground color to an RGB value.
source§

fn on_truecolor(&self, r: u8, g: u8, b: u8) -> BgDynColorDisplay<'_, Rgb, Self>

Sets the background color to an RGB value.
source§

fn style(&self, style: Style) -> Styled<&Self>

Apply a runtime-determined style
source§

impl<T> Pointable for T

source§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> TryClone for T
where T: Clone,

source§

fn try_clone(&self) -> Result<T, Error>

Clones self, possibly returning an error.
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.