From b9037c86ed8d1d55a59a1c1298fa12bbfcae6873 Mon Sep 17 00:00:00 2001 From: Kitson Kelly Date: Sun, 8 Mar 2020 21:27:23 +1100 Subject: [PATCH] Improvements to std/flags. (#4279) Adds JSDoc to module, improves the typing of the return type, uses iteration instead of Array forEach, uses the dotall support in Regular Expression which is now supported in JavaScript, uses destructuring and nullish coalescing where appropriate. --- std/flags/mod.ts | 215 ++++++++++++++++++++++++------------------ std/flags/num_test.ts | 2 +- 2 files changed, 125 insertions(+), 92 deletions(-) diff --git a/std/flags/mod.ts b/std/flags/mod.ts index 9bc4e8cdf5..59cae5d158 100644 --- a/std/flags/mod.ts +++ b/std/flags/mod.ts @@ -1,29 +1,62 @@ +// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. + import { assert } from "../testing/asserts.ts"; -// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. -export interface ArgParsingOptions { - unknown: (i: unknown) => unknown; - boolean: boolean | string | string[]; - alias: { [key: string]: string | string[] }; - string: string | string[]; - default: { [key: string]: unknown }; - "--": boolean; - stopEarly: boolean; +export interface Args { + /** Contains all the arguments that didn't have an option associated with + * them. */ + _: Array; + // eslint-disable-next-line @typescript-eslint/no-explicit-any + [key: string]: any; } -const DEFAULT_OPTIONS = { - unknown: (i: unknown): unknown => i, - boolean: false, - alias: {}, - string: [], - default: {}, - "--": false, - stopEarly: false -}; +export interface ArgParsingOptions { + /** When `true`, populate the result `_` with everything before the `--` and + * the result `['--']` with everything after the `--`. Here's an example: + * + * const { args } = Deno; + * import { parse } from "https://deno.land/std/flags/mod.ts"; + * // options['--'] is now set to false + * console.dir(parse(args, { "--": false })); + * // $ deno example.ts -- a arg1 + * // output: { _: [ "example.ts", "a", "arg1" ] } + * // options['--'] is now set to true + * console.dir(parse(args, { "--": true })); + * // $ deno example.ts -- a arg1 + * // output: { _: [ "example.ts" ], --: [ "a", "arg1" ] } + * + * Defaults to `false`. + */ + "--": boolean; + + /** An object mapping string names to strings or arrays of string argument + * names to use as aliases */ + alias: Record; + + /** 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: boolean | string | string[]; + + /** An object mapping string argument names to default values. */ + default: Record; + + /** 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: string | 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: (i: unknown) => unknown; +} interface Flags { - bools: { [key: string]: boolean }; - strings: { [key: string]: boolean }; + bools: Record; + strings: Record; unknownFn: (i: unknown) => unknown; allBools: boolean; } @@ -32,12 +65,13 @@ interface NestedMapping { [key: string]: NestedMapping | unknown; } -function get(obj: { [s: string]: T }, key: string): T | undefined { +function get(obj: Record, key: string): T | undefined { if (Object.prototype.hasOwnProperty.call(obj, key)) { return obj[key]; } } -function getForce(obj: { [s: string]: T }, key: string): T { + +function getForce(obj: Record, key: string): T { const v = get(obj, key); assert(v != null); return v; @@ -51,82 +85,80 @@ function isNumber(x: unknown): boolean { function hasKey(obj: NestedMapping, keys: string[]): boolean { let o = obj; - keys.slice(0, -1).forEach(function(key: string): void { - o = (get(o, key) || {}) as NestedMapping; + keys.slice(0, -1).forEach(key => { + o = (get(o, key) ?? {}) as NestedMapping; }); const key = keys[keys.length - 1]; return key in o; } +/** Take a set of command line arguments, with an optional set of options, and + * return an object representation of those argument. + * + * const parsedArgs = parse(Deno.args); + */ export function parse( - // eslint-disable-next-line @typescript-eslint/no-explicit-any - args: any[], - initialOptions: Partial = {} - // eslint-disable-next-line @typescript-eslint/no-explicit-any -): { [key: string]: any } { - const options: ArgParsingOptions = { - ...DEFAULT_OPTIONS, - ...initialOptions - }; - + args: string[], + { + "--": doubleDash = false, + alias = {}, + boolean = false, + default: defaults = {}, + stopEarly = false, + string = [], + unknown = (i: unknown): unknown => i + }: Partial = {} +): Args { const flags: Flags = { bools: {}, strings: {}, - unknownFn: options.unknown, + unknownFn: unknown, allBools: false }; - if (options.boolean !== undefined) { - if (typeof options.boolean === "boolean") { - flags.allBools = !!options.boolean; + if (boolean !== undefined) { + if (typeof boolean === "boolean") { + flags.allBools = !!boolean; } else { - const booleanArgs: string[] = - typeof options.boolean === "string" - ? [options.boolean] - : options.boolean; + const booleanArgs = typeof boolean === "string" ? [boolean] : boolean; - booleanArgs.filter(Boolean).forEach((key: string): void => { + for (const key of booleanArgs.filter(Boolean)) { flags.bools[key] = true; - }); + } } } - const aliases: { [key: string]: string[] } = {}; - if (options.alias !== undefined) { - for (const key in options.alias) { - const val = getForce(options.alias, key); + const aliases: Record = {}; + if (alias !== undefined) { + for (const key in alias) { + const val = getForce(alias, key); if (typeof val === "string") { aliases[key] = [val]; } else { aliases[key] = val; } for (const alias of getForce(aliases, key)) { - aliases[alias] = [key].concat( - aliases[key].filter((y: string): boolean => alias !== y) - ); + aliases[alias] = [key].concat(aliases[key].filter(y => alias !== y)); } } } - if (options.string !== undefined) { - const stringArgs = - typeof options.string === "string" ? [options.string] : options.string; + if (string !== undefined) { + const stringArgs = typeof string === "string" ? [string] : string; - stringArgs.filter(Boolean).forEach(function(key): void { + for (const key of stringArgs.filter(Boolean)) { flags.strings[key] = true; const alias = get(aliases, key); if (alias) { - alias.forEach((alias: string): void => { - flags.strings[alias] = true; - }); + for (const al of alias) { + flags.strings[al] = true; + } } - }); + } } - const defaults = options.default; - - const argv: { [key: string]: unknown[] } = { _: [] }; + const argv: Args = { _: [] }; function argDefined(key: string, arg: string): boolean { return ( @@ -172,25 +204,28 @@ export function parse( const value = !get(flags.strings, key) && isNumber(val) ? Number(val) : val; setKey(argv, key.split("."), value); - (get(aliases, key) || []).forEach(function(x): void { - setKey(argv, x.split("."), value); - }); + const alias = get(aliases, key); + if (alias) { + for (const x of alias) { + setKey(argv, x.split("."), value); + } + } } function aliasIsBoolean(key: string): boolean { - return getForce(aliases, key).some(function(x): boolean { - return typeof get(flags.bools, x) === "boolean"; - }); + return getForce(aliases, key).some( + x => typeof get(flags.bools, x) === "boolean" + ); } - Object.keys(flags.bools).forEach(function(key): void { + for (const key of Object.keys(flags.bools)) { setArg(key, defaults[key] === undefined ? false : defaults[key]); - }); + } let notFlags: string[] = []; // all args after "--" are not parsed - if (args.indexOf("--") !== -1) { + if (args.includes("--")) { notFlags = args.slice(args.indexOf("--") + 1); args = args.slice(0, args.indexOf("--")); } @@ -199,13 +234,9 @@ export function parse( const arg = args[i]; if (/^--.+=/.test(arg)) { - // Using [\s\S] instead of . because js doesn't support the - // 'dotall' regex modifier. See: - // http://stackoverflow.com/a/1068308/13216 - const m = arg.match(/^--([^=]+)=([\s\S]*)$/); + const m = arg.match(/^--([^=]+)=(.*)$/s); assert(m != null); - const key = m[1]; - const value = m[2]; + const [, key, value] = m; if (flags.bools[key]) { const booleanValue = value !== "false"; @@ -220,7 +251,7 @@ export function parse( } else if (/^--.+/.test(arg)) { const m = arg.match(/^--(.+)/); assert(m != null); - const key = m[1]; + const [, key] = m; const next = args[i + 1]; if ( next !== undefined && @@ -273,7 +304,7 @@ export function parse( } } - const key = arg.slice(-1)[0]; + const [key] = arg.slice(-1); if (!broken && key !== "-") { if ( args[i + 1] && @@ -292,34 +323,36 @@ export function parse( } } else { if (!flags.unknownFn || flags.unknownFn(arg) !== false) { - argv._.push(flags.strings["_"] || !isNumber(arg) ? arg : Number(arg)); + argv._.push(flags.strings["_"] ?? !isNumber(arg) ? arg : Number(arg)); } - if (options.stopEarly) { + if (stopEarly) { argv._.push(...args.slice(i + 1)); break; } } } - Object.keys(defaults).forEach(function(key): void { + for (const key of Object.keys(defaults)) { if (!hasKey(argv, key.split("."))) { setKey(argv, key.split("."), defaults[key]); - (aliases[key] || []).forEach(function(x): void { - setKey(argv, x.split("."), defaults[key]); - }); + if (aliases[key]) { + for (const x of aliases[key]) { + setKey(argv, x.split("."), defaults[key]); + } + } } - }); + } - if (options["--"]) { + if (doubleDash) { argv["--"] = []; - notFlags.forEach(function(key): void { + for (const key of notFlags) { argv["--"].push(key); - }); + } } else { - notFlags.forEach(function(key): void { + for (const key of notFlags) { argv._.push(key); - }); + } } return argv; diff --git a/std/flags/num_test.ts b/std/flags/num_test.ts index 979d36cbf9..0d6b634b9d 100755 --- a/std/flags/num_test.ts +++ b/std/flags/num_test.ts @@ -33,7 +33,7 @@ Deno.test(function nums(): void { }); Deno.test(function alreadyNumber(): void { - const argv = parse(["-x", 1234, 789]); + const argv = parse(["-x", "1234", "789"]); assertEquals(argv, { x: 1234, _: [789] }); assertEquals(typeof argv.x, "number"); assertEquals(typeof argv._[0], "number");