> For the complete documentation index, see [llms.txt](https://bryan-guner.gitbook.io/my-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bryan-guner.gitbook.io/my-docs/redux/repos/examples/real-world/node_modules/coa.md).

# Command-Option-Argument

Yet another parser for command line options.

[![NPM Status](https://img.shields.io/npm/v/coa.svg)](https://www.npmjs.org/package/coa) [![Travis Status](https://img.shields.io/travis/veged/coa.svg)](https://travis-ci.org/veged/coa) [![AppVeyor Status](https://ci.appveyor.com/api/projects/status/github/veged/coa?svg=true)](https://ci.appveyor.com/project/zxqfox/coa) [![Coverage Status](https://img.shields.io/coveralls/veged/coa.svg)](https://coveralls.io/r/veged/coa) [![Dependency Status](http://img.shields.io/david/veged/coa.svg)](https://david-dm.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