Skip to content
This repository
Newer
Older
100644 252 lines (207 sloc) 8.989 kb
5ab69443 »
2011-07-20 Init
1 # Command-Option-Argument
2
3 COA is a yet another parser for command line options.
4 You can choose one of the [existing modules](https://github.com/joyent/node/wiki/modules#parsers-commandline),
5 or write your own like me.
6
7 ## Examples
8
9 ````javascript
36b57d17 »
2011-08-21 Add more comments to examples in README
10 require('coa').Cmd() // main (top level) command declaration
11 .name(process.argv[1]) // set top level command name from program name
12 .title('My awesome command line util') // title for use in text messages
13 .helpful() // make command "helpful", i.e. options -h --help with usage message
14 .opt() // add some option
15 .name('version') // name for use in API
16 .title('Version') // title for use in text messages
17 .short('v') // short key: -v
18 .long('version') // long key: --version
19 .type(Boolean) // type Boolean for options without value
20 .act(function(opts) { // add action for option
21 this.exit( // exit program with code 0 and text message
22 JSON.parse(require('fs').readFileSync(__dirname + '/package.json'))
23 .version);
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
24 })
36b57d17 »
2011-08-21 Add more comments to examples in README
25 .end() // end option chain and return to main command
85118a68 »
2011-08-21 Edited README.md via GitHub
26 .cmd().name('subcommand').apply(require('./subcommand').COA).end() // load subcommand from module
5ab69443 »
2011-07-20 Init
27 .cmd() // inplace subcommand declaration
36b57d17 »
2011-08-21 Add more comments to examples in README
28 .name('othercommand').title('Awesome other subcommand').helpful()
5ab69443 »
2011-07-20 Init
29 .opt()
36b57d17 »
2011-08-21 Add more comments to examples in README
30 .name('input').title('input file, required')
31 .short('i').long('input')
bb38ef51 »
2011-08-30 Rename function for validation and processing value: validation() -> …
32 .val(function(v) { // validator function, also for translate simple values
36b57d17 »
2011-08-21 Add more comments to examples in README
33 return require('fs').createReadStream(v) })
34 .required() // make option required
35 .end() // end option chain and return to command
36 .end() // end subcommand chain and return to parent command
37 .parse(process.argv.slice(2)); // parse and run on process.argv
5ab69443 »
2011-07-20 Init
38 ````
39
40 ````javascript
41 // subcommand.js
42 exports.COA = function() {
43 this
44 .title('Awesome subcommand').helpful()
45 .opt()
36b57d17 »
2011-08-21 Add more comments to examples in README
46 .name('output').title('output file')
47 .short('o').long('output')
5ab69443 »
2011-07-20 Init
48 .output() // use default preset for "output" option declaration
49 .end()
50 };
51 ````
1dc5a3df »
2011-08-19 Add TODO
52
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
53 ## API
54
55 ### Cmd
70e0208a »
2011-08-21 README.md formatting fixes
56 Command is a top level entity. Commands may have options and arguments.
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
57
58 #### Cmd.name
59 Set a canonical command identifier to be used anywhere in the API.<br>
60 **@param** *String* `_name` command name<br>
70e0208a »
2011-08-21 README.md formatting fixes
61 **@returns** *COA.Cmd* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
62
63 #### Cmd.title
64 Set a long description for command to be used anywhere in text messages.<br>
65 **@param** *String* `_title` command title<br>
70e0208a »
2011-08-21 README.md formatting fixes
66 **@returns** *COA.Cmd* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
67
68 #### Cmd.cmd
69 Create new subcommand for current command.<br>
70e0208a »
2011-08-21 README.md formatting fixes
70 **@returns** *COA.Cmd* `new` subcommand instance
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
71
72 #### Cmd.opt
73 Create option for current command.<br>
70e0208a »
2011-08-21 README.md formatting fixes
74 **@returns** *COA.Opt* `new` option instance
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
75
76 #### Cmd.arg
77 Create argument for current command.<br>
70e0208a »
2011-08-21 README.md formatting fixes
78 **@returns** *COA.Opt* `new` argument instance
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
79
80 #### Cmd.act
81 Add (or set) action for current command.<br>
70e0208a »
2011-08-21 README.md formatting fixes
82 **@param** *Function* `act` action function,
83 invoked in the context of command instance
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
84 and has the parameters:<br>
85 - *Object* `opts` parsed options<br>
86 - *Array* `args` parsed arguments<br>
87 **@param** *{Boolean}* [force=false] flag for set action instead add to existings<br>
70e0208a »
2011-08-21 README.md formatting fixes
88 **@returns** *COA.Cmd* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
89
90 #### Cmd.apply
91 Apply function with arguments in context of command instance.<br>
92 **@param** *Function* `fn`<br>
93 **@param** *Array* `args`<br>
70e0208a »
2011-08-21 README.md formatting fixes
94 **@returns** *COA.Cmd* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
95
96 #### Cmd.helpful
97 Make command "helpful", i.e. add -h --help flags for print usage.<br>
70e0208a »
2011-08-21 README.md formatting fixes
98 **@returns** *COA.Cmd* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
99
100 #### Cmd.errorExit
70e0208a »
2011-08-21 README.md formatting fixes
101 Terminate program with error code 1.
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
102 **@param** *String* `msg` message for print to STDERR<br>
70e0208a »
2011-08-21 README.md formatting fixes
103 **@param** *{Object}* [o] optional object for print with message
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
104
105 #### Cmd.exit
106 Terminate program with error code 0.<br>
70e0208a »
2011-08-21 README.md formatting fixes
107 **@param** *String* `msg` message for print to STDERR
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
108
109 #### Cmd.usage
110 Build full usage text for current command instance.<br>
70e0208a »
2011-08-21 README.md formatting fixes
111 **@returns** *String* `usage` text
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
112
113 #### Cmd.parse
114 Parse arguments from simple format like NodeJS process.argv.<br>
115 **@param** *Array* `argv`<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.end
119 Finish chain for current subcommand and return parent command instance.<br>
70e0208a »
2011-08-21 README.md formatting fixes
120 **@returns** *COA.Cmd* `parent` command
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
121
122 ### Opt
123 Option is a named entity. Options may have short and long keys for use from command line.<br>
124 **@namespace**<br>
70e0208a »
2011-08-21 README.md formatting fixes
125 **@class** Presents option
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
126
127 #### Opt.name
128 Set a canonical option identifier to be used anywhere in the API.<br>
129 **@param** *String* `_name` option name<br>
70e0208a »
2011-08-21 README.md formatting fixes
130 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
131
132 #### Opt.title
133 Set a long description for option to be used anywhere in text messages.<br>
134 **@param** *String* `_title` option title<br>
70e0208a »
2011-08-21 README.md formatting fixes
135 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
136
137
138 #### Opt.short
139 Set a short key for option to be used with one hyphen from command line.<br>
140 **@param** *String* `_short`<br>
70e0208a »
2011-08-21 README.md formatting fixes
141 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
142
143 #### Opt.long
144 Set a short key for option to be used with double hyphens from command line.<br>
145 **@param** *String* `_long`<br>
70e0208a »
2011-08-21 README.md formatting fixes
146 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
147
48d29553 »
2011-08-30 Rename function for make options without value: type(Boolean) -> flag…
148 #### Opt.flag
149 Make an option boolean, i.e. option without value.<br>
70e0208a »
2011-08-21 README.md formatting fixes
150 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
151
abf91401 »
2011-08-30 Rename function for make opts/args array-value: push() -> arr().
152 #### Opt.arr
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
153 Makes an option accepts multiple values.<br>
154 Otherwise, the value will be used by the latter passed.<br>
70e0208a »
2011-08-21 README.md formatting fixes
155 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
156
157 #### Opt.required
158 Makes an option required.<br>
70e0208a »
2011-08-21 README.md formatting fixes
159 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
160
bb38ef51 »
2011-08-30 Rename function for validation and processing value: validation() -> …
161 #### Opt.val
162 Set a validation (or value) function for argument.<br>
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
163 Value from command line passes through before becoming available from API.<br>
bb38ef51 »
2011-08-30 Rename function for validation and processing value: validation() -> …
164 Using for validation and convertion simple types to any values.<br>
165 **@param** *Function* `_val` validating function,
70e0208a »
2011-08-21 README.md formatting fixes
166 invoked in the context of option instance
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
167 and has one parameter with value from command line<br>
70e0208a »
2011-08-21 README.md formatting fixes
168 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
169
170 #### Opt.def
70e0208a »
2011-08-21 README.md formatting fixes
171 Set a default value for option.
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
172 Default value passed through validation function as ordinary value.<br>
173 **@param** *Object* `_def`<br>
70e0208a »
2011-08-21 README.md formatting fixes
174 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
175
176 #### Opt.output
177 Make option value outputing stream.<br>
178 It's add useful validation and shortcut for STDOUT.<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.act
70e0208a »
2011-08-21 README.md formatting fixes
182 Add action for current option command.
183 This action is performed if the current option
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
184 is present in parsed options (with any value).<br>
70e0208a »
2011-08-21 README.md formatting fixes
185 **@param** *Function* `act` action function,
186 invoked in the context of command instance
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
187 and has the parameters:<br>
188 - *Object* `opts` parsed options<br>
189 - *Array* `args` parsed arguments<br>
70e0208a »
2011-08-21 README.md formatting fixes
190 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
191
192 #### Opt.end
193 Finish chain for current option and return parent command instance.<br>
70e0208a »
2011-08-21 README.md formatting fixes
194 **@returns** *COA.Cmd* `parent` command
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
195
196
197 ### Arg
198 Argument is a unnamed entity.<br>
70e0208a »
2011-08-21 README.md formatting fixes
199 From command line arguments passed as list of unnamed values.
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
200
201 #### Arg.name
202 Set a canonical argument identifier to be used anywhere in text messages.<br>
203 **@param** *String* `_name` argument name<br>
70e0208a »
2011-08-21 README.md formatting fixes
204 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
205
206 #### Arg.title
207 Set a long description for argument to be used anywhere in text messages.<br>
208 **@param** *String* `_title` argument title<br>
70e0208a »
2011-08-21 README.md formatting fixes
209 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
210
abf91401 »
2011-08-30 Rename function for make opts/args array-value: push() -> arr().
211 #### Arg.arr
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
212 Makes an argument accepts multiple values.<br>
213 Otherwise, the value will be used by the latter passed.<br>
70e0208a »
2011-08-21 README.md formatting fixes
214 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
215
216 #### Arg.required
217 Makes an argument required.<br>
70e0208a »
2011-08-21 README.md formatting fixes
218 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
219
bb38ef51 »
2011-08-30 Rename function for validation and processing value: validation() -> …
220 #### Arg.val
221 Set a validation (or value) function for argument.<br>
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
222 Value from command line passes through before becoming available from API.<br>
bb38ef51 »
2011-08-30 Rename function for validation and processing value: validation() -> …
223 Using for validation and convertion simple types to any values.<br>
224 **@param** *Function* `_val` validating function,
70e0208a »
2011-08-21 README.md formatting fixes
225 invoked in the context of argument instance
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
226 and has one parameter with value from command line<br>
70e0208a »
2011-08-21 README.md formatting fixes
227 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
228
229 #### Arg.def
70e0208a »
2011-08-21 README.md formatting fixes
230 Set a default value for argument.
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
231 Default value passed through validation function as ordinary value.<br>
232 **@param** *Object* `_def`<br>
70e0208a »
2011-08-21 README.md formatting fixes
233 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
234
235 #### Arg.output
236 Make argument value outputing stream.<br>
237 It's add useful validation and shortcut for STDOUT.<br>
70e0208a »
2011-08-21 README.md formatting fixes
238 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
239
240 #### Arg.end
241 Finish chain for current option and return parent command instance.<br>
70e0208a »
2011-08-21 README.md formatting fixes
242 **@returns** *COA.Cmd* `parent` command
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
243
244
1dc5a3df »
2011-08-19 Add TODO
245 ## TODO
246 * Program API for use COA-covered programs as modules
6f183d27 »
2011-08-19 Edited README.md via GitHub
247 * Shell completion
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
248 * Localization
f07cc578 »
2011-08-19 Edited README.md via GitHub
249 * Shell-mode
6b328886 »
2011-08-19 Edited README.md via GitHub
250 * Configs
9dfe97b8 »
2011-08-19 Edited README.md via GitHub
251 * Aliases
e64e1fcd »
2011-08-21 * Rewrite in CoffeeScript
252 * Defaults
Something went wrong with that request. Please try again.