parseopt
Parseopt is a command line optionparser loosely inspired by Python's optparse module. This module was written for node.js but should work with any other JavaScript framework. Only when some certain parameters are not provided, parseopt uses node.js specific code in order to lookup meaningful defaults.
Used node.js API:
process.argv
: array of stringsprocess.stdout
: object with awrite
method that accepts a string argumentprocess.exit
: method that accepts a number argument
See the demo folder the end of this file for example usage.
API Reference
Option Definition
Option definitions are objects that specify an option. You use them to specify the name(s), type and severall parameters of an option.
Option types:
float
integer
string
boolean
object
option
enum
flag
record
custom
Option definition object:
{
// Only when passed to the OptionParser constructor:
name: string or array
names: string or array, alias of name
Only one of both may be used at the same time.
Names can be long options (e.g. '--foo') and short options
(e.g. '-f'). The first name is used to identify the option.
Names musst be unique and may not contain '='.
Short options may be combined when passed to a program. E.g.
the options '-f' and '-b' can be combined to '-fb'. Only one
of these combined options may require an argument.
Short options are separated from their arguments by space,
long options by '='. If a long option requires an argument
and none is passed using '=' it also uses the next command
line argument as it's argument (like short options).
If '--' is encountered all remaining arguments are treated as
arguments and not as options.
// General fields:
target: string, per deflault inferred from first name
This defines the name used in the returned options object.
Multiple options may have the same target.
default: any, default: undefined
The default value associated with a certain target and is
overwritten by each new option with the same target.
type: string, default: 'string', see below
required: boolean, default: false
redefinable: boolean, default: true
help: string, optional
details: array, optional
short list of details shown in braces after the option name
e.g. integer type options add 'base: '+base if base !== undefined
metavar: string or array, per default inferred from type
onOption: function (value) -> boolean, optional
Returning true cancels any further option parsing
and the parse() method returns null.
// Type: string (alias: str)
// Type: boolean (alias: bool)
// Type: object (alias: obj)
// Type: integer (alias: int)
min: integer, optional
max: integer, optional
NaN: boolean, default: false
base: integer, optional
// Type: float (alias: number)
min: float, optional
max: float, optional
NaN: boolean, default: false
// Type: flag
value: boolean, default: true
default: boolean, default: false
// Type: option
value: any, per default inferred from first name
// Type: enum
ignoreCase: boolean, default: true
values: array of possible values or object where the user enters the
property name of the object and you get the value of the property
// Type: record
create: function () -> object, default: Array
args: array of type definitions (type part of option definitions)
// Type: custom
argc: integer, default: -1
Number of required arguments.
-1 means one optional argument.
parse: function (string, ...) -> value
stringify: function (value) -> string, optional
}
float
Type: Arguments: 1
Alias: number
Parse a float
option argument. You can optionally specify min
and max
parameters to the option definition in order to limit the range of allowed
values. Using the boolean NaN
parameter it can be controlled if NaN
values are allowed (default: false
).
Example:
parser.add(['-n','-d','--float'], {
type: 'float',
min: 0
});
integer
Type: Arguments: 1
Alias: int
Parse an integer
option argument. You can optionally specify min
and max
parameters to the option definition in order to limit the range of allowed
values. Using the boolean NaN
parameter it can be controlled if NaN
values are allowed (default: false
). The base
parameter controls the
base of the parsed number. Per default integers are parsed like JavaScript
integer literals, meaning a 0x
prefix specifies a hexadecimal number, a
0
prefix an octal number and otherwise it is interpreted as a decimal number.
Example:
parser.add('--int32', {
type: 'integer',
min: -2147483648,
max: 2147483647,
metavar: 'INT32'
});
string
Type: Arguments: 1
Alias: str
This is the default type. It doesn't do any parsing but just passes through the string option argument.
Example:
parser.add('--foo', {type: 'string'});
boolean
Type: Arguments: 1
Alias: bool
Parse a boolean
option argument.
Values accepted as true
(case is ignored):
true
on
1
yes
Values accepted as false
(case is ignored):
false
off
0
no
Example:
parser.add('--bar', {type: 'boolean'});
object
Type: Arguments: 1
Alias: obj
Parse option argument as JSON string.
Example:
parser.add('--obj', {
type: 'object',
default: {
foo: 'bar',
baz: [23, 42]
}
});
enum
Type: Arguments: 1
With this option type you can define a list of option values
as the allowed
option arguments. The values
parameter can either be an array of strings or
a object, where the property names are used as the values for the allowed
option arguments. The value stored to the parsed parameter object will be the
according property value. The boolean ignoreCase
parameter specifies whether
the case of the option argument is ignored (default: true
).
Example:
parser.add('--enum1', {
type: 'enum',
values: ['foo', 'bar', 'baz']
});
parser.add('--enum2', {
type: 'enum',
values: {
foo: 'FOO',
bar: [23, 42],
baz: null
}
});
option
Type: Arguments: 0
With the option
type you can specify an option with a fixed value. It makes
most sense if you have several options without argument that write the same
target
.
See also: flag
Example:
parser.add('--opt1', {
type: 'option',
target: 'what',
value: 555
});
flag
Type: Arguments: 0-1
Like option
but only for boolean values. If no option argument is provided
the value specified by the value
parameter is used.
Example:
parser.add('--use-something', {type: 'flag'});
record
Type: Arguments: *
A record
option accepts several option arguments. How many and which types
is specified through the args
parameter. This parameter accepts an array of
option definitions (some parameters of these option definitions are ignored:
name
, default
, required
, redefinable
, help
, details
, onOption
).
The type ot the record itself can be provided through the create
parameter
(function, default: Array).
Example:
parser.add('--record', {
type: 'record',
default: ['bla', [10, 'bleh']],
args: [
{type: 'string'},
{type: 'record', args: [
{type: 'integer'},
{type: 'string'},
]}
]
});
parser.add('--named', {
type: 'record',
create: Object,
default: {a: 0.5, b: 300, c: 'bla'},
args: [
{type: 'float', target: 'a'},
{type: 'integer', target: 'b'},
{type: 'string', target: 'c'}
]});
custom
Type: Arguments: *
Example:
parser.add('--b64', {
type: 'custom',
argc: 1,
metavar: 'BASE64-STRING',
parse: function (s) {
return new Buffer(s, 'base64');
},
stringify: function (buffer) {
return buffer.toString('base64');
},
help: 'Pass binary data as a base64 encoded string.'
});
OptionParser
Constructor
Arguments:
params
: object, optional
params
{
minargs: integer, optional
maxargs: integer, optional
program: string, per default inferred from process.argv
strings: object, optional
Table of strings used in the output. See below.
options: array, optional
Array of option definitions. See below.
}
strings
{
help: string, default: 'No help available for this option.'
usage: string, default: 'Usage'
options: string, default: 'OPTIONS'
arguments: string, default: 'ARGUMENTS'
required: string, default: 'required'
default: string, default: 'default'
base: string, default: 'base'
metavars: object, optional
Table of default metavar names per type.
Per default the type name in capital letters or derived
from the possible values.
}
Properties
Don't modifiy the properties unless you really know what you are doing.
optionsPerName
Type: Object
Map of option definitions. Option definitions may occur multiple times when there are name aliases.
options
Type: Array
Array of option definitions.
defaultValues
Type: Object
Map of default values.
Methods
parse
Arguments:
args
: array of strings, default:process.argv
add
Arguments:
names
: string or array of strings, optionaloptdef
: option definition, optional
error
Arguments:
msg
: stringout
:WriteStream
, default:process.stdout
usage
Arguments:
help
: stringout
:WriteStream
, default:process.stdout