Package Exports

raptor-args

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (raptor-args) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

raptor-args

A flexible and simple command line arguments parser that generates friendly help messages.

Installation

npm install raptor-args --save

Usage

// Create a parser:
var parser = require('raptor-args').createParser(options);
var parsed = parser.parse(argsArray);

// parsed will be an object with properties corresponding to provided arguments

Simple Example

Parse arguments provided by process.argv:

Given the following JavaScript code to parse the args:

// Create a parser and parse process.argv
require('raptor-args').createParser({
        '--foo -f': 'boolean',
        '--bar -b': 'string'
    })
    .parse();

And the following command:

node app.js --foo -b b

The output will be:

//Output:
{
    foo: true,
    bar: 'baz'
}

You can also parse your own array of arguments instead of using process.argv:

// Create a parser and parse provided args
require('raptor-args').createParser({
        '--foo -f': 'boolean',
        '--bar -b': 'string'
    })
    .parse(['--foo', '-b', 'baz']);

//Output:
{
    foo: true,
    bar: 'baz'
}

You can also be more descriptive and add usage, examples, error handlers and validation checks:

// Create a parser:
require('raptor-args')
    .createParser({
        '--help': {
            type: 'string',
            description: 'Show this help message'
        },
        '--foo -f': {
            type: 'string',
            description: 'Some helpful description for "foo"'
        },
        '--bar -b': {
            type: 'string',
            description: 'Some helpful description for "bar"'
        }
    })
    .usage('Usage: $0 [options]')
    .example(
        'First example',
        '$0 --foo hello')
    .example(
        'Second example',
        '$0 --foo hello --bar world')
    .validate(function(result) {
        if (result.help) {
            this.printUsage();
            process.exit(0);
        }

        if (!result.foo || !result.bar) {
            this.printUsage();
            console.log('--foo or --bar is required');
            process.exit(1);
        }
    })
    .onError(function(err) {
        this.printUsage();
        console.error(err);
        process.exit(1);
    })
    .parse();

Running the above program with the --help argument will produce the following output:

Usage: args [options]

Examples:

  First example:
     args --foo hello

  Second example:
     args --foo hello --bar world

Options:

  --help Show this help message [string]

--foo -f Some helpful description for "foo" [string]

--bar -b Some helpful description for "bar" [string]

Aliases

Aliases can be provided as space-separated values for an option:

// Create a parser:
var parser = require('raptor-args').createParser({
    '--foobar --foo -f': 'string', // "--foobar" has two aliases: "--foo" and "-f"
    '--hello -h': 'string',        // "--hello" has one alias: "-h"
});

parser.parse('--foo FOO -h HELLO'.split(' '));
// Output:
{
    foobar: 'FOO',
    hello: 'HELLO'
}

// **NOTE**: Only the first entry is used to determine the target property name--not the aliases.

Booleans

An argument value of "true" or "false" is automatically converted to the corresponding boolean type. If a argument is prefixed with "no-" then it will be set to false.

// Create a parser:
var parser = require('raptor-args').createParser({
    '--foo': 'boolean',
    '--bar': 'boolean'
});

parser.parse('--foo --no-bar'.split(' '));
// Output:
{
    foo: true,
    bar: false
}

Arrays

Any argument with multiple values will result in an Array value, but if you want to force an array for a single value then you can append "[]" to the option type as shown in the following sample code:

// Create a parser:
var parser = require('raptor-args').createParser({
    '--foo': 'string[]'
});

parser.parse('--foo a'.split(' '));
// Output:
{
    foo: ['a']
}

parser.parse('--foo a b c'.split(' '));
// Output:
{
    foo: ['a', 'b', 'c']
}

Wildcards

A parser will throw an error for unrecognized arguments unless wildcards are used as shown in the examples below.

// Create a parser:
var parser = require('raptor-args').createParser({
    '--foo -f *': 'string[]' // Any unrecognized argument at the beginning is an alias for "foo"
});

parser.parse('a b --foo c'.split(' '));
// Output:
{
    foo: ['a', 'b', 'c']
}

// Create a parser:
var parser = require('raptor-args').createParser({
    '*': null
});

parser.parse('a b --foo FOO --bar BAR'.split(' '));
// Output:
{
    '*': ['a', 'b'],
    foo: 'FOO',
    bar: 'BAR'
}

Complex Types

Square brackets can be used to begin and end complex types:

// Create a parser:
var parser = require('raptor-args').createParser({
    '--foo -f': 'boolean',
    '--plugins --plugin -p': {
        options: {
            '--module -m *': 'string',
            '-*': null
        }
    }
});

var parsed = parser.parse('--foo --plugins [ --module plugin1 -x -y ] [ plugin2 -z Hello ]'.split(' '));

// Output:
{
    foo: true,
    plugins: [
        {
            module: 'plugin1',
            x: true,
            y: true
        },
        {
            module: 'plugin2',
            z: 'Hello'
        }
    ]
}

Similar Projects

optimist - Popular but deprecated. Awkward API and not DRY as shown in the following comparison:

optimist:

var result = require('optimist')(args)
    .alias('h', 'help')
    .describe('h', 'Show this help message')
    .boolean('h')
    .alias('f', 'foo')
    .describe('f', 'Some helpful description for "foo"')
    .string('f')
    .alias('b', 'bar')
    .describe('b', 'Some helpful description for "bar"')
    .string('b')
    .argv;

raptor-args:

var result = require('raptor-args')
    .createParser({
        '--help':   { type: 'string', description: 'Show this help message' },
        '--foo -f': { type: 'string', description: 'Some helpful description for "foo"' },
        '--bar -b': { type: 'string', description: 'Some helpful description for "bar"' }
    })
    .parse();

yargs - A fork of optimist with documentation for those who speak Pirate.
minimist - Very few features (by design). Not DRY.

TODO

Support equal separator: --hello=world
Support number arg: -x256
Detect repeated declared options and throw an error
Add support for a default value

var parser = require('../')
    .createParser({
        '--foo -f': {
            type: 'boolean',
            defaultValue: true
        }
    });

Additional Reading

For module help, check out the test cases under the "test" directory.

License

MIT