shargs

shargs copied to clipboard

The closely related variadic and variadicPos represent arrays with unknown lengths.

array returns the following object:

const array = types => (key, args, fields) => ({
  key, args, types, ...fields
})

arrayPos returns the following object:

const arrayPos = types => (key, fields) => ({
  key, types, ...fields
})

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:

const bool = (key, args, fields) => ({
  key, args, types: ['bool'], ...fields
})

boolPos returns the following object:

const boolPos = (key, fields) => ({
  key, types: ['bool'], ...fields
})

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:

const subcommand = opts => (key, args, fields) => ({
  key, args, opts, ...fields
})

command returns the following object:

const command = (key, opts, fields) => ({
  key, opts, ...fields
})

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:

const flag = (key, args, fields) => ({
  key, args, types: [], ...fields
})

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:

const number = (key, args, fields) => ({
  key, args, types: ['number'], ...fields
})

numberPos returns the following object:

const numberPos = (key, fields) => ({
  key, types: ['number'], ...fields
})

string returns the following object:

const string = (key, args, fields) => ({
  key, args, types: ['string'], ...fields
})

stringPos returns the following object:

const stringPos = (key, fields) => ({
  key, types: ['string'], ...fields
})

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:

const variadic = (key, args, fields) => ({
  key, args, ...fields
})

variadicPos returns the following object:

const variadicPos = (key, fields) => ({
  key, ...fields
})

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.

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.

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.

More specifically, desc is used by desc, optsList, optsLists, optsDef, and optsDefs and their *With versions.

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.

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.

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.

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.

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.

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.

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.

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.

The complementary option has the same key as the original option, but reverses its value. If complement is used, you most probably want to also use the reverseBools or reverseFlags parser stage.

Example:

const {flag, complement} = require('shargs/opts')

const no = complement('--no-')

const html = flag('html', ['-H', '--html'], {defaultValues: ['false']})
const noHtml = no(html)

Is the same as:

const {flag} = require('shargs/opts')

const html = flag('html', ['-H', '--html'], {defaultValues: ['false']})
const noHtml = flag('html', ['--no-H', '--no-html'], {reverse: true})

Note the differences in defaultValues and reverse.

Example:

const {command, stringPos} = require('shargs/opts')

const opts = [stringPos('question')]
const deepThought = command('deepThought', opts)

const args = ['deepThought', 'D']
posArgToOpt(args)(deepThought)

Is the same as:

const {subcommand} = require('shargs/opts')

subcommand(opts)('deepThought', args)

Transforms a value into command-line argument values syntax, e.g.

"-p commit -am 'First commit'"

could be transformed to

['-p', 'commit', '-am', 'First commit']

Several stages that modify command-line argument values, e.g.

['-p', 'commit', '-am', 'First commit']

could be transformed to

['-p', 'commit', '-a', '-m', 'First commit']

Transforms argument values into command-line options, e.g.

['-p', 'commit', '-a', '-m', 'First commit']

could be transformed to

[
  {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']},
    ...
  ]},
  ...
]

Several stages that modify command-line options, e.g.

