FM / coa

/var/www/cobraambalaj/node_modules/coa

Name	Size	Mode	Actions
lib/	-	0755	rm
node_modules/	-	0755	rm
coa.d.ts	2164	0644	edit dl rm
index.js	35	0644	edit dl rm
LICENSE	1105	0644	edit dl rm
package.json	2451	0644	edit dl rm
README.md	12741	0644	edit dl rm
README.ru.md	22636	0644	edit dl rm

Edit: /var/www/cobraambalaj/node_modules/coa/README.md (12741B)

# Command-Option-Argument

Yet another parser for command line options.

[![NPM Status][npm-img]][npm]
[![Travis Status][test-img]][travis]
[![AppVeyor Status][appveyor-img]][appveyor]
[![Coverage Status][coverage-img]][coveralls]
[![Dependency Status][dependency-img]][david]

[npm]:          https://www.npmjs.org/package/coa
[npm-img]:      https://img.shields.io/npm/v/coa.svg
[travis]:       https://travis-ci.org/veged/coa
[test-img]:     https://img.shields.io/travis/veged/coa.svg
[appveyor]:     https://ci.appveyor.com/project/zxqfox/coa
[appveyor-img]: https://ci.appveyor.com/api/projects/status/github/veged/coa?svg=true
[coveralls]:    https://coveralls.io/r/veged/coa
[coverage-img]: https://img.shields.io/coveralls/veged/coa.svg
[david]:          https://david-dm.org/veged/coa
[dependency-img]: http://img.shields.io/david/veged/coa.svg

## 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

cmd: