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