[
  {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

[
  {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']},
    ...
  ]},
  ...
]

Transforms command-line options into arguments object arrays, e.g.

[
  {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

[
  {_: [], paginate: {type: 'flag', count: 1}},
  {commit: [
    {_: [], all: 'true', message: 'First commit'}
  ]}
]

Several stages that modify arguments object arrays, e.g.

[
  {_: [], paginate: {type: 'flag', count: 1}},
  {commit: [
    {_: [], all: 'true', message: 'First commit'}
  ]}
]

could be transformed to

[
  {_: [], paginate: {type: 'flag', count: 1}},
  {commit: {
    {_: [], all: true, message: 'First commit'}
  }}
]

Transforms argument object arrays into any result value:

[
  {_: [], paginate: {type: 'flag', count: 1}},
  {commit: [
    {_: [], all: true, message: 'First commit'}
  ]}
]

could be transformed to

{
  _: [],
  paginate: {type: 'flag', count: 1},
  commit: {
    _: [],
    all: true,
    message: 'First commit'
  }
}

Transforms a value into command-line argument values syntax, e.g.

"-p commit -am 'First commit'"

could be transformed to

['-p', 'commit', '-am', 'First commit']

Several stages that modify command-line argument values, e.g.

['-p', 'commit', '-am', 'First commit']

could be transformed to

['-p', 'commit', '-a', '-m', 'First commit']

Transforms argument values into command-line options, e.g.

['-p', 'commit', '-a', '-m', 'First commit']

could be transformed to

[
  {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']},
    ...
  ]},
  ...
]

Several stages that modify command-line options, e.g.

[
  {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

[
  {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']},
    ...
  ]},
  ...
]

Transforms command-line options into arguments object arrays, e.g.

[
  {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

[
  {_: [], paginate: {type: 'flag', count: 1}},
  {commit: [
    {_: [], all: 'true', message: 'First commit'}
  ]}
]

Several stages that modify arguments object arrays, e.g.

[
  {_: [], paginate: {type: 'flag', count: 1}},
  {commit: [
    {_: [], all: 'true', message: 'First commit'}
  ]}
]

could be transformed to

[
  {_: [], paginate: {type: 'flag', count: 1}},
  {commit: {
    {_: [], all: true, message: 'First commit'}
  }}
]

Transforms argument object arrays into any result value:

[
  {_: [], paginate: {type: 'flag', count: 1}},
  {commit: [
    {_: [], all: true, message: 'First commit'}
  ]}
]

could be transformed to

{
  _: [],
  paginate: {type: 'flag', count: 1},
  commit: {
    _: [],
    all: true,
    message: 'First commit'
  }
}

If rules is not a function, reports a WrongArgvRulesType error.

Example:

const {verifyArgv} = require('shargs/parser')

const rules = argv => (
  argv.some(_ => _ === '--question') &&
  argv.some(_ => _ === '--answer')
)

const argv = ['--answer', '42']

verifyArgv(rules)({argv})

Result:

{
  errs: [
    {
      code: 'FalseArgvRules',
      msg:  'Your argv rules returned false...',
      info: {...}
    }
  ]
}

It only removes the first =, so ['--question=1+2=3?'] is transformed into ['--question', '1+2=3?'].

Example:

const {equalsSignAsSpace} = require('shargs/parser')

const argv = ['--answer=42']

equalsSignAsSpace({argv})

Result:

{
  argv: ['--answer', '42']
}

Example:

const {shortOptsNoSpace} = require('shargs/parser')

const argv = ['-a42']

shortOptsNoSpace({argv})

Result:

{
  argv: ['-a', '42']
}

Example:

const {splitShortOpts} = require('shargs/parser')

const argv = ['-ha', '42']

splitShortOpts({argv})

Result:

{
  argv: ['-h', '-a', '42']
}

While p's signature is arg => true|false, f's signature must be (arg, index, argv) => ({errs = [], argv = []}). Many other argv checks and stages are defined in terms of traverseArgv and it is of great help for writing custom argv stages.

Example:

const {traverseArgv} = require('shargs/parser')

const argv = [
  '--answer=42',
  '--help'
]

const hasEqualsSign = arg => arg.indexOf('=') > -1

const replaceFirstEqualsSign = arg => ({
  argv: [
    arg.slice(0, arg.indexOf('=')),
    arg.slice(arg.indexOf('=') + 1)
  ]
})

traverseArgv(hasEqualsSign)(replaceFirstEqualsSign)({argv})

Result:

{
  argv: [
    '--answer', '42',
    '--help'
  ]
}

This is the case, if both, the option and an option from its contradicts list, have values. If contradicts is not a list, it reports a WrongContradictsType error.

Example:

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:

{
  errs: [
    {
      code: 'ContradictionDetected',
      msg:  'Some given keys contradict each other.',
      info: {...}
    }
  ]
}

Example:

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:

{
  errs: [
    {
      code: 'SubcommandRequired',
      msg:  'No subcommand found. Please use at least one subcommand!',
      info: {...}
    }
  ]
}

This is the case, if the option has values, but an option from its implies list has not. If implies is not a list, it reports a WrongImpliesType error.

Example:

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:

{
  errs: [
    {
      code: 'ImplicationViolated',
      msg:  'Some given keys that imply...',
      info: {...}
    }
  ]
}

If values is not an array, it reports a WrongFormatForRequiredOption error.

Example:

const {requireOpts} = require('shargs/parser')
const {string} = require('shargs/opts')

const opts = [
  string('question', ['--question'], {required: true})
]

requireOpts({opts})

Result:

{
  errs: [
    {
      code: 'RequiredOptionIsMissing',
      msg:  'A required option has not been provided.',
      info: {...}
    }
  ]
}

It checks all rest values, assuming they are in the rest category because of spelling mistakes. It collects all command-line options' args and computes a distance metric (currently Levenshtein distance) between each arg and each rest. It reports the results in a DidYouMean error, suggesting probable args replacements for spelling mistakes.

Example:

const {suggestOpts} = require('shargs/parser')
const {number} = require('shargs/opts')

const opts = [
  number('answer', ['-a', '--ans']),
  {values: ['--asn']}
]

suggestOpts({opts})

Result:

{
  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:

'Did you mean: ' + (
  options
  .slice(0, 3)
  .reduce((a, b) => a.concat(b))
  .flatMap(Object.keys)
  .join(', ')
)

Results in:

Did you mean: --age

If a positional argument is required, all previously defined positional arguments must be required, as well, and no other positional arguments can be defined after a variadicPos. In case of a violation of the second rule, validatePosArgs reports an InvalidVariadicPositionalArgument error.

Example:

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:

{
  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: {...}
    }
  ]
}

If rules is not a function, verifyOpts reports a WrongOptsRulesType error.

Example:

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:

{
  errs: [
    {
      code: 'FalseOptsRules',
      msg:  'Your opts rules returned false...',
      info: {...}
    }
  ]
}

See the values documentations for the exact rules. If the lengths of values and types do not match, an InvalidArity error is reported. If the types field has an invalid value, an InvalidTypes error is reported and verifyValuesArity reports an InvalidValues error in case of invalid values.

Example:

const {verifyValuesArity} = require('shargs/parser')
const {number} = require('shargs/opts')

const opts = [
  number('answer', ['--answer'], {values: ['42', '23']})
]

verifyValuesArity({opts})

Result:

{
  errs: [
    {
      code: 'InvalidArity',
      msg:  "An option's types arity does not match...",
      info: {...}
    }
  ]
}

Example:

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:

{
  opts: [
    array(['string', 'number'])('answer', ['-a'], {
      values: ['42', 42]
    })
  ]
}

Single rest options are interpreted as flags while two consecutive rest options are interpreted as strings if the first 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 is very similar to bestGuessOpts, but also considers non-consecutive rest values.

Example:

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:

{
  opts: [
    string('age', ['--age'], {values: ['unknown']}),
    flag('paranoid', [], {values: [1]}),
    string('name', [], {values: ['Marvin']}),
    {values: ['foo']}
  ]
}

Example:

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:

{
  opts: [
    number('answer', ['-a', '--answer'], {values: ['42']}),
    bool('verbose', ['--verbose'], {values: ['false']})
  ]
}

If types contains 'number', but values cannot be cast into a number, an ArgumentIsNotANumber error is reported. If types contains 'bool', but values is not ['true'] or ['false'], an ArgumentIsNotABool error is reported.

Example:

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:

{
  opts: [
    number('answer', ['-a', '--answer'], {values: [42]}),
    bool('verbose', ['--verbose'], {defaultValues: [false]})
  ]
}

If values are not found in only, a ValueRestrictionsViolated error is reported for each value.

Example:

const {restrictToOnly} = require('shargs/parser')
const {number} = require('shargs/opts')

const opts = [
  number('answer', ['--answer'], {only: ['42'], values: ['23']})
]

restrictToOnly({opts})

Result:

{
  errs: [
    {
      code: 'ValueRestrictionViolated',
      msg:  'A value lies outside the allowed values...',
      info: {...}
    }
  ],
  opts
}

Example:

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:

{
  opts: [
    bool('verbose', ['-v'], {reverse: true, values: [false]}),
    bool('verbose', ['-v'], {reverse: true, values: ['false']})
  ]
}

Example:

const {reverseFlags} = require('shargs/parser')
const {flag} = require('shargs/opts')

const opts = [
  flag('help', ['-h'], {reverse: true, values: [1]})
]

reverseFlags({opts})

Result:

{
  opts: [
    flag('help', ['-h'], {reverse: true, values: [-1]})
  ]
}

Example:

const opts = [
  flag(['-f'], {defaultValues: [1]}),
  bool(['-b'], {defaultValues: ['true']})
]

setDefaultValues({opts})

Result:

{
  opts: [
    flag(['-f'], {values: [1]}),
    bool(['-b'], {values: ['true']})
  ]
}

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:

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:

{
  opts: [
    number('answer', ['-a'], {values: ['42']}),
    flag('verbose', ['-v'], {values: [-1]}),
    flag('help', ['-h'], {values: [-1]})
  ]
}

Example:

const {failRest} = require('shargs/parser')

const args = {
  _: ['--help']
}

failRest({args})

Result:

{
  errs: [
    {
      code: 'UnexpectedArgument',
      msg:  'An unexpected argument was used...',
      info: {...}
    }
  ]
}

Reports a WrongArgsRulesType error if rules is not a function.

Example:

const {verifyArgs} = require('shargs/parser')

const rules = args => (
  typeof args.question !== 'undefined' &&
  typeof args.answer   !== 'undefined'
)

const args = {
  question: 'How much is the fish?'
}

verifyArgs(rules)({args})

Result:

{
  errs: [
    {
      code: 'FalseArgsRules',
      msg:  'Your args rules returned false...',
      info: {...}
    }
  ]
}

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, 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:

const {bestGuessArgs} = require('shargs/parser')

const obj = {
  args: {
    _: ['--answer', '42', 'foo', '-h'],
    command: {
      _: ['bar', '-v', '--question', 'What is answer?', '-v']
    }
  }
}

bestGuessArgs(obj)

Result:

{
  args: {
    _: ['foo'],
    answer: '42',
    h: {type: 'flag', count: 1},
    command: {
      _: ['bar'],
      v: {type: 'flag', count: 2},
      question: 'What is answer?'
    }
  }
}

It supports numbers and booleans (e.g. {help: 'true'} becomes {help: true}).

Example:

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:

{
  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
    }
  }
}

Example:

const args = {
  _: [],
  version: true
}

boolAsFlag('version')({args})

Result:

{
  _: [],
  version: {type: 'flag', count: 1}
}

Example:

const args = {
  _: [],
  html: false,
  version: true
}

boolsAsFlags({args})

Result:

{
  _: [],
  html: {type: 'flag', count: -1},
  version: {type: 'flag', count: 1}
}

Example:

const {clearRest} = require('shargs/parser')

const args = {_: ['--verbose']}

clearRest({args})

Result:

{
  args: {_: []}
}

If its count is greater than 0 it is considered true, otherwise it is considered false.

Example:

const {flagAsBool} = require('shargs/parser')

const args = {
  verbose: {type: 'flag', count: 1}
}

flagAsBool('verbose')({args})

Result:

{
  args: {
    verbose: true
  }
}

Example:

const {flagAsNumber} = require('shargs/parser')

const args = {
  verbose: {type: 'flag', count: 2}
}

flagAsNumber('version')({args})

Result:

{
  args: {
    verbose: 2
  }
}

Example:

const {flagsAsBools} = require('shargs/parser')

const args = {
  verbose: {type: 'flag', count: 1}
}

flagsAsBools({args})

Result:

{
  args: {
    verbose: true
  }
}

Example:

const {flagsAsNumbers} = require('shargs/parser')

const args = {
  verbose: {type: 'flag', count: 2}
}

flagsAsNumbers({args})

Result:

{
  args: {
    verbose: 2
  }
}

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:

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:

{
  args: {
    _: ['--help', '-v'],
    version: {type: 'flag', count: 2},
    name: 'Arthur',
    help: true,
    verbose: true
  }
}

Example:

const args = {
  _: [],
  answer: 42
}

numberAsFlag('answer')({args})

Result:

{
  _: [],
  answer: {type: 'flag', count: 42}
}

Example:

const args = {
  _: [],
  answer: 42
}

numbersAsFlags({args})

Result:

{
  _: [],
  answer: {type: 'flag', count: 42}
}

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: functions and otherwises 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:

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:

{
  args: {
    verbose: 2,
    answer: 42
  }
}

Allowed fs fields:

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})
}

