parse-cli-arguments
v1.0.1parse-cli-arguments
Parses passed cli arguments to an object
Install
This module requires node >=4.0.0
$ npm install --save parse-cli-arguments
Usage
let args = require('parse-cli-arguments')(configuration);
Example
//node index.js test -a
let args = require('parse-cli-arguments')({
options: {
optionA: { defaultOption: true },
aliasB: { alias: 'a' }
}
});
/*args = {
optionA: 'test',
aliasB: true
}*/
Configuration
let configuration = {
options: {}, //Object
flagSymbol: '--', //String
aliasSymbol: '-', //String
argumentSymbol: '=', //String
stopArgument: '--', //String
restArguments: 'argv', //String
debug: false //Boolean
}
options
The options-object is a collection of options. If no option is set or none is configured as a defaultOption
the collection will be extended by a catch-all option with the name _args
.
option
let option = {
flag: 'flag', //String or true
alias: 'f', //String
defaultOption: true, //Boolean
multiple: true, //Boolean
defaultValue: true, //any value
type: '', //String
transform: function(val) { return parseInt(val); }, //Function
propName: 'propName', //String
}
The shortest valid option is flag: { flag: true }
. It is valid to set only an empty object, but this option would always return undefined
as no value can be assigned to the option without configuring flag
, alias
or defaultValue
.
option.flag
This configuration sets the name of the flag. If it is set to true
the flag will be equal to the property name of the option.
option.alias
This configuration sets the name of the alias. It must only consist of one character.
option.defaultOption
This configuration must be set no more than once. All unassigned values will be added to this option. If no option is configured as defaultOption
, unassigned values will be available in an array with the name _args
.
option.multiple
This configuration allows the option to return multiple values. If it is set, the returned value will always be an array. If it is not set and multiple values for the same flag or alias are passed, only the last one will be returned.
option.defaultValue
This configuration sets the returned value if the flag/alias was not passed or no unassigned value was added to the defaultOption
. The returned object always contains every configured option. If no value is passed and no defaultValue
is configured the value will be undefined
or []
when configured as multiple
.
If a flag/alias is passed without a value, e.g. node index.js --flag
, the value will be set to true
.
option.type
This configuration is only used to distinguish between Booleans and all other values. If an option is configured as Boolean, the opposite of the defaultValue
will be returned when the flag or alias is set. If no defaultValue
is configured, the defaultValue
is automatically set to false
. Boolean options must not be configured as defaultOption
or multiple
.
option.transform
This configuration allows to define a function that modifies the value before it is added to the returned object. Three arguments will be passed to the function: the passed value, the matched option and a reference to lodash.
option.propName
This configuration sets the name of the property in the returned object. It will default to the property name in the configuration object.
flagSymbol
This configuration sets the prefix for all flags. The default value is --
.
aliasSymbol
This configuration sets the prefix for all aliases. The default value is -
.
argumentSymbol
This configuration sets the sign that separates flags/aliases and values. The default value is =
.
stopArgument
This configuration sets the symbol that will stop the parsing of the passed arguments.
restArguments
This configuration sets the name of the property that contains all unparsed values.
debug
This configuration activates warnings that are written to the console. This warnings notice the user of behaviors that could be misinterpreted as failure but work as intended.
There are currently 3 different warnings:
- "Option [option.name] has been overridden." - Triggered when an option is not configured as multiple but multiple values were passed. Only the last passed value will be returned.
- "Alias [aliases] ignored because not all parts could be identified." - Triggered when aliases are grouped, e.g.
-abc
, and not all aliases are configured. In this case the group will be treated as a value. - "Value [val] is discarded because [option.name] is configured as Boolean." - If a flag or alias is configured as Boolean but passed with a value, e.g.
-test="123"
, the value will be ignored.
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add tests for any new or changed functionality. Lint and test your code using npm test
.
Metadata
- MIT
- >=4.0.0
- Martin Sachse
- released 10/19/2015