Struct ShellExecutor 

pub struct ShellExecutor {

    pub scriptname: Option<String>,
    pub scriptfilename: Option<String>,
    pub subshell_snapshots: Vec<SubshellSnapshot>,
    pub inline_env_stack: Vec<Vec<(String, Option<String>, Option<String>)>>,
    pub current_command_glob_failed: Cell<bool>,
    pub jobs: JobTable,
    pub fpath: Vec<PathBuf>,
    pub history: Option<HistoryEngine>,
    pub completions: HashMap<String, CompSpec>,
    pub zstyles: Vec<zstyle_entry>,
    pub local_scope_depth: usize,
    pub pending_underscore: Option<String>,
    pub in_dq_context: u32,
    pub in_scalar_assign: u32,
    pub profiling_enabled: bool,
    pub compsys_cache: Option<CompsysCache>,
    pub compinit_pending: Option<(Receiver<CompInitBgResult>, Instant)>,
    pub plugin_cache: Option<PluginCache>,
    pub deferred_compdefs: Vec<Vec<String>>,
    pub returning: Option<i32>,
    pub zsh_compat: bool,
    pub bash_compat: bool,
    pub posix_mode: bool,
    pub worker_pool: Arc<WorkerPool>,
    pub intercepts: Vec<Intercept>,
    pub async_jobs: HashMap<u32, Receiver<(i32, String)>>,
    pub next_async_id: u32,
    pub redirect_scope_stack: Vec<Vec<(i32, i32)>>,
    pub multios_scope_stack: Vec<Vec<(i32, JoinHandle<()>)>>,
    pub redirect_failed: bool,
    pub functions_compiled: HashMap<String, Chunk>,
    pub function_source: HashMap<String, String>,
    pub function_line_base: HashMap<String, i64>,
    pub function_def_file: HashMap<String, Option<String>>,
    pub prompt_funcstack: Vec<(String, i64, Option<String>)>,
    pub tied_array_to_scalar: HashMap<String, (String, String)>,
    pub ztest_pass_count: AtomicUsize,
    pub ztest_fail_count: AtomicUsize,
    pub ztest_skip_count: AtomicUsize,
    pub ztest_pass_total: AtomicUsize,
    pub ztest_fail_total: AtomicUsize,
    pub ztest_skip_total: AtomicUsize,
    pub ztest_run_failed: AtomicBool,
    pub ztest_suppress_stdout: bool,
    /* private fields */
}

Top-level shell executor state. Port of the file-static globals + Estate chain Src/exec.c uses — execlist() (line 1349) drives every list, with execpline() (line 1668), execpline2() (line 1991), execsimple() (line 1290), and the per-WC_* execfuncs[] table (line 268) feeding off it. The Rust port collapses everything into one ShellExecutor so we don’t need thread-local globals.

Fields

scriptname: Option<String>

Mirrors C zsh’s file-static scriptname (Src/init.c). Used by PS4’s %N and the scriptname:line: … prefix on error messages. Inside a function, MUTATES to the function name (Src/exec.c:5903 scriptname = dupstring(name)). Init sets this in -c mode to the binary basename per init.c:479; when sourcing a file via source/bin_dot, it becomes the resolved file path; otherwise it falls back through $0 → $ZSH_ARGZERO.

scriptfilename: Option<String>

Mirrors C zsh’s scriptfilename global (Src/init.c). Tracks the FILE BEING READ (vs scriptname which tracks the active function name during a call). Used by PS4’s %x and certain error-message prefixes that want the file location, NOT the function name.

At -c-mode init, scriptname == scriptfilename == “zsh” (Src/init.c:479). When entering a function, ONLY scriptname updates (exec.c:5903); scriptfilename stays at the outer file path, so %x inside a function still shows the file the function was called from.

subshell_snapshots: Vec<SubshellSnapshot>

Stack of subshell-state snapshots. Each (…) subshell pushes a copy of variables/arrays/assoc_arrays at entry and pops/restores at exit. Without this, (x=inner; …); echo $x shows inner instead of the outer-scope value.

inline_env_stack: Vec<Vec<(String, Option<String>, Option<String>)>>

Stack of inline-assignment scopes — X=foo Y=bar cmd pushes a frame at the start, the assigns run inside it, and cmd returns into END_INLINE_ENV which restores both shell-vars and process-env to the pre-frame state. Each frame holds (name, prev_var, prev_env) per assigned name. zsh’s equivalent is the parser-level “addvar” list executed under addvars() (Src/exec.c) right before the command exec.