If the description is too long to fit one line, it is split and spread over several lines. desc is defined as descWith({id: 'line'}).

Example:

Deep Thought should answer the Ultimate 
Question                                

Code:

const {desc, usage} = require('shargs/usage')

const opt = {
  opts: [],
  desc: 'Deep Thought should answer the Ultimate Question'
}

const style = {
  line: [{width: 40}]
}

usage([
  desc
])(opt)(style)

If the string is too long to fit one line, it is split and spread over several lines. note is defined as noteWith({id: 'line'}).

Example:

Deep Thought was created to come up with
the Answer                              

Code:

const {note, usage} = require('shargs/usage')

const style = {
  line: [{width: 40}]
}

usage([
  note('Deep Thought was created to come up with the Answer')
])()(style)

If a string is too long to fit one line, it is split and spread over several lines. notes is defined as notesWith({id: 'line'}).

Example:

Deep Thought was created to come up with
the Answer                              
to The Ultimate Question.               

Code:

const {notes, usage} = require('shargs/usage')

const style = {
  line: [{width: 40}]
}

usage([
  notes([
    'Deep Thought was created to come up with the Answer',
    'to The Ultimate Question.'
  ])
])()(style)

The term part comprises of an opt's args, descArg, only, types, and key fields, followed by the contradicts, defaultValues, implies, and required fields. The desc field is given in the definition part. optsDef is defined as optsDefWith({id: 'line', pad: 4}).

