Struct Stack 

pub struct Stack {

    pub vars: Vec<(VarId, Value)>,
    pub env_vars: Vec<Arc<EnvVars>>,
    pub env_hidden: Arc<HashMap<String, HashSet<EnvName>>>,
    pub env_hide_history: Arc<HashMap<String, HashSet<EnvName>>>,
    pub active_overlays: Vec<String>,
    pub arguments: ArgumentStack,
    pub error_handlers: ErrorHandlerStack,
    pub finally_run_handlers: ErrorHandlerStack,
    pub recursion_count: u64,
    pub parent_stack: Option<Arc<Stack>>,
    pub parent_deletions: Vec<VarId>,
    pub deletions: Vec<VarId>,
    pub config: Option<Arc<Config>>,
    pub suppress_stdin: bool,
    pub active_scope_bindings: Vec<Arc<ScopeBindings>>,
    pub ir_scope_regions: Vec<ScopeRegion>,
    pub ir_instruction_index: Option<usize>,
    /* private fields */
}

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<Arc<EnvVars>>

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

env_hidden: Arc<HashMap<String, HashSet<EnvName>>>

Tells which environment variables from engine state are hidden, per overlay.

env_hide_history: Arc<HashMap<String, HashSet<EnvName>>>

Tracks env vars hidden in this stack context to report repeated hide-env calls.

This is separate from env_hidden: env_hidden controls runtime visibility for engine state values, while env_hide_history preserves command semantics for repeated hides.

active_overlays: Vec<String>

List of active overlays

arguments: ArgumentStack

Argument stack for IR evaluation

error_handlers: ErrorHandlerStack

Error handler stack for IR evaluation

finally_run_handlers: ErrorHandlerStack

Finally handler stack for IR evaluation

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)

deletions: Vec<VarId>

Variables deleted in this stack

config: Option<Arc<Config>>

Locally updated config. Use .get_config() to access correctly.

suppress_stdin: bool

When true, external processes spawned with PipelineData::Empty input receive /dev/null for stdin instead of inheriting the terminal.

active_scope_bindings: Vec<Arc<ScopeBindings>>

Active block-local scope bindings (commands/modules), outer → inner.

Pushed when evaluating a whole block via eval_ir_block (closures, custom commands). Used by scope together with Self::ir_scope_regions.

ir_scope_regions: Vec<ScopeRegion>

Scope regions of the IR block currently being evaluated (inlined keyword bodies).

ir_instruction_index: Option<usize>

Current program counter while evaluating IR (for matching Self::ir_scope_regions).

Implementations

impl Stack

pub const ANS_LAST_RESULT_METADATA_KEY: &str = "ans_last_result"

Marker key in PipelineMetadata::custom identifying pipeline data loaded from $ans.

Used so IR cell-path follow only reattaches last-result metadata for $ans.last, not every unrelated record field named last.

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::collect_value afterwards if you need to evaluate an expression to a Value (as opposed to a PipelineData).

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

pub fn push_scope_bindings(&mut self, bindings: Arc<ScopeBindings>)

Push block-local scope bindings for the duration of evaluating a whole block.

pub fn pop_scope_bindings(&mut self)

Pop the most recently pushed whole-block scope bindings.

pub fn with_changes_from_child(parent: Arc<Stack>, child: Stack) -> Stack

Take an Arc parent, and a child, and apply all the changes from a child back to the parent.

Here it is assumed that child was created by a call to Stack::with_parent with parent.

For this to be performant and not clone parent, child should be the only other referencer of parent.

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

pub fn clear_last_result(&mut self)

Drop the entire $ans slot (full clear).

pub fn clear_last_result_payload(&mut self)

Drop only $ans.last and its metadata/truncation flags, freeing payload memory.

Leaves present, exit_code, duration, and command unchanged so a budget of 0 can still expose timing/exit status/source without retaining the pipeline value.

pub fn set_last_result( &mut self, value: Value, metadata: Option<PipelineMetadata>, budget: usize, )

Store value as $ans.last, enforcing budget via truncation.

When budget == 0, payload capture is disabled (clears .last only; exit code, duration, and command stay). Preserves pipeline metadata (e.g. path_columns used for ls coloring) so replaying $ans.last can match the original display.

pub fn store_last_result_raw( &mut self, value: Value, metadata: Option<PipelineMetadata>, truncated: bool, )

Install an already-budgeted $ans.last value (caller handled truncation).

Marks $ans present. Does not reset exit_code / duration / command (those are updated by Self::snapshot_ans_repl_metadata at end of each REPL line).

pub fn snapshot_ans_repl_metadata( &mut self, engine_state: &EngineState, duration: Duration, command: impl Into<String>, )

After a REPL user command finishes: refresh $ans.exit_code, $ans.duration, and $ans.command.