current_command_glob_failed: Cell<bool>

Set by expand_glob’s no-match arm when nomatch is on (zsh default) — instructs the simple-command dispatcher to skip executing the current command, set last_status=1, and continue to the next command in the script. zsh’s bin_simple uses the errflag global for the same role: error printed, command suppressed, script continues. Without this we were calling process::exit(1) deep inside expand_glob, killing the whole shell on any unmatched glob even with multi-statement input. Cell because the no-match site only has a &self borrow.

jobs: JobTable

jobs field.

fpath: Vec<PathBuf>

fpath field.

history: Option<HistoryEngine>

history field.

completions: HashMap<String, CompSpec>

zstyles: Vec<zstyle_entry>

local_scope_depth: usize

Current function scope depth for local tracking.

pending_underscore: Option<String>

Last arg of the currently-running command, deferred into $_ when the next command dispatches. zsh: $_ reflects the LAST command’s last arg, so echo hi; echo $_ prints hi (not the _ arg of echo $_ itself). Promoted in pop_args and host.exec before the command’s args are read.

in_dq_context: u32

True while expanding inside a double-quoted context. Set by BUILTIN_EXPAND_TEXT mode 1 around expand_string calls. Used by parameter-flag application to suppress array-only flags ((o)/(O)/(n)/(i)/(M)/(u)) — zsh’s behaviour: those flags only fire in array context.

in_scalar_assign: u32

True (>0) while expanding the RHS of a scalar assignment. Direct port of zsh’s PREFORK_SINGLE bit set by Src/exec.c::addvars line 2546 (prefork(vl, isstr ? (PREFORK_SINGLE|PREFORK_ASSIGN) : PREFORK_ASSIGN, ...)). Subst_port’s paramsubst reads this via ssub and suppresses (f) / (s:STR:) / (0) / (z) split flags per Src/subst.c:1759 + 3902, so y="${(f)x}" preserves x’s original separator (newlines) instead of re-joining with IFS-first-char (space).

profiling_enabled: bool

profiling_enabled field.

compsys_cache: Option<CompsysCache>

compsys_cache field.

compinit_pending: Option<(Receiver<CompInitBgResult>, Instant)>

compinit_pending field.

plugin_cache: Option<PluginCache>

plugin_cache field.

deferred_compdefs: Vec<Vec<String>>

deferred_compdefs field.

returning: Option<i32>

zsh_compat: bool

zsh compatibility mode - use .zcompdump, fpath scanning, etc. Also serves as the --zsh parity-test flag: caches off, daemon off, plugin_cache replay off so every source re-runs the file fresh per Src/builtin.c:6080-6123 bin_dot semantics.

bash_compat: bool

bash compatibility mode (--bash). Same parity-mode semantics as zsh_compat (caches/daemon/replay off) plus bash-specific behavior tweaks where bash 5.x diverges from zsh — e.g. BASH_VERSION / BASH_REMATCH exposed, [[ =~ ]] populates match indices the bash way, mapfile/readarray as builtins.

posix_mode: bool

POSIX sh strict mode — no SQLite, no worker pool, no zsh extensions

worker_pool: Arc<WorkerPool>

Worker thread pool for background tasks (compinit, process subs, etc.)

intercepts: Vec<Intercept>

AOP intercept table: command/function name → advice chain. Glob patterns supported (e.g. “git ”, “”).

async_jobs: HashMap<u32, Receiver<(i32, String)>>

Async job handles: id → receiver for (status, stdout)

next_async_id: u32

Next async job ID

redirect_scope_stack: Vec<Vec<(i32, i32)>>

Per-scope saved-fd stacks for Op::WithRedirectsBegin/End. Each entry is a Vec of (fd, saved_dup_fd) pairs taken from dup(fd) before the redirect was applied; with_redirects_end dup2s them back and closes.

multios_scope_stack: Vec<Vec<(i32, JoinHandle<()>)>>

Per-scope MULTIOS tee state. Each entry is (pipe_write_fd, JoinHandle): the pipe write-end currently dup2’d onto the command’s fd, and the splitter thread that reads from the pipe read-end and writes to every collected target. Closed

• joined by host_redirect_scope_end BEFORE the saved fds are restored so the splitter drains every byte the body wrote into the pipe. Bug #36 in docs/BUGS.md.

