Skip to content

HTTPS clone URL

Subversion checkout URL

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