command is the exact reedline buffer for this line (same text history stores). Always marks $ans present so every user-typed line gets exit code, duration, and source (empty Enter / auto-cd do not call this). When budget == 0, also drops $ans.last (and its memory) so the record is { exit_code, duration, command } without a last field. When budget is positive, any .last already stored this line (or earlier) is kept.

pub fn last_result_metadata(&self) -> Option<PipelineMetadata>

Pipeline metadata associated with the stored $ans.last, if any.

pub fn last_result_memory_size(&self) -> usize

Estimated memory size of the stored $ans.last payload (0 if unset).

pub fn last_result_pipeline_data(&self, span: Span) -> PipelineData

Build PipelineData for $ans, restoring stored pipeline metadata on the record so $ans.last cell-path access can reattach it (see IR FollowCellPath).

pub fn last_result_was_truncated(&self) -> bool

Whether the currently stored $ans.last was truncated.

pub fn defer_last_result_truncation_warning(&self)

On $ans access after a truncated store: schedule a warning for after output prints.

Does not print anything. Call Self::take_last_result_warn_deferred after display so the truncated value is shown first, then the warning.

pub fn last_result_warn_pending(&self) -> bool

Whether a truncation warning is waiting to be shown after print (does not clear).

pub fn take_last_result_warn_deferred(&self) -> bool

Take the deferred truncation warning flag (clears it).

Returns true once after a truncated $ans was accessed; intended to be called after the pipeline has been printed so the warning appears below the data.

pub fn flush_last_result_truncation_warning( &self, engine_state: &EngineState, span: Span, )

Report a deferred last-result truncation warning, if any.

Prefer calling this after printing so output is not scrolled away by the warning.

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

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 get_config(&self, engine_state: &EngineState) -> Arc<Config>

Get the local config if set, otherwise the config from the engine state.

This is the canonical way to get Config when Stack is available.

pub fn update_config( &mut self, engine_state: &EngineState, ) -> Result<(), ShellError>

Update the local config with the config stored in the config environment variable. Run this after assigning to $env.config.

The config will be updated with successfully parsed values even if an error occurs.

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

pub fn get_var_mut(&mut self, var_id: VarId) -> Option<&mut Value>

Return a mutable reference to a variable’s value for in-place mutation.

Looks up the variable in the current stack frame first. If not found, pulls it from the parent chain into the current frame (cloning it once). This enables zero-clone mutation for local mut variables: use get_var_mut + mutate instead of lookup_var (clone) + mutate + add_var (move back).

pub fn upsert_var_cell_path( &mut self, var_id: VarId, members: &[PathMember], new_value: Value, span: Span, ) -> Result<(), ShellError>

Upsert a cell path on a variable in place (shared by AST and IR assignment paths).

Errors with ShellError::VariableNotFoundAtRuntime if the variable is not on this stack or its parent chain.

pub fn remove_var(&mut self, var_id: VarId)

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

pub fn set_last_exit_code(&mut self, code: i32, span: Span)

pub fn set_last_error(&mut self, error: &ShellError)

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

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

Like [captures_to_stack_preserve_out_dest], but sets the new scope up to collect output into a Value.

pub fn captures_to_stack_preserve_out_dest( &self, captures: Vec<(VarId, Value)>, ) -> Stack

Creates a derived stack for a new scope, with the given captures.

The caller is retained as Self::parent_stack so outer variables remain visible to scope variables (and other stack lookups that walk parents). Captured values are still copied onto this stack for isolation of the closure’s own locals.

pub fn gather_captures( &self, engine_state: &EngineState, captures: &[(VarId, Span)], ) -> 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_stack_env_vars(&self) -> HashMap<String, Value>

Get flattened environment variables only from the stack

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

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

Get hidden envs, but without envs defined previously in excluded_overlay_name.

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<'a>( &'a self, engine_state: &'a EngineState, name: &str, ) -> Option<&'a 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

Removes name from the stack. If it was not on the stack and lives in engine_state, marks it hidden in env_hidden. Returns true if the variable was found and removed.

Use this for temporary bookkeeping removals (e.g. FILE_PWD, canary variables) where the goal is to clean up a stack-level value without necessarily hiding the engine-state baseline. Use Self::hide_env_var when the intent is to make the variable invisible to subsequent lookups (e.g. hide-env).

pub fn is_env_var_hidden(&self, name: &str) -> bool

Returns true if name was hidden in this stack context (e.g. by hide-env), either by masking an engine_state baseline value or by removing a stack-level value.

A variable that was re-added after being hidden is still reported as hidden here, so only use this after a failed lookup to distinguish “hidden” from “never set”.

pub fn hide_env_var(&mut self, engine_state: &EngineState, name: &str) -> bool

Hides name so it is no longer visible to subsequent lookups. Removes it from the stack and, if no stack shadowing remains, also marks the engine_state baseline as hidden in env_hidden. Returns true if the variable was found.

This is the correct method for hide-env and redirect_env; it ensures that a variable set in engine_state (from a previous REPL merge) cannot be seen after hiding even when a stack-level override (e.g. an empty-string assignment) was present at hide time.

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)

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.

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.

pub fn pipe_stdout(&self) -> Option<&OutDest>

Returns the OutDest of the pipe redirection applied to the current command’s stdout.

pub fn pipe_stderr(&self) -> Option<&OutDest>

Returns the OutDest of the pipe redirection applied to the current command’s stderr.

pub fn invocation_stdout(&self) -> Option<&OutDest>

Returns the stdout destination of the innermost active custom-command invocation, if any.

This is the destination of that command’s return value. It stays stable even when intermediate expressions temporarily set OutDest::Value (e.g. if (…)), so callers can answer “where does this command go?” from anywhere in the body.

See also Self::is_stdout_redirected and StackWithInvocation.

pub fn is_stdout_redirected(&self) -> bool

Whether the current custom command’s return value is redirected away from display.

Uses the active Self::invocation_stdout frame when inside a custom command so the answer is stable across nested if / let collection. Outside a custom command, falls back to Self::stdout.

Semantics match OutDest::is_redirected (only OutDest::Print is not redirected). This is the engine-side helper behind the is-redirected command.

pub fn with_invocation_stdout(self, dest: OutDest) -> StackWithInvocation

Wrap this stack with an invocation-stdout frame for a custom command about to run.

Push the destination of the call’s return value (typically caller_stack.stdout().clone() after redirections are applied). The frame is popped when the returned StackWithInvocation is dropped.

Why a separate frame?

Intermediate evaluation sets OutDest::Value via Self::start_collect_value. Without an invocation frame, queries like is-redirected inside if (…) would always see Value and report redirected—even when the enclosing custom command’s result is printed.

pub fn start_collect_value(&mut self) -> StackCollectValueGuard<'_>

Temporarily set the pipe stdout redirection to OutDest::Value.

This is used before evaluating an expression into a Value.

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.

pub fn push_redirection( &mut self, stdout: Option<Redirection>, stderr: Option<Redirection>, ) -> StackIoGuard<'_>

Temporarily apply redirections to stdout and/or stderr.

pub fn collect_value(self) -> Self

Mark stdout for the last command as OutDest::Value.

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_collect_value which can temporarily set stdout as OutDest::Value for a mutable Stack reference.

pub fn capture_all(self) -> Self

Mark both stdout and stderr for the last command as OutDest::Value.

This captures all output (stdout and stderr) instead of letting it inherit to the process’s terminal. Useful for programmatic contexts like MCP servers where all output must be captured and returned.

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).

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).

pub fn suppress_output(self) -> Self

Redirects stdout and stderr to OutDest::Null, discarding all output.

Use this for background evaluation tasks (e.g., completion) that must never write to the terminal while reedline owns it.

pub fn suppress_stdin(self) -> Self

Causes external processes spawned with empty input to receive /dev/null for stdin instead of inheriting the terminal.

Use this together with suppress_output for background tasks (e.g. completion threads). Without it, subprocesses spawned by closure-based completers (carapace, fish_complete, etc.) inherit the live terminal fd and can race with reedline’s reads, causing Input/output error (EIO).

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).

pub fn stdout_file(self, file: File) -> Self

Replaces the default stdout of the stack with a given file.

This method configures the default stdout to redirect to a specified file. It is primarily useful for applications using nu as a language, where the stdout of external commands that are not explicitly piped can be redirected to a file.

Using Pipes

For use in third-party applications pipes might be very useful as they allow using the stdout of external commands for different uses. For example the os_pipe crate provides an elegant way to access the stdout.

let (mut reader, writer) = os_pipe::pipe().unwrap();
// Use a thread to avoid blocking the execution of the called command.
let reader = thread::spawn(move || {
    let mut buf: Vec<u8> = Vec::new();
    reader.read_to_end(&mut buf)?;
    Ok::<_, io::Error>(buf)
});

#[cfg(windows)]
let file = std::os::windows::io::OwnedHandle::from(writer).into();
#[cfg(unix)]
let file = std::os::unix::io::OwnedFd::from(writer).into();

let stack = Stack::new().stdout_file(file);

// Execute some nu code.

drop(stack); // drop the stack so that the writer will be dropped too
let buf = reader.join().unwrap().unwrap();
// Do with your buffer whatever you want.

pub fn stderr_file(self, file: File) -> Self

Replaces the default stderr of the stack with a given file.

For more info, see stdout_file.

pub fn set_cwd(&mut self, path: impl AsRef<Path>) -> Result<(), ShellError>

Set the PWD environment variable to path.

This method accepts path with trailing slashes, but they’re removed before writing the value into PWD.

Trait Implementations

impl Clone for Stack

fn clone(&self) -> Stack

Returns a duplicate 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.