@loomcli/core 0.7.0 → 0.8.0

package/dist/parse.d.ts

@@ -0,0 +1,162 @@
+import type { ArgumentSlot, BuiltCommand, BuiltGraph } from './command.js';
+import type { LoomError } from './errors.js';
+import type { OptionValues, SpellingTable, TableSpelling } from './options.js';
+/**
+ * Whether a word is an option word: `--` and at least one more character, or `-` and an ASCII
+ * letter. Every other word is a plain word, so `-`, `-5`, and `-.5` are values or arguments. The
+ * parser and `locate` read each word through this rule.
+ */
+declare function isOptionWord(word: string): boolean;
+/** A word the grammar never consumes as a separate value: an option word or the bare `--`. */
+declare function refusesValue(word: string): boolean;
+/**
+ * One occurrence an option word holds, read against one table before it touches a value. `lead`
+ * marks a value the word itself carries, after `=` or a short value letter, and holds the part of
+ * the word before it.
+ */
+type Occurrence = {
+    kind: 'value';
+    option: TableSpelling;
+    spelling: string;
+    /** A string, a Boolean's own value, or the `1` one occurrence of a counted option adds. */
+    value: string | boolean | number;
+    lead?: string;
+    /** A bare spelling of a string option with an implied value, which supplied that value. */
+    implied?: true;
+} | {
+    kind: 'unknown';
+    spelling: string;
+} | {
+    kind: 'misplaced';
+    spelling: string;
+} | {
+    kind: 'unexpected';
+    option: ValuelessSpelling;
+    spelling: string;
+    value: string;
+} | {
+    kind: 'repeated';
+    option: TableSpelling;
+    spelling: string;
+} | {
+    kind: 'missing';
+    option: TableSpelling;
+    spelling: string;
+} | {
+    kind: 'awaiting';
+    option: TableSpelling;
+    spelling: string;
+};
+/** A spelling of an option that takes no value: a Boolean option or a counted option. */
+type ValuelessSpelling = TableSpelling & {
+    type: 'boolean' | 'count';
+};
+/** What one option word holds, in order, and whether its last occurrence took the next word. */
+interface WordReading {
+    occurrences: readonly Occurrence[];
+    takesNext: boolean;
+}
+/**
+ * What one option word is read against: a table, and the values earlier words supplied, so an
+ * option that does not collect and was supplied already is a repeat that ends the walk.
+ */
+interface WordContext {
+    table: SpellingTable;
+    values: {
+        globals: OptionValues;
+        locals: OptionValues;
+    };
+}
+/** One option word read against one table, with the word after it as its possible value. */
+declare function readOptionWord(context: WordContext, word: string, next: string | undefined): WordReading;
+/**
+ * The first structural fault in word order: a failure, or the position of the first positional no
+ * slot accepts, which becomes a failure once every later positional is known. `at` is the order in
+ * which the faulted occurrence was read, so a fault found later than it was read still ranks by it.
+ */
+type HeldFault = ({
+    error: LoomError;
+} | {
+    extra: number;
+}) & {
+    at: number;
+};
+/** A string option the last word left waiting for its value. */
+interface AwaitingValue {
+    global: boolean;
+    name: string;
+    spelling: string;
+}
+/**
+ * The names a routing failure offers: the canonical names of the visible, current children, in
+ * authoring order. A candidate list is a listing, so a hidden or a deprecated child is absent from
+ * it, as completion leaves them out, and a parent whose children are all hidden or deprecated
+ * offers none. A deprecated child typed in full still routes.
+ */
+declare function candidatesOf(command: BuiltCommand): string[];
+/**
+ * The slot the positional at one index fills: the slot at that index, else a variadic last slot,
+ * which accepts every later positional, else none. Binding and `locate` read positions through it.
+ */
+declare function argumentSlot(slots: readonly ArgumentSlot[], position: number): ArgumentSlot | undefined;
+/** Every word the reading of one word list found, which may stop short of a complete invocation. */
+interface WordsRead {
+    awaiting: AwaitingValue | undefined;
+    command: BuiltCommand;
+    /** Whether the routed Command read a word, so no later plain word names a child. */
+    committed: boolean;
+    delimited: boolean;
+    fault: HeldFault | undefined;
+    globalFault: boolean;
+    passthrough: string[];
+    path: string[];
+    positionals: string[];
+    /** How many occurrences and positionals were read, the order a fault at the end ranks by. */
+    read: number;
+    supplied: readonly string[];
+    values: {
+        globals: OptionValues;
+        locals: OptionValues;
+    };
+}
+/**
+ * How one word list is read: who hears each routed name, and whether the list is the earlier words
+ * of an unfinished invocation, as `locate` reads them. A word after such a list may continue
+ * routing, so routing has not ended where the list runs out at a Command with children, and a
+ * parent's own option stays unbound.
+ */
+interface ReadOptions {
+    partial?: boolean;
+    walked?: (path: readonly string[]) => void;
+}
+/**
+ * Reads a word list through routing, against the global options and the own options of each
+ * Command with an action and children it passes through, binds those own options to the Command
+ * routing reached once routing has ended, and then reads that Command's own words, up to the first
+ * bare `--`, against the one table it holds.
+ * Parsing continues past a fault, so every global option is found wherever it sits, and only the
+ * first fault in word order is held. Only an unknown Command throws.
+ */
+declare function readWords(graph: BuiltGraph, words: readonly string[], options?: ReadOptions): WordsRead;
+/** One complete invocation, read through routing and the routed Command's table. */
+interface ParsedInvocation {
+    command: BuiltCommand;
+    /** The first structural fault in word order, which core holds to the dispatch boundary. */
+    fault: LoomError | undefined;
+    /** Whether a global option faulted, which leaves every middleware's `options` `null`. */
+    globalFault: boolean;
+    passthrough: string[];
+    path: readonly string[];
+    positionals: string[];
+    values: {
+        globals: OptionValues;
+        locals: OptionValues;
+    };
+}
+/**
+ * Parses a complete invocation, where a string option still waiting for its value at the end of
+ * the words is a missing value.
+ */
+declare function parseInvocation(graph: BuiltGraph, argv: readonly string[], walked: (path: readonly string[]) => void): ParsedInvocation;
+export type { AwaitingValue, ParsedInvocation, WordsRead };
+export { argumentSlot, candidatesOf, isOptionWord, parseInvocation, readOptionWord, readWords, refusesValue, };