README

Args List Parser

Converts arrays of strings such as

['-build', '-files', 'x', 'y', '-o', 'z']

to objects such as

{
  build: true,
  files: ['x', 'y'],
  output: ['z'],
  threads: [8]
}

Usage

Construct ArgsListParser with a description of the arguments expected. Call parse, optionally with an array of strings. If parse is called without a parameter, process.argv.slice(2) will be defaulted.

const ArgsListParser = require('args-list-parser');

let argDescriptions = [
  {
    names: ['build', 'b'],
    values: 0,
    example: '-b',
    explanation: 'if provided, re-builds',
  }, {
    names: ['files', 'f'],
    values: 2,
    example: '-f in_1.js in_2.js in_3.js',
    explanation: 'the input files to process',
  }, {
    names: ['output', 'o'],
    values: 1,
    example: '-o out.js',
    explanation: 'the output file to process',
  }, {
    names: ['threads', 't'],
    defaultValues: [8],
    type: 'int'
    values: 1,
    example: '-t 16',
    explanation: 'number of threads to use',
  }
];

let argsListParser = new ArgsListParser(argDescriptions);
let args = argsListParser.parse();

Arg descriptions

The argument descriptions used to construct ArgsListPaerser should be a list of objects of the format below.

names indicates aliases the user can use to specify a value for an argument.
type (optional) indicates the value type of an argument. Defaults to 'string'.
defaultValues (optional) sets the default values of an argument if the user does not provide any values.
values indicates whether an argument accepts 0, 1, or multiple values.
example and explanation are used to construct the help output described later.

{
  names: Array<string>,
  defaultValues: Array<string|int|bool>,
  type: string ('int'|'bool'|'string'),
  values: int (0|1|2),
  example: string,
  explanation: string,
},

Escaping `-`

Arg names are differentiated from arg values by the fact that arg names have a - as their first character. If an arg value needs to begin with a dash, (e.g. a negative number or simply a dash-prefixed string), then escape the value with backslash. Similarly, to begin an arg value with a backslash, prepend an additional backslash. E.g. \-3 will be parsed as an arg value of -3 while \\][ will be parsed as an arg vale of \][.

Help

Calling parse with an empty array, or an array beginning with the string 'help' will print a help message explaining the arg descriptions. The latter case will also early exit parse returning undefined.

Arguments:
    -b                            build|b      no values          if provided, re-builds    
    -f in_1.js in_2.js in_3.js    files|f      multiple values    the input files to process
    -o out.js                     output|o     single value       the output file to process
    -t 16                         threads|t    single value       number of threads to use

Usage no npm install needed!