node-getopt-long


node-getopt-long
================

Sophisticated command line argument passer

Version
=======

This documentation refers to node-getopt-long version 0.1.2

Synopsis
========

Quick examples:

``js
var options = require('node-getopt-long').options([
['flag|g', 'Flag for something'],
['
]);
`

Full detailed example:

`js
var options = require('node-getopt-long').options([
['arg|a', 'Simple true argument'],
['bar|b+', 'Numerically increasing argument'],
['foo|f++', 'Numerically argument (eg can use -f 123 or -123)'],
['can|c!', 'Negatable argument (allows --no-can to set to false)'],
['even|ev|e', 'Short, medium and long names'],
['first', 'Only long name'],
['int|i=i', 'Argument with an expected integer value'],
['float|f=d', 'Argument with an expected floating point value'],
['groups|g=s', 'Argument with an expected string value'],
['list|l=s@', 'Argument with an expected string value that can be specified multiple times'],
['object|o=s%', {
description: 'Argument with an expected key=value string, with other config options',
test: function(value, key, getoptLongObject, paramObject) {
if (value.match(/bad thing/)) {
// test failures must be thrown errors
throw '--object must not be a bad thing!';
}
// return value should be returned (useful for casting to ints, doubles etc)
return value;
},
on: function(value, getoptLongObject, paramObject) {
// do something --object is ecnountered there
}
}],
['fixed|F=s', {
description: 'This argument has a fixed set of values it can take',
test : ['yes', 'auto', 'no']
}]
], {
name : 'scriptname',
commandVersion: 0.1,
helpPrefix : 'Appears before arguments docs',
helpSuffix : 'Appears an the end of the help',
defaults : {
arg : false,
can : true,
int : 25
}
});

// or more verbosely
var getoptLong = require('node-getopt-long');

// get the configured getoptLong object
var getopt = getoptLong.configure([...], {...});

// Then process the arguments.
var options = getopt.process();

// use a passed parameter value
console.log('arg = ' + options.arg);
``

Description
===========

node-getopt-long in a command line option parser inspired by Perl's Getopt::Long option parser.

Exports
=======

(object) get
------------

The internal getoptLong object

(function) configure(parameters[, newOptions])
----------------------------------------------

Creates a new getoptLong object and configures it.

(function) options(parameters[, newOptions])
--------------------------------------------

Create a new getoptLong object, configures it and processes the command line options

Options
=======

Options are specified in one of two forms ['spec', 'description'] or
['sepc', { description: 'text'[, test: function() {} || , on: function () {}]}]
Every option generates an internal getoptLongParam object. Options specified
on the command line are checked in the specified order so if any conflicts
occur the first specified one wins.

$3

First the names, a pipe delimited list of names

eg

name|longer-name|n

The first name becomes the key to the returned options Object eg options.name

Then comes '!', '+', '++' or '='

* ! - negate - allows the user to specify they don't want that option (eg --no-name)
This sets the value for that object to false
* + - increment - Allows the value to be incremented by specifying the option
multiple times. E.g. for 'verbose|v+'

cmd -vvv

would set option.verbose to 3.
* ++ - Numerical arguments this allows for short hand numerical arguments eg if
the spec is 'foo|f++' then you can use "-5" on the command line to mean "--foo 5".
This should be done on only one argument, two or more use it the first argument
will win.
* = - assign a value - Allows the user to passing a value with a type n = integer,
s = string and f = float. E.g.
** string|s=s - requires a string value
** integer|i=i - requires an integer value
** float|f=f - requires a floating point number

Value parameters can also be Array or Object values, Array values can be
specified multiple times and object values are specified as key=value
pairs. Eg

* array|a=s@ - would allow 'cmd -a value --array value2
* object|o=s% - would allow 'cmd --object key=value -o key2=value2

$3

For the simple case option configuration can be passed just the description
as a string. If you want to specify more than the description you can pass
an Object. The supported keys of that object are:

* description - A description of the parameter for help
* paramName - A descriptive name or example value for help
* test - A function that can test a found value to see if it matches any
required conditions. The function is passed the following parameters
(value, key, getoptLongObject, paramObject). It must return the value,
this allows test to change the type of the value (eg convert a string to an
integer)
* on - Another function that is called after any tests and allows you to
perform other actions, no return value is required.

Configuration
=============

There are a number of configuration options supported

* name - Specify the commands name (if not specified the command name is dertermined by the how node is run
* commandVersion - Specify a version number for the command (also makes --version option appear)
* defaults - Object containing default values for parameters
* helpPrefix - Text to be put at the front of help message
* helpSuffix - Text to be put at the end of the help message
* subCommand - Flag, when set true processing of arguments will stop at the first non-parameter argument (this allows parameters to be passed on to sub-command)
* ignoreCase - TODO - choose weather arguments should be case sensitive or not (default is true)
* bundle - TODO - allow bundling of short arguments (default is true)