@thi.ng/args/args.d.ts

Declarative, functional CLI argument/options parser, value coercions, sub-commands etc.

import { type Fn } from "@thi.ng/api/fn";
import type { ArgSpec, KVDict, KVMultiDict, Tuple } from "./api.js";
/**
 * Returns a full {@link ArgSpec} for a boolean flag. The mere presence of this
 * arg will enable the flag.
 *
 * @param spec -
 */
export declare const flag: <S extends Partial<ArgSpec<boolean>>>(spec: S) => S & {
    flag: true;
    default: boolean;
    group: string;
};
/**
 * Returns a full {@link ArgSpec} for a string value arg.
 *
 * @param spec -
 */
export declare const string: <S extends Partial<ArgSpec<string>>>(spec: S) => S & {
    coerce: Fn<string, string>;
    hint: string;
    group: string;
};
/**
 * Multi-arg version of {@link string}. Returns a full {@link ArgSpec} for a
 * multi string value arg. This argument can be provided mutiple times with
 * values collected into an array.
 *
 * @param spec -
 */
export declare const strings: <S extends Partial<ArgSpec<string[]> & {
    delim: string;
}>>(spec: S) => S & {
    coerce: Fn<string[], string[]>;
    hint: string;
    multi: true;
    group: string;
};
/**
 * Returns a full {@link ArgSpec} for a floating point value arg. The value
 * will be autoatically coerced into a number using {@link coerceFloat}.
 *
 * @param spec -
 */
export declare const float: <S extends Partial<ArgSpec<number>>>(spec: S) => S & {
    coerce: Fn<string, number>;
    hint: string;
    group: string;
};
/**
 * Returns a full {@link ArgSpec} for a single hex integer value arg. The value
 * will be autoatically coerced into a number using {@link coerceHexInt}.
 *
 * @param spec -
 */
export declare const hex: <S extends Partial<ArgSpec<number>>>(spec: S) => S & {
    coerce: Fn<string, number>;
    hint: string;
    group: string;
};
/**
 * Returns a full {@link ArgSpec} for a single integer value arg. The value
 * will be autoatically coerced into a number using {@link coerceInt}.
 *
 * @param spec -
 */
export declare const int: <S extends Partial<ArgSpec<number>>>(spec: S) => S & {
    coerce: Fn<string, number>;
    hint: string;
    group: string;
};
/**
 * Multi-arg version of {@link float}. Returns a full {@link ArgSpec} for a
 * multi floating point value arg. This argument can be provided mutiple times
 * with values being coerced into numbers and collected into an array.
 *
 * @param spec -
 */
export declare const floats: <S extends Partial<ArgSpec<number[]> & {
    delim: string;
}>>(spec: S) => S & {
    coerce: Fn<string[], number[]>;
    hint: string;
    multi: true;
    group: string;
};
/**
 * Multi-arg version of {@link hex}. Returns a full {@link ArgSpec} for a multi
 * hex integer value arg. This argument can be provided mutiple times with
 * values being coerced into numbers and collected into an array.
 *
 * @param spec -
 */
export declare const hexes: <S extends Partial<ArgSpec<number[]> & {
    delim: string;
}>>(spec: S) => S & {
    coerce: Fn<string[], number[]>;
    hint: string;
    multi: true;
    group: string;
};
/**
 * Multi-arg version of {@link int}. Returns a full {@link ArgSpec} for a multi
 * integer value arg. This argument can be provided mutiple times with values
 * being coerced into numbers and collected into an array.
 *
 * @param spec -
 */
export declare const ints: <S extends Partial<ArgSpec<number[]> & {
    delim: string;
}>>(spec: S) => S & {
    coerce: Fn<string[], number[]>;
    hint: string;
    multi: true;
    group: string;
};
/**
 * Returns full {@link ArgSpec} for a JSON value arg. The raw CLI value string
 * will be automcatically coerced using {@link coerceJson}.
 *
 * @param spec -
 */
export declare const json: <T, S extends Partial<ArgSpec<T>>>(spec: S) => S & {
    coerce: Fn<string, T>;
    hint: string;
    group: string;
};
/**
 * Returns full {@link ArgSpec} for an enum-like string value arg. The raw CLI
 * value string will be automcatically validated using {@link coerceOneOf}.
 *
 * @param opts -
 * @param spec -
 */
export declare const oneOf: <K extends string, S extends Partial<ArgSpec<K>>>(opts: readonly K[], spec: S) => S & {
    coerce: Fn<string, K>;
    hint: string;
    group: string;
} & {
    desc: string;
};
/**
 * Multi-arg version of {@link oneOf}. Returns full {@link ArgSpec} for multiple
 * enum-like string value args. The raw CLI value strings will be automcatically
 * validated using {@link coerceOneOf} and collected into an array.
 *
 * @param opts -
 * @param spec -
 */
