@loomcli/core 0.6.0 → 0.8.0

package/dist/options.d.ts

@@ -8,33 +8,123 @@ export interface OptionValues {
     strings: Map<string, string>;
     lists: Map<string, string[]>;
     booleans: Map<string, boolean>;
+    /** How many times each counted option was supplied, or the count an input source filled. */
+    counts: Map<string, number>;
     /** The spelling of the token that supplied each parsed option, which no input source writes. */
     spellings: Map<string, string>;
+    /**
+     * For each string option a bare spelling supplied, the positions that held its implied value: `0`
+     * for a scalar, and each such occurrence's index in a multiple option's list. Validation supplies
+     * the implied value's prepared output there, and no input source writes it.
+     */
+    implied: Map<string, number[]>;
 }
-/** Every parsed value lands in one of these maps; `lists` holds the repeated string options. */
+/**
+ * Every parsed value lands in one of these maps; `lists` holds the repeated string options and
+ * `counts` the counted ones.
+ */
 export declare function emptyValues(): OptionValues;
-/** Which accepted form a table entry is. The table owns the convention, so readers never re-derive it. */
-export type SpellingRole = 'long' | 'negative' | 'short';
+/**
+ * Which accepted form a table entry is, and for an alias's spelling, positive or negative, its place
+ * in `aliases`. The table owns the convention, so readers never re-derive it.
+ */
+export type SpellingOrigin = {
+    role: 'long' | 'negative' | 'short';
+} | {
+    role: 'alias';
+    index: number;
+};
+/**
+ * How one option reads words: its kind, and its value class, of which there are four: a Boolean
+ * option, a counted option, a string option with an implied value, which never takes the next word
+ * and supplies `implied` when its spelling is bare, and a string option that takes the next word as
+ * its value when nothing is attached. Compiling the table derives the class once, and the parser, a
+ * rebound occurrence, and `locate` read that one fact.
+ */
 type OptionForm = {
     type: 'string';
+    valueClass: 'separate';
+    name: string;
+    multiple: boolean;
+} | {
+    type: 'string';
+    valueClass: 'implied';
     name: string;
     multiple: boolean;
+    implied: string;
 } | {
     type: 'boolean';
+    valueClass: 'boolean';
     name: string;
     value: boolean;
+} | {
+    type: 'count';
+    valueClass: 'count';
+    name: string;
 };
