Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 251 lines (205 sloc) 8.854 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
21 this.exit( // exit program with code 0 and text message
22 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')
32 .validate(function(v) { // validator function, also for translate simple values
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
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>
87 **@param** *{Boolean}* [force=false] flag for set action instead add to existings<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
88 **@returns** *COA.Cmd* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
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>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
94 **@returns** *COA.Cmd* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
95
96 #### Cmd.helpful
97 Make command "helpful", i.e. add -h --help flags for print usage.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
98 **@returns** *COA.Cmd* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
99
100 #### Cmd.errorExit
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
101 Terminate program with error code 1.
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
102 **@param** *String* `msg` message for print to STDERR<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
103 **@param** *{Object}* [o] optional object for print with message
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
104
105 #### Cmd.exit
106 Terminate program with error code 0.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
107 **@param** *String* `msg` message for print to STDERR
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
108
109 #### Cmd.usage
110 Build full usage text for current command instance.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
111 **@returns** *String* `usage` text
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
112
113 #### Cmd.parse
114 Parse arguments from simple format like NodeJS process.argv.<br>
115 **@param** *Array* `argv`<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
116 **@returns** *COA.Cmd* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
117
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
157 #### Opt.required
158 Makes an option required.<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
161 #### Opt.validate
162 Set a validation function for option.<br>
163 Value from command line passes through before becoming available from API.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
164 **@param** *Function* `_validate` validating function,
165 invoked in the context of option instance
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
166 and has one parameter with value from command line<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
169 #### Opt.def
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
170 Set a default value for option.
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
171 Default value passed through validation function as ordinary value.<br>
172 **@param** *Object* `_def`<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
173 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
174
175 #### Opt.output
176 Make option value outputing stream.<br>
177 It's add useful validation and shortcut for STDOUT.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
178 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
179
180 #### Opt.act
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
181 Add action for current option command.
182 This action is performed if the current option
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
183 is present in parsed options (with any value).<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
184 **@param** *Function* `act` action function,
185 invoked in the context of command instance
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
186 and has the parameters:<br>
187 - *Object* `opts` parsed options<br>
188 - *Array* `args` parsed arguments<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
189 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
190
191 #### Opt.end
192 Finish chain for current option and return parent command instance.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
193 **@returns** *COA.Cmd* `parent` command
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
194
195
196 ### Arg
197 Argument is a unnamed entity.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
198 From command line arguments passed as list of unnamed values.
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
199
200 #### Arg.name
201 Set a canonical argument identifier to be used anywhere in text messages.<br>
202 **@param** *String* `_name` argument name<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
203 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
204
205 #### Arg.title
206 Set a long description for argument to be used anywhere in text messages.<br>
207 **@param** *String* `_title` argument title<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
208 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
209
abf9140 Sergey Berezhnoy Rename function for make opts/args array-value: push() -> arr().
authored
210 #### Arg.arr
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
211 Makes an argument accepts multiple values.<br>
212 Otherwise, the value will be used by the latter passed.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
213 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
214
215 #### Arg.required
216 Makes an argument required.<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
219 #### Arg.validate
220 Set a validation function for argument.<br>
221 Value from command line passes through before becoming available from API.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
222 **@param** *Function* `_validate` validating function,
223 invoked in the context of argument instance
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
224 and has one parameter with value from command line<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
225 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
226
227 #### Arg.def
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
228 Set a default value for argument.
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
229 Default value passed through validation function as ordinary value.<br>
230 **@param** *Object* `_def`<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
231 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
232
233 #### Arg.output
234 Make argument value outputing stream.<br>
235 It's add useful validation and shortcut for STDOUT.<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.end
239 Finish chain for current option and return parent command instance.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
240 **@returns** *COA.Cmd* `parent` command
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
241
242
1dc5a3d Sergey Berezhnoy Add TODO
authored
243 ## TODO
244 * Program API for use COA-covered programs as modules
6f183d2 Sergey Berezhnoy Edited README.md via GitHub
authored
245 * Shell completion
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
246 * Localization
f07cc57 Sergey Berezhnoy Edited README.md via GitHub
authored
247 * Shell-mode
6b32888 Sergey Berezhnoy Edited README.md via GitHub
authored
248 * Configs
9dfe97b Sergey Berezhnoy Edited README.md via GitHub
authored
249 * Aliases
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
250 * Defaults
Something went wrong with that request. Please try again.