simple-argparse

simple-argparse

Simple Argument parser for Command-line Applications

installation

⇒ npm install simple-argparse

basic usage

sample.js:

require("simple-argparse")
  .description("Application Description")
  .version("0.3.0")
  .option("s", "start", "starts application", startFunc)
  .epilog("See License at http://opensource.org/licenses/MIT")
  .parse();

function startFunc(host, port) {
  app.listen(port, host);
}

sample output:

⇒ node Sample.js
 Application Description

    H, help     show this help information
    s, start    starts application
    V, version  show version information

 See License at http://opensource.org/licenses/MIT

API

The module exports a new Parser instance, that can be used immediately. If you wish to create more parsers, you instead use the Parser constructor exported at .Parser:

var Parser = require("simple-argparse").Parser;
var myParser = new Parser();

While instantiating a parser, an output function may be registered with the parser other than the default console.log:

var myOtherParser = new Parser(function(output) {
  socket.emit("commandComplete", output);
});

A Parser has these methods:

• Parser#description([name:String,] description:String)

• name:(Optional) refers to the name of your Application

• description: provides a description of your Application

• Parser#version(version:String)

• version: provides version information of your Application. Defaults to "0.0.0"

• Parser#option([short:String ,] command:String, description:String [, optionFunction:Function])

• short: (Optional) short string, preferably one or two letter string that can be used in place of the command.

• command:

  • a string that will be typed by user to fire the command
  • any spaces will be replaced by hyphens

• description: help information regarding this command

• optionFunction:(Optional) See Parsing below for more information.

• Parser#defaultOption([optionFunction:Function])

  • optionFunction: (Optional) default function to run rather than show help information. See Parsing below for more information.

• Parser#prerun([hookFunction:Function])

  • hookFunction: (Optional) function to run before any of the option functions. This function can manipulate the arguments passed to the option functions by using the this context.

• Parser#epilog(epilog:String)

• epilog: a string that will appear at the bottom of the help information

• Parser#parse([arguments:String])

• arguments:(Optional)

  • a string representing commands as typed in command-line
  • if left out, process.argv will be used instead

• Parser#showHelp()

  • shows the help information
  • is done by passing all the necessary data as string to the registered output function

• Parser#showVersion()

  • similar to Parser#showHelp() but only supplies version information, registered with .version().

Parsing

All arguments parsed by .parse() are processed using minimist, and made available to the option functions as their this argument.

An option function refers to the function passed to .option. Options that are NOT perceived as options/flags by minimist are passed to the function as arguments.

The option name, as inputted by the user, is made available to the function at this._option.

Note that for the default option (.defaultOption(func)) no arguments can be passed to the option function. Also this._option will always equal "default".

Consider the following example:

parse.js:

require("simple-argparse")
  .version("0.0.0")
  .option("test", "run tests", function(suite) {
    console.log("this._option === %s", this._option);
    console.log("this.verbose === %s", this.verbose);
    console.log("suite === %s", suite);
  })
  .defaultOption(function() {
    console.log("this._option === %s", this._option);
    console.log("this.verbose === %s", this.verbose);
  })
  .parse();

Now running the above script from a terminal:

# default command
⇒ node parse.js
this._option === default
this.verbose === undefined

# default command
⇒ node parse.js --verbose
this._option === default
this.verbose === true

# test command
⇒ node parse.js test
this._option === test
this.verbose === undefined
suite === undefined

# test command
⇒ node parse.js test someSuite
this._option === test
this.verbose === undefined
suite === someSuite

# test command
⇒ node parse.js test someSuite --verbose
this._option === test
this.verbose === true
suite === someSuite

See minimist for more information on the parsing.

The option function is optional. If it is left out, the option will be ignored. This may be useful for commands not yet implemented.

license

The MIT License (MIT)

Copyright (c) 2014-2015 Forfuture LLC [e-mail]

Changelog

0.3.0 - 2015-08-05

Added:

• Allow shorter commands
• Allow pre-run hook