Gecko [ unitednationsplay.com ]

Name	Size	Permission	Date
.nyc_output	[ DIR ]	drwxr-xr-x	2021-02-04 21:24
coverage	[ DIR ]	drwxr-xr-x	2021-02-04 21:24
lib	[ DIR ]	drwxr-xr-x	2021-02-04 21:24
src	[ DIR ]	drwxr-xr-x	2021-02-04 21:24
test	[ DIR ]	drwxr-xr-x	2021-02-04 21:24
tests	[ DIR ]	drwxr-xr-x	2021-02-04 21:24
.npmignore	70 B	-rw-r--r--	2017-07-05 13:46
.travis.yml	97 B	-rw-r--r--	2017-07-05 13:46
GNUmakefile	684 B	-rw-r--r--	2017-07-05 13:46
README.md	11.72 KB	-rw-r--r--	2017-07-05 13:46
README.ru.md	22.11 KB	-rw-r--r--	2017-02-10 18:52
index.js	68 B	-rw-r--r--	2017-07-05 13:46
package.json	1.86 KB	-rw-r--r--	2021-02-04 21:24
qq.js	547 B	-rw-r--r--	2017-06-10 18:04

Rename

# Command-Option-Argument
[![build status](https://secure.travis-ci.org/veged/coa.png)](http://travis-ci.org/veged/coa)

## 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](https://github.com/kriskowal/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

````javascript
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
````

````javascript
// 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. 
**@param** *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. 
**@param** *String* `_title` command title 
**@returns** *COA.Cmd* `this` instance (for chainability)

#### Cmd.cmd
Create new or add existing subcommand for current command. 
**@param** *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. 
**@param** *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. 
**@param** *{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. 
**@param** *Function* `fn` 
**@param** *Array* `args` 
**@returns** *COA.Cmd* `this` instance (for chainability)

#### Cmd.comp
Set custom additional completion for current command. 
**@param** *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. 
**@param** *Array* `argv` 
**@returns** *COA.Cmd* `this` instance (for chainability)

#### Cmd.invoke
Invoke specified (or current) command using provided options and arguments. 
**@param** *String|Array* `cmds` subcommand to invoke (optional) 
**@param** *Object* `opts` command options (optional) 
**@param** *Object* `args` command arguments (optional) 
**@returns** *Q.Promise*

#### Cmd.reject
Return reject of actions results promise. 
Use in .act() for return with error. 
**@param** *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. 
**@namespace** 
**@class** Presents option

#### Opt.name
Set a canonical option identifier to be used anywhere in the API. 
**@param** *String* `_name` option name 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.title
Set a long description for option to be used anywhere in text messages. 
**@param** *String* `_title` option title 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.short
Set a short key for option to be used with one hyphen from command line. 
**@param** *String* `_short` 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.long
Set a short key for option to be used with double hyphens from command line. 
**@param** *String* `_long` 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.flag
Make an option boolean, i.e. option without value. 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.arr
Makes an option accepts multiple values. 
Otherwise, the value will be used by the latter passed. 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.req
Makes an option req. 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.only
Makes an option to act as a command,
i.e. program will exit just after option action. 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.val
Set a validation (or value) function for argument. 
Value from command line passes through before becoming available from API. 
Using for validation and convertion simple types to any values. 
**@param** *Function* `_val` validating function,
 invoked in the context of option instance
 and has one parameter with value from command line 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.def
Set a default value for option.
Default value passed through validation function as ordinary value. 
**@param** *Object* `_def` 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.input
Make option value inputting stream.
It's add useful validation and shortcut for STDIN.
**@returns** *{COA.Opt}* `this` instance (for chainability)

#### Opt.output
Make option value outputing stream. 
It's add useful validation and shortcut for STDOUT. 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.act
Add action for current option command.
This action is performed if the current option
is present in parsed options (with any value). 
**@param** *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. 
**@returns** *COA.Opt* `this` instance (for chainability)

#### Opt.comp
Set custom additional completion for current option. 
**@param** *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.Opt* `this` instance (for chainability)

#### Opt.end
Finish chain for current option and return parent command instance. 
**@returns** *COA.Cmd* `parent` command

### Arg
Argument is a unnamed entity. 
From command line arguments passed as list of unnamed values.

#### Arg.name
Set a canonical argument identifier to be used anywhere in text messages. 
**@param** *String* `_name` argument name 
**@returns** *COA.Arg* `this` instance (for chainability)

#### Arg.title
Set a long description for argument to be used anywhere in text messages. 
**@param** *String* `_title` argument title 
**@returns** *COA.Arg* `this` instance (for chainability)

#### Arg.arr
Makes an argument accepts multiple values. 
Otherwise, the value will be used by the latter passed. 
**@returns** *COA.Arg* `this` instance (for chainability)

#### Arg.req
Makes an argument req. 
**@returns** *COA.Arg* `this` instance (for chainability)

#### Arg.val
Set a validation (or value) function for argument. 
Value from command line passes through before becoming available from API. 
Using for validation and convertion simple types to any values. 
**@param** *Function* `_val` validating function,
 invoked in the context of argument instance
 and has one parameter with value from command line 
**@returns** *COA.Arg* `this` instance (for chainability)

#### Arg.def
Set a default value for argument.
Default value passed through validation function as ordinary value. 
**@param** *Object* `_def` 
**@returns** *COA.Arg* `this` instance (for chainability)

#### Arg.output
Make argument value outputing stream. 
It's add useful validation and shortcut for STDOUT. 
**@returns** *COA.Arg* `this` instance (for chainability)

#### Arg.comp
Set custom additional completion for current argument. 
**@param** *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.Arg* `this` instance (for chainability)

#### Arg.end
Finish chain for current option and return parent command instance. 
**@returns** *COA.Cmd* `parent` command