deno.land / std@0.166.0 / flags / mod.ts
نووسراو ببینە
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license./** * Command line arguments parser based on * [minimist](https://github.com/minimistjs/minimist). * * This module is browser compatible. * * @module */import { assert } from "../_util/asserts.ts";
/** Combines recursively all intersection types and returns a new single type. */type Id<T> = T extends Record<string, unknown> ? T extends infer U ? { [K in keyof U]: Id<U[K]> } : never : T;
/** Converts an union type `A | B | C` into an intersection type `A & B & C`. */type UnionToIntersection<T> = (T extends unknown ? (args: T) => unknown : never) extends (args: infer R) => unknown ? R extends Record<string, unknown> ? R : never : never;
type BooleanType = boolean | string | undefined;type StringType = string | undefined;type ArgType = StringType | BooleanType;
type Collectable = string | undefined;type Negatable = string | undefined;
type UseTypes< B extends BooleanType, S extends StringType, C extends Collectable,> = undefined extends ( & (false extends B ? undefined : B) & C & S) ? false : true;
/** * Creates a record with all available flags with the corresponding type and * default type. */type Values< B extends BooleanType, S extends StringType, C extends Collectable, N extends Negatable, D extends Record<string, unknown> | undefined, A extends Aliases | undefined,> = UseTypes<B, S, C> extends true ? & Record<string, unknown> & AddAliases< SpreadDefaults< & CollectValues<S, string, C, N> & RecursiveRequired<CollectValues<B, boolean, C>> & CollectUnknownValues<B, S, C, N>, DedotRecord<D> >, A > // deno-lint-ignore no-explicit-any : Record<string, any>;
type Aliases<T = string, V extends string = string> = Partial< Record<Extract<T, string>, V | ReadonlyArray<V>>>;
type AddAliases< T, A extends Aliases | undefined,> = { [K in keyof T as AliasName<K, A>]: T[K] };
type AliasName< K, A extends Aliases | undefined,> = K extends keyof A ? string extends A[K] ? K : A[K] extends string ? K | A[K] : K : K;
/** * Spreads all default values of Record `D` into Record `A` * and makes default values required. * * **Example:** * `SpreadValues<{ foo?: boolean, bar?: number }, { foo: number }>` * * **Result:** `{ foo: boolan | number, bar?: number }` */type SpreadDefaults<A, D> = D extends undefined ? A : A extends Record<string, unknown> ? & Omit<A, keyof D> & { [K in keyof D]: K extends keyof A ? (A[K] & D[K] | D[K]) extends Record<string, unknown> ? NonNullable<SpreadDefaults<A[K], D[K]>> : D[K] | NonNullable<A[K]> : unknown; } : never;
/** * Defines the Record for the `default` option to add * auto suggestion support for IDE's. */type Defaults<B extends BooleanType, S extends StringType> = Id< UnionToIntersection< & Record<string, unknown> // Dedotted auto suggestions: { foo: { bar: unknown } } & MapTypes<S, unknown> & MapTypes<B, unknown> // Flat auto suggestions: { "foo.bar": unknown } & MapDefaults<B> & MapDefaults<S> >>;
type MapDefaults<T extends ArgType> = Partial< Record<T extends string ? T : string, unknown>>;
type RecursiveRequired<T> = T extends Record<string, unknown> ? { [K in keyof T]-?: RecursiveRequired<T[K]>; } : T;
/** Same as `MapTypes` but also supports collectable options. */type CollectValues< T extends ArgType, V, C extends Collectable, N extends Negatable = undefined,> = UnionToIntersection< C extends string ? & MapTypes<Exclude<T, C>, V, N> & (T extends undefined ? Record<never, never> : RecursiveRequired< MapTypes<Extract<C, T>, Array<V>, N> >) : MapTypes<T, V, N>>;
/** Same as `Record` but also supports dotted and negatable options. */type MapTypes<T extends ArgType, V, N extends Negatable = undefined> = undefined extends T ? Record<never, never> : T extends `${infer Name}.${infer Rest}` ? { [K in Name]?: MapTypes< Rest, V, N extends `${Name}.${infer Negate}` ? Negate : undefined >; } : T extends string ? Partial<Record<T, N extends T ? V | false : V>> : Record<never, never>;
type CollectUnknownValues< B extends BooleanType, S extends StringType, C extends Collectable, N extends Negatable,> = B & S extends C ? Record<never, never> : DedotRecord< // Unknown collectable & non-negatable args. & Record< Exclude< Extract<Exclude<C, N>, string>, Extract<S | B, string> >, Array<unknown> > // Unknown collectable & negatable args. & Record< Exclude< Extract<Extract<C, N>, string>, Extract<S | B, string> >, Array<unknown> | false > >;
/** Converts `{ "foo.bar.baz": unknown }` into `{ foo: { bar: { baz: unknown } } }`. */type DedotRecord<T> = Record<string, unknown> extends T ? T : T extends Record<string, unknown> ? UnionToIntersection< ValueOf< { [K in keyof T]: K extends string ? Dedot<K, T[K]> : never } > > : T;
type Dedot<T extends string, V> = T extends `${infer Name}.${infer Rest}` ? { [K in Name]: Dedot<Rest, V> } : { [K in T]: V };
type ValueOf<T> = T[keyof T];
/** The value returned from `parse`. */export type Args< // deno-lint-ignore no-explicit-any A extends Record<string, unknown> = Record<string, any>, DD extends boolean | undefined = undefined,> = Id< & A & { /** Contains all the arguments that didn't have an option associated with * them. */ _: Array<string | number>; } & (boolean extends DD ? DoubleDash : true extends DD ? Required<DoubleDash> : Record<never, never>)>;
type DoubleDash = { /** Contains all the arguments that appear after the double dash: "--". */ "--"?: Array<string>;};
/** The options for the `parse` call. */export interface ParseOptions< B extends BooleanType = BooleanType, S extends StringType = StringType, C extends Collectable = Collectable, N extends Negatable = Negatable, D extends Record<string, unknown> | undefined = | Record<string, unknown> | undefined, A extends Aliases<string, string> | undefined = | Aliases<string, string> | undefined, DD extends boolean | undefined = boolean | undefined,> { /** When `true`, populate the result `_` with everything before the `--` and * the result `['--']` with everything after the `--`. Here's an example: * * ```ts * // $ deno run example.ts -- a arg1 * import { parse } from "https://deno.land/std@$STD_VERSION/flags/mod.ts"; * console.dir(parse(Deno.args, { "--": false })); * // output: { _: [ "a", "arg1" ] } * console.dir(parse(Deno.args, { "--": true })); * // output: { _: [], --: [ "a", "arg1" ] } * ``` * * Defaults to `false`. */ "--"?: DD;
/** An object mapping string names to strings or arrays of string argument * names to use as aliases. */ alias?: A;
/** A boolean, string or array of strings to always treat as booleans. If * `true` will treat all double hyphenated arguments without equal signs as * `boolean` (e.g. affects `--foo`, not `-f` or `--foo=bar`) */ boolean?: B | ReadonlyArray<Extract<B, string>>;
/** An object mapping string argument names to default values. */ default?: D & Defaults<B, S>;
/** When `true`, populate the result `_` with everything after the first * non-option. */ stopEarly?: boolean;
/** A string or array of strings argument names to always treat as strings. */ string?: S | ReadonlyArray<Extract<S, string>>;
/** A string or array of strings argument names to always treat as arrays. * Collectable options can be used multiple times. All values will be * collected into one array. If a non-collectable option is used multiple * times, the last value is used. */ collect?: C | ReadonlyArray<Extract<C, string>>;
/** A string or array of strings argument names which can be negated * by prefixing them with `--no-`, like `--no-config`. */ negatable?: N | ReadonlyArray<Extract<N, string>>;
/** A function which is invoked with a command line parameter not defined in * the `options` configuration object. If the function returns `false`, the * unknown option is not added to `parsedArgs`. */ unknown?: (arg: string, key?: string, value?: unknown) => unknown;}
interface Flags { bools: Record<string, boolean>; strings: Record<string, boolean>; collect: Record<string, boolean>; negatable: Record<string, boolean>; unknownFn: (arg: string, key?: string, value?: unknown) => unknown; allBools: boolean;}
interface NestedMapping { [key: string]: NestedMapping | unknown;}
const { hasOwn } = Object;
function get<T>(obj: Record<string, T>, key: string): T | undefined { if (hasOwn(obj, key)) { return obj[key]; }}
function getForce<T>(obj: Record<string, T>, key: string): T { const v = get(obj, key); assert(v != null); return v;}
function isNumber(x: unknown): boolean { if (typeof x === "number") return true; if (/^0x[0-9a-f]+$/i.test(String(x))) return true; return /^[-+]?(?:\d+(?:\.\d*)?|\.\d+)(e[-+]?\d+)?$/.test(String(x));}
function hasKey(obj: NestedMapping, keys: string[]): boolean { let o = obj; keys.slice(0, -1).forEach((key) => { o = (get(o, key) ?? {}) as NestedMapping; });
const key = keys[keys.length - 1]; return hasOwn(o, key);}
/** Take a set of command line arguments, optionally with a set of options, and * return an object representing the flags found in the passed arguments. * * By default, any arguments starting with `-` or `--` are considered boolean * flags. If the argument name is followed by an equal sign (`=`) it is * considered a key-value pair. Any arguments which could not be parsed are * available in the `_` property of the returned object. * * ```ts * import { parse } from "https://deno.land/std@$STD_VERSION/flags/mod.ts"; * const parsedArgs = parse(Deno.args); * ``` * * ```ts * import { parse } from "https://deno.land/std@$STD_VERSION/flags/mod.ts"; * const parsedArgs = parse(["--foo", "--bar=baz", "./quux.txt"]); * // parsedArgs: { foo: true, bar: "baz", _: ["./quux.txt"] } * ``` */export function parse< V extends Values<B, S, C, N, D, A>, DD extends boolean | undefined = undefined, B extends BooleanType = undefined, S extends StringType = undefined, C extends Collectable = undefined, N extends Negatable = undefined, D extends Record<string, unknown> | undefined = undefined, A extends Aliases<AK, AV> | undefined = undefined, AK extends string = string, AV extends string = string,>( args: string[], { "--": doubleDash = false, alias = {} as NonNullable<A>, boolean = false, default: defaults = {} as D & Defaults<B, S>, stopEarly = false, string = [], collect = [], negatable = [], unknown = (i: string): unknown => i, }: ParseOptions<B, S, C, N, D, A, DD> = {},): Args<V, DD> { const aliases: Record<string, string[]> = {}; const flags: Flags = { bools: {}, strings: {}, unknownFn: unknown, allBools: false, collect: {}, negatable: {}, };
if (alias !== undefined) { for (const key in alias) { const val = getForce(alias, key); if (typeof val === "string") { aliases[key] = [val]; } else { aliases[key] = val as Array<string>; } for (const alias of getForce(aliases, key)) { aliases[alias] = [key].concat(aliases[key].filter((y) => alias !== y)); } } }
if (boolean !== undefined) { if (typeof boolean === "boolean") { flags.allBools = !!boolean; } else { const booleanArgs: ReadonlyArray<string> = typeof boolean === "string" ? [boolean] : boolean;
for (const key of booleanArgs.filter(Boolean)) { flags.bools[key] = true; const alias = get(aliases, key); if (alias) { for (const al of alias) { flags.bools[al] = true; } } } } }
if (string !== undefined) { const stringArgs: ReadonlyArray<string> = typeof string === "string" ? [string] : string;
for (const key of stringArgs.filter(Boolean)) { flags.strings[key] = true; const alias = get(aliases, key); if (alias) { for (const al of alias) { flags.strings[al] = true; } } } }
if (collect !== undefined) { const collectArgs: ReadonlyArray<string> = typeof collect === "string" ? [collect] : collect;
for (const key of collectArgs.filter(Boolean)) { flags.collect[key] = true; const alias = get(aliases, key); if (alias) { for (const al of alias) { flags.collect[al] = true; } } } }
if (negatable !== undefined) { const negatableArgs: ReadonlyArray<string> = typeof negatable === "string" ? [negatable] : negatable;
for (const key of negatableArgs.filter(Boolean)) { flags.negatable[key] = true; const alias = get(aliases, key); if (alias) { for (const al of alias) { flags.negatable[al] = true; } } } }
const argv: Args = { _: [] };
function argDefined(key: string, arg: string): boolean { return ( (flags.allBools && /^--[^=]+$/.test(arg)) || get(flags.bools, key) || !!get(flags.strings, key) || !!get(aliases, key) ); }
function setKey( obj: NestedMapping, name: string, value: unknown, collect = true, ) { let o = obj; const keys = name.split("."); keys.slice(0, -1).forEach(function (key) { if (get(o, key) === undefined) { o[key] = {}; } o = get(o, key) as NestedMapping; });
const key = keys[keys.length - 1]; const collectable = collect && !!get(flags.collect, name);
if (!collectable) { o[key] = value; } else if (get(o, key) === undefined) { o[key] = [value]; } else if (Array.isArray(get(o, key))) { (o[key] as unknown[]).push(value); } else { o[key] = [get(o, key), value]; } }
function setArg( key: string, val: unknown, arg: string | undefined = undefined, collect?: boolean, ) { if (arg && flags.unknownFn && !argDefined(key, arg)) { if (flags.unknownFn(arg, key, val) === false) return; }
const value = !get(flags.strings, key) && isNumber(val) ? Number(val) : val; setKey(argv, key, value, collect);
const alias = get(aliases, key); if (alias) { for (const x of alias) { setKey(argv, x, value, collect); } } }
function aliasIsBoolean(key: string): boolean { return getForce(aliases, key).some( (x) => typeof get(flags.bools, x) === "boolean", ); }
let notFlags: string[] = [];
// all args after "--" are not parsed if (args.includes("--")) { notFlags = args.slice(args.indexOf("--") + 1); args = args.slice(0, args.indexOf("--")); }
for (let i = 0; i < args.length; i++) { const arg = args[i];
if (/^--.+=/.test(arg)) { const m = arg.match(/^--([^=]+)=(.*)$/s); assert(m != null); const [, key, value] = m;
if (flags.bools[key]) { const booleanValue = value !== "false"; setArg(key, booleanValue, arg); } else { setArg(key, value, arg); } } else if ( /^--no-.+/.test(arg) && get(flags.negatable, arg.replace(/^--no-/, "")) ) { const m = arg.match(/^--no-(.+)/); assert(m != null); setArg(m[1], false, arg, false); } else if (/^--.+/.test(arg)) { const m = arg.match(/^--(.+)/); assert(m != null); const [, key] = m; const next = args[i + 1]; if ( next !== undefined && !/^-/.test(next) && !get(flags.bools, key) && !flags.allBools && (get(aliases, key) ? !aliasIsBoolean(key) : true) ) { setArg(key, next, arg); i++; } else if (/^(true|false)$/.test(next)) { setArg(key, next === "true", arg); i++; } else { setArg(key, get(flags.strings, key) ? "" : true, arg); } } else if (/^-[^-]+/.test(arg)) { const letters = arg.slice(1, -1).split("");
let broken = false; for (let j = 0; j < letters.length; j++) { const next = arg.slice(j + 2);
if (next === "-") { setArg(letters[j], next, arg); continue; }
if (/[A-Za-z]/.test(letters[j]) && /=/.test(next)) { setArg(letters[j], next.split(/=(.+)/)[1], arg); broken = true; break; }
if ( /[A-Za-z]/.test(letters[j]) && /-?\d+(\.\d*)?(e-?\d+)?$/.test(next) ) { setArg(letters[j], next, arg); broken = true; break; }
if (letters[j + 1] && letters[j + 1].match(/\W/)) { setArg(letters[j], arg.slice(j + 2), arg); broken = true; break; } else { setArg(letters[j], get(flags.strings, letters[j]) ? "" : true, arg); } }
const [key] = arg.slice(-1); if (!broken && key !== "-") { if ( args[i + 1] && !/^(-|--)[^-]/.test(args[i + 1]) && !get(flags.bools, key) && (get(aliases, key) ? !aliasIsBoolean(key) : true) ) { setArg(key, args[i + 1], arg); i++; } else if (args[i + 1] && /^(true|false)$/.test(args[i + 1])) { setArg(key, args[i + 1] === "true", arg); i++; } else { setArg(key, get(flags.strings, key) ? "" : true, arg); } } } else { if (!flags.unknownFn || flags.unknownFn(arg) !== false) { argv._.push(flags.strings["_"] ?? !isNumber(arg) ? arg : Number(arg)); } if (stopEarly) { argv._.push(...args.slice(i + 1)); break; } } }
for (const [key, value] of Object.entries(defaults)) { if (!hasKey(argv, key.split("."))) { setKey(argv, key, value);
if (aliases[key]) { for (const x of aliases[key]) { setKey(argv, x, value); } } } }
for (const key of Object.keys(flags.bools)) { if (!hasKey(argv, key.split("."))) { const value = get(flags.collect, key) ? [] : false; setKey( argv, key, value, false, ); } }
for (const key of Object.keys(flags.strings)) { if (!hasKey(argv, key.split(".")) && get(flags.collect, key)) { setKey( argv, key, [], false, ); } }
if (doubleDash) { argv["--"] = []; for (const key of notFlags) { argv["--"].push(key); } } else { for (const key of notFlags) { argv._.push(key); } }
return argv as Args<V, DD>;}
std
Version Info
a year ago
