From 43acceb75957c880a5ba5a31aae221394a36d5f6 Mon Sep 17 00:00:00 2001 From: littleblack111 Date: Thu, 16 May 2024 11:31:39 +0800 Subject: replaced html-minifier -> html-minifier-terser --- node_modules/commander/CHANGELOG.md | 419 ---------- node_modules/commander/Readme.md | 1222 ++++++++++++++++++++++------ node_modules/commander/index.js | 1225 +---------------------------- node_modules/commander/package.json | 74 +- node_modules/commander/typings/index.d.ts | 1177 ++++++++++++++++++++------- 5 files changed, 1914 insertions(+), 2203 deletions(-) delete mode 100644 node_modules/commander/CHANGELOG.md (limited to 'node_modules/commander') diff --git a/node_modules/commander/CHANGELOG.md b/node_modules/commander/CHANGELOG.md deleted file mode 100644 index 7dce779d..00000000 --- a/node_modules/commander/CHANGELOG.md +++ /dev/null @@ -1,419 +0,0 @@ -2.20.3 / 2019-10-11 -================== - - * Support Node.js 0.10 (Revert #1059) - * Ran "npm unpublish commander@2.20.2". There is no 2.20.2. - -2.20.1 / 2019-09-29 -================== - - * Improve executable subcommand tracking - * Update dev dependencies - -2.20.0 / 2019-04-02 -================== - - * fix: resolve symbolic links completely when hunting for subcommands (#935) - * Update index.d.ts (#930) - * Update Readme.md (#924) - * Remove --save option as it isn't required anymore (#918) - * Add link to the license file (#900) - * Added example of receiving args from options (#858) - * Added missing semicolon (#882) - * Add extension to .eslintrc (#876) - -2.19.0 / 2018-10-02 -================== - - * Removed newline after Options and Commands headers (#864) - * Bugfix - Error output (#862) - * Fix to change default value to string (#856) - -2.18.0 / 2018-09-07 -================== - - * Standardize help output (#853) - * chmod 644 travis.yml (#851) - * add support for execute typescript subcommand via ts-node (#849) - -2.17.1 / 2018-08-07 -================== - - * Fix bug in command emit (#844) - -2.17.0 / 2018-08-03 -================== - - * fixed newline output after help information (#833) - * Fix to emit the action even without command (#778) - * npm update (#823) - -2.16.0 / 2018-06-29 -================== - - * Remove Makefile and `test/run` (#821) - * Make 'npm test' run on Windows (#820) - * Add badge to display install size (#807) - * chore: cache node_modules (#814) - * chore: remove Node.js 4 (EOL), add Node.js 10 (#813) - * fixed typo in readme (#812) - * Fix types (#804) - * Update eslint to resolve vulnerabilities in lodash (#799) - * updated readme with custom event listeners. (#791) - * fix tests (#794) - -2.15.0 / 2018-03-07 -================== - - * Update downloads badge to point to graph of downloads over time instead of duplicating link to npm - * Arguments description - -2.14.1 / 2018-02-07 -================== - - * Fix typing of help function - -2.14.0 / 2018-02-05 -================== - - * only register the option:version event once - * Fixes issue #727: Passing empty string for option on command is set to undefined - * enable eqeqeq rule - * resolves #754 add linter configuration to project - * resolves #560 respect custom name for version option - * document how to override the version flag - * document using options per command - -2.13.0 / 2018-01-09 -================== - - * Do not print default for --no- - * remove trailing spaces in command help - * Update CI's Node.js to LTS and latest version - * typedefs: Command and Option types added to commander namespace - -2.12.2 / 2017-11-28 -================== - - * fix: typings are not shipped - -2.12.1 / 2017-11-23 -================== - - * Move @types/node to dev dependency - -2.12.0 / 2017-11-22 -================== - - * add attributeName() method to Option objects - * Documentation updated for options with --no prefix - * typings: `outputHelp` takes a string as the first parameter - * typings: use overloads - * feat(typings): update to match js api - * Print default value in option help - * Fix translation error - * Fail when using same command and alias (#491) - * feat(typings): add help callback - * fix bug when description is add after command with options (#662) - * Format js code - * Rename History.md to CHANGELOG.md (#668) - * feat(typings): add typings to support TypeScript (#646) - * use current node - -2.11.0 / 2017-07-03 -================== - - * Fix help section order and padding (#652) - * feature: support for signals to subcommands (#632) - * Fixed #37, --help should not display first (#447) - * Fix translation errors. (#570) - * Add package-lock.json - * Remove engines - * Upgrade package version - * Prefix events to prevent conflicts between commands and options (#494) - * Removing dependency on graceful-readlink - * Support setting name in #name function and make it chainable - * Add .vscode directory to .gitignore (Visual Studio Code metadata) - * Updated link to ruby commander in readme files - -2.10.0 / 2017-06-19 -================== - - * Update .travis.yml. drop support for older node.js versions. - * Fix require arguments in README.md - * On SemVer you do not start from 0.0.1 - * Add missing semi colon in readme - * Add save param to npm install - * node v6 travis test - * Update Readme_zh-CN.md - * Allow literal '--' to be passed-through as an argument - * Test subcommand alias help - * link build badge to master branch - * Support the alias of Git style sub-command - * added keyword commander for better search result on npm - * Fix Sub-Subcommands - * test node.js stable - * Fixes TypeError when a command has an option called `--description` - * Update README.md to make it beginner friendly and elaborate on the difference between angled and square brackets. - * Add chinese Readme file - -2.9.0 / 2015-10-13 -================== - - * Add option `isDefault` to set default subcommand #415 @Qix- - * Add callback to allow filtering or post-processing of help text #434 @djulien - * Fix `undefined` text in help information close #414 #416 @zhiyelee - -2.8.1 / 2015-04-22 -================== - - * Back out `support multiline description` Close #396 #397 - -2.8.0 / 2015-04-07 -================== - - * Add `process.execArg` support, execution args like `--harmony` will be passed to sub-commands #387 @DigitalIO @zhiyelee - * Fix bug in Git-style sub-commands #372 @zhiyelee - * Allow commands to be hidden from help #383 @tonylukasavage - * When git-style sub-commands are in use, yet none are called, display help #382 @claylo - * Add ability to specify arguments syntax for top-level command #258 @rrthomas - * Support multiline descriptions #208 @zxqfox - -2.7.1 / 2015-03-11 -================== - - * Revert #347 (fix collisions when option and first arg have same name) which causes a bug in #367. - -2.7.0 / 2015-03-09 -================== - - * Fix git-style bug when installed globally. Close #335 #349 @zhiyelee - * Fix collisions when option and first arg have same name. Close #346 #347 @tonylukasavage - * Add support for camelCase on `opts()`. Close #353 @nkzawa - * Add node.js 0.12 and io.js to travis.yml - * Allow RegEx options. #337 @palanik - * Fixes exit code when sub-command failing. Close #260 #332 @pirelenito - * git-style `bin` files in $PATH make sense. Close #196 #327 @zhiyelee - -2.6.0 / 2014-12-30 -================== - - * added `Command#allowUnknownOption` method. Close #138 #318 @doozr @zhiyelee - * Add application description to the help msg. Close #112 @dalssoft - -2.5.1 / 2014-12-15 -================== - - * fixed two bugs incurred by variadic arguments. Close #291 @Quentin01 #302 @zhiyelee - -2.5.0 / 2014-10-24 -================== - - * add support for variadic arguments. Closes #277 @whitlockjc - -2.4.0 / 2014-10-17 -================== - - * fixed a bug on executing the coercion function of subcommands option. Closes #270 - * added `Command.prototype.name` to retrieve command name. Closes #264 #266 @tonylukasavage - * added `Command.prototype.opts` to retrieve all the options as a simple object of key-value pairs. Closes #262 @tonylukasavage - * fixed a bug on subcommand name. Closes #248 @jonathandelgado - * fixed function normalize doesn’t honor option terminator. Closes #216 @abbr - -2.3.0 / 2014-07-16 -================== - - * add command alias'. Closes PR #210 - * fix: Typos. Closes #99 - * fix: Unused fs module. Closes #217 - -2.2.0 / 2014-03-29 -================== - - * add passing of previous option value - * fix: support subcommands on windows. Closes #142 - * Now the defaultValue passed as the second argument of the coercion function. - -2.1.0 / 2013-11-21 -================== - - * add: allow cflag style option params, unit test, fixes #174 - -2.0.0 / 2013-07-18 -================== - - * remove input methods (.prompt, .confirm, etc) - -1.3.2 / 2013-07-18 -================== - - * add support for sub-commands to co-exist with the original command - -1.3.1 / 2013-07-18 -================== - - * add quick .runningCommand hack so you can opt-out of other logic when running a sub command - -1.3.0 / 2013-07-09 -================== - - * add EACCES error handling - * fix sub-command --help - -1.2.0 / 2013-06-13 -================== - - * allow "-" hyphen as an option argument - * support for RegExp coercion - -1.1.1 / 2012-11-20 -================== - - * add more sub-command padding - * fix .usage() when args are present. Closes #106 - -1.1.0 / 2012-11-16 -================== - - * add git-style executable subcommand support. Closes #94 - -1.0.5 / 2012-10-09 -================== - - * fix `--name` clobbering. Closes #92 - * fix examples/help. Closes #89 - -1.0.4 / 2012-09-03 -================== - - * add `outputHelp()` method. - -1.0.3 / 2012-08-30 -================== - - * remove invalid .version() defaulting - -1.0.2 / 2012-08-24 -================== - - * add `--foo=bar` support [arv] - * fix password on node 0.8.8. Make backward compatible with 0.6 [focusaurus] - -1.0.1 / 2012-08-03 -================== - - * fix issue #56 - * fix tty.setRawMode(mode) was moved to tty.ReadStream#setRawMode() (i.e. process.stdin.setRawMode()) - -1.0.0 / 2012-07-05 -================== - - * add support for optional option descriptions - * add defaulting of `.version()` to package.json's version - -0.6.1 / 2012-06-01 -================== - - * Added: append (yes or no) on confirmation - * Added: allow node.js v0.7.x - -0.6.0 / 2012-04-10 -================== - - * Added `.prompt(obj, callback)` support. Closes #49 - * Added default support to .choose(). Closes #41 - * Fixed the choice example - -0.5.1 / 2011-12-20 -================== - - * Fixed `password()` for recent nodes. Closes #36 - -0.5.0 / 2011-12-04 -================== - - * Added sub-command option support [itay] - -0.4.3 / 2011-12-04 -================== - - * Fixed custom help ordering. Closes #32 - -0.4.2 / 2011-11-24 -================== - - * Added travis support - * Fixed: line-buffered input automatically trimmed. Closes #31 - -0.4.1 / 2011-11-18 -================== - - * Removed listening for "close" on --help - -0.4.0 / 2011-11-15 -================== - - * Added support for `--`. Closes #24 - -0.3.3 / 2011-11-14 -================== - - * Fixed: wait for close event when writing help info [Jerry Hamlet] - -0.3.2 / 2011-11-01 -================== - - * Fixed long flag definitions with values [felixge] - -0.3.1 / 2011-10-31 -================== - - * Changed `--version` short flag to `-V` from `-v` - * Changed `.version()` so it's configurable [felixge] - -0.3.0 / 2011-10-31 -================== - - * Added support for long flags only. Closes #18 - -0.2.1 / 2011-10-24 -================== - - * "node": ">= 0.4.x < 0.7.0". Closes #20 - -0.2.0 / 2011-09-26 -================== - - * Allow for defaults that are not just boolean. Default peassignment only occurs for --no-*, optional, and required arguments. [Jim Isaacs] - -0.1.0 / 2011-08-24 -================== - - * Added support for custom `--help` output - -0.0.5 / 2011-08-18 -================== - - * Changed: when the user enters nothing prompt for password again - * Fixed issue with passwords beginning with numbers [NuckChorris] - -0.0.4 / 2011-08-15 -================== - - * Fixed `Commander#args` - -0.0.3 / 2011-08-15 -================== - - * Added default option value support - -0.0.2 / 2011-08-15 -================== - - * Added mask support to `Command#password(str[, mask], fn)` - * Added `Command#password(str, fn)` - -0.0.1 / 2010-01-03 -================== - - * Initial release diff --git a/node_modules/commander/Readme.md b/node_modules/commander/Readme.md index c846e7a2..095e2aef 100644 --- a/node_modules/commander/Readme.md +++ b/node_modules/commander/Readme.md @@ -1,428 +1,1134 @@ # Commander.js - -[![Build Status](https://api.travis-ci.org/tj/commander.js.svg?branch=master)](http://travis-ci.org/tj/commander.js) +[![Build Status](https://github.com/tj/commander.js/workflows/build/badge.svg)](https://github.com/tj/commander.js/actions?query=workflow%3A%22build%22) [![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander) [![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true) [![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander) -[![Join the chat at https://gitter.im/tj/commander.js](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/tj/commander.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - - The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/commander-rb/commander). - [API documentation](http://tj.github.com/commander.js/) +The complete solution for [node.js](http://nodejs.org) command-line interfaces. + +Read this in other languages: English | [简体中文](./Readme_zh-CN.md) + +- [Commander.js](#commanderjs) + - [Installation](#installation) + - [Quick Start](#quick-start) + - [Declaring _program_ variable](#declaring-program-variable) + - [Options](#options) + - [Common option types, boolean and value](#common-option-types-boolean-and-value) + - [Default option value](#default-option-value) + - [Other option types, negatable boolean and boolean|value](#other-option-types-negatable-boolean-and-booleanvalue) + - [Required option](#required-option) + - [Variadic option](#variadic-option) + - [Version option](#version-option) + - [More configuration](#more-configuration) + - [Custom option processing](#custom-option-processing) + - [Commands](#commands) + - [Command-arguments](#command-arguments) + - [More configuration](#more-configuration-1) + - [Custom argument processing](#custom-argument-processing) + - [Action handler](#action-handler) + - [Stand-alone executable (sub)commands](#stand-alone-executable-subcommands) + - [Life cycle hooks](#life-cycle-hooks) + - [Automated help](#automated-help) + - [Custom help](#custom-help) + - [Display help after errors](#display-help-after-errors) + - [Display help from code](#display-help-from-code) + - [.name](#name) + - [.usage](#usage) + - [.description and .summary](#description-and-summary) + - [.helpOption(flags, description)](#helpoptionflags-description) + - [.addHelpCommand()](#addhelpcommand) + - [More configuration](#more-configuration-2) + - [Custom event listeners](#custom-event-listeners) + - [Bits and pieces](#bits-and-pieces) + - [.parse() and .parseAsync()](#parse-and-parseasync) + - [Parsing Configuration](#parsing-configuration) + - [Legacy options as properties](#legacy-options-as-properties) + - [TypeScript](#typescript) + - [createCommand()](#createcommand) + - [Node options such as `--harmony`](#node-options-such-as---harmony) + - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands) + - [Display error](#display-error) + - [Override exit and output handling](#override-exit-and-output-handling) + - [Additional documentation](#additional-documentation) + - [Support](#support) + - [Commander for enterprise](#commander-for-enterprise) + +For information about terms used in this document see: [terminology](./docs/terminology.md) ## Installation - $ npm install commander +```sh +npm install commander +``` + +## Quick Start + +You write code to describe your command line interface. +Commander looks after parsing the arguments into options and command-arguments, +displays usage errors for problems, and implements a help system. -## Option parsing +Commander is strict and displays an error for unrecognised options. +The two most used option types are a boolean option, and an option which takes its value from the following argument. -Options with commander are defined with the `.option()` method, also serving as documentation for the options. The example below parses args and options from `process.argv`, leaving remaining args as the `program.args` array which were not consumed by options. +Example file: [split.js](./examples/split.js) ```js -#!/usr/bin/env node +const { program } = require('commander'); + +program + .option('--first') + .option('-s, --separator '); + +program.parse(); + +const options = program.opts(); +const limit = options.first ? 1 : undefined; +console.log(program.args[0].split(options.separator, limit)); +``` + +```console +$ node split.js -s / --fits a/b/c +error: unknown option '--fits' +(Did you mean --first?) +$ node split.js -s / --first a/b/c +[ 'a' ] +``` + +Here is a more complete program using a subcommand and with descriptions for the help. In a multi-command program, you have an action handler for each command (or stand-alone executables for the commands). -/** - * Module dependencies. - */ +Example file: [string-util.js](./examples/string-util.js) -var program = require('commander'); +```js +const { Command } = require('commander'); +const program = new Command(); program - .version('0.1.0') - .option('-p, --peppers', 'Add peppers') - .option('-P, --pineapple', 'Add pineapple') - .option('-b, --bbq-sauce', 'Add bbq sauce') - .option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble') - .parse(process.argv); + .name('string-util') + .description('CLI to some JavaScript string utilities') + .version('0.8.0'); + +program.command('split') + .description('Split a string into substrings and display as an array') + .argument('', 'string to split') + .option('--first', 'display just the first substring') + .option('-s, --separator ', 'separator character', ',') + .action((str, options) => { + const limit = options.first ? 1 : undefined; + console.log(str.split(options.separator, limit)); + }); -console.log('you ordered a pizza with:'); -if (program.peppers) console.log(' - peppers'); -if (program.pineapple) console.log(' - pineapple'); -if (program.bbqSauce) console.log(' - bbq'); -console.log(' - %s cheese', program.cheese); +program.parse(); ``` -Short flags may be passed as a single arg, for example `-abc` is equivalent to `-a -b -c`. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc. +```console +$ node string-util.js help split +Usage: string-util split [options] + +Split a string into substrings and display as an array. + +Arguments: + string string to split + +Options: + --first display just the first substring + -s, --separator separator character (default: ",") + -h, --help display help for command + +$ node string-util.js split --separator=/ a/b/c +[ 'a', 'b', 'c' ] +``` -Note that multi-word options starting with `--no` prefix negate the boolean value of the following word. For example, `--no-sauce` sets the value of `program.sauce` to false. +More samples can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory. + +## Declaring _program_ variable + +Commander exports a global object which is convenient for quick programs. +This is used in the examples in this README for brevity. + +```js +// CommonJS (.cjs) +const { program } = require('commander'); +``` + +For larger programs which may use commander in multiple ways, including unit testing, it is better to create a local Command object to use. ```js -#!/usr/bin/env node +// CommonJS (.cjs) +const { Command } = require('commander'); +const program = new Command(); +``` + +```js +// ECMAScript (.mjs) +import { Command } from 'commander'; +const program = new Command(); +``` + +```ts +// TypeScript (.ts) +import { Command } from 'commander'; +const program = new Command(); +``` + +## Options + +Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|'). + +The parsed options can be accessed by calling `.opts()` on a `Command` object, and are passed to the action handler. + +Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc. + +An option and its option-argument can be separated by a space, or combined into the same argument. The option-argument can follow the short option directly or follow an `=` for a long option. + +```sh +serve -p 80 +serve -p80 +serve --port 80 +serve --port=80 +``` + +You can use `--` to indicate the end of the options, and any remaining arguments will be used without being interpreted. + +By default options on the command line are not positional, and can be specified before or after other arguments. -/** - * Module dependencies. - */ +There are additional related routines for when `.opts()` is not enough: -var program = require('commander'); +- `.optsWithGlobals()` returns merged local and global option values +- `.getOptionValue()` and `.setOptionValue()` work with a single option value +- `.getOptionValueSource()` and `.setOptionValueWithSource()` include where the option value came from +### Common option types, boolean and value + +The two most used option types are a boolean option, and an option which takes its value +from the following argument (declared with angle brackets like `--expect `). Both are `undefined` unless specified on command line. + +Example file: [options-common.js](./examples/options-common.js) + +```js +program + .option('-d, --debug', 'output extra debugging') + .option('-s, --small', 'small pizza size') + .option('-p, --pizza-type ', 'flavour of pizza'); + +program.parse(process.argv); + +const options = program.opts(); +if (options.debug) console.log(options); +console.log('pizza details:'); +if (options.small) console.log('- small pizza size'); +if (options.pizzaType) console.log(`- ${options.pizzaType}`); +``` + +```console +$ pizza-options -p +error: option '-p, --pizza-type ' argument missing +$ pizza-options -d -s -p vegetarian +{ debug: true, small: true, pizzaType: 'vegetarian' } +pizza details: +- small pizza size +- vegetarian +$ pizza-options --pizza-type=cheese +pizza details: +- cheese +``` + +Multiple boolean short options may be combined together following the dash, and may be followed by a single short option taking a value. +For example `-d -s -p cheese` may be written as `-ds -p cheese` or even `-dsp cheese`. + +Options with an expected option-argument are greedy and will consume the following argument whatever the value. +So `--id -xyz` reads `-xyz` as the option-argument. + +`program.parse(arguments)` processes the arguments, leaving any args not consumed by the program options in the `program.args` array. The parameter is optional and defaults to `process.argv`. + +### Default option value + +You can specify a default value for an option. + +Example file: [options-defaults.js](./examples/options-defaults.js) + +```js +program + .option('-c, --cheese ', 'add the specified type of cheese', 'blue'); + +program.parse(); + +console.log(`cheese: ${program.opts().cheese}`); +``` + +```console +$ pizza-options +cheese: blue +$ pizza-options --cheese stilton +cheese: stilton +``` + +### Other option types, negatable boolean and boolean|value + +You can define a boolean option long name with a leading `no-` to set the option value to false when used. +Defined alone this also makes the option true by default. + +If you define `--foo` first, adding `--no-foo` does not change the default value from what it would +otherwise be. + +Example file: [options-negatable.js](./examples/options-negatable.js) + +```js program .option('--no-sauce', 'Remove sauce') - .parse(process.argv); + .option('--cheese ', 'cheese flavour', 'mozzarella') + .option('--no-cheese', 'plain with no cheese') + .parse(); + +const options = program.opts(); +const sauceStr = options.sauce ? 'sauce' : 'no sauce'; +const cheeseStr = (options.cheese === false) ? 'no cheese' : `${options.cheese} cheese`; +console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`); +``` -console.log('you ordered a pizza'); -if (program.sauce) console.log(' with sauce'); -else console.log(' without sauce'); +```console +$ pizza-options +You ordered a pizza with sauce and mozzarella cheese +$ pizza-options --sauce +error: unknown option '--sauce' +$ pizza-options --cheese=blue +You ordered a pizza with sauce and blue cheese +$ pizza-options --no-sauce --no-cheese +You ordered a pizza with no sauce and no cheese ``` -To get string arguments from options you will need to use angle brackets <> for required inputs or square brackets [] for optional inputs. +You can specify an option which may be used as a boolean option but may optionally take an option-argument +(declared with square brackets like `--optional [value]`). -e.g. ```.option('-m --myarg [myVar]', 'my super cool description')``` +Example file: [options-boolean-or-value.js](./examples/options-boolean-or-value.js) -Then to access the input if it was passed in. +```js +program + .option('-c, --cheese [type]', 'Add cheese with optional type'); -e.g. ```var myInput = program.myarg``` +program.parse(process.argv); + +const options = program.opts(); +if (options.cheese === undefined) console.log('no cheese'); +else if (options.cheese === true) console.log('add cheese'); +else console.log(`add cheese type ${options.cheese}`); +``` -**NOTE**: If you pass a argument without using brackets the example above will return true and not the value passed in. +```console +$ pizza-options +no cheese +$ pizza-options --cheese +add cheese +$ pizza-options --cheese mozzarella +add cheese type mozzarella +``` +Options with an optional option-argument are not greedy and will ignore arguments starting with a dash. +So `id` behaves as a boolean option for `--id -5`, but you can use a combined form if needed like `--id=-5`. -## Version option +For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md). -Calling the `version` implicitly adds the `-V` and `--version` options to the command. -When either of these options is present, the command prints the version number and exits. +### Required option - $ ./examples/pizza -V - 0.0.1 +You may specify a required (mandatory) option using `.requiredOption()`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option()` in format, taking flags and description, and optional default value or custom processing. -If you want your program to respond to the `-v` option instead of the `-V` option, simply pass custom flags to the `version` method using the same syntax as the `option` method. +Example file: [options-required.js](./examples/options-required.js) ```js program - .version('0.0.1', '-v, --version') + .requiredOption('-c, --cheese ', 'pizza must have cheese'); + +program.parse(); ``` -The version flags can be named anything, but the long option is required. +```console +$ pizza +error: required option '-c, --cheese ' not specified +``` -## Command-specific options +### Variadic option -You can attach options to a command. +You may make an option variadic by appending `...` to the value placeholder when declaring the option. On the command line you +can then specify multiple option-arguments, and the parsed option value will be an array. The extra arguments +are read until the first argument starting with a dash. The special argument `--` stops option processing entirely. If a value +is specified in the same argument as the option then no further values are read. + +Example file: [options-variadic.js](./examples/options-variadic.js) ```js -#!/usr/bin/env node +program + .option('-n, --number ', 'specify numbers') + .option('-l, --letter [letters...]', 'specify letters'); -var program = require('commander'); +program.parse(); +console.log('Options: ', program.opts()); +console.log('Remaining arguments: ', program.args); +``` + +```console +$ collect -n 1 2 3 --letter a b c +Options: { number: [ '1', '2', '3' ], letter: [ 'a', 'b', 'c' ] } +Remaining arguments: [] +$ collect --letter=A -n80 operand +Options: { number: [ '80' ], letter: [ 'A' ] } +Remaining arguments: [ 'operand' ] +$ collect --letter -n 1 -n 2 3 -- operand +Options: { number: [ '1', '2', '3' ], letter: true } +Remaining arguments: [ 'operand' ] +``` + +For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md). + +### Version option + +The optional `version` method adds handling for displaying the command version. The default option flags are `-V` and `--version`, and when present the command prints the version number and exits. + +```js +program.version('0.0.1'); +``` + +```console +$ ./examples/pizza -V +0.0.1 +``` + +You may change the flags and description by passing additional parameters to the `version` method, using +the same syntax for flags as the `option` method. + +```js +program.version('0.0.1', '-v, --vers', 'output the current version'); +``` + +### More configuration + +You can add most options using the `.option()` method, but there are some additional features available +by constructing an `Option` explicitly for less common cases. + +Example files: [options-extra.js](./examples/options-extra.js), [options-env.js](./examples/options-env.js), [options-conflicts.js](./examples/options-conflicts.js), [options-implies.js](./examples/options-implies.js) + +```js program - .command('rm ') - .option('-r, --recursive', 'Remove recursively') - .action(function (dir, cmd) { - console.log('remove ' + dir + (cmd.recursive ? ' recursively' : '')) - }) + .addOption(new Option('-s, --secret').hideHelp()) + .addOption(new Option('-t, --timeout ', 'timeout in seconds').default(60, 'one minute')) + .addOption(new Option('-d, --drink ', 'drink size').choices(['small', 'medium', 'large'])) + .addOption(new Option('-p, --port ', 'port number').env('PORT')) + .addOption(new Option('--donate [amount]', 'optional donation in dollars').preset('20').argParser(parseFloat)) + .addOption(new Option('--disable-server', 'disables the server').conflicts('port')) + .addOption(new Option('--free-drink', 'small drink included free ').implies({ drink: 'small' })); +``` + +```console +$ extra --help +Usage: help [options] -program.parse(process.argv) +Options: + -t, --timeout timeout in seconds (default: one minute) + -d, --drink drink cup size (choices: "small", "medium", "large") + -p, --port port number (env: PORT) + --donate [amount] optional donation in dollars (preset: "20") + --disable-server disables the server + --free-drink small drink included free + -h, --help display help for command + +$ extra --drink huge +error: option '-d, --drink ' argument 'huge' is invalid. Allowed choices are small, medium, large. + +$ PORT=80 extra --donate --free-drink +Options: { timeout: 60, donate: 20, port: '80', freeDrink: true, drink: 'small' } + +$ extra --disable-server --port 8000 +error: option '--disable-server' cannot be used with option '-p, --port ' ``` -A command's options are validated when the command is used. Any unknown options will be reported as an error. However, if an action-based command does not define an action, then the options are not validated. +Specify a required (mandatory) option using the `Option` method `.makeOptionMandatory()`. This matches the `Command` method [.requiredOption()](#required-option). + +### Custom option processing + +You may specify a function to do custom processing of option-arguments. The callback function receives two parameters, +the user specified option-argument and the previous value for the option. It returns the new value for the option. + +This allows you to coerce the option-argument to the desired type, or accumulate values, or do entirely custom processing. -## Coercion +You can optionally specify the default/starting value for the option after the function parameter. + +Example file: [options-custom-processing.js](./examples/options-custom-processing.js) ```js -function range(val) { - return val.split('..').map(Number); +function myParseInt(value, dummyPrevious) { + // parseInt takes a string and a radix + const parsedValue = parseInt(value, 10); + if (isNaN(parsedValue)) { + throw new commander.InvalidArgumentError('Not a number.'); + } + return parsedValue; } -function list(val) { - return val.split(','); +function increaseVerbosity(dummyValue, previous) { + return previous + 1; } -function collect(val, memo) { - memo.push(val); - return memo; +function collect(value, previous) { + return previous.concat([value]); } -function increaseVerbosity(v, total) { - return total + 1; +function commaSeparatedList(value, dummyPrevious) { + return value.split(','); } program - .version('0.1.0') - .usage('[options] ') - .option('-i, --integer ', 'An integer argument', parseInt) - .option('-f, --float ', 'A float argument', parseFloat) - .option('-r, --range ..', 'A range', range) - .option('-l, --list ', 'A list', list) - .option('-o, --optional [value]', 'An optional value') - .option('-c, --collect [value]', 'A repeatable value', collect, []) - .option('-v, --verbose', 'A value that can be increased', increaseVerbosity, 0) - .parse(process.argv); - -console.log(' int: %j', program.integer); -console.log(' float: %j', program.float); -console.log(' optional: %j', program.optional); -program.range = program.range || []; -console.log(' range: %j..%j', program.range[0], program.range[1]); -console.log(' list: %j', program.list); -console.log(' collect: %j', program.collect); -console.log(' verbosity: %j', program.verbose); -console.log(' args: %j', program.args); -``` - -## Regular Expression + .option('-f, --float ', 'float argument', parseFloat) + .option('-i, --integer ', 'integer argument', myParseInt) + .option('-v, --verbose', 'verbosity that can be increased', increaseVerbosity, 0) + .option('-c, --collect ', 'repeatable value', collect, []) + .option('-l, --list ', 'comma separated list', commaSeparatedList) +; + +program.parse(); + +const options = program.opts(); +if (options.float !== undefined) console.log(`float: ${options.float}`); +if (options.integer !== undefined) console.log(`integer: ${options.integer}`); +if (options.verbose > 0) console.log(`verbosity: ${options.verbose}`); +if (options.collect.length > 0) console.log(options.collect); +if (options.list !== undefined) console.log(options.list); +``` + +```console +$ custom -f 1e2 +float: 100 +$ custom --integer 2 +integer: 2 +$ custom -v -v -v +verbose: 3 +$ custom -c a -c b -c c +[ 'a', 'b', 'c' ] +$ custom --list x,y,z +[ 'x', 'y', 'z' ] +``` + +## Commands + +You can specify (sub)commands using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)). + +In the first parameter to `.command()` you specify the command name. You may append the command-arguments after the command name, or specify them separately using `.argument()`. The arguments may be `` or `[optional]`, and the last argument may also be `variadic...`. + +You can use `.addCommand()` to add an already configured subcommand to the program. + +For example: + ```js +// Command implemented using action handler (description is supplied separately to `.command`) +// Returns new command for configuring. program - .version('0.1.0') - .option('-s --size ', 'Pizza size', /^(large|medium|small)$/i, 'medium') - .option('-d --drink [drink]', 'Drink', /^(coke|pepsi|izze)$/i) - .parse(process.argv); + .command('clone [destination]') + .description('clone a repository into a newly created directory') + .action((source, destination) => { + console.log('clone command called'); + }); + +// Command implemented using stand-alone executable file, indicated by adding description as second parameter to `.command`. +// Returns `this` for adding more commands. +program + .command('start ', 'start named service') + .command('stop [service]', 'stop named service, or all if no name supplied'); -console.log(' size: %j', program.size); -console.log(' drink: %j', program.drink); +// Command prepared separately. +// Returns `this` for adding more commands. +program + .addCommand(build.makeBuildCommand()); ``` -## Variadic arguments +Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will +remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other +subcommand is specified ([example](./examples/defaultCommand.js)). - The last argument of a command can be variadic, and only the last argument. To make an argument variadic you have to - append `...` to the argument name. Here is an example: +You can add alternative names for a command with `.alias()`. ([example](./examples/alias.js)) -```js -#!/usr/bin/env node +For safety, `.addCommand()` does not automatically copy the inherited settings from the parent command. There is a helper routine `.copyInheritedSettings()` for copying the settings when they are wanted. + +### Command-arguments -/** - * Module dependencies. - */ +For subcommands, you can specify the argument syntax in the call to `.command()` (as shown above). This +is the only method usable for subcommands implemented using a stand-alone executable, but for other subcommands +you can instead use the following method. -var program = require('commander'); +To configure a command, you can use `.argument()` to specify each expected command-argument. +You supply the argument name and an optional description. The argument may be `` or `[optional]`. +You can specify a default value for an optional command-argument. +Example file: [argument.js](./examples/argument.js) + +```js program .version('0.1.0') - .command('rmdir [otherDirs...]') - .action(function (dir, otherDirs) { - console.log('rmdir %s', dir); - if (otherDirs) { - otherDirs.forEach(function (oDir) { - console.log('rmdir %s', oDir); - }); - } + .argument('', 'user to login') + .argument('[password]', 'password for user, if required', 'no password given') + .action((username, password) => { + console.log('username:', username); + console.log('password:', password); }); +``` -program.parse(process.argv); + The last argument of a command can be variadic, and only the last argument. To make an argument variadic you + append `...` to the argument name. A variadic argument is passed to the action handler as an array. For example: + +```js +program + .version('0.1.0') + .command('rmdir') + .argument('') + .action(function (dirs) { + dirs.forEach((dir) => { + console.log('rmdir %s', dir); + }); + }); +``` + +There is a convenience method to add multiple arguments at once, but without descriptions: + +```js +program + .arguments(' '); +``` + +#### More configuration + +There are some additional features available by constructing an `Argument` explicitly for less common cases. + +Example file: [arguments-extra.js](./examples/arguments-extra.js) + +```js +program + .addArgument(new commander.Argument('', 'drink cup size').choices(['small', 'medium', 'large'])) + .addArgument(new commander.Argument('[timeout]', 'timeout in seconds').default(60, 'one minute')) ``` - An `Array` is used for the value of a variadic argument. This applies to `program.args` as well as the argument passed - to your action as demonstrated above. +#### Custom argument processing + +You may specify a function to do custom processing of command-arguments (like for option-arguments). +The callback function receives two parameters, the user specified command-argument and the previous value for the argument. +It returns the new value for the argument. + +The processed argument values are passed to the action handler, and saved as `.processedArgs`. -## Specify the argument syntax +You can optionally specify the default/starting value for the argument after the function parameter. + +Example file: [arguments-custom-processing.js](./examples/arguments-custom-processing.js) ```js -#!/usr/bin/env node +program + .command('add') + .argument('', 'integer argument', myParseInt) + .argument('[second]', 'integer argument', myParseInt, 1000) + .action((first, second) => { + console.log(`${first} + ${second} = ${first + second}`); + }) +; +``` + +### Action handler -var program = require('commander'); +The action handler gets passed a parameter for each command-argument you declared, and two additional parameters +which are the parsed options and the command object itself. +Example file: [thank.js](./examples/thank.js) + +```js program - .version('0.1.0') - .arguments(' [env]') - .action(function (cmd, env) { - cmdValue = cmd; - envValue = env; + .argument('') + .option('-t, --title ', 'title to use before name') + .option('-d, --debug', 'display some debugging') + .action((name, options, command) => { + if (options.debug) { + console.error('Called %s with options %o', command.name(), options); + } + const title = options.title ? `${options.title} ` : ''; + console.log(`Thank-you ${title}${name}`); }); +``` -program.parse(process.argv); +If you prefer, you can work with the command directly and skip declaring the parameters for the action handler. The `this` keyword is set to the running command and can be used from a function expression (but not from an arrow function). -if (typeof cmdValue === 'undefined') { - console.error('no command given!'); - process.exit(1); -} -console.log('command:', cmdValue); -console.log('environment:', envValue || "no environment given"); +Example file: [action-this.js](./examples/action-this.js) + +```js +program + .command('serve') + .argument('