Struct Scope 

pub struct Scope { /* private fields */ }

Variable scope with nested frames and last-result tracking.

Variables are looked up from innermost to outermost frame. The ? variable always refers to the last command result.

The frames field is wrapped in Arc for copy-on-write (COW) semantics. Cloning a Scope is O(1) — just bumps the Arc refcount. Mutations use Arc::make_mut to clone the inner data only when shared. This matters because execute_pipeline snapshots the scope into ExecContext (clone) and syncs it back (clone) on every command.

Implementations

impl Scope

pub fn new() -> Self

Create a new scope with one empty frame.

pub fn pid(&self) -> u32

Get the process ID ($$).

pub fn push_frame(&mut self)

Push a new scope frame (for entering a loop, tool call, etc.)

pub fn pop_frame(&mut self)

Pop the innermost scope frame.

Panics if attempting to pop the last frame.

pub fn set(&mut self, name: impl Into<String>, value: Value)

Set a variable in the current (innermost) frame.

Use this for local variable declarations.

pub fn set_global(&mut self, name: impl Into<String>, value: Value)

Set a variable with global semantics (shell default).

If the variable exists in any frame, update it there. Otherwise, create it in the outermost (root) frame. Use this for non-local variable assignments.

pub fn get(&self, name: &str) -> Option<&Value>

Get a variable by name, searching from innermost to outermost frame.

pub fn remove(&mut self, name: &str) -> Option<Value>

Remove a variable, searching from innermost to outermost frame.

Returns the removed value if found, None otherwise.

pub fn set_last_result(&mut self, result: ExecResult)

Set the last command result (accessible via $?).

pub fn last_result(&self) -> &ExecResult

Get the last command result.

pub fn set_positional( &mut self, script_name: impl Into<String>, args: Vec<String>, )

Set the positional parameters ($0, $1-$9, $@, $#).

The script_name becomes $0, and args become $1, $2, etc.

pub fn save_positional(&self) -> (String, Vec<String>)

Save current positional parameters for later restoration.

Returns (script_name, args) tuple that can be passed to set_positional.

pub fn get_positional(&self, n: usize) -> Option<&str>

Get a positional parameter by index ($0-$9).

$0 returns the script name, $1-$9 return arguments.

pub fn all_args(&self) -> &[String]

Get all positional arguments as a slice ($@).

pub fn arg_count(&self) -> usize

Get the count of positional arguments ($#).

pub fn error_exit_enabled(&self) -> bool

Check if error-exit mode is enabled (set -e).

pub fn set_error_exit(&mut self, enabled: bool)

Set error-exit mode (set -e / set +e).

pub fn export(&mut self, name: impl Into<String>)

Mark a variable as exported (visible to child processes).

The variable doesn’t need to exist yet; it will be exported when set.

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

Check if a variable is marked for export.

pub fn set_exported(&mut self, name: impl Into<String>, value: Value)

Set a variable and mark it as exported.

pub fn unexport(&mut self, name: &str)

Unmark a variable from export.

pub fn exported_vars(&self) -> Vec<(String, Value)>

Get all exported variables with their values.

Only returns variables that exist and are marked for export.

pub fn exported_names(&self) -> Vec<&str>

Get all exported variable names.

pub fn resolve_path(&self, path: &VarPath) -> Option<Value>

Resolve a variable path like ${VAR} or ${?.field}.

Returns None if the path cannot be resolved. Field access is only supported for the special $? variable.

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

Check if a variable exists in any frame.

pub fn all_names(&self) -> Vec<&str>

Get all variable names in scope (for debugging/introspection).

pub fn all(&self) -> Vec<(String, Value)>

Get all variables as (name, value) pairs.

Variables are deduplicated, with inner frames shadowing outer ones.

Trait Implementations

impl Clone for Scope

fn clone(&self) -> Scope

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Scope

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

Formats the value using the given formatter.

impl Default for Scope

fn default() -> Self

Returns the “default value” for a type.