redirect_failed: bool

Set by host_apply_redirect when a redirect target couldn’t be opened (permission denied, no such directory, etc). The next builtin/command checks this at entry and short-circuits with status 1 instead of running. Mirrors zsh’s “command skip” on redirect failure.

functions_compiled: HashMap<String, Chunk>

Compiled function bodies — name → fusevm::Chunk. Populated by BUILTIN_REGISTER_FUNCTION (from FunctionDef lowering) and lazily by ZshrsHost::call_function when only an AST exists in self.functions (autoloaded, sourced, etc.). Op::CallFunction dispatches through here.

function_source: HashMap<String, String>

Canonical source text for functions. Populated by autoload paths (the raw file/cache body), runtime FuncDef compile (the parsed source span), and unfunction removal. Used by introspection (whence, which, typeset -f) instead of reconstructing from a ShellCommand AST. When a function is in functions_compiled but not here, introspection falls back to text::getpermtext(self.functions[name]).

function_line_base: HashMap<String, i64>

first_body_line - 1 per compiled function — matches inner ZshCompiler::lineno_offset / zsh funcstack->flineno combined with relative $LINENO for Src/prompt.c:909 %I.

function_def_file: HashMap<String, Option<String>>

scriptfilename when BUILTIN_REGISTER_COMPILED_FN ran — %x inside a function (prompt.c:931-934) reads funcstack->filename.

prompt_funcstack: Vec<(String, i64, Option<String>)>

Innermost-last stack of active compiled-call frames for prompt %I / %x.

tied_array_to_scalar: HashMap<String, (String, String)>

Scalar→(array, sep) tie table set up by typeset -T VAR var [SEP]. Array→(scalar, sep) reverse-tie table. Used by BUILTIN_SET_ARRAY to join the array elements with sep and mirror to the scalar side.

ztest_pass_count: AtomicUsize

Per-block pass count (reset by ztest_run).

ztest_fail_count: AtomicUsize

Per-block fail count (reset by ztest_run).

ztest_skip_count: AtomicUsize

Per-block skip count (reset by ztest_run).

ztest_pass_total: AtomicUsize

Cumulative pass total across the run.

ztest_fail_total: AtomicUsize

Cumulative fail total across the run.

ztest_skip_total: AtomicUsize

Cumulative skip total across the run.

ztest_run_failed: AtomicBool

Sticky failure flag — set by any ztest_run that observed fails; the CLI runner reads this so a test that asserts then exits 0 still counts as a failed file.

ztest_suppress_stdout: bool

Suppress per-assertion ✓/✗ lines on stderr. Set by the worker runner inside the forked child when it has already redirected fd 2 to a tmp file (we still want the lines, but only after the runner re-emits them under print_lock to avoid line-tearing).

Implementations

impl ShellExecutor

pub fn drain_compinit_bg(&mut self)

Non-blocking drain of background compinit results. Call this before any completion lookup (prompt, tab-complete, etc.). If the background thread hasn’t finished yet, this is a no-op.

impl ShellExecutor

pub fn host_apply_redirect(&mut self, fd: u8, op_byte: u8, target: &str)

host_apply_redirect — see implementation.

pub fn host_redirect_scope_begin(&mut self, _count: u8)

Push a fresh redirect scope. _count is informational — the actual saved fds are appended by host_apply_redirect into the top scope.

pub fn host_redirect_scope_end(&mut self)

Pop the top redirect scope, restoring saved fds.

pub fn host_set_pending_stdin(&mut self, content: String)

Set up content as stdin (fd 0) for the next command via a real pipe. Used by Op::HereDoc(idx) and Op::HereString.

The pattern: dup2 the read end of a fresh pipe onto fd 0, save the original fd 0 into the active redirect scope so WithRedirectsEnd restores it, and spawn a thread that writes content to the write end and closes it (so the consumer sees EOF after the body). A thread is needed because writing could block on a finite pipe buffer.

pub fn host_exec_external(&mut self, args: &[String]) -> i32

Spawn an external command using zshrs’s full dispatch logic (intercepts, command_hash, redirect handling). Used by ZshrsHost::exec so the bytecode VM’s Op::Exec and Op::CallFunction external fallback get the same semantics as the tree-walker’s execute_external rather than a plain Command::new shortcut. Returns the exit status.

