Command-line Arguments
Maps command-line arguments to a configuration object.
Installation
$ npm install argv-to-object
Usage
var argv = ;
argv( map[, options] )
Maps command-line arguments to a configuration object
.
var map ='env':'keypath': 'argv''type': 'string''default': 'dev''port':'keypath': 'server.port''type': 'integer''default': 8080'alias':'p''radix': 10'ssl':'keypath': 'server.ssl''type': 'boolean''loglevel':'keypath': 'logger.level''type': 'string''default': 'info';// --env=test --port 7331 --ssl --loglevel debugvar out = ;/*{'env': 'test','server': {'port': 7331,'ssl': true},'logger': {'level': 'debug'}}*/
A command-line argument mapping must include a keypath
, which is a dot-delimited object
path. By default, this module parses a command-line argument value as a string
. The following types are supported:
The function
accepts the following options
:
-
parsers: an
object
containing command-line argument parsers. Eachkey
should correspond to a definedtype
, and eachvalue
should be afunction
which accepts a command-line argument value and any associatedoptions
.var map ='custom_type':'keypath': 'custom''type': 'custom'... // => options;var parsers ='custom_type': custom;{var v = ;if v !== vreturn 'invalid value. Value must be an integer. Value: `' + str + '`.' ;return v * 6;}// --custom_type=5var out = ;/*{'custom': 30}*/
Types
All command-line argument value types
support the following options
:
- default: default value.
- alias:
array
of command-line argument aliases.
Except for boolean
, all command-line argument value types
support the following options
:
- multiple:
boolean
indicating whether a command-line argument can be provided multiple times. Iftrue
, the command-line argument value is always anarray
containing values of a specifiedtype
. Default:false
.
===
string
Coerce a command-line argument value to a string
.
var map ='str':'keypath': 'str''type': 'string';// --str=beepvar out = ;/*{'str': 'beep'}*/// --str=1234var out = ;/*{'str': '1234'}*/
===
number
Coerce a command-line argument value to a number
.
var map ='num':'keypath': 'num''type': 'number';// --num='3.14'var out = ;/*{'num': 3.14}*/// --num=bopvar out = ;// => throws
===
integer
Coerce a command-line argument value to an integer
.
var map ='int':'keypath': 'int''type': 'integer';// --int=2var out = ;/*{'int': 2}*/// --int=beepvar out = ;// => throws
The integer
type supports the following options
:
-
radix: an
integer
on the interval[2,36]
. Default:10
.var map ='int':'keypath': 'int''type': 'integer''radix': 2;// --int=1var out = ;/*{'int': 1}*/// --int=2var out = ;// => throws
===
boolean
Coerce a command-line argument value to a boolean
.
var map ='bool':'keypath': 'bool''type': 'boolean';// --boolvar out = ;/*{'bool': true}*/
Prefixing --no-*
to a boolean
command-line argument will override a default
value.
var map ='bool':'keypath': 'bool''type': 'boolean''default': true;// --no-boolvar out = ;/*{'bool': false}*/
If a boolean
command-line argument does not have a default
value, using the --no-*
prefix is equivalent to not specifying the command-line argument.
var map ='bool':'keypath': 'bool''type': 'boolean';// --no-boolvar out = ;/*{}*/
===
object
Parse a command-line argument value as a JSON object
. Note that a value must be valid JSON.
var map ='obj':'keypath': 'obj''type': 'object';// --obj='{"beep":"boop"}'var out = ;/*{'obj': {'beep': 'boop'}}*/// --obj='[1,2,3,"4",null]'var out = ;/*{'obj': [ 1, 2, 3, '4', null ]}*/// --obj='{"beep:"boop"}'var out = ;// => throws
===
date
Coerce a command-line argument to a Date
object.
var map ='date':'keypath': 'date''type': 'date';// --date='2015-10-17'var out = ;/*{'date': <Date>}*/// --date=beepvar out = ;// => throws
===
regexp
Parse a command-line argument as a RegExp
.
var map ='regexp':'keypath': 're''type': 'regexp';// --regexp='/\\w+/'var out = ;/*{'re': /\w+/}*/// --regexp=beepvar out = ;// => throws
Notes
-
If a command-line argument does not exist and no default value is specified, the corresponding configuration
keypath
will not exist in the outputobject
.var map ='unset_argv':'keypath': 'a.b.c';var out = ;// returns {}
Examples
var argv = ;var map ='env':'keypath': 'env''default': 'dev''port':'keypath': 'server.port''type': 'integer''default': 8080'alias':'p''radix': 10'ssl':'keypath': 'server.ssl''type': 'boolean''loglevel':'keypath': 'logger.level''type': 'string''default': 'info''num':'keypath': 'num''type': 'number''obj':'keypath': 'obj''type': 'object''arr':'keypath': 'arr''type': 'object''bool':'keypath': 'bool''type': 'boolean''nested':'keypath': 'a.b.c.d''type': 'object''date':'keypath': 'date''type': 'date''regex':'keypath': 're''type': 'regexp''mnum':'keypath': 'mnum''type': 'integer''multiple': true;// --env=test --ssl --p 7331 --num='3.14' --obj='{"hello":"world"}' --arr='[1,2,3,4]' --nested='{"beep":"boop"}' --date="2015-10-17" --regex '/\\w+/' --no-bool --mnum 1 --mnum=2 --mnum=3 --mnum 4var out = ;/*{'env': 'test','server': {'ssl': true,'port': 7331},'logger': {'level': 'info'},'num': 3.14,'obj': {'hello': 'world'},'arr': [ 1, 2, 3, 4 ],'nested': {'a': {'b': {'c': {'d': {'beep': 'boop'}}}}},'date': <Date>,'re': /\w+/,'mnum': [ 1, 2, 3, 4 ]}*/
To run the example code from the top-level application directory,
$ node ./examples/index.js --env=test --ssl --p 7331 --num='3.14' --obj='{"hello":"world"}' --arr='[1,2,3,4]' --nested='{"beep":"boop"}' --date="2015-10-17" --regex '/\\w+/' --no-bool --mnum 1 --mnum=2 --mnum=3 --mnum 4
Tests
Unit
Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:
$ make test
All new feature development should have corresponding unit tests to validate correct functionality.
Test Coverage
This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:
$ make test-cov
Istanbul creates a ./reports/coverage
directory. To access an HTML version of the report,
$ make view-cov
License
Copyright
Copyright © 2015. Athan Reines.