Example:

-a, --answer=<number> [default: 42]     
    The answer.                         
-h, --help                              
    Prints help.                        
--version                               
    The version.                        

Code:

const {optsDef, usage} = require('shargs/usage')
const {flag, number} = require('shargs/opts')

const opt = {
  opts: [
    number('answer', ['-a', '--answer'], {
      desc: 'The answer.', defaultValues: ['42']
    }),
    flag('help', ['-h', '--help'], {desc: 'Prints help.'}),
    flag('version', ['--version'], {desc: 'The version.'})
  ]
}

const style = {
  line: [{width: 40}]
}

usage([
  optsDef
])(opt)(style)

optsDefs is defined as optsDefsWith({id: 'line', pad: 4}).

Example:

-a, --answer=<number> [default: 42]     
    The answer.                         
-h, --help                              
    Show the usage docs.                
ask [required]                          
    Ask questions.                      
    -h                                  
        Usage docs.                     
    <questions>... [required]           
        Questions.                      

Code:

const {optsDefs, usage} = require('shargs/usage')
const {flag, subcommand} = require('shargs/opts')
const {number, variadicPos} = require('shargs/opts')

const required = true

const askOpts = [
  flag('help', ['-h'], {desc: 'Show the usage docs.'}),
  variadicPos('questions', {required, desc: 'Questions.'})
]

const ask = subcommand(askOpts)

const opt = {
  opts: [
    ask('ask', ['ask'], {desc: 'Ask questions.', required}),
    number('answer', ['-a', '--answer'], {
      desc: 'The answer.', defaultValues: ['42']
    }),
    flag('help', ['-h', '--help'], {desc: 'Usage docs.'})
  ]
}

const style = {
  line: [{width: 40}]
}

usage([
  optsDefs
])(opt)(style)

The first column comprises of an opt's args, descArg, only, types, and key fields. The desc field is given in the second column, followed by the contradicts, defaultValues, implies, and required fields. optsList is defined as optsListWith({id: 'cols'}).

Example:

-a, --answer=<number>    The answer. [default: 42]
-h, --help               Prints help.             
--version                The version.             

Code:

const {optsList, usage} = require('shargs/usage')
const {flag, number} = require('shargs/opts')

const opt = {
  opts: [
    number('answer', ['-a', '--answer'], {
      desc: 'The answer.', defaultValues: ['42']
    }),
    flag('help', ['-h', '--help'], {desc: 'Prints help.'}),
    flag('version', ['--version'], {desc: 'The version.'})
  ]
}

const style = {
  cols: [{width: 25}, {width: 25}]
}

usage([
  optsList
])(opt)(style)

optsLists is defined as optsListsWith({id: 'cols', pad: 4}).

Example:

-a, --answer=<number>    The answer. [default: 42]
-h, --help               Usage docs.              
ask                      Ask questions. [required]
    -h                   Show the usage docs.     
    <questions>...       Questions. [required]    

Code:

const {optsLists, usage} = require('shargs/usage')
const {flag, subcommand} = require('shargs/opts')
const {number, variadicPos} = require('shargs/opts')

const required = true

const askOpts = [
  flag('help', ['-h'], {desc: 'Show the usage docs.'}),
  variadicPos('questions', {required, desc: 'Questions.'})
]

const ask = subcommand(askOpts)

const opt = {
  opts: [
    ask('ask', ['ask'], {desc: 'Ask questions.', required}),
    number('answer', ['-a', '--answer'], {
      desc: 'The answer.', defaultValues: ['42']
    }),
    flag('help', ['-h', '--help'], {desc: 'Usage docs.'})
  ]
}

const style = {
  cols: [{width: 25}, {width: 25}]
}

usage([
  optsLists
])(opt)(style)

space is defined as spaceWith({id: 'line', lines: 1}).

Example:

Deep Thought was created to come up with
                                        
the Answer to The Ultimate Question.    

Code:

const {note, space, usage} = require('shargs/usage')

const style = {
  line: [{width: 40}]
}

usage([
  note('Deep Thought was created to come up with'),
  space,
  note('the Answer to The Ultimate Question.')
])()(style)

synopses is defined as synopsesWith({id: 'line'}).

Example:

deepThought (-a|--answer) [-h|--help]   
deepThought (ask) [-h] (<questions>...)   

Code:

const {synopses, usage} = require('shargs/usage')
const {command, flag, number} = require('shargs/opts')
const {subcommand, variadicPos} = require('shargs/opts')

const required = true

const askOpts = [
  flag('help', ['-h']),
  variadicPos('questions', {required})
]

const ask = subcommand(askOpts)

const opts = [
  ask('ask', ['ask'], {required}),
  number('answer', ['-a', '--answer'], {required}),
  flag('help', ['-h', '--help'])
]

const deepThought = command('deepThought', opts)

const style = {
  line: [{width: 40}]
}

usage([
  synopses
])(deepThought)(style)

For each opt, the args, descArg, only, required, types, and key fields are used for a brief overview. synopsis is defined as synopsisWith({id: 'line'}).

Example:

deepThought (-a|--answer) [-h|--help]   
            [--version] <questions>...  

Code:

const {synopsis, usage} = require('shargs/usage')
const {command, flag} = require('shargs/opts')
const {number, variadicPos} = require('shargs/opts')

const opts = [
  number('answer', ['-a', '--answer'], {
    desc: 'The answer.', required: true
  }),
  flag('help', ['-h', '--help'], {desc: 'Prints help.'}),
  flag('version', ['--version'], {desc: 'The version.'}),
  variadicPos('questions')
]