impl ShellExecutor

pub fn set_scalar(&mut self, name: String, value: String)

Set a scalar parameter via the canonical paramtab (Src/params.c:3350 setsparam). The single store.

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

Read positional parameters from canonical PPARAMS Mutex<Vec<String>> (Src/init.c:pparams). The single store.

pub fn set_pparams(&mut self, params: Vec<String>)

Write positional parameters to canonical PPARAMS.

pub fn param_flags(&self, name: &str) -> i32

Read PM_* type flags from the paramtab Param entry. Used by SET_VAR / += arms (case-fold, integer-add, readonly guard). Returns 0 when the name isn’t in paramtab. Mirrors the C source’s direct pm->node.flags & PM_INTEGER checks.

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

readonly / typeset -r / read-only-by-design (LINENO, PPID, $$, $?, $!, …) — match user-side rejection in C’s assignstrvalue at Src/params.c:2699-2703 which gates on pm->node.flags & PM_READONLY where the IPDEF4 family declares PM_READONLY_SPECIAL = PM_SPECIAL | PM_READONLY | PM_RO_BY_DESIGN (both bits set together). zshrs’s special_params table carries PM_RO_BY_DESIGN alone for IPDEF4 entries so internal direct-write paths (BUILTIN_SET_LINENO bypasses via pm.u_val) don’t trip the readonly guard. User-facing checks must accept either bit. Bug #418-family / test_lineno_intrinsic_readonly.

pub fn last_status(&self) -> i32

Most-recent-command exit status. Reads canonical builtin::LASTVAL AtomicI32 (Src/builtin.c:6443).

pub fn set_last_status(&mut self, status: i32)

Write the most-recent-command exit status. The canonical store is builtin::LASTVAL; this is the single setter. Used everywhere $? / %? / errexit / ZERR trap read.

pub fn set_array(&mut self, name: String, value: Vec<String>)

Set an indexed array parameter via canonical paramtab (setaparam, Src/params.c:3595). The single store.

pub fn set_assoc(&mut self, name: String, value: IndexMap<String, String>)

Set an associative array parameter via canonical sethparam (Src/params.c:3602). The single store.

pub fn scalar(&self, name: &str) -> Option<String>

Read a scalar parameter. Mirrors C getsparam at Src/params.c:3076 — reads through paramtab, falls back to special-var hooks and env.

pub fn array(&self, name: &str) -> Option<Vec<String>>

Read an array parameter via canonical getaparam (Src/params.c:3101).

pub fn assoc(&self, name: &str) -> Option<IndexMap<String, String>>

Read an associative array parameter from canonical paramtab_hashed_storage. Mirrors C gethparam at Src/params.c:3115 — returns the typed IndexMap.

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

Test whether a scalar parameter exists in paramtab. Mirrors the C paramtab->getnode(name) != NULL check.

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

Test whether an array parameter exists in paramtab. Routes through canonical getaparam (PM_TYPE check + digit-first-name rejection).

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

Test whether an associative array parameter exists. Reads canonical paramtab_hashed_storage (Src/params.c hashed PM_HASHED slot).

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

Unset an associative array parameter via canonical unsetparam (Src/params.c:3819) — PM_READONLY rejection, stdunsetfn dispatch, env clear. Also clears the zshrs-side paramtab_hashed_storage parallel IndexMap shadow.

pub fn alias(&self, name: &str) -> Option<String>

Read a regular (non-global) alias value. Reads canonical aliastab (Src/hashtable.c:1186). Filters out aliases that have the ALIAS_GLOBAL flag set so the regular-alias slot is distinct from the global-alias slot, mirroring C’s two separate dispatch paths via aliasflags checks.

pub fn set_alias(&mut self, name: String, value: String)

Set a regular alias. Writes canonical aliastab with ALIAS_GLOBAL bit cleared.

pub fn set_global_alias(&mut self, name: String, value: String)

Set a global alias (alias -g). Writes canonical aliastab with ALIAS_GLOBAL bit set.

pub fn set_suffix_alias(&mut self, name: String, value: String)

Set a suffix alias (alias -s ext=cmd). Writes canonical sufaliastab with ALIAS_SUFFIX node flag — mirrors C Src/builtin.c:4480-4481 (flags1 |= ALIAS_SUFFIX; ht = sufaliastab;) → c:4527 (createaliasnode(value, flags1)). Without ALIAS_SUFFIX in node.flags, ${saliases[k]} / ${(k)saliases} introspection (parameter.c:1953/2018) fails because both paths strict-equality-match flags == ALIAS_SUFFIX.

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

