@struktoai/mirage-core/dist/workspace/expand/variable.d.ts

A Unified Virtual Filesystem For AI Agents

import type { ArithWrite } from '../../shell/types.ts';
import type { RandomReader } from '../session/state.ts';
import type { CallStack } from '../../shell/call_stack.ts';
import { type TSNodeLike } from '../../shell/types.ts';
import type { SessionView } from '../../view/types.ts';
import type { SessionState } from '../session/session.ts';
import { type Chunk } from './types.ts';
export type ExpandChild = (node: TSNodeLike, quoted: boolean) => Promise<Chunk[]>;
/**
 * Resolve one variable name to its value.
 *
 * `strict` honors `set -u`: an unset plain name or positional raises;
 * the defaulting operators (`:-` family) pass false because they handle
 * unset themselves. Specials (`@ * # ? $ ! 0`) never raise, matching
 * bash >= 4.4.
 */
export declare function lookupVar(name: string, session: SessionState, callStack: CallStack | null, strict?: boolean): string;
/**
 * The IFS in scope, a function's `local IFS` first; null when IFS is
 * unset, which splits the way the default does.
 */
export declare function ifsValue(session: SessionState, callStack: CallStack | null): string | null;
/**
 * One `$name` reference as pieces of the word it stands in. `$@` is one
 * field per positional parameter, quoted or not, and so is an unquoted
 * `$*`; inside double quotes `$*` is the parameters joined on the first
 * character of IFS.
 */
export declare function parameterChunks(name: string, session: SessionState, callStack: CallStack | null, quoted: boolean): Promise<Chunk[]>;
/**
 * Whether an expansion is a `$@`-style splat. Inside double quotes such
 * a splat yields one field per element and no field at all when there is
 * none: `"$@"` with no parameters is no word, where `"$*"` is one empty
 * word. `${#a[@]}` is a count, so it is one word like any other.
 */
export declare function isAtSplat(node: TSNodeLike): boolean;
/**
 * Land an arithmetic expansion's assignments and settle its draws. Each
 * write goes through `expansionWrite` in evaluation order; then the
 * `RANDOM` reader replays the draws the expression made after it seeded
 * the generator, now that the session view holds the seed. One entry point for a
 * completed expression and for one that failed partway, since bash
 * binds each assignment as it is made.
 */
export declare function landArithWrites(session: SessionState, view: SessionView | null, writes: readonly ArithWrite[], reader: RandomReader): Promise<void>;
/**
 * One expansion-time write, through the session view.
 *
 * `${X:=d}`, `${a[i]:=d}` and `$((X=5))` are assignments the shell
 * performs while expanding a word rather than while running a command,
 * and they used to land on the raw session env. That made a `preSession`
 * rule one `${X:=d}` away from irrelevant: a deployment refusing `AWS_*`
 * still had `${AWS_PROFILE:=prod}` write it. They go through the session view
 * now, so one rule covers every spelling.
 *
 * Without a session view (a unit test outside a workspace) the write lands
 * directly, with the hidden half still applied: skipping that would let
 * the write-back clobber a value the host's wiring reads.
 *
 * The element mechanics are `assignElement`'s: a bare name (null key)
 * over an array takes the write at element 0 and keeps its other
 * elements (`a=(1 2 3)` then `$((a=5))` leaves `5 2 3`), an associative
 * one writes the literal key "0", and a subscripted target arrives with
 * its key already canonical. Throws ExitSignal when the name is hidden,
 * a preSession rule refuses, the subscript is bad, or the name carries
 * `-i` and the text does not evaluate (the line dies with status 1, the
 * shape `${var:?}` uses); a readonly name discards the line too, and ends a
 * `( )` subshell with `contained`.
 */
export declare function expansionWrite(session: SessionState, view: SessionView | undefined, name: string, key: string | null, value: string, contained?: number): Promise<void>;
/**
 * Expand `${VAR}`, `${VAR<op>...}`, `${a[i]}`, `${#a[@]}`, etc. to pieces.
 *
 * An offset, length or slice bound is arithmetic and may assign
 * (`${v:x=1:y=2}`) or seed (`${v:RANDOM%10:1}`); those land through the
 * session view before the next bound expands, including its nested substitutions.
 * `quoted` says whether the expansion sits inside double quotes, which
 * decides the rules an operator's word follows and the shape a
 * `$*`-style splat takes.
 */
export declare function expandBraces(node: TSNodeLike, session: SessionState, callStack: CallStack | null, expandChild: ExpandChild, view?: SessionView, quoted?: boolean, signal?: AbortSignal): Promise<Chunk[]>;
//# sourceMappingURL=variable.d.ts.map