Parseopts NPM | npm.io

node-parseopts

An argv parser.

Usage

var parseopts = require('parseopts');

var opts = parseopts(process.argv, {

	// Required boolean. These values are interpreted as false (case
	// insensitively): "false", "off", "no", "0", and "" (empty string). All
	// other values are true.
	"bool": Boolean,

	// Required CSV.
	"csv": Array,

	// No value allowed. If the option is present, then the value will be true.
	// If a value is given, an error will be thrown.
	"flag": null,

	// Required function. The value string may optionally include an anonymous
	// function enclosure to specify function arguments.
	"func": Function,

	// Required JSON. If JSON parse fails, the value will be interpreted as a
	// literal string. This can be used as a form of type auto detection.
	"json": Object,

	// Required number.
	"number": Number,

	// Required regular expression. May be wrapped in forward slashes and
	// with trailing i, g, and/or m options.
	"regex": RegExp,

	// Required string.
	"string": String,

	// You can wrap any of the above in an array to specify that the option can
	// be given more than once. If an option is given at least once, then the
	// value in the returned options map will be an array of length >= 1. If an
	// option type is not wrapped in an array, then the last value given will
	// overwrite all previous values.

	"multiple-bools": [Boolean],
	"multiple-csvs": [Array],	// If a multiple CSV option is given more than
								// once, all values will be concatenated
								// together. The resulting option value will
								// still be one dimensional.
	"multiple-flags": [null],
	"multiple-funcs": [Function],
	"multiple-jsons": [Object],
	"multiple-numbers": [Number],
	"multiple-regexs": [RegExp],
	"multiple-strings": [String],

	// You can also use functions to create your own custom types. Whatever the
	// function returns becomes the option value.

	"custom": function(value, opts, index)
	{
		// `value` is the raw string value of the option.
		// `opts` is the map of already parsed options.
		// `index` is the order of the argument in the argv array.

		// Options are parsed in the order that they are defined, which means
		// you can make a custom type that behaves differently based on the
		// value of another option, and the order that those options are given
		// in the argv array won't matter.

		// NOTE: V8 keeps object properties in insertion order, EXCEPT for
		//       numeric keys. This is an unspecified behavior. To be certain
		//       that arguments are parsed in the correct order, you can specify
		//       the "ordered" option. See the underscore key for how to set
		//       options.

		return "parsed value";

		// If the function returns undefined, the option will not be included.
	},

	// Options can be aliased by setting their type to the name of the option
	// they are aliasing. The resulting options map will never have the alias as
	// a key.

	"b": "bool",

	// Underscore is a reserved property and cannot be used to defined an argv
	// option name. It's used to pass options to the `parseopts()` function.

	_: {

		// You can use "ordered" to set the order of option parsing. This may be
		// necessary if your custom option function depends on some other option
		// being parsed first, you can set the order with an array of option
		// names. The following example ensures that the "regex" option will be
		// handled before the "custom" option. All options named in this array
		// will be sorted AFTER options that are NOT named.
		ordered: ["regex", "custom"],

		// You can use "required" to specify options that MUST be present. If an
		// option named in this array is not present, then an Error will be
		// thrown.
		required: ["custom"]

	}
});

You can also use the built-in option parsers as types if you don't want to use the JavaScript type constructors (Boolean, Array, etc).

parseopts.type.bool
parseopts.type.csv
parseopts.type.flag
parseopts.type.func
parseopts.type.json
parseopts.type.number
parseopts.type.regexp
parseopts.type.string

// These two options are the same type.
parseopts(argv, {
	"a": parseopts.type.bool,
	"b": Boolean
});

Optional/Default Values

Are not supported. If an option is not present in the argv array, then it will not be in the returned options map. If an option has a type of anything but true or [true], then a value is required and an error will be thrown if there is no value. An error will also be thrown if a true option has a value.

Single (`-`) vs Double (`--`) Hyphen Prefix

Options can be prefixed with a single hyphen (-) or a double hyphen (--).

If a single hyphen prefixes multiple characters, then each character will be interpreted as a seperate option. Only the last one can have a value.

These two examples are equivalent.

foo -abc
foo -a -b -c

A double hyphen prefixed argument is always a single option.

Values

Option values can be separated from the option name by a space or an equal = character.

These two examples are equivalent.

foo --bar baz
foo --bar=baz

If an option expects a value, and the option does not contain an equal (=) character, then the next argv item will be consumed as the value, even if it is prefixed with a hyphen (-).

This will result in option "bar" having the value "--baz".

foo --bar --baz

Bare Values

Any non-prefixed items in the argv array that are not consumed as values for prefixed options, will be added to the underscore (_) array in the returned options map.

foo bar baz

The options map for the above will be { '_': [ 'bar', 'baz' ] }.

Options parsing stops when a standalone double hyphen (--) is encountered. All remaining parameters will be added to the special underscore (_) array in the returned options map.

foo --bar=baz -- --other

The options map for the above will be { '_': [ '--other' ], 'bar': 'baz' }.

Underscore Key

In the definition object, underscore is used to set parsing options.

In the returned options map, the underscore (_) property is always defined and will always be an array. It will contain all the bare values in the argv array.

Other Notes

The first two values are always removed from the argv array that you pass to parseopts(). This is because Node's process.argv array begins with the node executable followed by the script being interpreted. Command line options start at index two.