Struct Scope 

pub struct Scope { /* private fields */ }

Manages lexical scoping with a stack of frames. Innermost frame is last in the vector.

Implementations

impl Scope

pub fn new() -> Self

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

Enable Self::parallel_guard for parallel worker interpreters (pmap, fan, …).

pub fn parallel_guard(&self) -> bool

pub fn depth(&self) -> usize

pub fn pop_to_depth(&mut self, target_depth: usize)

Pop frames until we’re at target_depth. Used by VM ReturnValue to cleanly unwind through if/while/for blocks on return.

pub fn push_frame(&mut self)

pub fn get_scalar_slot(&self, slot: u8) -> PerlValue

Read scalar from slot — innermost binding for slot wins (same index can exist on nested frames; padding entries without [Frame::owns_scalar_slot_index] do not shadow outers).

pub fn set_scalar_slot(&mut self, slot: u8, val: PerlValue)

Write scalar to slot — innermost binding for slot wins (see Self::get_scalar_slot).

pub fn set_scalar_slot_checked( &mut self, slot: u8, val: PerlValue, slot_name: Option<&str>, ) -> Result<(), PerlError>

Like [set_scalar_slot] but respects the parallel guard — returns Err when assigning to a slot that belongs to an outer frame inside a parallel block. slot_name is resolved from the bytecode’s name table by the caller when available.

pub fn declare_scalar_slot( &mut self, slot: u8, val: PerlValue, name: Option<&str>, )

Declare + initialize scalar in the current frame’s slot array. name (bare identifier, e.g. x for $x) is stored for Scope::capture when the binding is slot-only (no duplicate frame.scalars row).

pub fn scalar_slot_concat_repeat_inplace( &mut self, slot: u8, rhs: &str, n: usize, ) -> bool

Slot-indexed .= — avoids frame walking and string comparison on every iteration.

Returns a PerlValue::shallow_clone (Arc::clone) of the stored value rather than a full Clone, which would deep-copy the entire String payload and turn a $s .= "x" loop into O(N²) memcpy. Repeated $slot .= rhs fused-loop fast path: locates the slot’s frame once, tries try_concat_repeat_inplace (unique heap-String → single reserve+push_str burst), and returns true on success. Returns false when the slot is not a uniquely-held String so the caller can fall back to the per-iteration slow path. Called from Op::ConcatConstSlotLoop.

pub fn scalar_slot_concat_repeat_slow(&mut self, slot: u8, rhs: &str, n: usize)

Slow fallback for the fused string-append loop: clones the RHS into a new PerlValue::string once and runs the existing scalar_slot_concat_inplace path n times. Used by Op::ConcatConstSlotLoop when the slot is aliased and the in-place fast path rejected the mutation.

pub fn scalar_slot_concat_inplace( &mut self, slot: u8, rhs: &PerlValue, ) -> PerlValue

pub fn pop_frame(&mut self)

pub fn local_set_scalar( &mut self, name: &str, val: PerlValue, ) -> Result<(), PerlError>

local $name — save current value, assign val; restore on pop_frame.

pub fn local_set_array( &mut self, name: &str, val: Vec<PerlValue>, ) -> Result<(), PerlError>

local @name — not valid for mysync arrays.

pub fn local_set_hash( &mut self, name: &str, val: IndexMap<String, PerlValue>, ) -> Result<(), PerlError>

local %name

pub fn local_set_hash_element( &mut self, name: &str, key: &str, val: PerlValue, ) -> Result<(), PerlError>

local $h{key} = val — save key state; restore one slot on pop_frame.

pub fn local_set_array_element( &mut self, name: &str, index: i64, val: PerlValue, ) -> Result<(), PerlError>

local $a[i] = val — save element (as returned by Self::get_array_element), assign; restore on Self::pop_frame.

pub fn declare_scalar(&mut self, name: &str, val: PerlValue)

pub fn declare_scalar_frozen( &mut self, name: &str, val: PerlValue, frozen: bool, ty: Option<PerlTypeName>, ) -> Result<(), PerlError>

Declare a lexical scalar; frozen means no further assignment to this binding. ty is from typed my $x : Int — enforced on every assignment.

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

True if the innermost lexical scalar binding for name is frozen.

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

True if the innermost lexical array binding for name is frozen.

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

True if the innermost lexical hash binding for name is frozen.

pub fn check_frozen(&self, sigil: &str, name: &str) -> Option<&'static str>