const deepThought = command('deepThought', opts)

const style = {
  line: [{width: 40}]
}

usage([
  synopsis
])(deepThought)(style)

Example:

deepThought [-a|--answer] [-h|--help] [--version] 
                                                  
-a, --answer=<number>    The answer.              
-h, --help               Prints help.             
--version                Prints version.          
                                                  
Deep Thought was created to come up with the      
Answer.                                           

Code:

const {note, optsList, space} = require('shargs/usage')
const {synopsis, usage} = require('shargs/usage')
const {command, flag, number} = require('shargs/opts')

const opts = [
  number('answer', ['-a', '--answer'], {desc: 'The answer.'}),
  flag('help', ['-h', '--help'], {desc: 'Prints help.'}),
  flag('version', ['--version'], {desc: 'Prints version.'})
]

const deepThought = command('deepThought', opts, {
  desc: 'Deep Thought was created to come up with the Answer.'
})

const style = {
  line: [{width: 50}],
  cols: [{width: 25}, {width: 25}]
}

usage([synopsis, space, optsList, space, desc])(deepThought)(style)

Example:

-a, --answer                            
    The answer.                         
-h, --help                              
    Prints help.                        
--version                               
    Prints version.                     

Code:

const {text, textWith, usageMap} = require('shargs/usage')
const {flag, number} = require('shargs/opts')

const opt = {
  opts: [
    number('answer', ['-a', '--answer'], {desc: 'The answer.'}),
    flag('help', ['-h', '--help'], {desc: 'Prints help.'}),
    flag('version', ['--version'], {desc: 'Prints version.'})
  ]
}

const style = {
  line: [{width: 40}]
}

usageMap(({args, desc}) => layout([
  text(args.join(', ')),
  textWith({id: 'desc'})(desc)
]))(opt)(style)

Example:

const {justArgs, usage} = require('shargs/usage')
const {flag, number, subcommand} = require('shargs/opts')

const style = {
  cols: [{width: 25}, {width: 25}]
}

const opt = {
  opts: [
    number('answer', ['-a', '--answer'], {
      desc: 'The answer'
    }),
    subcommand([])('ask', ['ask'], {desc: 'Asks a question'}),
    flag('version', ['--version'], {desc: 'Prints version'})
  ]
}

usage([
  justArgs(['-a'])(optsList)
])(opt)(style)

Result:

-a, --answer=<number>    The answer               

Example:

const {noSubcommands, usage} = require('shargs/usage')
const {flag, number, subcommand} = require('shargs/opts')

const style = {
  cols: [{width: 25}, {width: 25}]
}

const opt = {
  opts: [
    number('answer', ['-a', '--answer'], {
      desc: 'The answer'
    }),
    subcommand([])('ask', ['ask'], {desc: 'Asks a question'}),
    flag('version', ['--version'], {desc: 'Prints version'})
  ]
}

usage([
  noSubcommands(optsList)
])(opt)(style)

Result:

-a, --answer=<number>    The answer               
--version                Prints version           

Example:

const {onlySubcommands, usage} = require('shargs/usage')
const {flag, number, subcommand} = require('shargs/opts')

const style = {
  cols: [{width: 25}, {width: 25}]
}

const opt = {
  opts: [
    number('answer', ['-a', '--answer'], {
      desc: 'The answer'
    }),
    subcommand([])('ask', ['ask'], {desc: 'Asks a question'}),
    flag('version', ['--version'], {desc: 'Prints version'})
  ]
}

usage([
  onlySubcommands(optsList)
])(opt)(style)

Result:

ask                      Asks a question          

Example:

const {onlyFirstArg, usage} = require('shargs/usage')
const {flag, number, subcommand} = require('shargs/opts')

const style = {
  cols: [{width: 25}, {width: 25}]
}

const opt = {
  opts: [
    number('answer', ['-a', '--answer'], {
      desc: 'The answer'
    }),
    subcommand([])('ask', ['ask'], {desc: 'Asks a question'}),
    flag('version', ['--version'], {desc: 'Prints version'})
  ]
}

usage([
  onlyFirstArg(optsList)
])(opt)(style)

Result:

-a <number>              The answer               
ask                      Asks a question          
--version                Prints version           

Example:

const {optsFilter, usage} = require('shargs/usage')
const {flag, number, subcommand} = require('shargs/opts')

const style = {
  cols: [{width: 25}, {width: 25}]
}

const opt = {
  opts: [
    number('answer', ['-a', '--answer'], {
      desc: 'The answer'
    }),
    subcommand([])('ask', ['ask'], {desc: 'Asks a question'}),
    flag('version', ['--version'], {desc: 'Prints version'})
  ]
}

usage([
  optsFilter(({types}) => types !== null)(optsList)
])(opt)(style)

Result:

-a, --answer=<number>    The answer               
ask                      Asks a question          
--version                Prints version           

Example:

const {optsMap, usage} = require('shargs/usage')
const {flag, number, subcommand} = require('shargs/opts')

const style = {
  cols: [{width: 25}, {width: 25}]
}

const opt = {
  opts: [
    number('answer', ['-a', '--answer'], {
      desc: 'The answer'
    }),
    subcommand([])('ask', ['ask'], {desc: 'Asks a question'}),
    flag('version', ['--version'], {desc: 'Prints version'})
  ]
}

usage([
  optsMap(opt => ({...opt, args: opt.args.slice(0, 1)}))(optsList)
])(opt)(style)

Result:

-a <number>              The answer               
ask                      Asks a question          
--version                Prints version           

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.'}
]

const {command, flag, number, subcommand} = require('shargs/opts')

