<commit_before>A light, featureful and explicit option parsing library for node.js.

[Why another one? See below](#why). tl;dr: The others I've tried are one of
too loosey goosey (not explicit), too big/too many deps, or ill specified.
YMMV.

Follow <a href="https://twitter.com/intent/user?screen_name=trentmick" target="_blank">@trentmick</a>
for updates to node-dashdash.

# Install

    npm install dashdash


# Usage

    var dashdash = require('dashdash');

    // Specify the options. Minimally `name` (or `names`) and `type`
    // must be given for each.
    var options = [
        {
            // `names` or a single `name`. First element is the `opts.KEY`.
            names: ['help', 'h'],
            // See "Option config" below for types.
            type: 'bool',
            help: 'Print this help and exit.'
        }
    ];

    // Shortcut form. As called it infers `process.argv`. See below for
    // the longer form to use methods like `.help()` on the Parser object.
    var opts = dashdash.parse({options: options});

    console.log("opts:", opts);
    console.log("args:", opts._args);


# Longer Example

A more realistic [starter script "foo.js"](./examples/foo.js) is as follows.
This also shows using `parser.help()` for formatted option help.

    var dashdash = require('./lib/dashdash');

    var options = [
        {
            name: 'version',
            type: 'bool',
            help: 'Print tool version and exit.'
        },
        {
            names: ['help', 'h'],
            type: 'bool',
            help: 'Print this help and exit.'
        },
        {
            names: ['verbose', 'v'],
            type: 'arrayOfBool',
            help: 'Verbose output. Use multiple times for more verbose.'
        },
        {
            names: ['file', 'f'],
            type: 'string',
            help: 'File to process',
            helpArg: 'FILE'
        }
    ];

    var parser = dashdash.createParser({options: options});
    try {
        var opts = parser.parse(process.argv);
    } catch (e) {
        console.error('foo: error: %s', e.message);
        process.exit(1);
    }

    console.log("# opts:", opts);
    console.log("# args:", opts._args);

    // Use `parser.help()` for formatted options help.
    if (opts.help) {
        var help = parser.help({includeEnv: true}).trimRight();
        console.log('usage: node foo.js [OPTIONS]\n'
                    + 'options:\n'
                    + help);
        process.exit(0);
    }

    // ...


Some example output from this script (foo.js):

    $ node foo.js -h
    # opts: { help: true,
      _order: [ { name: 'help', value: true, from: 'argv' } ],
      _args: [] }
    # args: []
    usage: node foo.js [OPTIONS]
    options:
        --version             Print tool version and exit.
        -h, --help            Print this help and exit.
        -v, --verbose         Verbose output. Use multiple times for more verbose.
        -f FILE, --file=FILE  File to process

    $ node foo.js -v
    # opts: { verbose: [ true ],
      _order: [ { name: 'verbose', value: true, from: 'argv' } ],
      _args: [] }
    # args: []

    $ node foo.js --version arg1
    # opts: { version: true,
      _order: [ { name: 'version', value: true, from: 'argv' } ],
      _args: [ 'arg1' ] }
    # args: [ 'arg1' ]

    $ node foo.js -f bar.txt
    # opts: { file: 'bar.txt',
      _order: [ { name: 'file', value: 'bar.txt', from: 'argv' } ],
      _args: [] }
    # args: []

    $ node foo.js -vvv --file=blah
    # opts: { verbose: [ true, true, true ],
      file: 'blah',
      _order:
       [ { name: 'verbose', value: true, from: 'argv' },
         { name: 'verbose', value: true, from: 'argv' },
         { name: 'verbose', value: true, from: 'argv' },
         { name: 'file', value: 'blah', from: 'argv' } ],
      _args: [] }
    # args: []


# Environment variable integration

If you want to allow environment variables to specify options to your tool,
dashdash makes this easy. We can change the 'verbose' option in the example
above to include an 'env' field:

        {
            names: ['verbose', 'v'],
            type: 'arrayOfBool',
            env: 'FOO_VERBOSE',         // <--- add this line
            help: 'Verbose output. Use multiple times for more verbose.'
        },

then the **"FOO_VERBOSE" environment variable** can be used to set this
option:

    $ FOO_VERBOSE=1 node foo.js
    # opts: { verbose: [ true ],
      _order: [ { name: 'verbose', value: true, from: 'env' } ],
      _args: [] }
    # args: []

With the `includeEnv: true` config to `parser.help()` the environment
variable can also be included in **help output**:

    usage: node foo.js [OPTIONS]
    options:
        --version             Print tool version and exit.
        -h, --help            Print this help and exit.
        -v, --verbose         Verbose output. Use multiple times for more verbose.
                              Environment: FOO_VERBOSE=1
        -f FILE, --file=FILE  File to process


# Parser config

Parser construction (i.e. `dashdash.createParser(CONFIG)`) takes the
following fields:

- `options` (Array of option specs). Required. See the
  [Option specs](#option-specs) section below.

- `interspersed` (Boolean). Option. Default is true. If true this allows
  interspersed arguments and options. I.e.:

        node ./tool.js -v arg1 arg2 -h   # '-h' is after interspersed args

  Set it to false to have '-h' **not** get parsed as an option in the above
  example.


# Option specs

Each option spec in the `options` array must/can have the following fields:

- `name` (String) or `names` (Array). Required. These give the option name
  and aliases. The first name (if more than one given) is the key for the
  parsed `opts` object.
<commit_msg>tweak<commit_after>A light, featureful and explicit option parsing library for node.js.

[Why another one? See below](#why). tl;dr: The others I've tried are one of
too loosey goosey (not explicit), too big/too many deps, or ill specified.
YMMV.

Follow <a href="https://twitter.com/intent/user?screen_name=trentmick" target="_blank">@trentmick</a>
for updates to node-dashdash.

# Install

    npm install dashdash


# Usage

    var dashdash = require('dashdash');

    // Specify the options. Minimally `name` (or `names`) and `type`
    // must be given for each.
    var options = [
        {
            // `names` or a single `name`. First element is the `opts.KEY`.
            names: ['help', 'h'],
            // See "Option config" below for types.
            type: 'bool',
            help: 'Print this help and exit.'
        }
    ];

    // Shortcut form. As called it infers `process.argv`. See below for
    // the longer form to use methods like `.help()` on the Parser object.
    var opts = dashdash.parse({options: options});

    console.log("opts:", opts);
    console.log("args:", opts._args);


# Longer Example

A more realistic [starter script "foo.js"](./examples/foo.js) is as follows.
This also shows using `parser.help()` for formatted option help.

    var dashdash = require('./lib/dashdash');

    var options = [
        {
            name: 'version',
            type: 'bool',
            help: 'Print tool version and exit.'
        },
        {
            names: ['help', 'h'],
            type: 'bool',
            help: 'Print this help and exit.'
        },
        {
            names: ['verbose', 'v'],
            type: 'arrayOfBool',
            help: 'Verbose output. Use multiple times for more verbose.'
        },
        {
            names: ['file', 'f'],
            type: 'string',
            help: 'File to process',
            helpArg: 'FILE'
        }
    ];

    var parser = dashdash.createParser({options: options});
    try {
        var opts = parser.parse(process.argv);
    } catch (e) {
        console.error('foo: error: %s', e.message);
        process.exit(1);
    }

    console.log("# opts:", opts);
    console.log("# args:", opts._args);

    // Use `parser.help()` for formatted options help.
    if (opts.help) {
        var help = parser.help({includeEnv: true}).trimRight();
        console.log('usage: node foo.js [OPTIONS]\n'
                    + 'options:\n'
                    + help);
        process.exit(0);
    }

    // ...


Some example output from this script (foo.js):

    $ node foo.js -h
    # opts: { help: true,
      _order: [ { name: 'help', value: true, from: 'argv' } ],
      _args: [] }
    # args: []
    usage: node foo.js [OPTIONS]
    options:
        --version             Print tool version and exit.
        -h, --help            Print this help and exit.
        -v, --verbose         Verbose output. Use multiple times for more verbose.
        -f FILE, --file=FILE  File to process

    $ node foo.js -v
    # opts: { verbose: [ true ],
      _order: [ { name: 'verbose', value: true, from: 'argv' } ],
      _args: [] }
    # args: []

    $ node foo.js --version arg1
    # opts: { version: true,
      _order: [ { name: 'version', value: true, from: 'argv' } ],
      _args: [ 'arg1' ] }
    # args: [ 'arg1' ]

    $ node foo.js -f bar.txt
    # opts: { file: 'bar.txt',
      _order: [ { name: 'file', value: 'bar.txt', from: 'argv' } ],
      _args: [] }
    # args: []

    $ node foo.js -vvv --file=blah
    # opts: { verbose: [ true, true, true ],
      file: 'blah',
      _order:
       [ { name: 'verbose', value: true, from: 'argv' },
         { name: 'verbose', value: true, from: 'argv' },
         { name: 'verbose', value: true, from: 'argv' },
         { name: 'file', value: 'blah', from: 'argv' } ],
      _args: [] }
    # args: []


# Environment variable integration

If you want to allow environment variables to specify options to your tool,
dashdash makes this easy. We can change the 'verbose' option in the example
above to include an 'env' field:

        {
            names: ['verbose', 'v'],
            type: 'arrayOfBool',
            env: 'FOO_VERBOSE',         // <--- add this line
            help: 'Verbose output. Use multiple times for more verbose.'
        },

then the **"FOO_VERBOSE" environment variable** can be used to set this
option:

    $ FOO_VERBOSE=1 node foo.js
    # opts: { verbose: [ true ],
      _order: [ { name: 'verbose', value: true, from: 'env' } ],
      _args: [] }
    # args: []

With the `includeEnv: true` config to `parser.help()` the environment
variable can also be included in **help output**:

    usage: node foo.js [OPTIONS]
    options:
        --version             Print tool version and exit.
        -h, --help            Print this help and exit.
        -v, --verbose         Verbose output. Use multiple times for more verbose.
                              Environment: FOO_VERBOSE=1
        -f FILE, --file=FILE  File to process


# Parser config

Parser construction (i.e. `dashdash.createParser(CONFIG)`) takes the
following fields:

- `options` (Array of option specs). Required. See the
  [Option specs](#option-specs) section below.

- `interspersed` (Boolean). Option. Default is true. If true this allows
  interspersed arguments and options. I.e.:

        node ./tool.js -v arg1 arg2 -h   # '-h' is after interspersed args

  Set it to false to have '-h' **not** get parsed as an option in the above
  example.


# Option specs

Example using all fields:

    {
        names: ['file', 'f'],       // Required (or `name`).
        type: 'string',             // Required.
        env: 'MYTOOL_FILE',
        help: 'Config file to load before running "mytool"',
        helpArg: 'PATH',
        default: path.resolve(process.env.HOME, '.mytoolrc')
    }

Each option spec in the `options` array must/can have the following fields:

- `name` (String) or `names` (Array). Required. These give the option name
  and aliases. The first name (if more than one given) is the key for the
  parsed `opts` object.

{'fraction_non_alphanumeric': 0.1384809064204784, 'fraction_numerical': 0.0015107007973143096, 'mean_word_length': 2.037471322967117, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '34931', 'n_tokens_mistral': 3664, 'n_tokens_neox': 3553, 'n_words': 1270}