Returns Some(sigil) if the named variable is frozen, None if mutable.

pub fn get_scalar(&self, name: &str) -> PerlValue

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

True if any frame has a lexical scalar binding for name (my / our / assignment).

pub fn all_scalar_names(&self) -> Vec<String>

Collect all scalar variable names across all frames (for debugger).

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

True if any frame or atomic slot holds an array named name.

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

True if any frame or atomic slot holds a hash named name.

pub fn get_scalar_raw(&self, name: &str) -> PerlValue

Get the raw scalar value WITHOUT unwrapping Atomic. Used by scope.capture() to preserve the Arc for sharing across threads.

pub fn atomic_mutate( &mut self, name: &str, f: impl FnOnce(&PerlValue) -> PerlValue, ) -> Result<PerlValue, PerlError>

Atomically read-modify-write a scalar. Holds the Mutex lock for the entire cycle so mysync variables are race-free under fan/pfor. Returns the NEW value. Returns Err when the parallel guard rejects the write — ++/+=/-= on a captured non-atomic outer-scope variable now fails fast just like plain = does, instead of silently dropping writes.

pub fn atomic_mutate_post( &mut self, name: &str, f: impl FnOnce(&PerlValue) -> PerlValue, ) -> Result<PerlValue, PerlError>

Like Self::atomic_mutate but returns the OLD value (for postfix $x++). Returns Err for non-atomic captured-outer writes inside parallel blocks (same DESIGN-001 strict-error path as atomic_mutate).

pub fn scalar_concat_inplace( &mut self, name: &str, rhs: &PerlValue, ) -> Result<PerlValue, PerlError>

Append rhs to a scalar string in-place (no clone of the existing string). If the scalar is not yet a String, it is converted first.

The binding and the returned PerlValue share the same heap Arc via PerlValue::shallow_clone on the store — a full Clone would deep-copy the entire String each time and make repeated .= O(N²) in the total length.

pub fn set_scalar( &mut self, name: &str, val: PerlValue, ) -> Result<(), PerlError>

pub fn set_topic(&mut self, val: PerlValue)

Set the topic variable $_ and its numeric alias $_0 together. Use this for block-form closures (map { ... }, grep { ... }, sort { ... }, threaded ~> @arr map { ... }, fi { ... }, etc.) so $_, $_0, and the outer-topic chain ($_<, $_<<, …) all behave correctly. EXPR-form HOFs (grep EXPR, LIST, map EXPR, LIST, reject EXPR, LIST, grepv EXPR, LIST, etc. — anything with no {}) MUST use Self::set_topic_local instead; EXPR position is in the same lexical scope as the surrounding code, so there is no scope/frame boundary and the chain MUST NOT shift. User-facing rule: {} triggers the shift; no {} means no shift.

This declares $_/$_0 in the current scope (not global), suitable for sub calls.

Shifts the outer-topic chain ($_<, $_<<, $_<<<, $_<<<<, $_<<<<<) on the FIRST call in a given frame so nested blocks can peek up to 5 frames out. Subsequent calls in the same frame (the next iteration of the SAME map/grep/etc.) only refresh _ and _0 so _< keeps pointing at the enclosing scope’s topic, not the previous iteration’s value. This is the “frame-based” reading: from inside a nested closure, _< means “the topic of the closure that contains me” (which is constant across my iterations), not “the topic the previous iter set” (which would roll). All previously-activated positional slots shift in lockstep on the first call.

pub fn set_topic_local(&mut self, val: PerlValue)

EXPR-form variant: rebinds $_ / $_0 to val for the current iteration WITHOUT shifting any chain or zeroing slot 1+ aliases. Used by grep EXPR, LIST / map EXPR, LIST and the streaming equivalents — the EXPR is evaluated in the lexical scope of the surrounding code, with no block boundary, so the topic chain shouldn’t roll. Crucially this preserves _1, _2, …, _N from the caller fn so patterns like grep _1, @$_ work without chain-ascent.

pub fn set_closure_args(&mut self, args: &[PerlValue])

Set numeric closure argument aliases $_0, $_1, $_2, … for all args. Also sets $_ to the first argument (if any) and shifts the outer-topic chain on EVERY positional slot ever activated, so a 5-deep nested block can read _2<<<<< to reach the third positional argument from 5 frames up. (Stryke-only — no other language has nested implicit positionals.)

The shift fires on slots 0..=max(args.len()-1, max_active_slot). A frame that binds fewer args than the high-water mark still rotates the older slots (the new “current” for an unbound slot is undef, so old values march through _N<<<< and eventually fall off the end).

