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