Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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