npm install parameters

Node parameters is sugar for parsing typical unix command line options.

• Standard and commands-based command lines (think git pull ...)
• Reversability: parse and stringify is bi-directional
• Auto-discovery: extract unregistered options
• Object literals: config and parsed results are serializable and human readable
• Routing: run dedicated functions or modules based on user commands
• Auto generated help
• Complete tests coverages plus samples

Usage

The parameters package is made available to your module with the declaration parameters = require('parameters');. The returned variable is a function expecting a definition object and returning the following functions:

• help (command[string:null])
  Returned a string with the complete help content or the content of a single command if the command argument is passed.
• parse (argv[array:process])
  Transform an array of arguments into a parameter object. If null or the native process object, the first two arguments (the node binary and the script file) are skipped.
• load (module[string])
  Internal function used to load modules, see the "load" option to pass a function or a module referencing the function.
• run (argv[array:process], args[obj]...)
  Similar to parse but also call the function or the module defined by the "run" option; first arguments are the arguments to parse, other arguments are simply passed to the run function or module as first arguments.
• stringify (params[obj], options[obj])
  Convert an object of parameters into an array of arguments. Possible options are "no_default".

Definition

The parameter definition is an object passed as an argument to the function exported by this package.

The root properties are:

• commands (object)
  Group the parameters into a specific command.
• load (function|string)
  Function or a module referencing the function to load modules, the default implementation ensure modules starting with './' are relative to process.cwd() and use require.main.require.
• main (object)
  Anything left which is not a parameter at the end of the arguments.
• options (object) Defined the expected main parameters.
• strict (boolean)
  Disable auto-discovery.

The properties for commands are:

• name (string)
  The command name.
• options (object) Defined the expected command parameters.

The properties for options are:

• default (anything)
  Default value if none is provided; always part of the object return by parse, part of the arguments returned by stringify unless the "no_default" option is set.
• main (object)
  Anything left which is not a parameter at the end of the arguments.
• name (string)
  The name of the option.
• one_of (array)
  A list of possible and accepted values.
• required (boolean)
  Whether or not this option must always be present.
• run (function|string)
  Execute a function or the function return by a module, provide the params object as first argument and pass the returned value.
• shortcut (char)
  Single character alias for the option name.
• type (string)
  The type used to cast between a string argument and a JS value, not all types share the same behavior. Accepted values are 'boolean', 'string', 'integer' and 'array'.

The properties for main are:

• name (string)
  The name of the main property.
• required (boolean)
  Whether or not the value must always be present.

Help usage

Call the help function and pass no argument to retrieve the global help and the name of a specific command.

Here's an example on how to integrate the help functionnality inside your code:

params = parameters(my_config).parse())
if( params.command === 'help' ){
  return console.log(parameters.help(params.subcommand));
}

This will satisfy a help command with or without an extra command such as myscript help and myscript help mycommand.

Standard command line example

command = parameters({
  name: 'server',
  description: 'Start a web server',
  options: [{
    name: 'host', shortcut: 'h', 
    description: 'Web server listen host'
  },{
    name: 'port', shortcut: 'p', type: 'integer', 
    description: 'Web server listen port'
  }]
});
// Print help
console.log( command.help() );
// Extract command arguments
command.parse(
  ['--host', '127.0.0.1', '-p', '80']
).should.eql({
  host: '127.0.0.1',
  port: 80
});
// Create a command
command.stringify({
  host: '127.0.0.1',
  port: 80
}).should.eql(
  ['--host', '127.0.0.1', '--port', '80']
);

Command-based command line example

command = parameters({
  name: 'server',
  description: 'Manage a web server',
  commands: [{
    name: 'start',
    description: 'Start a web server',
    options: [{
      name: 'host', shortcut: 'h', 
      description: 'Web server listen host'
    },{
      name: 'port', shortcut: 'p', type: 'integer', 
      description: 'Web server listen port'
    }]
  }]
});
// Print help
console.log( command.help() );
// Extract command arguments
command.parse(
  ['start', '--host', '127.0.0.1', '-p', '80']
).should.eql({
  command: 'start',
  host: '127.0.0.1',
  port: 80
});
// Create a command
command.stringify({
  command: 'start',
  host: '127.0.0.1',
  port: 80
}).should.eql(
  ['start', '--host', '127.0.0.1', '--port', '80']
);

Development

Tests are executed with mocha. To install it, simple run npm install, it will install mocha and its dependencies in your project "node_modules" directory.

To run the tests:

npm test

The tests run against the CoffeeScript source files.

To generate the JavaScript files:

make build

The test suite is run online with [Travis][travis] against the supported Node.js versions.

Contributors

• David Worms: https://github.com/wdavidw