From 7b386197085a0c32d924b1ef1c690716491eae15 Mon Sep 17 00:00:00 2001 From: John Gee Date: Sun, 10 Sep 2023 16:41:45 +1200 Subject: [PATCH 1/3] Improve option() parseArg param inline docs --- lib/command.js | 59 +++++++++++++--------------------------------- typings/index.d.ts | 48 ++++++++++--------------------------- 2 files changed, 29 insertions(+), 78 deletions(-) diff --git a/lib/command.js b/lib/command.js index 1ade8881f..9509d7054 100644 --- a/lib/command.js +++ b/lib/command.js @@ -632,57 +632,32 @@ Expecting one of '${allowedValues.join("', '")}'`); } /** - * Define option with `flags`, `description` and optional - * coercion `fn`. + * Define option with `flags`, `description`, and optional argument parsing function or `defaultValue` or both. * - * The `flags` string contains the short and/or long flags, - * separated by comma, a pipe or space. The following are all valid - * all will output this way when `--help` is used. + * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. A required + * option-argument is indicated by `<>` and an optional option-argument by `[]`. * - * "-p, --pepper" - * "-p|--pepper" - * "-p --pepper" + * See the README for more details, and see also addOption() and requiredOption(). * * @example - * // simple boolean defaulting to undefined - * program.option('-p, --pepper', 'add pepper'); * - * program.pepper - * // => undefined - * - * --pepper - * program.pepper - * // => true - * - * // simple boolean defaulting to true (unless non-negated option is also defined) - * program.option('-C, --no-cheese', 'remove cheese'); - * - * program.cheese - * // => true - * - * --no-cheese - * program.cheese - * // => false - * - * // required argument - * program.option('-C, --chdir ', 'change the working directory'); - * - * --chdir /tmp - * program.chdir - * // => "/tmp" - * - * // optional argument - * program.option('-c, --cheese [type]', 'add cheese [marble]'); + * ```js + * program + * .option('-p, --pepper', 'add pepper') + * .option('-p, --pizza-type ', 'type of pizza') // required option-argument + * .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default + * .option('-t, --tip ', 'add tip to purchase cost', parseFloat) // custom parse function + * ``` * * @param {string} flags * @param {string} [description] - * @param {Function|*} [fn] - custom option processing function or default value + * @param {Function|*} [parseArg] - custom option processing function or default value * @param {*} [defaultValue] * @return {Command} `this` command for chaining */ - option(flags, description, fn, defaultValue) { - return this._optionEx({}, flags, description, fn, defaultValue); + option(flags, description, parseArg, defaultValue) { + return this._optionEx({}, flags, description, parseArg, defaultValue); } /** @@ -693,13 +668,13 @@ Expecting one of '${allowedValues.join("', '")}'`); * * @param {string} flags * @param {string} [description] - * @param {Function|*} [fn] - custom option processing function or default value + * @param {Function|*} [parseArg] - custom option processing function or default value * @param {*} [defaultValue] * @return {Command} `this` command for chaining */ - requiredOption(flags, description, fn, defaultValue) { - return this._optionEx({ mandatory: true }, flags, description, fn, defaultValue); + requiredOption(flags, description, parseArg, defaultValue) { + return this._optionEx({ mandatory: true }, flags, description, parseArg, defaultValue); } /** diff --git a/typings/index.d.ts b/typings/index.d.ts index e032d91b3..cc6b9ca8a 100644 --- a/typings/index.d.ts +++ b/typings/index.d.ts @@ -510,51 +510,27 @@ export class Command { action(fn: (...args: any[]) => void | Promise): this; /** - * Define option with `flags`, `description` and optional - * coercion `fn`. + * Define option with `flags`, `description`, and optional argument parsing function or `defaultValue` or both. * - * The `flags` string contains the short and/or long flags, - * separated by comma, a pipe or space. The following are all valid - * all will output this way when `--help` is used. + * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. A required + * option-argument is indicated by `<>` and an optional option-argument by `[]`. * - * "-p, --pepper" - * "-p|--pepper" - * "-p --pepper" + * See the README for more details, and see also addOption() and requiredOption(). * * @example - * ``` - * // simple boolean defaulting to false - * program.option('-p, --pepper', 'add pepper'); - * - * --pepper - * program.pepper - * // => Boolean - * - * // simple boolean defaulting to true - * program.option('-C, --no-cheese', 'remove cheese'); - * - * program.cheese - * // => true * - * --no-cheese - * program.cheese - * // => false - * - * // required argument - * program.option('-C, --chdir ', 'change the working directory'); - * - * --chdir /tmp - * program.chdir - * // => "/tmp" - * - * // optional argument - * program.option('-c, --cheese [type]', 'add cheese [marble]'); + * ```js + * program + * .option('-p, --pepper', 'add pepper') + * .option('-p, --pizza-type ', 'type of pizza') // required option-argument + * .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default + * .option('-t, --tip ', 'add tip to purchase cost', parseFloat) // custom parse function * ``` * * @returns `this` command for chaining */ option(flags: string, description?: string, defaultValue?: string | boolean | string[]): this; - option(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this; + option(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this; /** @deprecated since v7, instead use choices or a custom function */ option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this; @@ -565,7 +541,7 @@ export class Command { * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. */ requiredOption(flags: string, description?: string, defaultValue?: string | boolean | string[]): this; - requiredOption(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this; + requiredOption(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this; /** @deprecated since v7, instead use choices or a custom function */ requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this; From 74bdc268989bf3ada971d774ae4094a28c16d9a0 Mon Sep 17 00:00:00 2001 From: John Gee Date: Sun, 10 Sep 2023 16:52:35 +1200 Subject: [PATCH 2/3] Follow JSDoc style --- lib/command.js | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/lib/command.js b/lib/command.js index 9509d7054..3f55dd9ec 100644 --- a/lib/command.js +++ b/lib/command.js @@ -640,14 +640,11 @@ Expecting one of '${allowedValues.join("', '")}'`); * See the README for more details, and see also addOption() and requiredOption(). * * @example - * - * ```js * program * .option('-p, --pepper', 'add pepper') * .option('-p, --pizza-type ', 'type of pizza') // required option-argument * .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default * .option('-t, --tip ', 'add tip to purchase cost', parseFloat) // custom parse function - * ``` * * @param {string} flags * @param {string} [description] @@ -656,7 +653,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * @return {Command} `this` command for chaining */ - option(flags, description, parseArg, defaultValue) { + optionx(flags, description, parseArg, defaultValue) { return this._optionEx({}, flags, description, parseArg, defaultValue); } From d4450be3ccde08c85db246ff815bf29a9684295a Mon Sep 17 00:00:00 2001 From: John Gee Date: Sun, 10 Sep 2023 16:57:35 +1200 Subject: [PATCH 3/3] Remove function rename (from testing inline docs) --- lib/command.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/command.js b/lib/command.js index 3f55dd9ec..e9f655f6b 100644 --- a/lib/command.js +++ b/lib/command.js @@ -653,7 +653,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * @return {Command} `this` command for chaining */ - optionx(flags, description, parseArg, defaultValue) { + option(flags, description, parseArg, defaultValue) { return this._optionEx({}, flags, description, parseArg, defaultValue); }