Command-Option-Argument

Yet another parser for command line options.

# What is it?

COA is a parser for command line options that aim to get maximum profit from formalization your program API. Once you write definition in terms of commands, options and arguments you automaticaly get:

- Command line help text
- Program API for use COA-based programs as modules
- Shell completion

## Other features

- Rich types for options and arguments, such as arrays, boolean flags and required
- Commands can be async throught using promising (powered by Q)
- Easy submoduling some existing commands to new top-level one
- Combined validation and complex parsing of values

## TODO

- Localization
- Shell-mode
- Configs
  - Aliases
  - Defaults

# Examples

require('coa').Cmd() // main (top level) command declaration
.name(process.argv[1]) // set top level command name from program name
.title('My awesome command line util') // title for use in text messages
.helpful() // make command "helpful", i.e. options -h --help with usage message
.opt() // add some option
.name('version') // name for use in API
.title('Version') // title for use in text messages
.short('v') // short key: -v
.long('version') // long key: --version
.flag() // for options without value
.act(function(opts) { // add action for option
// return message as result of action
return JSON.parse(require('fs').readFileSync(__dirname + '/package.json'))
.version;
})
.end() // end option chain and return to main command
.cmd().name('subcommand').apply(require('./subcommand').COA).end() // load subcommand from module
.cmd() // inplace subcommand declaration
.name('othercommand').title('Awesome other subcommand').helpful()
.opt()
.name('input').title('input file, required')
.short('i').long('input')
.val(function(v) { // validator function, also for translate simple values
return require('fs').createReadStream(v) })
.req() // make option required
.end() // end option chain and return to command
.end() // end subcommand chain and return to parent command
.run(process.argv.slice(2)); // parse and run on process.argv
// subcommand.js
exports.COA = function() {
this
.title('Awesome subcommand').helpful()
.opt()
.name('output').title('output file')
.short('o').long('output')
.output() // use default preset for "output" option declaration
.end()
};

# API reference

## Cmd

Command is a top level entity. Commands may have options and arguments.

### Cmd.api

Returns object containing all its subcommands as methods to use from other programs.

Returns
  *{Object}*

### Cmd.name

Set a canonical command identifier to be used anywhere in the API.

Parameters

  </strong> | String `_name` command name

Returns
  COA.Cmd `this` instance (for chainability)

### Cmd.title

Set a long description for command to be used anywhere in text messages.

Parameters

  </strong> | String `_title` command title

Returns
  COA.Cmd `this` instance (for chainability)

### Cmd.cmd

Create new or add existing subcommand for current command.

Parameters

  </strong> | COA.Cmd `[cmd]` existing command instance

Returns
  COA.Cmd new or added subcommand instance

### Cmd.opt

Create option for current command.

Returns
  COA.Opt `new` option instance

### Cmd.arg

Create argument for current command.

Returns
  COA.Opt `new` argument instance

### Cmd.act

Add (or set) action for current command.

Parameters

  </strong>

  Function `act` action function, invoked in the context of command instance and has the parameters:
  - Object `opts` parsed options
  - Array `args` parsed arguments
  - Object `res` actions result accumulator
    It can return rejected promise by Cmd.reject (in case of error) or any other value treated as result.

  </strong> | *{Boolean}* [force=false] flag for set action instead add to existings

Returns
  COA.Cmd `this` instance (for chainability)

### Cmd.apply

Apply function with arguments in context of command instance.

Parameters

  </strong> | Function `fn`
  </strong> | Array `args`

Returns
  COA.Cmd `this` instance (for chainability)

### Cmd.comp

Set custom additional completion for current command.

Parameters

  </strong>

  Function `fn` completion generation function, invoked in the context of command instance. Accepts parameters:
  - Object `opts` completion options
    It can return promise or any other value treated as result.

Returns
  COA.Cmd `this` instance (for chainability)

### Cmd.helpful

Make command "helpful", i.e. add -h –help flags for print usage.

Returns
  COA.Cmd `this` instance (for chainability)

### Cmd.completable

Adds shell completion to command, adds "completion" subcommand, that makes all the magic.
Must be called only on root command.

Returns
  COA.Cmd `this` instance (for chainability)

### Cmd.usage

Build full usage text for current command instance.

Returns
  String `usage` text

### Cmd.run

Parse arguments from simple format like NodeJS process.argv and run ahead current program, i.e. call process.exit when all actions done.

Parameters

  </strong> | Array `argv`

Returns
  COA.Cmd `this` instance (for chainability)

### Cmd.invoke

Invoke specified (or current) command using provided options and arguments.

Parameters

  </strong> | String|Array `cmds` subcommand to invoke (optional)
  </strong> | Object `opts` command options (optional)
  </strong> | Object `args` command arguments (optional)

Returns
  Q.Promise

### Cmd.reject

Return reject of actions results promise.
Use in .act() for return with error.

Parameters

  </strong> | Object `reason` reject reason You can customize toString() method and exitCode property of reason object.

Returns
  Q.promise rejected promise

### Cmd.end

Finish chain for current subcommand and return parent command instance.

Returns
  COA.Cmd `parent` command

## Opt

Option is a named entity. Options may have short and long keys for use from command line.