From 26105034da4fcce7ac883c899d781f016559310d Mon Sep 17 00:00:00 2001 From: ruki Date: Thu, 8 Nov 2018 00:38:48 +0800 Subject: switch to vuepress --- node_modules/coa/README.md | 322 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 322 insertions(+) create mode 100644 node_modules/coa/README.md (limited to 'node_modules/coa/README.md') diff --git a/node_modules/coa/README.md b/node_modules/coa/README.md new file mode 100644 index 00000000..fc1b0a9f --- /dev/null +++ b/node_modules/coa/README.md @@ -0,0 +1,322 @@ +# 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 -- cgit v1.2.3