JarCastingCommand-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)
Arg.end
Finish chain for current option and return parent command instance.
@returns COA.Cmd parent command