-type OptionSpelling = OptionForm & {
-    role: SpellingRole;
+export type OptionSpelling = OptionForm & SpellingOrigin;
+/**
+ * One entry of a Command's spelling table: a spelling of one declaration, and whether that
+ * declaration is a global option, whose value every action reads, or the Command's own.
+ */
+export type TableSpelling = OptionSpelling & {
+    readonly global: boolean;
 };
+/** The one table the parser reads a Command's words against, keyed by spelling. */
+export type SpellingTable = ReadonlyMap<string, TableSpelling>;
+/** One scope's compiled spellings as table entries, each marked with whether the scope is global. */
+export declare function tableEntries(spellings: ReadonlyMap<string, OptionSpelling>, global: boolean): [string, TableSpelling][];
+/** The accepted spellings of one option, `null` where the declaration publishes none. */
+export interface Spellings {
+    long: string | null;
+    negative: string | null;
+    short: string | null;
+}
 /**
- * The part of one declaration that yields a spelling of the given role, which a spelling fault
- * marks: the declared name for the long form, `short` for the short alias, and the `polarity` that
- * generates a negative form.
+ * Reads one option's spellings out of a compiled table, so a reader cannot report a form the parser
+ * does not accept. Each entry carries its own role, so the naming convention has one owner: the
+ * table that writes it.
  */
-export declare function spellingMark(site: InputSite, role: SpellingRole): string;
+export declare function spellingsOf(table: ReadonlyMap<string, OptionSpelling>, name: string): Spellings;
+/**
+ * The spelling every reported problem names an option by: its long form, a negative-only Boolean
+ * option's negative form, and otherwise its short form, which a short-only option alone publishes.
+ * The problem belongs to the option, so an alias or the spelling the operator typed is never it.
+ */
+export declare function reportedOf({ long, negative, short }: Spellings, name: string): string;
+/**
+ * The part of one declaration that yields a spelling of the given origin, which a spelling fault
+ * marks: the declared name for the long form, `short` for the short alias, the `polarity` that
+ * generates a negative form, and the alias in `aliases` for either form of an alias.
+ */
+export declare function spellingMark(site: InputSite, origin: SpellingOrigin): string;
 /** The declared name answers the declared-name rule an argument's name answers. */
 export declare function checkOptionName(name: unknown, site: InputSite): void;
+/**
+ * The one name rule for an argument, option, alias of an option, or view name: a bare token the
+ * parser can read, nonempty, with no leading hyphen, whitespace, or `=`, which it reads apart.
+ */
+export declare function isDeclaredName(name: unknown): name is string;
+/** The one correction every declared-name diagnostic for a string ends with. */
+export declare const declaredNameCorrection = "Use a nonempty name without a leading hyphen, whitespace, or \"=\".";
+/** The sentence and correction of each repeated-alias fault, for the Command or option `subject` names. */
+export declare function repeatedAliasText(subject: string, alias: string): {
+    own: {
+        correction: string;
+        sentence: string;
+    };
+    twice: {
+        correction: string;
+        sentence: string;
+    };
+};
+/** Whether a declared short alias is one ASCII letter, the rule every short spelling answers. */
+export declare function isShortAlias(short: unknown): boolean;
+/** The sentence and correction of the short-alias fault for the option `subject` names. */
+export declare function shortAliasText(subject: string): {
+    sentence: string;
+    correction: string;
+};
 /**
  * The scope one table compiles: the phrase a repeated name names it by, and where each of its
  * options was declared, which every fault's findings rebuild.
@@ -46,8 +136,8 @@ export interface CompileScope<Declaration extends OptionDeclaration> {
 /**
  * One Boolean option's value for one invocation: the value the parser consumed, or the value its
  * declared polarity gives an absent option. A negative-only option is absent as `true`, because its
- * one spelling turns the value off. Every scope reads it here, so a plugin option and a validated
- * declaration answer the same rule.
+ * one spelling turns the value off. Validation reads every Boolean option's value here, whichever
+ * scope declared it.
  */
 export declare function booleanValue(values: OptionValues, name: string, config: OptionConfig): boolean;
 /**
@@ -55,58 +145,6 @@ export declare function booleanValue(values: OptionValues, name: string, config:
  * declaration answers alone and every rule two of them answer together.
  */
 export declare function compileOptions<Declaration extends OptionDeclaration>(declarations: readonly Declaration[], scope: CompileScope<Declaration>): Map<string, OptionSpelling>;
-/**
- * Whether a token reads as an option: it starts with a hyphen. Routing stops at one, and a
- * separate value is never one. The parser and `locate` read each token through this rule.
- */
-export declare function isOptionToken(token: string): boolean;
-/** A long option token and the inline value it carries after its first `=`, if any. */
-export interface LongToken {
-    spelling: string;
-    inline: string | undefined;
-}
-/**
- * A token that starts with `--` split at its first `=` into the spelling and the inline value, or
- * `undefined` for any other token. The parser and `locate` split long tokens through this rule.
- */
-export declare function longToken(token: string): LongToken | undefined;
-/**
- * The name of the string option one long spelling names in a table, which takes its value after
- * `=`, or `undefined` for a Boolean, negative, short, or unknown spelling.
- */
-export declare function longStringOption(spellings: ReadonlyMap<string, OptionSpelling>, spelling: string): string | undefined;
-/**
- * A string option whose value the next token supplies, where the tokens ended first. A complete
- * invocation reports it as a missing value; a partial one reads the next word as that value.
- */
-export interface AwaitingValue {
-    name: string;
-    spelling: string;
-}
-/** One option name a token newly supplied, with the index of that token in the list read. */
-export interface SuppliedOption {
-    name: string;
-    token: number;
-}
-/**
- * The pre-scan's reading of a token list that may stop short. `positions` holds the index in
- * `tokens` of each `rest` token, and `awaiting` is the global option the last token left without
- * its value.
- */
-export interface GlobalScan {
-    awaiting: AwaitingValue | undefined;
-    positions: number[];
-    rest: string[];
-    supplied: SuppliedOption[];
-    values: OptionValues;
-}
-/** Consumes global options anywhere before the passthrough delimiter and leaves the rest routable. */
-export declare function scanGlobals(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): GlobalScan;
-/** The pre-scan of a complete invocation, where a global still waiting for its value is a fault. */
-export declare function extractGlobals(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): {
-    rest: string[];
-    values: OptionValues;
-};
 /**
  * Whether one option holds a value a tier supplied: a token in any spelling it accepts, or a fill
  * from an input source. A declared default is never in these maps, so it never counts.
@@ -116,24 +154,4 @@ export declare function isSupplied(values: OptionValues, name: string): boolean;
 export declare function copyValues(values: OptionValues): OptionValues;
 /** Global and local keys never overlap, so one merged view feeds a single validation pass. */
 export declare function mergeValues(globals: OptionValues, locals: OptionValues): OptionValues;
-/**
- * One Command's reading of its own tokens, which may stop short. `delimited` says a bare `--` was
- * read, and `awaiting` is the option the last token left without its value.
- */
-export interface InputScan {
-    awaiting: AwaitingValue | undefined;
-    delimited: boolean;
-    options: OptionValues;
-    passthrough: string[];
-    positionals: string[];
-    supplied: SuppliedOption[];
-}
-/** Reads one Command's tokens into options, positionals, and the passthrough tail. */
-export declare function scanInputs(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): InputScan;
-/** Parses a complete invocation's local tokens, where a waiting option is a missing value. */
-export declare function parseInputs(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): {
-    options: OptionValues;
-    passthrough: string[];
-    positionals: string[];
-};
 export {};