Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 252 lines (206 sloc) 8.912 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
148 #### Opt.type
149 Set a type of option. Mainly using with Boolean for options without value.<br>
150 **@param** *Object* `_type`<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
151 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
152
153 #### Opt.push
154 Makes an option accepts multiple values.<br>
155 Otherwise, the value will be used by the latter passed.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
156 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
157
158 #### Opt.required
159 Makes an option required.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
160 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
161
162 #### Opt.validate
163 Set a validation function for option.<br>
164 Value from command line passes through before becoming available from API.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
165 **@param** *Function* `_validate` validating function,
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>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
190 **@returns** *COA.Opt* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
191
192 #### Opt.end
193 Finish chain for current option and return parent command instance.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
194 **@returns** *COA.Cmd* `parent` command
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
195
196
197 ### Arg
198 Argument is a unnamed entity.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
199 From command line arguments passed as list of unnamed values.
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
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>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
204 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
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>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
209 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
210
211 #### Arg.push
212 Makes an argument accepts multiple values.<br>
213 Otherwise, the value will be used by the latter passed.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
214 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
215
216 #### Arg.required
217 Makes an argument required.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
218 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
219
220 #### Arg.validate
221 Set a validation function for argument.<br>
222 Value from command line passes through before becoming available from API.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
223 **@param** *Function* `_validate` validating function,
224 invoked in the context of argument instance
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
225 and has one parameter with value from command line<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
226 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
227
228 #### Arg.def
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
229 Set a default value for argument.
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
230 Default value passed through validation function as ordinary value.<br>
231 **@param** *Object* `_def`<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
232 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
233
234 #### Arg.output
235 Make argument value outputing stream.<br>
236 It's add useful validation and shortcut for STDOUT.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
237 **@returns** *COA.Arg* `this` instance (for chainability)
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
238
239 #### Arg.end
240 Finish chain for current option and return parent command instance.<br>
70e0208 Sergey Berezhnoy README.md formatting fixes
authored
241 **@returns** *COA.Cmd* `parent` command
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
242
243
1dc5a3d Sergey Berezhnoy Add TODO
authored
244 ## TODO
245 * Program API for use COA-covered programs as modules
6f183d2 Sergey Berezhnoy Edited README.md via GitHub
authored
246 * Shell completion
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
247 * Localization
f07cc57 Sergey Berezhnoy Edited README.md via GitHub
authored
248 * Shell-mode
6b32888 Sergey Berezhnoy Edited README.md via GitHub
authored
249 * Configs
9dfe97b Sergey Berezhnoy Edited README.md via GitHub
authored
250 * Aliases
e64e1fc Sergey Berezhnoy * Rewrite in CoffeeScript
authored
251 * Defaults
Something went wrong with that request. Please try again.