Snapshot the alias map as a sorted Vec<(name, value)>, only entries WITHOUT the ALIAS_GLOBAL flag (regular aliases).

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

Snapshot the global-alias entries (ALIAS_GLOBAL flag set).

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

Snapshot the suffix-alias entries.

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

Unset an array parameter. Direct port of unsetparam_pm for a PM_ARRAY Param. Mirrors are kept for now while the field transitions. Unset an array parameter via canonical unsetparam (Src/params.c:3819). Routes through the C-faithful port that runs PM_NAMEREF skip + PM_READONLY rejection via unsetparam_pm + stdunsetfn dispatch + pm.old scope restore. Inline tab.remove(name) skipped all four.

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

Unset a scalar parameter via canonical unsetparam. Same C-faithful path as unset_array; the C unsetparam itself is type-agnostic and dispatches through PM_TYPE inside.

pub fn new() -> Self

new — see implementation.

pub fn execute_script_file(&mut self, file_path: &str) -> Result<i32, String>

Execute a script file with bytecode caching — skips lex+parse+compile on cache hit. Bytecode is stored in rkyv keyed by (path, mtime).

pub fn execute_script_zsh_pipeline( &mut self, script: &str, ) -> Result<i32, String>

Execute via the lex+parse free ported + ZshCompiler pipeline. This is the only execution path; execute_script delegates here.

pub fn execute_script(&mut self, script: &str) -> Result<i32, String>

execute_script — see implementation.

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

Whether name is a known function. Checks the compiled-functions table and the autoload-pending registry — autoload foo should make whence foo/type foo/functions foo recognize foo as a function before it’s actually loaded. Doesn’t trigger autoload itself; use maybe_autoload first if you need to load before introspecting.

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

Sorted list of every known function name (union of compiled + source).

pub fn run_function_body_only( &mut self, name: &str, args: &[String], ) -> Option<i32>

Dispatch a function by name. Thin passthru — autoload-materialize the body if needed, build a synthetic shfunc, and hand off to the canonical doshfunc port (Src/exec.c:5823 → src/ported/exec.rs::doshfunc). doshfunc owns ALL scope management (starttrapscope/endtrapscope, startparamscope/ endparamscope, funcdepth bump, pipestats save/restore, scriptname snapshot, BREAKS/CONTFLAG/LOOPS/RETFLAG snapshot+restore, $0 override via FUNCTIONARGZERO, etc.). The body run itself is the Rust-only adaptation passed via the body_runner closure because zshrs runs function bodies through fusevm bytecode (not C zsh’s wordcode walker via runshfunc).

Returns None when the name isn’t a known function so the caller can fall through to external dispatch. Body-only counterpart to [dispatch_function_call] — runs the function body WITHOUT wrapping in doshfunc. Used as the body_runner closure target by src/ported/ callers that already wrap their own crate::ported::exec::doshfunc(...) call (so going back through dispatch_function_call would double-wrap the scope). Mirrors C’s runshfunc(prog, wrappers, name) at exec.c:6042 from doshfunc’s perspective.

pub fn dispatch_function_call( &mut self, name: &str, args: &[String], ) -> Option<i32>

pub fn run_command_substitution(&mut self, cmd_str: &str) -> String

run_command_substitution — see implementation.

impl ShellExecutor

pub fn run_trap(&mut self, signal: &str)

Execute the trap body for a signal name from the REPL signal loop (bins/zshrs.rs CtrlC/CtrlD dispatch). Thin passthru to traps_table lookup + execute_script — kept as a method because the REPL loop owns &mut ShellExecutor and needs a single call point. The async signal-handler dispatch path goes through crate::ported::signals::dotrap instead.

impl ShellExecutor

pub fn expand_glob(&self, pattern: &str) -> Vec<String>

Expand glob pattern via canonical glob_path (port of Src/glob.c::zglob). Adds executor-side current_command_glob_failed cell so the dispatch layer skips the current command on NOMATCH + looks_like_glob instead of exiting the shell.

impl ShellExecutor

pub fn enter_posix_mode(&mut self)

enter_posix_mode — see implementation.

pub fn enter_ksh_mode(&mut self)

enter_ksh_mode — see implementation.