pub fn set_sort_pair(&mut self, a: PerlValue, b: PerlValue)

Set the canonical sort/reduce binding pair: $a / $b (Perl-isms) AND $_0 / $_1 (the stryke positional aliases — preferred under --no-interop because the $a/$b pair is inconsistent — there is no $c). The bareword forms _0 / _1 resolve to $_0 / $_1 via the parser, so blocks like sort { _0 <=> _1 } and reduce { _0 + _1 } just work. Use this helper anywhere the legacy code wrote two adjacent set_scalar("a", …); set_scalar("b", …) lines.

pub fn push_defer(&mut self, coderef: PerlValue)

Register a defer { BLOCK } closure to run when this scope exits.

pub fn take_defers(&mut self) -> Vec<PerlValue>

Take all deferred blocks from the current frame (for execution on scope exit). Returns them in reverse order (LIFO - last defer runs first).

pub fn declare_atomic_array(&mut self, name: &str, val: Vec<PerlValue>)

pub fn declare_atomic_hash( &mut self, name: &str, val: IndexMap<String, PerlValue>, )

pub fn take_sub_underscore(&mut self) -> Option<Vec<PerlValue>>

Remove @_ from the innermost frame without cloning (move out of the frame sub_underscore field). Call sites restore with Self::declare_array before running a body that uses shift / @_.

pub fn declare_array(&mut self, name: &str, val: Vec<PerlValue>)

pub fn declare_array_frozen( &mut self, name: &str, val: Vec<PerlValue>, frozen: bool, )

pub fn get_array(&self, name: &str) -> Vec<PerlValue>

pub fn get_array_borrow(&self, name: &str) -> Option<&[PerlValue]>

Borrow the innermost binding for name when it is a plain Vec (not mysync). Used to pass @_ to [crate::list_builtins::native_dispatch] without cloning the vector.

pub fn resolve_container_binding_ref(&self, val: PerlValue) -> PerlValue

Resolve an [ArrayBindingRef] or [HashBindingRef] to an Arc-backed snapshot so the value survives scope pop. Called when a value is stored as an element inside a container (array/hash) — NOT for scalar assignment, where binding refs must stay live for aliasing.

pub fn promote_array_to_shared( &mut self, name: &str, ) -> Arc<RwLock<Vec<PerlValue>>>

Promote @name to shared Arc-backed storage and return an [ArrayRef] that shares the same Arc. Both the scope binding and the returned ref point to the same data, so mutations through either path are visible.

pub fn promote_hash_to_shared( &mut self, name: &str, ) -> Arc<RwLock<IndexMap<String, PerlValue>>>

Promote %name to shared Arc-backed storage and return a [HashRef] that shares the same Arc.

pub fn get_array_mut( &mut self, name: &str, ) -> Result<&mut Vec<PerlValue>, PerlError>

pub fn push_to_array( &mut self, name: &str, val: PerlValue, ) -> Result<(), PerlError>

Push to array — works for both regular and atomic arrays.

pub fn push_int_range_to_array( &mut self, name: &str, start: i64, end: i64, ) -> Result<(), PerlError>

Bulk push @name, start..end-1 for the fused counted-loop superinstruction: reserves the Vec once, then pushes PerlValue::integer(i) for i in start..end in a tight Rust loop. Atomic arrays take a single lock().push() burst.

pub fn pop_from_array(&mut self, name: &str) -> Result<PerlValue, PerlError>

Pop from array — works for regular, shared, and atomic arrays.

pub fn shift_from_array(&mut self, name: &str) -> Result<PerlValue, PerlError>

Shift from array — works for regular, shared, and atomic arrays.

pub fn splice_in_place( &mut self, name: &str, off: usize, end: usize, rep_vals: Vec<PerlValue>, ) -> Result<Vec<PerlValue>, PerlError>

Splice in place — works for regular, shared, and atomic arrays. off..end must already be clamped (use splice_compute_range to compute). Returns the removed elements.

pub fn array_len(&self, name: &str) -> usize

Get array length — works for both regular and atomic arrays.

pub fn set_array( &mut self, name: &str, val: Vec<PerlValue>, ) -> Result<(), PerlError>

pub fn get_array_element(&self, name: &str, index: i64) -> PerlValue

Direct element access — works for both regular and atomic arrays.

