From fd1fdad7021e5936eb26ec68372c3df6d7118d67 Mon Sep 17 00:00:00 2001 From: John Gee Date: Sat, 26 Sep 2020 15:25:55 +1200 Subject: [PATCH] Use revised terminology --- Readme.md | 40 ++++++++++--------- ...r-value.js => options-boolean-or-value.js} | 0 2 files changed, 22 insertions(+), 18 deletions(-) rename examples/{options-flag-or-value.js => options-boolean-or-value.js} (100%) diff --git a/Readme.md b/Readme.md index 3f9f73d75..6f72e081a 100644 --- a/Readme.md +++ b/Readme.md @@ -15,7 +15,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md) - [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 flag|value](#other-option-types-negatable-boolean-and-flagvalue) + - [Other option types, negatable boolean and boolean|value](#other-option-types-negatable-boolean-and-booleanvalue) - [Custom option processing](#custom-option-processing) - [Required option](#required-option) - [Variadic option](#variadic-option) @@ -82,14 +82,13 @@ Multiple short flags may optionally be combined in a single argument following t For example `-a -b -p 80` may be written as `-ab -p80` or even `-abp80`. You can use `--` to indicate the end of the options, and any remaining arguments will be used without being interpreted. -This is particularly useful for passing options through to another -command, like: `do -- git --version`. -Options on the command line are not positional, and can be specified before or after other command arguments. +Options on the command line are not positional, and can be specified before or after other arguments. ### Common option types, boolean and value -The two most used option types are a boolean flag, and an option which takes a value (declared using angle brackets). Both are `undefined` unless specified on command line. +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) @@ -147,13 +146,13 @@ $ pizza-options --cheese stilton cheese: stilton ``` -### Other option types, negatable boolean and flag|value +### Other option types, negatable boolean and boolean|value -You can specify a boolean option long name with a leading `no-` to set the option value to false when used. +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. You can specify a default boolean value for a boolean flag and it can be overridden on command line. +otherwise be. You can specify a default boolean value for a boolean option and it can be overridden on command line. Example file: [options-negatable.js](./examples/options-negatable.js) @@ -180,9 +179,10 @@ $ pizza-options --no-sauce --no-cheese You ordered a pizza with no sauce and no cheese ``` -You can specify an option which functions as a flag but may also take a value (declared using square brackets). +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]`). -Example file: [options-flag-or-value.js](./examples/options-flag-or-value.js) +Example file: [options-boolean-or-value.js](./examples/options-boolean-or-value.js) ```js program @@ -208,12 +208,12 @@ For information about possible ambiguous cases, see [options taking varying argu ### Custom option processing -You may specify a function to do custom processing of option values. The callback function receives two parameters, the user specified value and the -previous value for the option. It returns the new value for the option. +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 value to the desired type, or accumulate values, or do entirely custom processing. +This allows you to coerce the option-argument to the desired type, or accumulate values, or do entirely custom processing. -You can optionally specify the default/starting value for the option after the function. +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) @@ -286,7 +286,7 @@ error: required option '-c, --cheese ' not specified ### Variadic option 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 +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. @@ -341,7 +341,7 @@ program.version('0.0.1', '-v, --vers', 'output the current version'); 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 and any command arguments. The arguments may be `` or `[optional]`, and the last argument may also be `variadic...`. +In the first parameter to `.command()` you specify the command name and any command-arguments. 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. @@ -369,11 +369,15 @@ program .addCommand(build.makeBuildCommand()); ``` -Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `true` for `opts.hidden` will remove the command from the generated help output. Specifying `true` for `opts.isDefault` will run the subcommand if no other subcommand is specified ([example](./examples/defaultCommand.js)). +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)). ### Specify the argument syntax -You use `.arguments` to specify the arguments for the top-level command, and for subcommands they are usually included in the `.command` call. Angled brackets (e.g. ``) indicate required input. Square brackets (e.g. `[optional]`) indicate optional input. +You use `.arguments` to specify the expected command-arguments for the top-level command, and for subcommands they are usually +included in the `.command` call. Angled brackets (e.g. ``) indicate required command-arguments. +Square brackets (e.g. `[optional]`) indicate optional command-arguments. You can optionally describe the arguments in the help by supplying a hash as second parameter to `.description()`. Example file: [env](./examples/env) diff --git a/examples/options-flag-or-value.js b/examples/options-boolean-or-value.js similarity index 100% rename from examples/options-flag-or-value.js rename to examples/options-boolean-or-value.js