export declare const oneOfMulti: <K extends string, S extends Partial<ArgSpec<K[]> & {
    delim: string;
}>>(opts: readonly K[], spec: S) => S & {
    coerce: Fn<string[], K[]>;
    hint: string;
    multi: true;
    group: string;
} & {
    desc: string;
};
/**
 * Returns a full {@link ArgSpec} for multiple `key=value` pair args, coerced
 * into a result object.
 *
 * @remarks
 * The default delimiter (`=`) can be overridden. Also by default, key-only args
 * are allowed and will receive a `"true"` as their value. However, if `strict`
 * is true, only full KV pairs are allowed.
 *
 * @param spec -
 * @param delim -
 */
export declare const kvPairs: <S extends Partial<ArgSpec<KVDict>>>(spec: S, delim?: string, strict?: boolean) => S & {
    coerce: Fn<string[], KVDict>;
    hint: string;
    multi: true;
    group: string;
};
/**
 * Like {@link kvPairs}, but coerces KV pairs into a result {@link KVMultiDict}
 * which supports multiple values per given key (each key's values are collected
 * into arrays).
 *
 * @param spec -
 * @param delim -
 * @param strict -
 */
export declare const kvPairsMulti: <S extends Partial<ArgSpec<KVMultiDict>>>(spec: S, delim?: string, strict?: boolean) => S & {
    coerce: Fn<string[], KVMultiDict>;
    hint: string;
    multi: true;
    group: string;
};
/**
 * Returns a full {@link ArgSpec} for a fixed `size` tuple extracted from a
 * single value string. The individual values are delimited by `delim` and will
 * be coerced into their target type via `coerce`. The result tuple will be
 * wrapped in a {@link Tuple} instance.
 *
 * @remarks
 * An error will be thrown if the number of extracted values differs from the
 * specified tuple size or any value coercion fails.
 *
 * @example
 * ```ts tangle:../export/tuple.ts
 * import { coerceInt, parse, tuple } from "@thi.ng/args";
 *
 * console.log(
 *   parse({ a: tuple(coerceInt, 2, {})}, ["--a", "1,2"])
 * );
 * // {
 * //   result: { a: Tuple { value: [1, 2] } },
 * //   index: 2,
 * //   rest: [],
 * //   done: true
 * // }
 * ```
 *
 * @param coerce -
 * @param size -
 * @param spec -
 * @param delim -
 */
export declare const tuple: <T, S extends Partial<ArgSpec<Tuple<T>>>>(coerce: Fn<string, T>, size: number, spec: S, delim?: string) => S & {
    coerce: Fn<string, Tuple<T>>;
    hint: string;
    group: string;
};
/**
 * Syntax sugar for `tuple(coerceInt, size, {...}, delim)`.
 *
 * @param size -
 * @param spec -
 * @param delim -
 */
export declare const size: <S extends Partial<ArgSpec<Tuple<number>>>>(size: number, spec: S, delim?: string) => S & {
    coerce: Fn<string, Tuple<number>>;
    hint: string;
    group: string;
};
/**
 * Syntax sugar for `tuple(coerceFloat, size, {...}, delim)`.
 *
 * @param size -
 * @param spec -
 * @param delim -
 */
export declare const vec: <S extends Partial<ArgSpec<Tuple<number>>>>(size: number, spec: S, delim?: string) => S & {
    coerce: Fn<string, Tuple<number>>;
    hint: string;
    group: string;
};
/**
 * Re-usable preset arg spec for a `--dry-run` flag.
 */
export declare const ARG_DRY_RUN: {
    dryRun: {
        desc: string;
    } & {
        flag: true;
        default: boolean;
        group: string;
    };
};
/**
 * Re-usable preset arg spec for a `--quiet` / `-q` flag.
 */
export declare const ARG_QUIET: {
    quiet: {
        alias: string;
        desc: string;
    } & {
        flag: true;
        default: boolean;
        group: string;
    };
};
/**
 * Re-usable preset arg spec for a `--verbose` / `-v` flag.
 */
export declare const ARG_VERBOSE: {
    verbose: {
        alias: string;
        desc: string;
    } & {
        flag: true;
        default: boolean;
        group: string;
    };
};
/**
 * Higher-order re-usable preset arg spec for a `--out-dir` / `-O` arg. Accepts
 * optional default value (e.g. sourced from an env var). If the the
 * `defaultVal` is defined, the arg is declared as optional, otherwise
 * mandatory.
 *
 * @param defaultVal
 * @param desc
 */
export declare const ARG_OUT_DIR: <T extends string | undefined>(defaultVal?: string, desc?: string) => {
    outDir: ReturnType<typeof string> & (T extends string ? {
        default: string;
    } : {
        optional: false;
    });
};
/**
 * Higher-order re-usable preset arg spec for a `--out-file` / `-o` arg. Accepts
 * optional default value (e.g. sourced from an env var). If the the
 * `defaultVal` is defined, the arg is declared as optional, otherwise
 * mandatory.
 *
 * @param defaultVal
 * @param desc
 */
export declare const ARG_OUT_FILE: <T extends string | undefined>(defaultVal?: T, desc?: string) => {
    outFile: ReturnType<typeof string> & (T extends string ? {
        default: string;
    } : {
        optional: false;
    });
};
//# sourceMappingURL=args.d.ts.map