node-getopt/index.html

featured command line args parser

<h1>node-getopt</h1>

<p>Featured command line parser.</p>

<h2>Basic Usage</h2>

<p><strong>Parse Commandline</strong></p>

<p>code: oneline.js</p>

<pre><code>// node-getopt oneline example.
opt = require('node-getopt').create([
  ['s' , ''                    , 'short option.'],
  [''  , 'long'                , 'long option.'],
  ['S' , 'short-with-arg=ARG'  , 'option with argument'],
  ['L' , 'long-with-arg=ARG'   , 'long option with argument'],
  [''  , 'color[=COLOR]'       , 'COLOR is optional'],
  ['m' , 'multi-with-arg=ARG+' , 'multiple option with argument'],
  [''  , 'no-comment'],
  ['h' , 'help'                , 'display this help'],
  ['v' , 'version'             , 'show version']
])              // create Getopt instance
.bindHelp()     // bind option 'help' to default action
.parseSystem(); // parse command line

console.info(opt);
</code></pre>

<p><code>$ node oneline.js  foo -s --long-with-arg bar -m a -m b -- --others</code></p>

<pre><code>{ argv: [ 'foo', '--others' ],
  options:
   { s: true,
     'long-with-arg': 'bar',
     'multi-with-arg': [ 'a', 'b' ] } }

$ node oneline.js -h
Usage: node oneline.js

  -s                         short option.
      --long                 long option.
  -S, --short-with-arg=ARG   option with argument
  -L, --long-with-arg=ARG    long option with argument
      --color[=COLOR]        COLOR is optional
  -m, --multi-with-arg=ARG+  multiple option with argument
      --no-comment
  -h, --help                 display this help
  -v, --version              show version
</code></pre>

<p>code: simple.js</p>

<pre><code>// examples/simple.js
// argv parse
Getopt = require('node-getopt');

// Getopt arguments options
//   '=':   has argument
//   '[=]': has argument but optional
//   '+':   multiple option supported
getopt = new Getopt([
  ['s' , ''],
  ['L' , '='],
  ['m' , '=+'],
  [''  , 'color[=]'],
  ['h' , 'help']
]);

// process.argv needs slice(2) for it starts with 'node' and 'script name'
// parseSystem is alias  of parse(process.argv.slice(2))
// opt = getopt.parseSystem();
opt = getopt.parse(process.argv.slice(2));
console.info(opt);
</code></pre>

<p><code>$ node simple.js foo -s --long-with-arg bar -m a -m b -- --others</code></p>

<pre><code>{ argv: [ 'foo', '--others' ],
  options: { s: true, 'long-with-arg': 'bar', m: [ 'a', 'b' ] } }
</code></pre>

<p><strong>Work with help</strong></p>

<p>code: help.js</p>

<pre><code>// examples/help.js
// Works with help
Getopt = require('node-getopt');

getopt = new Getopt([
  ['s' , ''                    , 'short option.'],
  [''  , 'long'                , 'long option.'],
  ['S' , 'short-with-arg=ARG'  , 'option with argument'],
  ['L' , 'long-with-arg=ARG'   , 'long option with argument'],
  [''  , 'color[=COLOR]'       , 'COLOR is optional'],
  ['m' , 'multi-with-arg=ARG+' , 'multiple option with argument'],
  [''  , 'no-comment'],
  ['h' , 'help'                , 'display this help']
]);

// Use custom help template instead of default help
// [[OPTIONS]] is the placeholder for options list
getopt.setHelp(
  "Usage: node help.js [OPTION]\n" +
  "node-getopt help demo.\n" +
  "\n" +
  "[[OPTIONS]]\n" +
  "\n" +
  "Installation: npm install node-getopt\n" +
  "Respository:  https://github.com/jiangmiao/node-getopt"
);

getopt.showHelp();
</code></pre>

<p><code>$ node examples/help.js</code></p>

<pre><code>Usage: node help.js [OPTION]
node-getopt help demo.

  -s                         short option.
      --long                 long option.
  -S, --short-with-arg=ARG   option with argument
  -L, --long-with-arg=ARG    long option with argument
      --color[=COLOR]        COLOR is optional
  -m, --multi-with-arg=ARG+  multiple option with argument
      --no-comment
  -h, --help                 display this help

Installation: npm install node-getopt
Respository:  https://github.com/jiangmiao/node-getopt
</code></pre>

<h2>Features</h2>

<p>short option name</p>

<pre><code>$ node simple.js -s
{ argv: [], options: { short: true } }

$ node simple.js -S foo
{ argv: [], options: { 'short-with-arg': 'foo' } }
</code></pre>

<p>long option name</p>

<pre><code>$ node simple.js --long
{ argv: [], options: { long: true } }

$ node simple.js --long-with-arg foo
{ argv: [], options: { 'long-with-arg': 'foo' } }
</code></pre>

<p>argument required</p>

<pre><code>$ node simple.js --long-with-arg
ERROR: option long-with-arg need argument

$ node simple.js --long-with-arg foo
{ argv: [], options: { 'long-with-arg': 'foo' } }

$ node simple.js --long-with-arg=foo
{ argv: [], options: { 'long-with-arg': 'foo' } }
</code></pre>

<p>optional argument</p>

<pre><code>$ node simple.js --color
{ argv: [], options: { color: '' } }

$ node simple.js --color=foo
{ argv: [], options: { color: 'foo' } }

$ node simple.js --color foo
{ argv: [ 'foo' ], options: { color: '' }
</code></pre>

<p>chain option</p>

<pre><code>$ node simple.js -slS foo
{ argv: [],
  options: { short: true, long: true, 'short-with-arg': 'foo' } }
</code></pre>

<p>multi option supported</p>

<pre><code>$ node simple.js -m a -m b -m c
{ argv: [], options: { 'multi-with-arg': [ 'a', 'b', 'c' ] } }
</code></pre>

<p>text argv supported</p>

<pre><code>$ node simple.js foo -m a bar -m b baz -m c
{ argv: [ 'foo', 'bar', 'baz' ],
  options: { 'multi-with-arg': [ 'a', 'b', 'c' ] } }
</code></pre>

<p>keep text after --</p>

<pre><code>$ node simple.js -s -- -s
{ argv: [ '-s' ], options: { short: true } }
</code></pre>

<h2>References</h2>

<pre><code>require('node-getopt') returns class Getopt
</code></pre>

<p>Getopt Methods:</p>

<pre><code>constructor(Array options)
    options is a set of option. each option contains 3 fields.
    [short_name, long_name_with_definition, comment]
    Definition:
        * '=ARG':   has argument
        * '[=ARG]': has argument but optional
        * '+':      multiple option supported

        ARG can be replaced by any word.

Object parse(Array argv)
    parse argv

    Returns: {argv: '...', options: {...}}

Object parseSystem()
    alias of parse(process.argv.slice(2))


Getopt setHelp(String helpTemplate)
    Set help template. the placeholders will be replaced by getopt.

    Placeholders:
        * [[OPTIONS]] - The options list

    Returns: String

String getHelp()
    Get the help generated.

Getopt showHelp()
    console.info(getopt.getHelp());

Getopt bindHelp([String HELP])
    set help template to HELP if HELP is not empty.
    bind 'help' option to default action, show help and exit with 0.

Getpot on(String optionName, Function&lt;Array argv, Object options&gt; action)
    after parsing, trigger the action if optionName is found.
    the 'this' in action will be the instance of Getopt.

Getopt error(Function&lt;Error e&gt; callback)
    when parse failed callback will be trigger. default is display error message and exit with 1.
</code></pre>

<p>Getopt Static Methods:</p>

<pre><code>create(Array options)
    equals new Getopt(options)
</code></pre>

<p>Others:</p>

<pre><code>default help template:

    "Usage: node #{process.argv[1].match(/(?:.*[\/\\])?(.*)$/)[1]}\n\n[[OPTIONS]]\n"
</code></pre>

<h2>Remarks</h2>

<pre><code>v0.2.* is NOT compatible with v0.1.*
</code></pre>