Differential D22653 Diff 62759 node_modules/coa/README.md

Changeset View

Standalone View

node_modules/coa/README.md

This file was added.

		1		# Command-Option-Argument
		2
		3		Yet another parser for command line options.
		4
		5		[![NPM Status][npm-img]][npm]
		6		[![Travis Status][test-img]][travis]
		7		[![AppVeyor Status][appveyor-img]][appveyor]
		8		[![Coverage Status][coverage-img]][coveralls]
		9		[![Dependency Status][dependency-img]][david]
		10
		11		[npm]: https://www.npmjs.org/package/coa
		12		[npm-img]: https://img.shields.io/npm/v/coa.svg
		13		[travis]: https://travis-ci.org/veged/coa
		14		[test-img]: https://img.shields.io/travis/veged/coa.svg
		15		[appveyor]: https://ci.appveyor.com/project/zxqfox/coa
		16		[appveyor-img]: https://ci.appveyor.com/api/projects/status/github/veged/coa?svg=true
		17		[coveralls]: https://coveralls.io/r/veged/coa
		18		[coverage-img]: https://img.shields.io/coveralls/veged/coa.svg
		19		[david]: https://david-dm.org/veged/coa
		20		[dependency-img]: http://img.shields.io/david/veged/coa.svg
		21
		22		## What is it?
		23
		24		COA is a parser for command line options that aim to get maximum profit from formalization your program API.
		25		Once you write definition in terms of commands, options and arguments you automaticaly get:
		26
		27		* Command line help text
		28		* Program API for use COA-based programs as modules
		29		* Shell completion
		30
		31		### Other features
		32
		33		* Rich types for options and arguments, such as arrays, boolean flags and required
		34		* Commands can be async throught using promising (powered by [Q](https://github.com/kriskowal/q))
		35		* Easy submoduling some existing commands to new top-level one
		36		* Combined validation and complex parsing of values
		37
		38		### TODO
		39
		40		* Localization
		41		* Shell-mode
		42		* Configs
		43		* Aliases
		44		* Defaults
		45
		46		## Examples
		47
		48		````javascript
		49		require('coa').Cmd() // main (top level) command declaration
		50		.name(process.argv[1]) // set top level command name from program name
		51		.title('My awesome command line util') // title for use in text messages
		52		.helpful() // make command "helpful", i.e. options -h --help with usage message
		53		.opt() // add some option
		54		.name('version') // name for use in API
		55		.title('Version') // title for use in text messages
		56		.short('v') // short key: -v
		57		.long('version') // long key: --version
		58		.flag() // for options without value
		59		.act(function(opts) { // add action for option
		60		// return message as result of action
		61		return JSON.parse(require('fs').readFileSync(__dirname + '/package.json'))
		62		.version;
		63		})
		64		.end() // end option chain and return to main command
		65		.cmd().name('subcommand').apply(require('./subcommand').COA).end() // load subcommand from module
		66		.cmd() // inplace subcommand declaration
		67		.name('othercommand').title('Awesome other subcommand').helpful()
		68		.opt()
		69		.name('input').title('input file, required')
		70		.short('i').long('input')
		71		.val(function(v) { // validator function, also for translate simple values
		72		return require('fs').createReadStream(v) })
		73		.req() // make option required
		74		.end() // end option chain and return to command
		75		.end() // end subcommand chain and return to parent command
		76		.run(process.argv.slice(2)); // parse and run on process.argv
		77		````
		78
		79		````javascript
		80		// subcommand.js
		81		exports.COA = function() {
		82		this
		83		.title('Awesome subcommand').helpful()
		84		.opt()
		85		.name('output').title('output file')
		86		.short('o').long('output')
		87		.output() // use default preset for "output" option declaration
		88		.end()
		89		};
		90		````
		91
		92		## API reference
		93
		94		### Cmd
		95		Command is a top level entity. Commands may have options and arguments.
		96
		97		#### Cmd.api
		98		Returns object containing all its subcommands as methods to use from other programs.<br>
		99		@returns {Object}
		100
		101		#### Cmd.name
		102		Set a canonical command identifier to be used anywhere in the API.<br>
		103		@param String `_name` command name<br>
		104		@returns COA.Cmd `this` instance (for chainability)
		105
		106		#### Cmd.title
		107		Set a long description for command to be used anywhere in text messages.<br>
		108		@param String `_title` command title<br>
		109		@returns COA.Cmd `this` instance (for chainability)
		110
		111		#### Cmd.cmd
		112		Create new or add existing subcommand for current command.<br>
		113		@param COA.Cmd `[cmd]` existing command instance<br>
		114		@returns COA.Cmd new or added subcommand instance
		115
		116		#### Cmd.opt
		117		Create option for current command.<br>
		118		@returns COA.Opt `new` option instance
		119
		120		#### Cmd.arg
		121		Create argument for current command.<br>
		122		@returns COA.Opt `new` argument instance
		123
		124		#### Cmd.act
		125		Add (or set) action for current command.<br>
		126		@param Function `act` action function,
		127		invoked in the context of command instance
		128		and has the parameters:<br>
		129		- Object `opts` parsed options<br>
		130		- Array `args` parsed arguments<br>
		131		- Object `res` actions result accumulator<br>
		132		It can return rejected promise by Cmd.reject (in case of error)
		133		or any other value treated as result.<br>
		134		@param {Boolean} [force=false] flag for set action instead add to existings<br>
		135		@returns COA.Cmd `this` instance (for chainability)
		136
		137		#### Cmd.apply
		138		Apply function with arguments in context of command instance.<br>
		139		@param Function `fn`<br>
		140		@param Array `args`<br>
		141		@returns COA.Cmd `this` instance (for chainability)
		142
		143		#### Cmd.comp
		144		Set custom additional completion for current command.<br>
		145		@param Function `fn` completion generation function,
		146		invoked in the context of command instance.
		147		Accepts parameters:<br>
		148		- Object `opts` completion options<br>
		149		It can return promise or any other value treated as result.<br>
		150		@returns COA.Cmd `this` instance (for chainability)
		151
		152		#### Cmd.helpful
		153		Make command "helpful", i.e. add -h --help flags for print usage.<br>
		154		@returns COA.Cmd `this` instance (for chainability)
		155
		156		#### Cmd.completable
		157		Adds shell completion to command, adds "completion" subcommand, that makes all the magic.<br>
		158		Must be called only on root command.<br>
		159		@returns COA.Cmd `this` instance (for chainability)
		160
		161		#### Cmd.usage
		162		Build full usage text for current command instance.<br>
		163		@returns String `usage` text
		164
		165		#### Cmd.run
		166		Parse arguments from simple format like NodeJS process.argv
		167		and run ahead current program, i.e. call process.exit when all actions done.<br>
		168		@param Array `argv`<br>
		169		@returns COA.Cmd `this` instance (for chainability)
		170
		171		#### Cmd.invoke
		172		Invoke specified (or current) command using provided options and arguments.<br>
		173		@param String\|Array `cmds` subcommand to invoke (optional)<br>
		174		@param Object `opts` command options (optional)<br>
		175		@param Object `args` command arguments (optional)<br>
		176		@returns Q.Promise
		177
		178		#### Cmd.reject
		179		Return reject of actions results promise.<br>
		180		Use in .act() for return with error.<br>
		181		@param Object `reason` reject reason<br>
		182		You can customize toString() method and exitCode property
		183		of reason object.<br>
		184		@returns Q.promise rejected promise
		185
		186		#### Cmd.end
		187		Finish chain for current subcommand and return parent command instance.<br>
		188		@returns COA.Cmd `parent` command
		189
		190		### Opt
		191		Option is a named entity. Options may have short and long keys for use from command line.<br>
		192		@namespace<br>
		193		@class Presents option
		194
		195		#### Opt.name
		196		Set a canonical option identifier to be used anywhere in the API.<br>
		197		@param String `_name` option name<br>
		198		@returns COA.Opt `this` instance (for chainability)
		199
		200		#### Opt.title
		201		Set a long description for option to be used anywhere in text messages.<br>
		202		@param String `_title` option title<br>
		203		@returns COA.Opt `this` instance (for chainability)
		204
		205		#### Opt.short
		206		Set a short key for option to be used with one hyphen from command line.<br>
		207		@param String `_short`<br>
		208		@returns COA.Opt `this` instance (for chainability)
		209
		210		#### Opt.long
		211		Set a short key for option to be used with double hyphens from command line.<br>
		212		@param String `_long`<br>
		213		@returns COA.Opt `this` instance (for chainability)
		214
		215		#### Opt.flag
		216		Make an option boolean, i.e. option without value.<br>
		217		@returns COA.Opt `this` instance (for chainability)
		218
		219		#### Opt.arr
		220		Makes an option accepts multiple values.<br>
		221		Otherwise, the value will be used by the latter passed.<br>
		222		@returns COA.Opt `this` instance (for chainability)
		223
		224		#### Opt.req
		225		Makes an option req.<br>
		226		@returns COA.Opt `this` instance (for chainability)
		227
		228		#### Opt.only
		229		Makes an option to act as a command,
		230		i.e. program will exit just after option action.<br>
		231		@returns COA.Opt `this` instance (for chainability)
		232
		233		#### Opt.val
		234		Set a validation (or value) function for argument.<br>
		235		Value from command line passes through before becoming available from API.<br>
		236		Using for validation and convertion simple types to any values.<br>
		237		@param Function `_val` validating function,
		238		invoked in the context of option instance
		239		and has one parameter with value from command line<br>
		240		@returns COA.Opt `this` instance (for chainability)
		241
		242		#### Opt.def
		243		Set a default value for option.
		244		Default value passed through validation function as ordinary value.<br>
		245		@param Object `_def`<br>
		246		@returns COA.Opt `this` instance (for chainability)
		247
		248		#### Opt.input
		249		Make option value inputting stream.
		250		It's add useful validation and shortcut for STDIN.
		251		@returns {COA.Opt} `this` instance (for chainability)
		252
		253		#### Opt.output
		254		Make option value outputing stream.<br>
		255		It's add useful validation and shortcut for STDOUT.<br>
		256		@returns COA.Opt `this` instance (for chainability)
		257
		258		#### Opt.act
		259		Add action for current option command.
		260		This action is performed if the current option
		261		is present in parsed options (with any value).<br>
		262		@param Function `act` action function,
		263		invoked in the context of command instance
		264		and has the parameters:<br>
		265		- Object `opts` parsed options<br>
		266		- Array `args` parsed arguments<br>
		267		- Object `res` actions result accumulator<br>
		268		It can return rejected promise by Cmd.reject (in case of error)
		269		or any other value treated as result.<br>
		270		@returns COA.Opt `this` instance (for chainability)
		271
		272		#### Opt.comp
		273		Set custom additional completion for current option.<br>
		274		@param Function `fn` completion generation function,
		275		invoked in the context of command instance.
		276		Accepts parameters:<br>
		277		- Object `opts` completion options<br>
		278		It can return promise or any other value treated as result.<br>
		279		@returns COA.Opt `this` instance (for chainability)
		280
		281		#### Opt.end
		282		Finish chain for current option and return parent command instance.<br>
		283		@returns COA.Cmd `parent` command
		284
		285
		286		### Arg
		287		Argument is a unnamed entity.<br>
		288		From command line arguments passed as list of unnamed values.
		289
		290		#### Arg.name
		291		Set a canonical argument identifier to be used anywhere in text messages.<br>
		292		@param String `_name` argument name<br>
		293		@returns COA.Arg `this` instance (for chainability)
		294
		295		#### Arg.title
		296		Set a long description for argument to be used anywhere in text messages.<br>
		297		@param String `_title` argument title<br>
		298		@returns COA.Arg `this` instance (for chainability)
		299
		300		#### Arg.arr
		301		Makes an argument accepts multiple values.<br>
		302		Otherwise, the value will be used by the latter passed.<br>
		303		@returns COA.Arg `this` instance (for chainability)
		304
		305		#### Arg.req
		306		Makes an argument req.<br>
		307		@returns COA.Arg `this` instance (for chainability)
		308
		309		#### Arg.val
		310		Set a validation (or value) function for argument.<br>
		311		Value from command line passes through before becoming available from API.<br>
		312		Using for validation and convertion simple types to any values.<br>
		313		@param Function `_val` validating function,
		314		invoked in the context of argument instance
		315		and has one parameter with value from command line<br>
		316		@returns COA.Arg `this` instance (for chainability)
		317
		318		#### Arg.def
		319		Set a default value for argument.
		320		Default value passed through validation function as ordinary value.<br>
		321		@param Object `_def`<br>
		322		@returns COA.Arg `this` instance (for chainability)
		323
		324		#### Arg.output
		325		Make argument value outputing stream.<br>
		326		It's add useful validation and shortcut for STDOUT.<br>
		327		@returns COA.Arg `this` instance (for chainability)
		328
		329		#### Arg.comp
		330		Set custom additional completion for current argument.<br>
		331		@param Function `fn` completion generation function,
		332		invoked in the context of command instance.
		333		Accepts parameters:<br>
		334		- Object `opts` completion options<br>
		335		It can return promise or any other value treated as result.<br>
		336		@returns COA.Arg `this` instance (for chainability)
		337
		338		#### Arg.end
		339		Finish chain for current option and return parent command instance.<br>
		340		@returns COA.Cmd `parent` command