@struktoai/mirage-core/dist/commands/spec/flag_view.d.ts

A Unified Virtual Filesystem For AI Agents

import { PathSpec } from '../../types.ts';
import type { CommandSpec, FlagValue, ParsedFlagValue } from './types.ts';
export declare function flagOccurrences(flags: Record<string, FlagValue>): [string, ParsedFlagValue][];
/**
 * The flags with each operand's tape entry spread over its words.
 *
 * The parse runs before a glob expands, so the tape holds an operand as it
 * was typed. A program that reads its operands in order (join) needs each
 * match where the glob stood, as its argv would hold them. A tape that does
 * not place exactly these operands is kept as it is. Mirrors Python's
 * `spread_operands`.
 */
export declare function spreadOperands(flags: Record<string, FlagValue>, groups: readonly (readonly string[])[]): Record<string, FlagValue>;
/**
 * Collect the kwarg names a spec's options can produce.
 *
 * One name per option: the long spelling when an option declares both,
 * matching the parser's canonical dest. Keeping the short spelling here
 * too would let a stale `fl.asBool('a')` stay legal and read false
 * forever after dest unification; canonical-only turns that silent miss
 * into a throw. Mirrors Python's `spec_flag_names`.
 */
export declare function specFlagNames(spec: CommandSpec): ReadonlySet<string>;
/**
 * Typed read-only view over raw flag kwargs.
 *
 * Commands receive flags as an untyped record from the dispatcher; this
 * view is the one sanctioned way to read them, replacing ad-hoc
 * `flags.x === true` checks and typeof chains. Mirrors Python's
 * `FlagView`.
 *
 * When constructed with a spec, reading a name the spec does not declare
 * throws. A missing key is otherwise indistinguishable from "flag not
 * passed", so a typo in the name would silently read as false/undefined.
 */
export declare class FlagView {
    private readonly flags;
    private readonly allowed;
    constructor(flags?: Readonly<Record<string, FlagValue>>, spec?: CommandSpec);
    private key;
    /**
     * The given flag names, ordered by their recorded occurrences.
     *
     * The parser fills the bag in scan order and every hop between
     * (object spreads, copies) preserves string-key insertion order, so
     * a key's position is its last occurrence for scalars, first for accumulating options; a flag
     * supplied by a default or the environment lands after every typed
     * one. Names the line never carried are dropped. This is what an
     * order-sensitive option family (grep's --include/--exclude, where
     * the later kind overrides the earlier) reads, since the bag has no
     * per-occurrence positions.
     */
    typedOrder(...names: string[]): string[];
    /**
     * Read each typed occurrence, then defaults without a typed value.
     *
     * OPERAND among the names reads the operands too, each as [OPERAND, word]
     * where it was typed among the options, and REFUSED and SPELLED read the
     * refused options and the spelled words the same way. Flags with no tape (a
     * plain record) have none of them.
     */
    occurrences(...names: string[]): [string, ParsedFlagValue][];
    /**
     * Each typed occurrence as the text a line would have typed: a string as
     * given, an integer as its digits (`asText`) and a switch that is on as
     * the empty text, in `occurrences` order: what a program that reads its
     * own options sees. A switch that is off was never typed, so it is left
     * out. Mirrors Python's `texts`.
     */
    texts(...names: string[]): [string, string][];
    asBool(name: string): boolean;
    /**
     * The option as an integer, `fallback` only when it is absent. A value the
     * line gave, `0` included, is the value: an absent option and an explicit
     * zero are different requests. Mirrors Python's `as_int`.
     */
    asInt(name: string): number | undefined;
    asInt(name: string, fallback: number): number;
    /**
     * The option as a number, `fallback` only when it is absent. Mirrors
     * Python's `as_float`.
     */
    asFloat(name: string): number | undefined;
    asFloat(name: string, fallback: number): number;
    /**
     * The option as the text a line would have typed for it: a string as given,
     * an integer (a direct call's `{ c: 4 }`) as its decimal digits, undefined
     * when absent. A boolean is a switch, not a number, so it reads as absent.
     * Mirrors Python's `as_text`.
     */
    asText(name: string): string | undefined;
    /**
     * The option as text, `fallback` only when it is absent. A given-but-empty
     * value (`--to=`, `-d ''`) is the value, as it is to the program: what an
     * empty one means is the command's to decide, never the accessor's.
     * Mirrors Python's `as_str`.
     */
    asStr(name: string): string | undefined;
    asStr(name: string, fallback: string): string;
    /**
     * The option as text, `fallback` when it is absent or empty. For a program
     * that cannot tell an empty value from none, as a Go flag's zero value
     * cannot (gh's `if opts.Name != ""`): there the empty one reads as unset,
     * and nowhere else. Mirrors Python's `as_nonempty`.
     */
    asNonEmpty(name: string): string | undefined;
    asNonEmpty(name: string, fallback: string): string;
    asList(name: string): string[];
    asPath(name: string): PathSpec | undefined;
    asPaths(name: string): PathSpec[];
    raw(name: string): FlagValue | undefined;
}
//# sourceMappingURL=flag_view.d.ts.map