| Type Function |
Description |
array(types)(key, args, fields)
arrayPos(types)(key, fields)
|
array generates an array option,
while arrayPos generates an array positional argument,
representing arrays whose length is known in advance.
The closely related variadic
and variadicPos represent arrays with unknown lengths.
`array` returns the following object:
```js
const array = types => (key, args, fields) => ({
key, args, types, ...fields
})
```
`arrayPos` returns the following object:
```js
const arrayPos = types => (key, fields) => ({
key, types, ...fields
})
```
|
bool(key, args, fields)
boolPos(key, fields)
|
bool generates a primitive option,
while boolPos generates a primitive positional argument,
representing the boolean values 'true' and 'false'.
Note that the values are represented as strings and you may want to cast them.
If you need more values representing 'true' (e.g. 't', 'yes')
or 'false' (e.g. 'F', 'no'),
have a look at broadenBools.
If you want to treat a value as its reverse,
see reverseBools.
If you need flags instead of bools, have a look at the
boolAsFlag and boolsAsFlags
parser stages.
`bool` returns the following object:
```js
const bool = (key, args, fields) => ({
key, args, types: ['bool'], ...fields
})
```
`boolPos` returns the following object:
```js
const boolPos = (key, fields) => ({
key, types: ['bool'], ...fields
})
```
|
subcommand(opts)(key, args, fields)
command(key, opts, fields)
|
subcommand generates a subcommand option,
while command generates a command positional argument.
Combined, they enable commands to do multiple things like git init, git commit, and git push.
subcommand's and command's opts fields
are arrays of command-line options used to parse their values.
Subcommands may have their own command-specific parsers
or are parsed by command's parser.
command or subcommand values are either terminated by the end of the input
or by --.
`subcommand` returns the following object:
```js
const subcommand = opts => (key, args, fields) => ({
key, args, opts, ...fields
})
```
`command` returns the following object:
```js
const command = (key, opts, fields) => ({
key, opts, ...fields
})
```
|
flag(key, args, fields) |
flag generates a flag option,
representing command-line options that take no value.
Shargs counts the number of times a flag occurs, so a flag may be amplified by repeating it.
If you don't need counts and prefer numbers or boolean values, have a look at the
flagAsBool, flagAsNumber,
flagsAsBools and flagsAsNumbers
parser stages.
If you need the presence of a flag to imply negativity (e.g. --no-fun),
see complement,
reverse and reverseFlags.
`flag` returns the following object:
```js
const flag = (key, args, fields) => ({
key, args, types: [], ...fields
})
```
|
number(key, args, fields)
numberPos(key, fields)
|
number generates a primitive option,
while numberPos generates a primitive positional argument,
representing JavaScript numbers.
Numbers are represented as strings and you may want to cast them.
If you need flags instead of numbers, have a look at the
numberAsFlag and numbersAsFlags
parser stages.
`number` returns the following object:
```js
const number = (key, args, fields) => ({
key, args, types: ['number'], ...fields
})
```
`numberPos` returns the following object:
```js
const numberPos = (key, fields) => ({
key, types: ['number'], ...fields
})
```
|
string(key, args, fields)
stringPos(key, fields)
|
string generates a primitive option,
while stringPos generates a primitive positional argument,
representing strings.
`string` returns the following object:
```js
const string = (key, args, fields) => ({
key, args, types: ['string'], ...fields
})
```
`stringPos` returns the following object:
```js
const stringPos = (key, fields) => ({
key, types: ['string'], ...fields
})
```
|
variadic(key, args, fields)
variadicPos(key, fields)
|
variadic generates a variadic option,
while variadicPos generates a variadic positional argument.
These types represent arrays whose length is not known in advance.
An opts array can have at most one variadic positional argument
and no other positional arguments (*Pos) may be defined after it.
The closely related array
and arrayPos represent arrays with known lengths, while
command and subcommand are
variadicPos and variadic with opts fields.
A variadic's or variadicPos' values are either terminated by the end of the input
or by --.
`variadic` returns the following object:
```js
const variadic = (key, args, fields) => ({
key, args, ...fields
})
```
`variadicPos` returns the following object:
```js
const variadicPos = (key, fields) => ({
key, ...fields
})
```
|
You may write out command-line options by hand, or write your own DSLs for creating them, they are just JavaScript objects:
```js
const askOpts = [
{key: 'format', args: ['--format'], types: ['string'], only: ['json', 'xml'], defaultValues: ['json'],
desc: 'Respond either with json or xml.'},
{key: 'html', args: ['--no-html'], types: [], reverse: true, desc: 'Remove HTML tags.'},
{key: 'help', args: ['-h', '--help'], types: [], desc: 'Print this help message and exit.'},
{key: 'question', types: ['string'], required: true, desc: 'State your question.'}
]
```
Apart from [`key`](#key), [`args`](#args), [`types`](#types), [`opts`](#opts), and [`values`](#values)
that we have already seen and that determine an option's type,
command-line option objects may be given any other
| Field |
Type |
Description |
args |
string[] |
args defines argument names for command-line options (e.g. ['-h', '--help']).
Argument names have no restrictions and can be any string.
E.g. ['-h', '--help'] could be used for a help flag
or ['ask'] could be used for a command.
Positional arguments must not have an args field,
as they are not given by argument, but by their position.
|
contradicts |
key[] |
contradicts defines what keys an option is incompatible with.
This information is used by the contradictOpts parser stage
to report errors if incompatible options are used together.
Note that contradicts is unidirectional and not transitive
(e.g. if a contradicts b and b contradicts c,
a does not contradict c, and thus a and c are compatible).
Only two keys that each contradict the other key
are mutually exclusive.
|
defaultValues |
* |
defaultValues defines default values for command-line options.
They are used by the setDefaultValues parser stage
that sets the values field if no values are supplied.
The defaultValues' type depends on the command-line option type:
Subcommands takes the same array of options as opts.
Flag options' values have to be a number.
All other options take an array of values,
that must have the same length as their types field.
|
desc |
string |
desc defines an option description used by various usage functions.
More specifically, desc is used by
desc, optsList,
optsLists, optsDef,
and optsDefs and their *With versions.
|
descArg |
string |
descArg defines a description for an argument value
(e.g. {descArg: 'format'} would print --format=<format>
instead of --format=<string>).
It is used by the optsList, optsLists,
optsDef, and optsDefs usage functions
and their *With versions.
only, types, and key
are other fields that change the argument value description.
These fields are applied in the following order (highest priority first):
descArg, only, types,
and key.
If descArg is an empty string, no argument value description is displayed.
|
descDefault |
string |
descDefault overrides the default shield (e.g. [default: 42]) displayed in several usage commands.
It is used by the optsList, optsLists,
optsDef, and optsDefs usage functions
and their *With versions.
If descDefault is an empty string, the default shield is hidden.
|
implies |
key[] |
implies defines what keys an option must be defined with.
This information is used by the implyOpts parser stage
to report errors if mandatory options are missing.
Note that implies is unidirectional
(e.g. if a implies b and a is present, b must be present as well,
but if b is present, a does not have to be present)
and transitive
(e.g. if a implies b and b implies c,
a also implies c,
and thus if a is present, c must also be present).
Only two keys that each imply the other key
are mutually inclusive.
|
key |
string |
key defines the name of a command-line option.
It is used by the parser function
as a field name for the parsed values in the resulting args object.
Most command-line options should have a unique key to avoid collisions with other options.
However, if two different options describe the same result field, it may make sense to give them a shared key.
See complement for an example.
A key must not be named _.
It is also used by the
optsList, optsLists,
optsDef, optsDefs,
synopses, and synopsis usage functions
and their *With versions to describe argument values (e.g. --format=<format>).
descArg, only,
and types are other fields that change the argument value description.
These fields are applied in the following order (highest priority first):
descArg, only,
types, and key.
|
only |
any[] |
only defines valid values of an option.
It is used by the restrictToOnly parser stage to validate user input.
only may be used to implement enumerations.
It is also used by the optsList, optsLists,
optsDef, and optsDefs usage functions
and their *With versions to describe argument values (e.g. --format=<json|xml>).
descArg, types,
and key are other fields that change the argument value description.
These fields are applied in the following order (highest priority first):
descArg, only, types,
and key.
|
opts |
option[] |
opts defines the command-line options of commands
and subcommands.
|
required |
boolean |
required defines whether a command-line option has to be present or not.
It is used by the requireOpts stage that reports an error
if a required option does not have values.
A positional argument (*Pos) can only be required,
if all previously defined positional arguments are required as well.
The synopsis, synopses,
optsList, optsLists,
optsDef, and optsDefs usage functions
and their *With versions mark required options.
|
reverse |
boolean |
reverse defines whether the values of a given option should be reversed by
the reverseBools or reverseFlags
parser stages.
|
types |
string[] |
types defines what user input a command-line option takes.
Flag options' types must be [].
Primitive options' and primitive positional arguments'
types must be [\_],
and array options' and array positional arguments'
types must be [\_, \_, ...],
where _ is the name of a type given as a string.
Variadic options, variadic positional arguments,
subcommand options, and command positional arguments
must not have a types field.
types is also used by the
optsList, optsLists,
optsDef, and optsDefs usage functions
and their *With versions to describe argument values
(e.g. --format=<bool> for a bool option).
descArg, only,
and key are other fields that change the argument value description.
These fields are applied in the following order (highest priority first):
descArg, only, types,
and key.
|
values |
any[] |
This field should only be set by parser stages and never manually.
values are assigned by the parser.
You may want to use defaultValues.
The length of a values' array depends on the command-line option type:
Flag options, primitive options,
primitive positional arguments, and rest
must each have values of length 1.
Array options' and array positional arguments'
values field must match their types in length.
subcommand option's, command positional argument's,
variadic option's, and variadic positional argument's
values may have any number of entries.
|
#### Option Decorators
Certain changes to options are so frequent, that [`shargs-opts`][shargs-opts] provides decorators for them.
You may think of decorators as recurring patterns that are provided as functions.
[`shargs-opts`][shargs-opts] provides the following decorators:
| Stage |
Field |
Type |
| 1 |
toArgv |
any => {errs, argv}
Transforms a value into command-line argument values syntax, e.g.
```js
"-p commit -am 'First commit'"
```
could be transformed to
```js
['-p', 'commit', '-am', 'First commit']
```
|
| 2 |
argv |
Array<{errs, argv} => {errs, argv}>
Several stages that modify command-line argument values, e.g.
```js
['-p', 'commit', '-am', 'First commit']
```
could be transformed to
```js
['-p', 'commit', '-a', '-m', 'First commit']
```
|
| 3 |
toOpts |
command => {errs, argv} => {errs, opts}
Transforms argument values into command-line options, e.g.
```js
['-p', 'commit', '-a', '-m', 'First commit']
```
could be transformed to
```js
[
{key: 'paginate', args: ['-p'], types: [], values: [1]},
{key: 'commit', args: ['commit'], opts: [...], values: [
{key: 'all', args: ['-a'], types: [], values: [1]},
{key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},
...
]},
...
]
```
|
| 4 |
opts |
Array<{errs, opts} => {errs, opts}>
Several stages that modify command-line options, e.g.
```js
[
{key: 'paginate', args: ['-p'], types: [], values: [1]},
{key: 'commit', args: ['commit'], opts: [...], values: [
{key: 'all', args: ['-a'], types: [], values: [1]},
{key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},
...
]},
...
]
```
could be transformed to
```js
[
{key: 'paginate', args: ['-p'], types: [], values: [1]},
{key: 'commit', args: ['commit'], opts: [...], values: [
{key: 'all', args: ['-a'], types: ['bool'], values: ['true']},
{key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},
...
]},
...
]
```
|
| 5 |
toArgs |
{errs, opts} => {errs, args}
Transforms command-line options into arguments object arrays, e.g.
```js
[
{key: 'paginate', args: ['-p'], types: [], values: [1]},
{key: 'commit', args: ['commit'], opts: [...], values: [
{key: 'all', args: ['-a'], types: ['bool'], values: ['true']},
{key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},
...
]},
...
]
```
could be transformed to
```js
[
{_: [], paginate: {type: 'flag', count: 1}},
{commit: [
{_: [], all: 'true', message: 'First commit'}
]}
]
```
|
| 6 |
args |
Array<{errs, args} => {errs, args}>
Several stages that modify arguments object arrays, e.g.
```js
[
{_: [], paginate: {type: 'flag', count: 1}},
{commit: [
{_: [], all: 'true', message: 'First commit'}
]}
]
```
could be transformed to
```js
[
{_: [], paginate: {type: 'flag', count: 1}},
{commit: {
{_: [], all: true, message: 'First commit'}
}}
]
```
|
| 7 |
fromArgs |
{errs, args} => any
Transforms argument object arrays into any result value:
```js
[
{_: [], paginate: {type: 'flag', count: 1}},
{commit: [
{_: [], all: true, message: 'First commit'}
]}
]
```
could be transformed to
```js
{
_: [],
paginate: {type: 'flag', count: 1},
commit: {
_: [],
all: true,
message: 'First commit'
}
}
```
|
The [`argv`](#argv-field), [`opts`](#opts-field), and [`args`](#args-field) stages
are the user-facing API to declare a parser's behavior.
The [`toOps`](#toOpts-field) and [`toArgs`](#toArgs-field) stages
define the core behavior of [`parserSync`](#the-parserSync-function) (and [`parser`](#async-parsers))
and shargs defines sensible defaults that should not have to be changed in most use cases.
However, if you do have a use case that needs adjustments to those stages, you may carefully swap them out.
If you read the types from top to bottom, you get a good impression of how `parserSync` works.
#### `substages`
`substages` define custom `opts` stages for subcommands.
That means, while most subcommands are parsed using the `opts` defined in `stages`,
those whose [`key`](#key) matches a key in the `substages` object are parsed using the `opts` defined under that key.
Keys may be deeply nested to account for [`subcommand`](#subcommand)s of [`subcommand`](#subcommand)s:
E.g. if `ask` had a subcommand with the `question` [`key`](#key), `{ask: {question: [...stages.opts, restrictToOnly]}}` would assign custom `opts` to `question`.
The `_` [`key`](#key) is special in `substages`:
It is a wildcard that is used by any [`subcommand`](#subcommand) that is not given explicitly by [`key`](#key).
E.g. `{ask: {_: [...stages.opts, restrictToOnly]}}` and `{_: {_: [...stages.opts, restrictToOnly]}}` both work for `question`.
#### Async Parsers
The [`parserSync`](#the-parsersync-function) function has an asynchronous alternative called `parser`.
It is used exactly like `parserSync`, but also works with stages returning
[JavaScript Promises](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)
and returns a Promise itself:
```js
// stages, substages, deepThought, argv are taken from the Getting Started section
const {parser} = require('shargs')
const asyncParser = parser(stages, substages)
const parse = asyncParser(deepThought)
const {errs, args} = await parse(argv)
```
In addition to `parserSync`'s parameters,
`parser`'s [`stages`](#stages) and [`substages`](#substages) parameters also take parser stages that return Promises:
| Stage |
Field |
Type |
| 1 |
toArgv |
any => {errs, argv}
any => Promise<{errs, argv}>
Transforms a value into command-line argument values syntax, e.g.
```js
"-p commit -am 'First commit'"
```
could be transformed to
```js
['-p', 'commit', '-am', 'First commit']
```
|
| 2 |
argv |
Array<{errs, argv} => {errs, argv}>
Array<{errs, argv} => Promise<{errs, argv}>>
Several stages that modify command-line argument values, e.g.
```js
['-p', 'commit', '-am', 'First commit']
```
could be transformed to
```js
['-p', 'commit', '-a', '-m', 'First commit']
```
|
| 3 |
toOpts |
command => {errs, argv} => {errs, opts}
command => {errs, argv} => Promise<{errs, opts}>
Transforms argument values into command-line options, e.g.
```js
['-p', 'commit', '-a', '-m', 'First commit']
```
could be transformed to
```js
[
{key: 'paginate', args: ['-p'], types: [], values: [1]},
{key: 'commit', args: ['commit'], opts: [...], values: [
{key: 'all', args: ['-a'], types: [], values: [1]},
{key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},
...
]},
...
]
```
|
| 4 |
opts |
Array<{errs, opts} => {errs, opts}>
Array<{errs, opts} => Promise<{errs, opts}>>
Several stages that modify command-line options, e.g.
```js
[
{key: 'paginate', args: ['-p'], types: [], values: [1]},
{key: 'commit', args: ['commit'], opts: [...], values: [
{key: 'all', args: ['-a'], types: [], values: [1]},
{key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},
...
]},
...
]
```
could be transformed to
```js
[
{key: 'paginate', args: ['-p'], types: [], values: [1]},
{key: 'commit', args: ['commit'], opts: [...], values: [
{key: 'all', args: ['-a'], types: ['bool'], values: ['true']},
{key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},
...
]},
...
]
```
|
| 5 |
toArgs |
{errs, opts} => {errs, args}
{errs, opts} => Promise<{errs, args}>
Transforms command-line options into arguments object arrays, e.g.
```js
[
{key: 'paginate', args: ['-p'], types: [], values: [1]},
{key: 'commit', args: ['commit'], opts: [...], values: [
{key: 'all', args: ['-a'], types: ['bool'], values: ['true']},
{key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},
...
]},
...
]
```
could be transformed to
```js
[
{_: [], paginate: {type: 'flag', count: 1}},
{commit: [
{_: [], all: 'true', message: 'First commit'}
]}
]
```
|
| 6 |
args |
Array<{errs, args} => {errs, args}>
Array<{errs, args} => Promise<{errs, args}>>
Several stages that modify arguments object arrays, e.g.
```js
[
{_: [], paginate: {type: 'flag', count: 1}},
{commit: [
{_: [], all: 'true', message: 'First commit'}
]}
]
```
could be transformed to
```js
[
{_: [], paginate: {type: 'flag', count: 1}},
{commit: {
{_: [], all: true, message: 'First commit'}
}}
]
```
|
| 7 |
fromArgs |
{errs, args} => any
{errs, args} => Promise<any>
Transforms argument object arrays into any result value:
```js
[
{_: [], paginate: {type: 'flag', count: 1}},
{commit: [
{_: [], all: true, message: 'First commit'}
]}
]
```
could be transformed to
```js
{
_: [],
paginate: {type: 'flag', count: 1},
commit: {
_: [],
all: true,
message: 'First commit'
}
}
```
|
If you read the stages' field types from top to bottom, you get a good impression of what an asynchronous parser does.
Internally, an asynchronous shargs parser really differs only in one major way from a synchronous parser:
Instead of using function composition, it uses [Promise.prototype.then][then] to chain parser stages.
#### Advanced Parsers
+ [Multiple subcommands](#multiple-subcommands)
### Command-line Parsers
You do not have to write all parser stages yourself.
The [`shargs-parser`][shargs-parser] library offers a large collection of common parser stages, you can use.
The parser stages presented here are split into *checks* and *stages*.
While *checks* only report errors, *stages* also transform their `argv`, `opts`, or `args`.
Usually, it makes sense to declare *checks* before *stages*.
#### `argv` Checks
| |
Description |
contradictOpts |
Reports a ContradictionDetected error if options with a contradicts list violate their constraints.
This is the case, if both, the option and an option from its [`contradicts`](#contradicts) list, have [`values`](#values).
If [`contradicts`](#contradicts) is not a list, it reports a [`WrongContradictsType`](#WrongContradictsType) error.
Example:
```js
const {contradictOpts} = require('shargs/parser')
const {number, string} = require('shargs/opts')
const opts = [
number('age', ['-a'], {
values: ['27']
}),
string('birthday', ['-b'], {
contradicts: ['age'],
values: ['27.7.1927']
})
]
contradictOpts({opts})
```
Result:
```js
{
errs: [
{
code: 'ContradictionDetected',
msg: 'Some given keys contradict each other.',
info: {...}
}
]
}
```
|
demandASubcommand |
Reports a SubcommandRequired
unless at least one subcommand has values.
Example:
```js
const {demandASubcommand} = require('shargs/parser')
const {flag, number, subcommand} = require('shargs/opts')
const opts = [
subcommand([])('ask', ['ask'], {desc: 'Ask a question.'}),
number('answer', ['-a', '--answer'], {
values: ['42'],
desc: 'The answer.'
}),
flag('help', ['-h', '--help'], {
desc: 'Print this help message and exit.'
})
]
demandASubcommand({opts})
```
Result:
```js
{
errs: [
{
code: 'SubcommandRequired',
msg: 'No subcommand found. Please use at least one subcommand!',
info: {...}
}
]
}
```
|
implyOpts |
Reports an ImplicationViolated error
if options with an implies list violate their constraints.
This is the case, if the option has [`values`](#values), but an option from its [`implies`](#implies) list has not.
If [`implies`](#implies) is not a list, it reports a [`WrongImpliesType`](#WrongImpliesType) error.
Example:
```js
const {implyOpts} = require('shargs/parser')
const {number, string} = require('shargs/opts')
const opts = [
number('answer', ['-a']),
string('question', ['-q'], {
implies: ['answer'],
values: ['How much is the fish?']
})
]
implyOpts({opts})
```
Result:
```js
{
errs: [
{
code: 'ImplicationViolated',
msg: 'Some given keys that imply...',
info: {...}
}
]
}
```
|
requireOpts |
Reports a RequiredOptionMissing error
if an option whose required field is true is missing.
If [`values`](#values) is not an array,
it reports a [`WrongFormatForRequiredOption`](#WrongFormatForRequiredOption) error.
Example:
```js
const {requireOpts} = require('shargs/parser')
const {string} = require('shargs/opts')
const opts = [
string('question', ['--question'], {required: true})
]
requireOpts({opts})
```
Result:
```js
{
errs: [
{
code: 'RequiredOptionIsMissing',
msg: 'A required option has not been provided.',
info: {...}
}
]
}
```
|
suggestOpts |
Corrects spelling mistakes by suggesting existing command-line arguments for all unknown provided arguments.
E.g. if --asnwer was provided, the --answer argument would be suggested.
It checks all [rest](#rest) [`values`](#values),
assuming they are in the [rest](#rest) category because of spelling mistakes.
It collects all command-line options' [`args`](#args)
and computes a distance metric (currently Levenshtein distance) between each arg and each [`rest`](#rest).
It reports the results in a [`DidYouMean`](#DidYouMean) error,
suggesting probable [`args`](#args) replacements for spelling mistakes.
Example:
```js
const {suggestOpts} = require('shargs/parser')
const {number} = require('shargs/opts')
const opts = [
number('answer', ['-a', '--ans']),
{values: ['--asn']}
]
suggestOpts({opts})
```
Result:
```js
{
errs: [
{
code: 'DidYouMean',
msg: 'An unknown command-line argument...',
info: {
argv: '--asn',
options: [
[],
[],
[{'--ans': number('answer', ['-a', '--ans'])}],
[{'-a': number('answer', ['-a', '--ans'])}]
]
}
}
]
}
```
The `options` array looks a little bit strange, so an explanation is in order.
The array's index is the cost necessary to transform the unknown option in the arguments, represented as keys.
Because of this, you can conveniently work with the results, e.g. by only using the most probable ones:
```js
'Did you mean: ' + (
options
.slice(0, 3)
.reduce((a, b) => a.concat(b))
.flatMap(Object.keys)
.join(', ')
)
```
Results in:
```bash
Did you mean: --age
```
|
validatePosArgs |
Reports an InvalidRequiredPositionalArgument error
if defined positional arguments (*Pos) violate their rules for the
required field
or the position of variadicPos.
If a positional argument is [`required`](#required),
all previously defined positional arguments must be [`required`](#required), as well,
and no other positional arguments can be defined after a [`variadicPos`](#variadicPos).
In case of a violation of the second rule, `validatePosArgs` reports an
[`InvalidVariadicPositionalArgument`](#InvalidVariadicPositionalArgument) error.
Example:
```js
const {validatePosArgs} = require('shargs/parser')
const {stringPos, variadicPos} = require('shargs/opts')
const opts = [
stringPos('name1', {required: true, values: ['Arthur']}),
stringPos('name2', {required: false, values: ['Ford']}),
stringPos('name3', {required: true, values: ['Trillian']}),
variadicPos('names', {values: ['Zaphod', 'Marvin']}),
stringPos('name4', {values: ['Douglas']})
]
validatePosArgs({opts})
```
Result:
```js
{
errs: [
{
code: 'InvalidRequiredPositionalArgument',
msg: 'If a positional argument is required, all prev...',
info: {...}
},
{
code: 'InvalidVariadicPositionalArgument',
msg: 'Only the last positional argument may be variadic.',
info: {...}
}
]
}
```
|
verifyOpts(rules) |
Reports a FalseOptsRules error
if the opts array does not adhere to the rules predicate.
rules must have the following function signature: opt => true|false.
If `rules` is not a function, `verifyOpts` reports a [`WrongOptsRulesType`](#WrongOptsRulesType) error.
Example:
```js
const {verifyOpts} = require('shargs/parser')
const {string} = require('shargs/opts')
const implies = (p, q) => !p || q
const rules = opts => implies(
opts.some(_ => _.key === 'question' && _.values),
opts.some(_ => _.key === 'answer' && _.values)
)
const opts = [
string('question', ['--question'], {
values: ['How much is the fish?']
}),
number('answer', ['-a'])
]
verifyOpts(rules)({opts})
```
Result:
```js
{
errs: [
{
code: 'FalseOptsRules',
msg: 'Your opts rules returned false...',
info: {...}
}
]
}
```
|
verifyValuesArity |
Reports an error if an option's
values do not fit its types.
See the [`values`](#values) documentations for the exact rules.
If the lengths of [`values`](#values) and [`types`](#types) do not match,
an [`InvalidArity`](#InvalidArity) error is reported.
If the [`types`](#types) field has an invalid value, an [`InvalidTypes`](#InvalidTypes) error is reported
and `verifyValuesArity` reports an [`InvalidValues`](#InvalidValues) error in case of invalid [`values`](#values).
Example:
```js
const {verifyValuesArity} = require('shargs/parser')
const {number} = require('shargs/opts')
const opts = [
number('answer', ['--answer'], {values: ['42', '23']})
]
verifyValuesArity({opts})
```
Result:
```js
{
errs: [
{
code: 'InvalidArity',
msg: "An option's types arity does not match...",
info: {...}
}
]
}
```
|
#### `opts` Stages
| |
Description |
arrayOnRepeat |
Collects all repeated keys in an array,
instead of keeping only the first mention of a key.
Example:
```js
const {arrayOnRepeat} = require('shargs/parser')
const {number, string} = require('shargs/opts')
const opts = [
string('answer', ['-a'], {values: ['42']}),
number('answer', ['-a'], {values: [42]})
]
arrayOnRepeat({opts})
```
Result:
```js
{
opts: [
array(['string', 'number'])('answer', ['-a'], {
values: ['42', 42]
})
]
}
```
|
bestGuessOpts |
Takes a best guess approach to transform rest values that did not match a command-line option
into new command-line options.
E.g. {values: ['--version']} becomes {key: 'version', types: [], values: [1]} and
[{values: ['--not']}, {values: ['panic']}]
becomes {key: 'not', types: ['string'], args: ['--not'], values: ['panic']}.
Single [`rest`](#rest) options are interpreted as [`flag`](#flag)s
while two consecutive [`rest`](#rest) options are interpreted as [`string`](#string)s
if the first [`rest`](#rest) is in short option format
(one minus with a single character, e.g. `-n`, `-a`)
or in long option format (two minuses with any more characters, e.g. `--name`, `--answer`).
[`bestGuessArgs`](#bestGuessArgs) is very similar to `bestGuessOpts`,
but also considers non-consecutive rest [`values`](#values).
Example:
```js
const {bestGuessOpts} = require('shargs/parser')
const {flag, string} = require('shargs/opts')
const opts = [
string('age', ['--age'], {values: ['unknown']}),
{values: ['--paranoid']},
{values: ['--name']},
{values: ['Marvin']},
{values: ['foo']}
]
bestGuessOpts({opts})
```
Result:
```js
{
opts: [
string('age', ['--age'], {values: ['unknown']}),
flag('paranoid', [], {values: [1]}),
string('name', [], {values: ['Marvin']}),
{values: ['foo']}
]
}
```
|
broadenBools(alt) |
Transforms bools with
values like 'yes' or 'no' into
bools with 'true' or 'false'
values based on an alt mapping
(e.g. {true: ['yes'], false: ['no']}).
Example:
```js
const {broadenBools} = require('shargs/parser')
const {bool, number} = require('shargs/opts')
const opts = [
number('answer', ['-a', '--answer'], {values: ['42']}),
bool('verbose', ['--verbose'], {values: ['no']})
]
const alt = {
true: ['yes'],
false: ['no', 'f']
}
broadenBools(alt)({opts})
```
Result:
```js
{
opts: [
number('answer', ['-a', '--answer'], {values: ['42']}),
bool('verbose', ['--verbose'], {values: ['false']})
]
}
```
|
cast |
Casts string values
into other JavaScript types (e.g. numbers, booleans)
according to the command-line options' types
(e.g. {key: 'answer', types: ['number'], values: ['42']} is transformed to
{key: 'answer', types: ['number'], values: [42]}).
If [`types`](#types) contains `'number'`, but [`values`](#values)
cannot be cast into a number, an [`ArgumentIsNotANumber`](#ArgumentIsNotANumber) error is reported.
If [`types`](#types) contains `'bool'`, but [`values`](#values)
is not `['true']` or `['false']`, an [`ArgumentIsNotABool`](#ArgumentIsNotABool) error is reported.
Example:
```js
const {cast} = require('shargs/parser')
const {bool, number} = require('shargs/opts')
const opts = [
number('answer', ['-a', '--answer'], {values: ['42']}),
bool('verbose', ['--verbose'], {defaultValues: ['false']})
]
cast({opts})
```
Result:
```js
{
opts: [
number('answer', ['-a', '--answer'], {values: [42]}),
bool('verbose', ['--verbose'], {defaultValues: [false]})
]
}
```
|
restrictToOnly |
Validates all command-line options with both, only
and values fields,
by making sure that all values in values
are also contained in only.
If values are not found in [`only`](#only),
a [`ValueRestrictionsViolated`](#ValueRestrictionsViolated) error is reported for each value.
Example:
```js
const {restrictToOnly} = require('shargs/parser')
const {number} = require('shargs/opts')
const opts = [
number('answer', ['--answer'], {only: ['42'], values: ['23']})
]
restrictToOnly({opts})
```
Result:
```js
{
errs: [
{
code: 'ValueRestrictionViolated',
msg: 'A value lies outside the allowed values...',
info: {...}
}
],
opts
}
```
|
reverseBools |
Transforms
values of
primitive options and
array options
whose types contain 'bool' and whose
reverse field is true
by replacing 'true'/true with 'false'/false and vice versa.
Example:
```js
const {reverseBools} = require('shargs/parser')
const {bool} = require('shargs/opts')
const opts = [
bool('verbose', ['-v'], {reverse: true, values: [true]}),
bool('verbose', ['-v'], {reverse: true, values: ['true']})
]
reverseBools({opts})
```
Result:
```js
{
opts: [
bool('verbose', ['-v'], {reverse: true, values: [false]}),
bool('verbose', ['-v'], {reverse: true, values: ['false']})
]
}
```
|
reverseFlags |
Transforms
values of
flag options whose reverse field is true
by inverting the flag's value (e.g. 1 becomes -1).
Example:
```js
const {reverseFlags} = require('shargs/parser')
const {flag} = require('shargs/opts')
const opts = [
flag('help', ['-h'], {reverse: true, values: [1]})
]
reverseFlags({opts})
```
Result:
```js
{
opts: [
flag('help', ['-h'], {reverse: true, values: [-1]})
]
}
```
|
setDefaultValues |
Transforms all options that have no
values, but defaultValues,
by setting the values field
to the defaultValues' value.
Example:
```js
const opts = [
flag(['-f'], {defaultValues: [1]}),
bool(['-b'], {defaultValues: ['true']})
]
setDefaultValues({opts})
```
Result:
```js
{
opts: [
flag(['-f'], {values: [1]}),
bool(['-b'], {values: ['true']})
]
}
```
|
traverseOpts(p)(f) |
Transforms opts by applying a function f
to each option satisfying a predicate p.
While `p`'s signature is `opt => true|false`,
`f`'s signature must be `(opt, index, opts) => ({errs = [], opts = []})`.
Many other `opts` checks and stages are defined in terms of `traverseOpts`
and it is of great help for writing custom `opts` stages.
Example:
```js
const {traverseOpts} = require('shargs/parser')
const {flag, number} = require('shargs/opts')
const opts = [
number('answer', ['-a'], {values: ['42']}),
flag('verbose', ['-v'], {values: [1]}),
flag('help', ['-h'], {values: [1]})
]
const isFlag = _ => Array.isArray(_.types) && _.types.length === 0
const reverseFlags = opt => ({
opts: [
{...opt, values: [-opt.values[0]]}
]
})
traverseOpts(isFlag)(reverseFlags)({opts})
```
Result:
```js
{
opts: [
number('answer', ['-a'], {values: ['42']}),
flag('verbose', ['-v'], {values: [-1]}),
flag('help', ['-h'], {values: [-1]})
]
}
```
|
#### `args` Checks
| |
Description |
bestGuessArgs |
Introduces new arguments by best guess based on rest field values
(e.g. {_: ['--version']} becomes {version: {type: 'flag', count: 1}}
and {_: ['--not', 'panic']} becomes {not: 'panic'}).
Transforms single rest field values into a flag and two consecutive rest options into a string.
It only assumes rest field values to be strings if the first rest is in short option format
(one minus with a single character, e.g. `-h`, `-v`)
or in long option format (two minuses with any more characters, e.g. `--help`, `--verbose`).
`bestGuessArgs` is very similar to [`bestGuessOpts`](#bestGuessOpts),
but also considers rest fields that originally did not directly follow each other.
E.g. assuming `--help` to be a known argument, `--not --help panic` would produce `{not: 'panic'}`,
although its components were not in tandem.
Example:
```js
const {bestGuessArgs} = require('shargs/parser')
const obj = {
args: {
_: ['--answer', '42', 'foo', '-h'],
command: {
_: ['bar', '-v', '--question', 'What is answer?', '-v']
}
}
}
bestGuessArgs(obj)
```
Result:
```js
{
args: {
_: ['foo'],
answer: '42',
h: {type: 'flag', count: 1},
command: {
_: ['bar'],
v: {type: 'flag', count: 2},
question: 'What is answer?'
}
}
}
```
|
bestGuessCast |
Casts string args into other JavaScript types
using a best guess approach based on their values (e.g. {answer: '42'} becomes {answer: 42}
and {all: 'true'} becomes {all: true}).
It supports numbers and booleans (e.g. `{help: 'true'}` becomes `{help: true}`).
Example:
```js
const {bestGuessCast} = require('shargs/parser')
const args = {
_: ['--name', 'Marvin'],
str1: 'yay',
num1: '42.3',
num2: '123e-1',
num3: '0x11',
num4: '0b11',
bool1: 'true',
arr1: ['-42', 'true', 'yay'],
obj: {
num5: '0o11',
num6: '-Infinity',
num7: '',
num8: null,
bool2: 'false',
bool3: undefined
}
}
bestGuessCast({args})
```
Result:
```js
{
args: {
_: ['--name', 'Marvin'],
str1: 'yay',
num1: 42.3,
num2: 12.3,
num3: 17,
num4: 3,
bool1: true,
arr1: [-42, true, 'yay'],
obj: {
num5: 9,
num6: -Infinity,
num7: '',
num8: null,
bool2: false,
bool3: undefined
}
}
}
```
|
boolAsFlag(key) |
Transforms bool arguments with key in args to a flag object.
E.g., assuming the all key,
{all: true} is transformed to {all: {type: 'flag', count: 1}} and
{all: false} to {all: {type: 'flag', count: -1}}.
Example:
```js
const args = {
_: [],
version: true
}
boolAsFlag('version')({args})
```
Result:
```js
{
_: [],
version: {type: 'flag', count: 1}
}
```
|
boolsAsFlags |
Transforms all bool arguments in args to flag objects
using boolAsFlag.
Example:
```js
const args = {
_: [],
html: false,
version: true
}
boolsAsFlags({args})
```
Result:
```js
{
_: [],
html: {type: 'flag', count: -1},
version: {type: 'flag', count: 1}
}
```
|
clearRest |
Sets rest values to an empty array (i.e. {_: []}).
Example:
```js
const {clearRest} = require('shargs/parser')
const args = {_: ['--verbose']}
clearRest({args})
```
Result:
```js
{
args: {_: []}
}
```
|
flagAsBool(key) |
Transforms flags with key in args to a bool value.
E.g., assuming the all key,
{all: {type: 'flag', count: 1}} is transformed to {all: true} and
{all: {type: 'flag', count: -1}} to {all: false}.
If its `count` is greater than `0` it is considered `true`, otherwise it is considered `false`.
Example:
```js
const {flagAsBool} = require('shargs/parser')
const args = {
verbose: {type: 'flag', count: 1}
}
flagAsBool('verbose')({args})
```
Result:
```js
{
args: {
verbose: true
}
}
```
|
flagAsNumber(key) |
Transforms flags with key in args to a number using its count.
E.g., assuming the verbose key,
{verbose: {type: 'flag', count: 3}} becomes {verbose: 3}.
Example:
```js
const {flagAsNumber} = require('shargs/parser')
const args = {
verbose: {type: 'flag', count: 2}
}
flagAsNumber('version')({args})
```
Result:
```js
{
args: {
verbose: 2
}
}
```
|
flagsAsBools |
Transforms all flag arguments in args to bool values
using flagAsBool.
Example:
```js
const {flagsAsBools} = require('shargs/parser')
const args = {
verbose: {type: 'flag', count: 1}
}
flagsAsBools({args})
```
Result:
```js
{
args: {
verbose: true
}
}
```
|
flagsAsNumbers |
Transforms all flag arguments in args to numbers using their count
like flagAsNumber.
Example:
```js
const {flagsAsNumbers} = require('shargs/parser')
const args = {
verbose: {type: 'flag', count: 2}
}
flagsAsNumbers({args})
```
Result:
```js
{
args: {
verbose: 2
}
}
```
|
mergeArgs(merge) |
Transforms args by flattening them
by recursively merging nested objects into their parent object
(e.g. {ask: {question: '42?'}, answer: 42} becomes {question: '42?', answer: 42}).
A custom `merge` function may be passed with the following function signature:
`(obj1 = {}, obj2 = {}) => {}`.
The default `merge` function (if `merge` is `undefined`)
prefers keys from the parent object over keys from nested objects,
but concatenates rest values (`_`) from both objects
(e.g. `{_: ['foo'], answer: 42, ask: {_: ['bar'], answer: 23}}` becomes
`{_: ['foo', 'bar'], answer: 42}`).
Example:
```js
const {mergeArgs} = require('shargs/parser')
const args = {
_: ['--help'],
version: {type: 'flag', count: 2},
name: 'Arthur',
command: {
_: ['-v'],
version: {type: 'flag', count: 1},
name: 'Trillian',
help: true
},
verbose: true
}
const mergeLeft = (outer, inner) => ({
...inner,
...outer,
_: [
...(outer._ || []),
...(inner._ || [])
]
})
mergeArgs(mergeLeft)({args})
```
Result:
```js
{
args: {
_: ['--help', '-v'],
version: {type: 'flag', count: 2},
name: 'Arthur',
help: true,
verbose: true
}
}
```
|
numberAsFlag(key) |
Transforms numbers with key in args to flag objects.
The number becomes the flag's count.
E.g. {answer: 42} becomes {answer: {type: 'flag', count: 42}}.
Example:
```js
const args = {
_: [],
answer: 42
}
numberAsFlag('answer')({args})
```
Result:
```js
{
_: [],
answer: {type: 'flag', count: 42}
}
```
|
numbersAsFlags |
Transforms all numbers in args to flag objects using numberAsFlag.
Example:
```js
const args = {
_: [],
answer: 42
}
numbersAsFlags({args})
```
Result:
```js
{
_: [],
answer: {type: 'flag', count: 42}
}
```
|
traverseArgs(fs) |
Transforms args by applying functions fs to each key/value pair based on the value's type.
`fs` supports the following types:
`array`, `boolean`, `flag`, `function`, `null`, `number`, `object`, `string`, `undefined`, and `otherwise`.
The default behavior for most types is to not change the value, with three notable exceptions:
`function`s and `otherwise`s key/value pairs are removed from args,
while `object`'s default function applies `fs` to nested objects.
`{flag: ({key, val, errs, args}) => ({errs, args})}`
is the signature for `fs` with fields for each type.
Many other `args` checks and stages are defined in terms of `traverseArgs`
and it is of great help for writing custom `args` stages.
Example:
```js
const {traverseArgs} = require('shargs/parser')
const args = {
verbose: {type: 'flag', count: 2},
answer: 23
}
const fs = {
flag: ({key, val, errs, args}) => ({
errs,
args: {...args, [key]: val.count}
}),
number: ({key, val, errs, args}) => ({
errs,
args: {...args, [key]: val + 19}
})
}
traverseArgs(fs)({args})
```
Result:
```js
{
args: {
verbose: 2,
answer: 42
}
}
```
Allowed fs fields:
```js
const fs = {
array: ({key, val, errs, args}) => ({errs, args}),
boolean: ({key, val, errs, args}) => ({errs, args}),
flag: ({key, val, errs, args}) => ({errs, args}),
function: ({key, val, errs, args}) => ({errs, args}),
null: ({key, val, errs, args}) => ({errs, args}),
number: ({key, val, errs, args}) => ({errs, args}),
otherwise: ({key, val, errs, args}) => ({errs, args}),
object: ({key, val, errs, args}) => ({errs, args}),
string: ({key, val, errs, args}) => ({errs, args}),
undefined: ({key, val, errs, args}) => ({errs, args})
}
```
|
#### Advanced Parser Stages
+ [Custom checks and stages](#custom-checks-and-stages)
### Automatic Usage Documentation Generation
Shargs strictly separates the concerns of parsing command-line arguments and generating usage documentation.
The [`shargs-usage`][shargs-usage] module specializes on
generating terminal-based usage documentation for `--help` flags
from [command-line options](#command-line-options):
```js
const {desc, optsLists, space, synopses, usage} = require('shargs/usage')
const docs = usage([
synopses,
space,
optsLists,
space,
desc
])
```
[`shargs-usage`][shargs-usage] lets you define how your usage documentation should look like in a declarative way.
In the example, we tell our `docs` to start with [`synopses`](#synopses), have [`optsLists`](#optsLists) in the body,
and close with a [`desc`](#usage-desc)ription.
We separate these three parts with [`space`](#space)s and enclose everything in a [`usage`](#usage) function.
Note that we did not mention any command-line options, yet:
```js
const {command, flag, number, stringPos} = require('shargs/opts')
const opts = [
stringPos('question', {desc: 'Ask a question.', required: true}),
number('answer', ['-a', '--answer'], {desc: 'The answer.', defaultValues: [42]}),
flag('help', ['-h', '--help'], {desc: 'Print this help message and exit.'})
]
const deepThought = command('deepThought', opts, {
desc: 'Deep Thought was created to come up with the Answer to ' +
'The Ultimate Question of Life, the Universe, and Everything.'
})
const optsDocs = docs(deepThought)
```
`optsDocs` now knows what to layout (`deepThought`), and how to layout it (`docs`).
Finally, we `style` the different parts (lines and columns) of the documentation:
```js
const style = {
line: [{width: 60}],
cols: [{width: 25}, {width: 35}]
}
const text = optsDocs(style)
```
Now, if we `console.log(text)`, the following `text` is printed to the console:
```bash
deepThought (