const opts = [
  subcommand(askOpts)('ask', ['ask'], {required: true, desc: 'Ask a question.'}),
  number('answer', ['-a', '--answer'], {defaultValues: [42], desc: 'The answer.'}),
  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 {parserSync} = require('shargs')
const {cast, flagsAsBools, requireOpts, restrictToOnly} = require('shargs/parser')
const {reverseFlags, setDefaultValues, splitShortOpts} = require('shargs/parser')

const stages = {
  argv: [splitShortOpts],
  opts: [setDefaultValues, requireOpts, reverseFlags, cast],
  args: [flagsAsBools]
}

const substages = {
  ask: [...stages.opts, restrictToOnly]
}

const parser = parserSync(stages, substages)

const {desc, optsLists, space, synopses, usage} = require('shargs/usage')

const docs = usage([
  synopses,
  space,
  optsLists,
  space,
  desc
])

const style = {
  line: [{width: 80}],
  cols: [{width: 25}, {width: 55}]
}

br is defined as brWith({id: 'line', lines: 1}).

Example:

Deep Thought was created to come up with
the Answer                              
                                        
to The Ultimate Question.               

Code:

const {br, layout, text} = require('shargs/usage')

const style = {
  line: [{width: 40}]
}

layout([
  text('Deep Thought was created to come up with the Answer'),
  br,
  text('to The Ultimate Question.')
])(style)

It formats the columns according to their widths and cuts off strings that are too long. cols is defined as colsWith({id: 'cols'}).

Example:

-a, --answer=<number>    The answer. [default: 42]
-h, --help               Prints help.             
--version                Prints version.          

Code:

const {cols, layout} = require('shargs/usage')

const style = {
  cols: [{width: 25}, {width: 25}]
}

layout([
  cols([
    [
      '-a, --answer=<number>',
      '-h, --help',
      '--version'
    ],
    [
      'The answer. [default: 42]',
      'Prints help.',
      'Prints version.'
    ]
  ])
])(style)

It formats its tuples as a definition list over two lines, with the term in the first, and the definition in the second line. If a term or definition extends its line, it is continued in another line. defs is defined as defsWith({id: 'line', pad: 4}).

Example:

-a, --answer=<number> [default: 42]     
    The answer.                         
-h, --help                              
    Prints help.                        
--version                               
    Prints version.                     

Code:

const {defs, layout} = require('shargs/usage')

const style = {
  line: [{width: 40}]
}

layout([
  defs([
    ['-a, --answer=<number> [default: 42]', 'The answer.'],
    ['-h, --help', 'Prints help.'],
    ['--version', 'Prints version.']
  ])
])(style)

If a string exceeds its width, it is cut off, otherwise, the width is filled up with spaces. It ends with a line break. line is defined as lineWith({id: 'line'}).

Example:

Deep Thought was created to come up with
the Answer                              

Code:

const {layout, line} = require('shargs/usage')

const style = {
  line: [{width: 40}]
}

layout([
  line('Deep Thought was created to come up with'),
  line('the Answer')
])(style)

lines is defined as linesWith({id: 'line'}).

Example:

Deep Thought was created to come up with
the Answer                              
to The Ultimate Question.               

Code:

const {layout, lines} = require('shargs/usage')

const style = {
  line: [{width: 40}]
}

layout([
  lines([
    'Deep Thought was created to come up with',
    'the Answer',
    'to The Ultimate Question.'
  ])
])(style)

If an entry exceeds the length of a column, it breaks into the next row. table is defined as tableWith({id: 'cols'}).

Example:

-a, --answer=<number>    The answer. [default: 42]
-h, --help               Prints help.             
--version                Prints version.          

Code:

const {layout, table} = require('shargs/usage')

const style = {
  cols: [{width: 25}, {width: 25}]
}

layout([
  table([
    ['-a, --answer=<number>', 'The answer. [default: 42]'],
    ['-h, --help', 'Prints help.'],
    ['--version', 'Prints version.']
  ])
])(style)

If the string exceeds a line, it continues on the next. text is defined as textWith({id: 'line'}).

Example:

Deep Thought was created to come up with
the Answer                              

Code:

const {layout, text} = require('shargs/usage')

const style = {
  line: [{width: 40}]
}

layout([
  text('Deep Thought was created to come up with the Answer')
])(style)

texts is defined as textsWith({id: 'line'}).

Example:

Deep Thought was created to come up with
the Answer                              
to The Ultimate Question.               

Code:

const {layout, texts} = require('shargs/usage')

const style = {
  line: [{width: 40}]
}

layout([
  texts([
    'Deep Thought was created to come up with the Answer',
    'to The Ultimate Question.'
  ])
])(style)

Example:

const {layout, line} = require('shargs/usage')

const style = {
  line: [{width: 40}]
}

layout([
  line('Deep Thought was created to come up with'),
  line('the Answer')
])(style)

Result:

Deep Thought was created to come up with
the Answer                              

Example:

const {layout, layoutMap, textWith} = require('shargs/usage')

const defsWith = ({id}) => layoutMap(
  ([term, definition] = []) => layout([
    textWith({id})(term),
    textWith({id})(definition)
  ])
)

const defs = defsWith({id: 'line'})

const style = {
  line: [{width: 40}]
}

defs([
  ['-a, --answer=<number> [default: 42]', 'The answer.'],
  ['-h, --help', 'Prints help.'],
  ['--version', 'Prints version.']
])(style)

Result:

-a, --answer=<number> [default: 42]     
    The answer.                         
-h, --help                              
    Prints help.                        
--version                               
    Prints version.                     

Example:

const {layout, pad, table} = require('shargs/usage')

const style = {
  cols: [{width: 20}, {width: 20}]
}

layout([
  pad(['cols', 0], 4)(table([['--answer', '42']]))
])(style)

Result:

    --answer        42                  

const {layout, stylePath, table} = require('shargs/usage')

const pad4 = obj => ({
  ...obj,
  padStart: (obj.padStart || 0) + 4,
  width: obj.width - 4
})

const style = {
  cols: [{width: 20}, {width: 20}]
}

layout([
  stylePath(['cols', 0], pad4)(table([['--answer', '42']]))
])(style)

Result:

    --answer        42                  

If you just want to have default values, you may want to check out the defaultValues options field. If this does not suffice or you have a different problem, read on.

Say we have read in a config object from somewhere:

const config = {
  question: 'How can I use config objects with shargs?',
  answer: 'Read the FAQ section!'
}

And we have run a shargs parser and have obtained the following args object:

const args = {
  _: [],
  question: 'What is the meaning of life, the universe, and everything?'
}

Then using the config object would just mean merging the two objects:

const preferArgs = {
  ...config,
  ...args
}

const preferConfig = {
  ...args,
  ...config
}

Of course these example merges are simple cases, because the objects are flat.

In case of subcommands, the args object would have (deeply) nested objects. Such cases are common and there are specialized libraries for merging deeply nested objects, like ramda or lodash:

const {mergeDeepLeft, mergeDeepRight} = require('ramda')

const preferArgs = mergeDeepLeft(args, config)

const preferConfig = mergeDeepRight(args, config)

Command-line parsers read arguments and assign them to variables that are passed as inputs to programs. So we are dealing with two different sets of names, here: Names of arguments and names of variables. Those two sets are connected by a unidirectional mapping, where arguments map to variable names.

If a single argument would only ever map to a single variable, the two could just as well have the same name. But for more complex mappings, things start to get complex, too:

Say we have two arguments, -v and --version, that can be used interchangeably. If they would map to two variables, -v and --version, the program would have to have knowledge about the arguments being interchangeable, in order to correctly interpret its inputs. As leaking this knowledge to the program would be undesirable, parsers usually work around this by assigning the value of one argument to both variables. But now we are in a situation where we have two dependant variables that always have the same value. A less verbose solution is just letting both arguments map to the same variable (the key field):

const {string} = require('shargs/opts')

const opts = [
  string('version', ['-v', '--version'])
]

A special situation of two arguments mapping to the same variable is, when the arguments belong to separate options. This frequently occurs for flag and bool options that have a complement:

const {flag} = require('shargs/opts')

const opts = [
  flag('fun', ['--fun']),
  flag('fun', ['--no-fun'], {reverse: true})
]

In the example, --fun adds 1 to the flag count, while --no-fun adds -1 due to reverse (assuming the parser has the reverseFlags stage).

But we have other possible mappings yet to explore: Situations, where one argument maps to two different variable names. Say we have a --birthday argument and the birthday and age variables. birthday is a string in date format, while age is a number holding the current age, transformed by the custom ageAsNumber stage. This kind of mapping is only possible if the parser's arguments are independent of the program's variables.

So, command-line options have a key field, because:

1. Separating internal variable names from external argument names is a good practice.
2. Separating argument and variable names enables functionality that would otherwise not be possible.
3. Separating arguments and variables makes interpreting variables less verbose for programs.

If you really do not need key fields and wish to use just argument names instead, it is straight forward to adjust the type function syntax accordingly:

const array2 = types => (args = [], fields = {}) => ({
  key: args.length > 0 ? args[0] : undefined,
  args,
  types,
  ...fields
})

const number2 = array2(['number'])

// ...

Say you want to add your own custom date type. First, you need to add a command-line option of that type:

const {array} = require('shargs/opts')

const date = array(['date'])

A date is an option that takes exactly one argument, whose type is described as 'date'.

Now we have an option, we may want to write parser stages that work with dates. How about a stage that transforms dates to their millisecond representation:

const {traverseOpts} = require('shargs/parser')

function dateToMillis ({errs = [], opts = []} = {}) {
  const isDate = ({types}) => (
    Array.isArray(types) &&
    types.length === 1 &&
    types[0] === 'date'
  )

  const toMillis = string => new Date(string).getTime()

  const dateToMillis = opt => ({
    opts: [{
      ...opt,
      ...(Array.isArray(opt.values)
          ? {values: opt.values.map(toMillis)}
          : {}
      )
    }]
  })

  return traverseOpts(isDate)(dateToMillis)({errs, opts})
}

This parser stage works alongside the other parser stages. Note, that a real implementation would test much more edge cases, like dates that occur in arrays.

We are inventing a new option type for this FAQ: commas:

const {array} = require('shargs/opts')

const commas = array(['commas'])

The commas type function is used to mark options we want to split.

We then write a custom opts stage to perform the splitting:

const {traverseOpts} = require('shargs/parser')

const isCommas = ({key, types, values}) => (
  typeof key !== 'undefined' &&
  Array.isArray(types) && types.indexOf('commas') > -1 &&
  Array.isArray(values) && values.length === types.length
)

const transformCommaArray = opt => {
  let values = []
  let types  = []

  for (let i = 0; i < opt.values.length; i++) {
    const value = opt.values[i]
    const type = opt.types[i]

    if (type === 'commas') {
      const elements = value.split(',')
      values = [...values, ...elements]
      types = [...types, ...Array.from({length: elements.length}, () => 'string')]
    } else {
      values.push(value)
      types.push(type)
    }
  }

  return {opts: [{...opt, types, values}]}
}

const splitCommas = traverseOpts(isCommas)(transformCommaArray)

splitCommas may now be used with options of type commas!

So why doesn't shargs-parser support comma-separated values by default? The reason is that using comma-separated values is just not that common. And if you nonetheless need comma-separated values, it is simple enough to implement yourself.

We generally recommend against using options with 0..1 cardinalities in programs. This is also why shargs does not support it.

A better approach is using an enumeration, implemented with the only options field and the restrictToOnly parser stage.

If you want to use it anyway, here is how you could do it in shargs:

Flags give you only two cases, the presence of the flag (true if flagsAsBools is used), and its absence (unknown):

const {flag} = require('shargs/opts')

const fun = flag('fun', ['--fun'])

You could add a third case by using only flags by defining a complement:

const {complement} = require('shargs/opts')

const noFun = complement('--no-')(fun)

Which is the same as writing:

const noFun = flag('fun', ['--no-fun'], {reverse: true})

If you provide --fun, the fun variable is set to true, on --no-fun it is set to false, and providing neither --fun, nor --no-fun would mean unknown.

You could implement the same behavior with an option that takes none or one argument, by using a combination of variable length arrays, aka subcommands and a custom command-line options field. The general idea is to mark a subcommand as threeValued with a field, and then transform it to a custom type in the opts stage.

First, let us define an option:

const {stringPos, subcommand} = require('shargs/opts')

const funOpts = [
  stringPos('threeValues')
]

const fun = subcommand(funOpts)('fun', ['--fun'], {threeValued: true})

Now, let us define an opts stage that transforms the subcommand:

const {traverseOpts} = require('shargs/parser')

const isThreeValued = ({threeValued}) => threeValued === true

  const toThreeValued = opt => {
  const types = ['threeValued']

  let values = ['unknown']

  if (Array.isArray(opt.values)) {
    const threeValues = opt.values.find(opt => opt.key === 'threeValues')
    values = threeValues.values || ['true']
  }

  return {
    opts: [
      {...opt, types, values: values.slice(0, 1), opts: undefined}
    ]
  }
}

const subcommandsToThreeValued = traverseOpts(isThreeValued)(toThreeValued)

subcommandsToThreeValued only transforms subcommands that have the threeValued field. For each subcommand, it checks, whether the subcommand is not present (unknown), it is present but has no values (true), or if it is present and has at least one value, (true if the value is true, false if it is false, otherwise unknown).

Note that this sample implementation is very brittle and should not be used as presented in a program.

const {string} = require('shargs/opts')

const answers = string('answers', ['-a'], {only: ['yes', 'no', 'maybe']})

First, let us write a helper function for traversing args objects:

function traverseKeys (p) {
  return f => ({errs, args}) => Object.keys(args).reduce(
    ({errs, args: obj}, key) => {
      const val = args[key]
      if (!Array.isArray(val) && typeof val === 'object') {
        obj[key] = traverseKeys(p)(f)(val)
      }
      if (p(key)) {
        const {[key]: _, ...rest} = obj
        obj = {...rest, ...f(key, val)}
      }
      return {errs, args: obj}
    },
    {errs, args}
  )
}

Using traverseKeys, we can implement a nestKeys args stage:

const _ = require('lodash')

const hasDots = key => key.indexOf('.') > -1

const nestValue = (key, val) => {
  const obj = {}
  _.set(obj, key, val)
  return obj
}

const nestKeys = traverseKeys(hasDots)(nestValue)

The nestKeys args stage should now nest the values into an object.

The reason why shargs does not include such a stage by default is, that this is a niche case that can be either implemented after parsing, or is easy enough to implement yourself.

shargs builds command-line parsers and usage documentation by composing parser and usage functions with functions it calls combinators. An exemplary combinator function is layout(functions)(style).

layout takes a list of functions that have a common signature: They take a style, and return a string. Next, it takes its own style parameter and feeds it to each function, getting a list of strings. Then it concatenates all strings together, which results in a string:

const {layout, text} = require('shargs/usage')

const style = {line: [{width: 10}]}

const string = layout([
  text('First.'),
  text('Second.')
])(style)

// string === 'First.    \nSecond.   \n'

What layout basically gives us is a way to provide only one style parameter to a list of functions, instead of one parameter per function. But why does layout have to have such a weird signature?

Let us assume we had the following layout2 and text2 functions, instead:

const {layout, text} = require('shargs/usage')

const layout2 = (functions, style) => layout(functions)(style)

const text2 = (string, style) => text(string)(style)

How could we concatenate strings only using text2?

const style = {line: [{width: 10}]}

const string = text2('First.', style) + text2('Second.', style)

// string === 'First.    \nSecond.   \n'

Do you see how the style parameter is repeated for every function? It gets worse if you have more functions.

Now let us use layout2:

const style = {line: [{width: 10}]}

const string = layout2([
  style => text2('First.', style),
  style => text2('Second.', style)
], style)

// string === 'First.    \nSecond.   \n'

See how style is still repeated and we do not have the advantage of only providing it once? Actually, using layout2 looks worse than using just text2!

But we can do better and rewrite the same example with text and two parameter lists:

const {text} = require('shargs/usage')

const style = {line: [{width: 10}]}

const string = layout2([
  style => text('First.')(style),
  style => text('Second.')(style)
], style)

// string === 'First.    \nSecond.   \n'

And then we can apply an optimization: See how we define a function that takes a style and feed it to a function text('First.') that takes a style? This is redundant, and we can just leave out style altogether:

const {text} = require('shargs/usage')

const style = {line: [{width: 10}]}

const string = layout2([
  text('First.'),
  text('Second.')
], style)

// string === 'First.    \nSecond.   \n'

Now we do not repeat style for every function! The code is much shorter and is easier to read.

And we can do even better by using a signature like layout. Because then layout is also a function that takes a style and returns a string, like text, and can be used inside other layout functions!

const {layout, text} = require('shargs/usage')

const style = {line: [{width: 10}]}

const firstSecond = layout([
  text('First.'),
  text('Second.')
])

const andThird = layout([
  firstSecond,
  text('Third.')
])

const string = andThird(style)

// string === 'First.    \nSecond.   \nThird.    \n'

And although we have five functions that each take a style parameter, we only have to apply it once.

Shargs employs tacit programming techniques to reduce boilerplate in its DSLs. A side-effect is that function signatures are weird (the technical term is curried).

Some JavaScript libraries like Ramda and lodash/fp use a technique called auto-currying. If layout would be auto-curried, it would have the signatures of layout and layout2 at the same time and you could choose which one to use. Shargs decided against auto-currying its functions, since it is simple enough to curry your functions yourself if you wanted:

const {curry} = require('ramda')
const {layout} = require('shargs/usage')

const curriedLayout = curry((fs, style) => layout(fs)(style))

curriedLayout can now be used like layout and like layout2.