Struct nu_protocol::engine::Stack

pub struct Stack {
    pub vars: HashMap<VarId, Value>,
    pub env_vars: Vec<HashMap<String, Value>>,
    pub env_hidden: HashSet<String>,
}

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: HashMap<VarId, Value>

Variables

env_vars: Vec<HashMap<String, Value>>

Environment variables arranged as a stack to be able to recover values from parent scopes

env_hidden: HashSet<String>

Tells which environment variables from engine state are hidden. We don’t need to track the env vars in the stack since we can just delete them.

Implementations

impl Stack

pub fn new() -> Stack

pub fn with_env(
    &mut self,
    env_vars: &[HashMap<String, Value>],
    env_hidden: &HashSet<String>
)

pub fn get_var(&self, var_id: VarId, span: Span) -> Result<Value, ShellError>

pub fn get_var_with_origin(
    &self,
    var_id: VarId,
    span: Span
) -> Result<Value, ShellError>

pub fn add_var(&mut self, var_id: VarId, value: Value)

pub fn add_env_var(&mut self, var: String, value: Value)

pub fn captures_to_stack(&self, captures: &HashMap<VarId, Value>) -> Stack

pub fn gather_captures(&self, captures: &[VarId]) -> Stack

pub fn get_env_vars(&self, engine_state: &EngineState) -> HashMap<String, Value>

Flatten the env var scope frames into one frame

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
) -> Option<Value>

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

pub fn update_config(&mut self, name: &str, value: Value)

pub fn print_stack(&self)

Trait Implementations

impl Clone for Stack

fn clone(&self) -> Stack

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Stack

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

Formats the value using the given formatter.

impl Default for Stack

fn default() -> Self

Returns the “default value” for a type.