Struct nu_protocol::engine::Stack
source · pub struct Stack {
pub vars: Vec<(VarId, Value)>,
pub env_vars: Vec<EnvVars>,
pub env_hidden: HashMap<String, HashSet<String>>,
pub active_overlays: Vec<String>,
pub recursion_count: u64,
pub parent_stack: Option<Arc<Stack>>,
pub parent_deletions: Vec<VarId>,
/* private fields */
}
Expand description
A runtime value stack used during evaluation
A note on implementation:
We previously set up the stack in a traditional way, where stack frames had parents which would represent other frames that you might return to when exiting a function.
While experimenting with blocks, we found that we needed to have closure captures of variables seen outside of the blocks, so that they blocks could be run in a way that was both thread-safe and followed the restrictions for closures applied to iterators. The end result left us with closure-captured single stack frames that blocks could see.
Blocks make up the only scope and stack definition abstraction in Nushell. As a result, we were creating closure captures at any point we wanted to have a Block value we could safely evaluate in any context. This meant that the parents were going largely unused, with captured variables taking their place. The end result is this, where we no longer have separate frames, but instead use the Stack as a way of representing the local and closure-captured state.
Fields§
§vars: Vec<(VarId, Value)>
Variables
env_vars: Vec<EnvVars>
Environment variables arranged as a stack to be able to recover values from parent scopes
Tells which environment variables from engine state are hidden, per overlay.
active_overlays: Vec<String>
List of active overlays
recursion_count: u64
§parent_stack: Option<Arc<Stack>>
§parent_deletions: Vec<VarId>
Variables that have been deleted (this is used to hide values from parent stack lookups)
Implementations§
source§impl Stack
impl Stack
sourcepub fn new() -> Self
pub fn new() -> Self
Create a new stack.
stdout and stderr will be set to OutDest::Inherit
. So, if the last command is an external command,
then its output will be forwarded to the terminal/stdio streams.
Use Stack::capture
afterwards if you need to evaluate an expression to a Value
(as opposed to a PipelineData
).
sourcepub fn unwrap_unique(stack_arc: Arc<Stack>) -> Stack
pub fn unwrap_unique(stack_arc: Arc<Stack>) -> Stack
Unwrap a uniquely-owned stack.
In debug mode, this panics if there are multiple references. In production this will instead clone the underlying stack.
sourcepub fn with_parent(parent: Arc<Stack>) -> Stack
pub fn with_parent(parent: Arc<Stack>) -> Stack
Create a new child stack from a parent.
Changes from this child can be merged back into the parent with Stack::with_changes_from_child
sourcepub fn with_changes_from_child(parent: Arc<Stack>, child: Stack) -> Stack
pub fn with_changes_from_child(parent: Arc<Stack>, child: Stack) -> Stack
Take an Arc of a parent (assumed to be unique), and a child, and apply all the changes from a child back to the parent.
Here it is assumed that child was created with a call to Stack::with_parent with parent
pub fn with_env( &mut self, env_vars: &[EnvVars], env_hidden: &HashMap<String, HashSet<String>> )
sourcepub fn get_var(&self, var_id: VarId, span: Span) -> Result<Value, ShellError>
pub fn get_var(&self, var_id: VarId, span: Span) -> Result<Value, ShellError>
Lookup a variable, erroring if it is not found
The passed-in span will be used to tag the value
sourcepub fn get_var_with_origin(
&self,
var_id: VarId,
span: Span
) -> Result<Value, ShellError>
pub fn get_var_with_origin( &self, var_id: VarId, span: Span ) -> Result<Value, ShellError>
Lookup a variable, erroring if it is not found
While the passed-in span will be used for errors, the returned value has the span from where it was originally defined
pub fn add_var(&mut self, var_id: VarId, value: Value)
pub fn remove_var(&mut self, var_id: VarId)
pub fn add_env_var(&mut self, var: String, value: Value)
pub fn last_overlay_name(&self) -> Result<String, ShellError>
pub fn captures_to_stack(&self, captures: Vec<(VarId, Value)>) -> Stack
pub fn captures_to_stack_preserve_out_dest( &self, captures: Vec<(VarId, Value)> ) -> Stack
pub fn gather_captures( &self, engine_state: &EngineState, captures: &[VarId] ) -> Stack
sourcepub fn get_env_vars(&self, engine_state: &EngineState) -> HashMap<String, Value>
pub fn get_env_vars(&self, engine_state: &EngineState) -> HashMap<String, Value>
Flatten the env var scope frames into one frame
sourcepub fn get_stack_env_vars(&self) -> HashMap<String, Value>
pub fn get_stack_env_vars(&self) -> HashMap<String, Value>
Get flattened environment variables only from the stack
sourcepub fn get_stack_overlay_env_vars(
&self,
overlay_name: &str
) -> HashMap<String, Value>
pub fn get_stack_overlay_env_vars( &self, overlay_name: &str ) -> HashMap<String, Value>
Get flattened environment variables only from the stack and one overlay
sourcepub fn get_env_var_names(&self, engine_state: &EngineState) -> HashSet<String>
pub fn get_env_var_names(&self, engine_state: &EngineState) -> HashSet<String>
Same as get_env_vars, but returns only the names as a HashSet
pub fn get_env_var( &self, engine_state: &EngineState, name: &str ) -> Option<Value>
pub fn has_env_var(&self, engine_state: &EngineState, name: &str) -> bool
pub fn remove_env_var(&mut self, engine_state: &EngineState, name: &str) -> bool
pub fn has_env_overlay(&self, name: &str, engine_state: &EngineState) -> bool
pub fn is_overlay_active(&self, name: &str) -> bool
pub fn add_overlay(&mut self, name: String)
pub fn remove_overlay(&mut self, name: &str)
sourcepub fn stdout(&self) -> &OutDest
pub fn stdout(&self) -> &OutDest
Returns the OutDest
to use for the current command’s stdout.
This will be the pipe redirection if one is set,
otherwise it will be the current file redirection,
otherwise it will be the process’s stdout indicated by OutDest::Inherit
.
sourcepub fn stderr(&self) -> &OutDest
pub fn stderr(&self) -> &OutDest
Returns the OutDest
to use for the current command’s stderr.
This will be the pipe redirection if one is set,
otherwise it will be the current file redirection,
otherwise it will be the process’s stderr indicated by OutDest::Inherit
.
sourcepub fn pipe_stdout(&self) -> Option<&OutDest>
pub fn pipe_stdout(&self) -> Option<&OutDest>
Returns the OutDest
of the pipe redirection applied to the current command’s stdout.
sourcepub fn pipe_stderr(&self) -> Option<&OutDest>
pub fn pipe_stderr(&self) -> Option<&OutDest>
Returns the OutDest
of the pipe redirection applied to the current command’s stderr.
sourcepub fn start_capture(&mut self) -> StackCaptureGuard<'_>
pub fn start_capture(&mut self) -> StackCaptureGuard<'_>
Temporarily set the pipe stdout redirection to OutDest::Capture
.
This is used before evaluating an expression into a Value
.
sourcepub fn use_call_arg_out_dest(&mut self) -> StackCallArgGuard<'_>
pub fn use_call_arg_out_dest(&mut self) -> StackCallArgGuard<'_>
Temporarily use the output redirections in the parent scope.
This is used before evaluating an argument to a call.
sourcepub fn push_redirection(
&mut self,
stdout: Option<Redirection>,
stderr: Option<Redirection>
) -> StackIoGuard<'_>
pub fn push_redirection( &mut self, stdout: Option<Redirection>, stderr: Option<Redirection> ) -> StackIoGuard<'_>
Temporarily apply redirections to stdout and/or stderr.
sourcepub fn capture(self) -> Self
pub fn capture(self) -> Self
Mark stdout for the last command as OutDest::Capture
.
This will irreversibly alter the output redirections, and so it only makes sense to use this on an owned Stack
(which is why this function does not take &mut self
).
See Stack::start_capture
which can temporarily set stdout as OutDest::Capture
for a mutable Stack
reference.
sourcepub fn reset_out_dest(self) -> Self
pub fn reset_out_dest(self) -> Self
Clears any pipe and file redirections and resets stdout and stderr to OutDest::Inherit
.
This will irreversibly reset the output redirections, and so it only makes sense to use this on an owned Stack
(which is why this function does not take &mut self
).
sourcepub fn reset_pipes(self) -> Self
pub fn reset_pipes(self) -> Self
Clears any pipe redirections, keeping the current stdout and stderr.
This will irreversibly reset some of the output redirections, and so it only makes sense to use this on an owned Stack
(which is why this function does not take &mut self
).
Trait Implementations§
Auto Trait Implementations§
impl Freeze for Stack
impl !RefUnwindSafe for Stack
impl Send for Stack
impl Sync for Stack
impl Unpin for Stack
impl !UnwindSafe for Stack
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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 moresource§impl<T> IntoSpanned for T
impl<T> IntoSpanned for T
source§impl<D> OwoColorize for D
impl<D> OwoColorize for D
source§fn fg<C>(&self) -> FgColorDisplay<'_, C, Self>where
C: Color,
fn fg<C>(&self) -> FgColorDisplay<'_, C, Self>where
C: Color,
source§fn bg<C>(&self) -> BgColorDisplay<'_, C, Self>where
C: Color,
fn bg<C>(&self) -> BgColorDisplay<'_, C, Self>where
C: Color,
source§fn black(&self) -> FgColorDisplay<'_, Black, Self>
fn black(&self) -> FgColorDisplay<'_, Black, Self>
source§fn on_black(&self) -> BgColorDisplay<'_, Black, Self>
fn on_black(&self) -> BgColorDisplay<'_, Black, Self>
source§fn red(&self) -> FgColorDisplay<'_, Red, Self>
fn red(&self) -> FgColorDisplay<'_, Red, Self>
source§fn on_red(&self) -> BgColorDisplay<'_, Red, Self>
fn on_red(&self) -> BgColorDisplay<'_, Red, Self>
source§fn green(&self) -> FgColorDisplay<'_, Green, Self>
fn green(&self) -> FgColorDisplay<'_, Green, Self>
source§fn on_green(&self) -> BgColorDisplay<'_, Green, Self>
fn on_green(&self) -> BgColorDisplay<'_, Green, Self>
source§fn yellow(&self) -> FgColorDisplay<'_, Yellow, Self>
fn yellow(&self) -> FgColorDisplay<'_, Yellow, Self>
source§fn on_yellow(&self) -> BgColorDisplay<'_, Yellow, Self>
fn on_yellow(&self) -> BgColorDisplay<'_, Yellow, Self>
source§fn blue(&self) -> FgColorDisplay<'_, Blue, Self>
fn blue(&self) -> FgColorDisplay<'_, Blue, Self>
source§fn on_blue(&self) -> BgColorDisplay<'_, Blue, Self>
fn on_blue(&self) -> BgColorDisplay<'_, Blue, Self>
source§fn magenta(&self) -> FgColorDisplay<'_, Magenta, Self>
fn magenta(&self) -> FgColorDisplay<'_, Magenta, Self>
source§fn on_magenta(&self) -> BgColorDisplay<'_, Magenta, Self>
fn on_magenta(&self) -> BgColorDisplay<'_, Magenta, Self>
source§fn purple(&self) -> FgColorDisplay<'_, Magenta, Self>
fn purple(&self) -> FgColorDisplay<'_, Magenta, Self>
source§fn on_purple(&self) -> BgColorDisplay<'_, Magenta, Self>
fn on_purple(&self) -> BgColorDisplay<'_, Magenta, Self>
source§fn cyan(&self) -> FgColorDisplay<'_, Cyan, Self>
fn cyan(&self) -> FgColorDisplay<'_, Cyan, Self>
source§fn on_cyan(&self) -> BgColorDisplay<'_, Cyan, Self>
fn on_cyan(&self) -> BgColorDisplay<'_, Cyan, Self>
source§fn white(&self) -> FgColorDisplay<'_, White, Self>
fn white(&self) -> FgColorDisplay<'_, White, Self>
source§fn on_white(&self) -> BgColorDisplay<'_, White, Self>
fn on_white(&self) -> BgColorDisplay<'_, White, Self>
source§fn default_color(&self) -> FgColorDisplay<'_, Default, Self>
fn default_color(&self) -> FgColorDisplay<'_, Default, Self>
source§fn on_default_color(&self) -> BgColorDisplay<'_, Default, Self>
fn on_default_color(&self) -> BgColorDisplay<'_, Default, Self>
source§fn bright_black(&self) -> FgColorDisplay<'_, BrightBlack, Self>
fn bright_black(&self) -> FgColorDisplay<'_, BrightBlack, Self>
source§fn on_bright_black(&self) -> BgColorDisplay<'_, BrightBlack, Self>
fn on_bright_black(&self) -> BgColorDisplay<'_, BrightBlack, Self>
source§fn bright_red(&self) -> FgColorDisplay<'_, BrightRed, Self>
fn bright_red(&self) -> FgColorDisplay<'_, BrightRed, Self>
source§fn on_bright_red(&self) -> BgColorDisplay<'_, BrightRed, Self>
fn on_bright_red(&self) -> BgColorDisplay<'_, BrightRed, Self>
source§fn bright_green(&self) -> FgColorDisplay<'_, BrightGreen, Self>
fn bright_green(&self) -> FgColorDisplay<'_, BrightGreen, Self>
source§fn on_bright_green(&self) -> BgColorDisplay<'_, BrightGreen, Self>
fn on_bright_green(&self) -> BgColorDisplay<'_, BrightGreen, Self>
source§fn bright_yellow(&self) -> FgColorDisplay<'_, BrightYellow, Self>
fn bright_yellow(&self) -> FgColorDisplay<'_, BrightYellow, Self>
source§fn on_bright_yellow(&self) -> BgColorDisplay<'_, BrightYellow, Self>
fn on_bright_yellow(&self) -> BgColorDisplay<'_, BrightYellow, Self>
source§fn bright_blue(&self) -> FgColorDisplay<'_, BrightBlue, Self>
fn bright_blue(&self) -> FgColorDisplay<'_, BrightBlue, Self>
source§fn on_bright_blue(&self) -> BgColorDisplay<'_, BrightBlue, Self>
fn on_bright_blue(&self) -> BgColorDisplay<'_, BrightBlue, Self>
source§fn bright_magenta(&self) -> FgColorDisplay<'_, BrightMagenta, Self>
fn bright_magenta(&self) -> FgColorDisplay<'_, BrightMagenta, Self>
source§fn on_bright_magenta(&self) -> BgColorDisplay<'_, BrightMagenta, Self>
fn on_bright_magenta(&self) -> BgColorDisplay<'_, BrightMagenta, Self>
source§fn bright_purple(&self) -> FgColorDisplay<'_, BrightMagenta, Self>
fn bright_purple(&self) -> FgColorDisplay<'_, BrightMagenta, Self>
source§fn on_bright_purple(&self) -> BgColorDisplay<'_, BrightMagenta, Self>
fn on_bright_purple(&self) -> BgColorDisplay<'_, BrightMagenta, Self>
source§fn bright_cyan(&self) -> FgColorDisplay<'_, BrightCyan, Self>
fn bright_cyan(&self) -> FgColorDisplay<'_, BrightCyan, Self>
source§fn on_bright_cyan(&self) -> BgColorDisplay<'_, BrightCyan, Self>
fn on_bright_cyan(&self) -> BgColorDisplay<'_, BrightCyan, Self>
source§fn bright_white(&self) -> FgColorDisplay<'_, BrightWhite, Self>
fn bright_white(&self) -> FgColorDisplay<'_, BrightWhite, Self>
source§fn on_bright_white(&self) -> BgColorDisplay<'_, BrightWhite, Self>
fn on_bright_white(&self) -> BgColorDisplay<'_, BrightWhite, Self>
source§fn bold(&self) -> BoldDisplay<'_, Self>
fn bold(&self) -> BoldDisplay<'_, Self>
source§fn dimmed(&self) -> DimDisplay<'_, Self>
fn dimmed(&self) -> DimDisplay<'_, Self>
source§fn italic(&self) -> ItalicDisplay<'_, Self>
fn italic(&self) -> ItalicDisplay<'_, Self>
source§fn underline(&self) -> UnderlineDisplay<'_, Self>
fn underline(&self) -> UnderlineDisplay<'_, Self>
source§fn blink(&self) -> BlinkDisplay<'_, Self>
fn blink(&self) -> BlinkDisplay<'_, Self>
source§fn blink_fast(&self) -> BlinkFastDisplay<'_, Self>
fn blink_fast(&self) -> BlinkFastDisplay<'_, Self>
source§fn reversed(&self) -> ReversedDisplay<'_, Self>
fn reversed(&self) -> ReversedDisplay<'_, Self>
source§fn strikethrough(&self) -> StrikeThroughDisplay<'_, Self>
fn strikethrough(&self) -> StrikeThroughDisplay<'_, Self>
source§fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self>where
Color: DynColor,
fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self>where
Color: DynColor,
OwoColorize::fg
or
a color-specific method, such as OwoColorize::green
, Read moresource§fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self>where
Color: DynColor,
fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self>where
Color: DynColor,
OwoColorize::bg
or
a color-specific method, such as OwoColorize::on_yellow
, Read more