Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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