pub fn set_array_element( &mut self, name: &str, index: i64, val: PerlValue, ) -> Result<(), PerlError>

pub fn exists_array_element(&self, name: &str, index: i64) -> bool

Perl exists $a[$i] — true when the slot index is within the current array length.

pub fn delete_array_element( &mut self, name: &str, index: i64, ) -> Result<PerlValue, PerlError>

Perl delete $a[$i] — sets the element to undef, returns the previous value.

pub fn declare_hash(&mut self, name: &str, val: IndexMap<String, PerlValue>)

pub fn declare_hash_frozen( &mut self, name: &str, val: IndexMap<String, PerlValue>, frozen: bool, )

pub fn declare_hash_global( &mut self, name: &str, val: IndexMap<String, PerlValue>, )

Declare a hash in the bottom (global) frame, not the current lexical frame.

pub fn declare_hash_global_frozen( &mut self, name: &str, val: IndexMap<String, PerlValue>, )

Declare a frozen hash in the bottom (global) frame — prevents user reassignment.

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

Returns true if a lexical (non-bottom) frame declares %name.

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

Returns true if ANY frame (including global) declares %name.

pub fn get_hash(&self, name: &str) -> IndexMap<String, PerlValue>

pub fn get_hash_mut( &mut self, name: &str, ) -> Result<&mut IndexMap<String, PerlValue>, PerlError>

pub fn set_hash( &mut self, name: &str, val: IndexMap<String, PerlValue>, ) -> Result<(), PerlError>

pub fn get_hash_element(&self, name: &str, key: &str) -> PerlValue

pub fn atomic_hash_mutate( &mut self, name: &str, key: &str, f: impl FnOnce(&PerlValue) -> PerlValue, ) -> Result<PerlValue, PerlError>

Atomically read-modify-write a hash element. For atomic hashes, holds the Mutex for the full cycle. Returns the new value.

pub fn atomic_array_mutate( &mut self, name: &str, index: i64, f: impl FnOnce(&PerlValue) -> PerlValue, ) -> Result<PerlValue, PerlError>

Atomically read-modify-write an array element. Returns the new value.

pub fn set_hash_element( &mut self, name: &str, key: &str, val: PerlValue, ) -> Result<(), PerlError>

pub fn set_hash_int_times_range( &mut self, name: &str, start: i64, end: i64, k: i64, ) -> Result<(), PerlError>

Bulk for i in start..end { $h{i} = i * k } for the fused hash-insert loop. Reserves capacity once and runs the whole range in a tight Rust loop. itoa is used to stringify each key without a transient format! allocation.

pub fn delete_hash_element( &mut self, name: &str, key: &str, ) -> Result<PerlValue, PerlError>

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

pub fn for_each_hash_value(&self, name: &str, visit: impl FnMut(&PerlValue))

Walk all values of the named hash with a visitor. Used by the fused for my $k (keys %h) { $sum += $h{$k} } op so the hot loop runs without cloning the entire map into a keys array (vs the un-fused shape, which allocates one PerlValue::string per key).

pub fn frames_for_introspection(&self) -> Vec<(Vec<&str>, Vec<&str>, Vec<&str>)>

Per-frame view of binding names (not values) for introspection pipelines that need to walk every name in every frame without reaching into private fields. Returns (scalars, arrays, hashes). Atomic / shared variants are folded into the matching kind so the caller doesn’t need to know the storage form.

pub fn parameters_pairs(&self) -> Vec<(String, &'static str)>

Sigil-prefixed name → variable-class string ("scalar", "array", "hash", "atomic_array", "atomic_hash", "shared_array", "shared_hash") for every binding in every frame. Backs the parameters() builtin (zsh-$parameters analogue). Walks frames outermost → innermost so an inner shadow wins on duplicate names.

pub fn repl_binding_names(&self) -> Vec<String>

Sigil-prefixed names ($x, @a, %h) from all frames, for REPL tab-completion.

pub fn capture(&mut self) -> Vec<(String, PerlValue)>

pub fn capture_with_atomics( &self, ) -> (Vec<(String, PerlValue)>, Vec<(String, AtomicArray)>, Vec<(String, AtomicHash)>)

Extended capture that returns atomic arrays/hashes separately.

pub fn restore_capture(&mut self, captured: &[(String, PerlValue)])

pub fn restore_atomics( &mut self, arrays: &[(String, AtomicArray)], hashes: &[(String, AtomicHash)], )

Restore atomic arrays/hashes from capture_with_atomics.

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.