Coa NPM | npm.io

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. @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)