Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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