@struktoai/mirage-core/dist/shell/array.d.ts

A Unified Virtual Filesystem For AI Agents

/**
 * A shell array: assigned values by index, with `null` for a hole left by
 * `unset arr[i]` or skipped by `arr[9]=v`. Holes are addressable but do
 * not count toward `${#arr[@]}` and do not expand in `${arr[@]}`.
 */
export type ShellArray = (string | null)[];
/** Build a dense array from consecutive values, starting at index 0. */
export declare function makeArray(values: string[]): ShellArray;
/**
 * One past the highest assigned index, which is what bash resolves a
 * negative subscript against.
 */
export declare function arrayExtent(arr: ShellArray): number;
/** The assigned values in index order, skipping holes. */
export declare function arrayValues(arr: ShellArray): string[];
/** The assigned indices in order, skipping holes. */
export declare function arrayIndices(arr: ShellArray): number[];
/** The number of assigned elements, which is `${#arr[@]}`. */
export declare function arrayCount(arr: ShellArray): number;
/** Whether `idx` holds an assigned element. */
export declare function arrayHas(arr: ShellArray, idx: number): boolean;
/**
 * The element at `idx`, or the empty string for a hole or an
 * out-of-range index.
 */
export declare function arrayGet(arr: ShellArray, idx: number): string;
/**
 * Assign `value` at `idx`, extending with holes as needed.
 *
 * The subscript comes from script text, so the write goes through
 * `splice` rather than `arr[idx] = value`: an element assignment on a
 * caller-supplied key is a prototype-pollution shape, and `splice`
 * cannot name a property at all.
 */
export declare function arraySet(arr: ShellArray, idx: number, value: string): void;
/**
 * A copy of `arr` with `value` assigned at `idx`.
 *
 * What a writer hands the session view: the session view speaks in whole
 * variables, so an element write states itself as the array the write
 * produces. Building it on a copy is what keeps a refusal from leaving
 * the element applied.
 */
export declare function arrayWith(arr: ShellArray, idx: number, value: string): ShellArray;
/**
 * Take the assigned elements from index `offset` on, in index order.
 *
 * bash slices an indexed array by *subscript*, not by position among the
 * assigned values: for `a=([1]=b [3]=d [9]=j)`, `${a[@]:2}` is `d j`
 * because it keeps every index >= 2. `length` then caps how many of those
 * are taken. A negative offset counts back from the extent and yields
 * nothing if it is still negative.
 */
export declare function arraySlice(arr: ShellArray, offset: number, length: number | null): string[];
/**
 * Clear one element, keeping the indices of the elements after it.
 *
 * Trailing holes are dropped so the extent stays at one past the highest
 * assigned index, matching how bash resolves `arr[-1]`.
 */
export declare function arrayUnset(arr: ShellArray, idx: number): void;
/**
 * Split one `[key]=value` literal element, null for a plain word.
 *
 * The split lands on the first `]=`, which is where bash finds it after
 * quote removal; a key that itself holds `]=` needed quoting in bash too
 * and is the one spelling this cannot recover.
 */
export declare function keyedWord(word: string): [string, string] | null;
/**
 * The indexed array a compound literal produces.
 *
 * A `[i]=v` element places at `i` and moves the cursor past it, a plain
 * word continues from the cursor, and a repeated index keeps the last
 * value, which is GNU's `([3]=x y [1]=z)` giving
 * `([1]="z" [3]="x" [4]="y")`. `+=` starts the cursor at the extent
 * instead of replacing. `indexOf` is async because a subscript may
 * assign, and the assignment lands through the session view.
 */
export declare function buildIndexedLiteral(base: ShellArray | null, words: readonly string[], append: boolean, indexOf: (subscript: string) => Promise<number>): Promise<ShellArray>;
/**
 * The associative array a compound literal produces.
 *
 * The first word picks the grammar, as GNU does: a `[key]=value` first
 * word makes every plain word an error (reported back for the caller to
 * render in bash's must-use-subscript voice), while a plain first word
 * reads the whole list as alternating keys and values, `[a]=1`
 * spellings included, literally. An odd pair list stores the last key
 * with an empty value. A repeated key keeps the last value; `+=` merges
 * over the existing map instead of replacing.
 */
export declare function buildAssocLiteral(base: Readonly<Record<string, string>> | null, words: readonly string[], append: boolean): {
    map: Record<string, string>;
    badWords: string[];
};
//# sourceMappingURL=array.d.ts.map