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.

pid defaults to 0 (sentinel). The owning Kernel calls set_pid() during construction to assign the real session identifier.

pub fn pid(&self) -> u64

Get the kaish session identifier ($$).

pub fn set_pid(&mut self, pid: u64)

Set the kaish session identifier ($$). Called by the Kernel during construction to thread the assigned counter value into the scope. Also used by kaish-clear to preserve $$ across a session reset.

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.

The name is NFC-normalized here, which is what makes the scope’s keys canonical no matter which door bound them. Parse-time normalization covers the four written spellings of a name; this covers every runtime binder — for, read, unset, scatter --as, and the embedder’s own initial_vars — without each having to remember.

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 note_cmdsubst_code(&mut self, code: i64)

Note the exit code of a command substitution that just completed. Overwritten by each later substitution, so the last one performed wins.

pub fn clear_cmdsubst_code(&mut self)

Forget any noted command-substitution code. Called before evaluating an assignment’s value so an earlier statement’s substitution cannot leak into this one’s status.

pub fn take_cmdsubst_code(&mut self) -> Option<i64>

Take the noted command-substitution code, leaving none.

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 active (set -e and not suppressed).

Returns false when inside the left side of && or || chains, matching bash behavior where those operators handle failure themselves.

pub fn error_exit_flag(&self) -> bool

The raw set -e flag, ignoring any active suppression.

Self::error_exit_enabled answers “should errexit fire right now”, which is false while suppressed inside a &&/|| left side. Anything that SAVES the setting to restore later must read this instead, or a save taken during suppression restores set -e as off and quietly disables it for everything after.

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

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

pub fn suppress_errexit(&mut self)

Suppress errexit temporarily (for &&/|| left side).

pub fn unsuppress_errexit(&mut self)

Unsuppress errexit (after &&/|| left side completes).

pub fn show_ast(&self) -> bool

Check if AST display mode is enabled (kaish-ast -on).

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

Set AST display mode (kaish-ast -on / kaish-ast -off).

pub fn pipefail_enabled(&self) -> bool

Check if pipefail is enabled (set -o pipefail).

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

Set pipefail mode (set -o pipefail / set +o pipefail).

pub fn set_pipestatus(&mut self, codes: &[i64])

Record every stage’s exit code as PIPESTATUS, a list.

A list rather than bash’s ${PIPESTATUS[@]} word-array, because kaish has collections and no word splitting: ${PIPESTATUS[0]} indexes it, ${#PIPESTATUS} counts it, and $(values $PIPESTATUS) iterates it. Written for EVERY pipeline including a one-stage one, as bash does — false; echo ${PIPESTATUS[0]} is 1.

pub fn pipestatus_rightmost_failure(&self) -> Option<i64>

The rightmost non-zero code in PIPESTATUS, or None when every stage succeeded.

bash’s pipefail rule is the LAST failing stage, not the first: set -o pipefail; (exit 3) | (exit 4) | true is 4. Reading left-to-right is the easy mistake, and it is wrong on exactly the input that proves a pipeline can fail more than once.

pub fn trash_enabled(&self) -> bool

Check if trash mode is enabled (set -o trash).

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

Set trash mode (set -o trash / set +o trash).

pub fn trash_max_size(&self) -> u64

Get the maximum file size for trash (bytes).

pub fn set_trash_max_size(&mut self, size: u64)

Set the maximum file size for trash (bytes).

pub fn glob_enabled(&self) -> bool

Check if glob expansion is enabled (set -o glob, default true).

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

Set glob expansion mode (set -o glob / set +o glob).

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 in the innermost frame and mark it as exported.

Used for frame-scoped overlays (execute_with_vars, FOO=bar cmd) and for seeding root-frame exports at construction. For the export builtin’s assignment form use set_exported_global so the value survives a function return (shared-scope semantics).

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

Set a variable with global (shared-scope) semantics and mark it as exported. This is export NAME=VALUE: like a plain assignment, the value updates an existing variable wherever it lives or lands in the root frame, so it persists past a function return rather than dying with the function’s frame.

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) -> Result<Value, PathError>

Resolve a variable path: ${VAR}, ${xs[0]}, ${r[key]}, ${a[b][c]}.

The first segment is the root name; the rest are bracket subscripts, walked left to right into the root’s Value::Json. A subscript landing on a JSON scalar unwraps to a native Value (envelope-free); a subscript landing on a collection stays Value::Json. $? resolves to the previous command’s exit code (bare only).

Traversal borrows into the root’s JSON tree and clones only the selected leaf (a slice builds a new list); the whole-root clone is never taken, so repeated ${u[$k]} in a loop stays O(depth), not O(root size). The per-hop classification lives in resolve_step, shared with the future lvalue-write walk so read and write can never diverge.

Errors distinguish an undefined root (soft) from a loud path error (see PathError).

pub fn walk_write( &mut self, path: &VarPath, value: Value, ) -> Result<(), PathError>

Write a value into a collection lvalue path: xs[0]=9, user[email]=amy@example.com, services[web][port]=9090.

Shares resolve_step with resolve_path so classification (bounds, shape) never drifts between read and write. The walk itself diverges at the leaf: every intermediate hop requires the child to already exist (descend_mut — no autovivification), while the final hop may insert a new record key (apply_leaf_write) — the ONLY thing a path-set may create. A list index write is in-bounds update only (resolve_step’s classify_index already turns an out-of-bounds index into a loud Absence); push is how lists grow. A slice lvalue (xs[0:2]=…) is always a Shape error.

The root must already be defined (UndefinedRoot) and be a collection (Shape for a scalar root) — same rule as a read. On success the mutated root replaces the old value via set_global. A bracket-path write updates the variable wherever it lives and ignores local, because it mutates an existing binding instead of creating one. See docs/LANGUAGE.md, “Assignment — bracket-path lvalues”.

pub fn walk_append( &mut self, path: &VarPath, values: Vec<Value>, ) -> Result<(), String>

Append value(s) to a list variable, in place: a top-level bareword target (push xs val) or a bracket-path target (push services[web][tags] item).

The target must already exist and be a list — an undefined root, a non-list leaf, or a missing intermediate hop is a loud error, never a silent create or autoviv. See docs/LANGUAGE.md, “Assignment — bracket-path lvalues + push”. Intermediate hops share walk_write’s resolve_step/descend_mut, so a push path and an assignment path classify identically. Only the final hop differs: it appends instead of replacing.

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.