1 | # DEPRECATION NOTICE
|
2 |
|
3 | I don't want to maintain this module anymore since I just use
|
4 | [minimist](https://npmjs.org/package/minimist), the argument parsing engine,
|
5 | directly instead nowadays.
|
6 |
|
7 | See [yargs](https://github.com/chevex/yargs) for the modern, pirate-themed
|
8 | successor to optimist.
|
9 |
|
10 | [![yarrrrrrrgs!](http://i.imgur.com/4WFGVJ9.png)](https://github.com/chevex/yargs)
|
11 |
|
12 | You should also consider [nomnom](https://github.com/harthur/nomnom).
|
13 |
|
14 | optimist
|
15 | ========
|
16 |
|
17 | Optimist is a node.js library for option parsing for people who hate option
|
18 | parsing. More specifically, this module is for people who like all the --bells
|
19 | and -whistlz of program usage but think optstrings are a waste of time.
|
20 |
|
21 | With optimist, option parsing doesn't have to suck (as much).
|
22 |
|
23 | [![build status](https://secure.travis-ci.org/substack/node-optimist.png)](http://travis-ci.org/substack/node-optimist)
|
24 |
|
25 | examples
|
26 | ========
|
27 |
|
28 | With Optimist, the options are just a hash! No optstrings attached.
|
29 | -------------------------------------------------------------------
|
30 |
|
31 | xup.js:
|
32 |
|
33 | ````javascript
|
34 | #!/usr/bin/env node
|
35 | var argv = require('optimist').argv;
|
36 |
|
37 | if (argv.rif - 5 * argv.xup > 7.138) {
|
38 | console.log('Buy more riffiwobbles');
|
39 | }
|
40 | else {
|
41 | console.log('Sell the xupptumblers');
|
42 | }
|
43 | ````
|
44 |
|
45 | ***
|
46 |
|
47 | $ ./xup.js --rif=55 --xup=9.52
|
48 | Buy more riffiwobbles
|
49 |
|
50 | $ ./xup.js --rif 12 --xup 8.1
|
51 | Sell the xupptumblers
|
52 |
|
53 | ![This one's optimistic.](http://substack.net/images/optimistic.png)
|
54 |
|
55 | But wait! There's more! You can do short options:
|
56 | -------------------------------------------------
|
57 |
|
58 | short.js:
|
59 |
|
60 | ````javascript
|
61 | #!/usr/bin/env node
|
62 | var argv = require('optimist').argv;
|
63 | console.log('(%d,%d)', argv.x, argv.y);
|
64 | ````
|
65 |
|
66 | ***
|
67 |
|
68 | $ ./short.js -x 10 -y 21
|
69 | (10,21)
|
70 |
|
71 | And booleans, both long and short (and grouped):
|
72 | ----------------------------------
|
73 |
|
74 | bool.js:
|
75 |
|
76 | ````javascript
|
77 | #!/usr/bin/env node
|
78 | var util = require('util');
|
79 | var argv = require('optimist').argv;
|
80 |
|
81 | if (argv.s) {
|
82 | util.print(argv.fr ? 'Le chat dit: ' : 'The cat says: ');
|
83 | }
|
84 | console.log(
|
85 | (argv.fr ? 'miaou' : 'meow') + (argv.p ? '.' : '')
|
86 | );
|
87 | ````
|
88 |
|
89 | ***
|
90 |
|
91 | $ ./bool.js -s
|
92 | The cat says: meow
|
93 |
|
94 | $ ./bool.js -sp
|
95 | The cat says: meow.
|
96 |
|
97 | $ ./bool.js -sp --fr
|
98 | Le chat dit: miaou.
|
99 |
|
100 | And non-hypenated options too! Just use `argv._`!
|
101 | -------------------------------------------------
|
102 |
|
103 | nonopt.js:
|
104 |
|
105 | ````javascript
|
106 | #!/usr/bin/env node
|
107 | var argv = require('optimist').argv;
|
108 | console.log('(%d,%d)', argv.x, argv.y);
|
109 | console.log(argv._);
|
110 | ````
|
111 |
|
112 | ***
|
113 |
|
114 | $ ./nonopt.js -x 6.82 -y 3.35 moo
|
115 | (6.82,3.35)
|
116 | [ 'moo' ]
|
117 |
|
118 | $ ./nonopt.js foo -x 0.54 bar -y 1.12 baz
|
119 | (0.54,1.12)
|
120 | [ 'foo', 'bar', 'baz' ]
|
121 |
|
122 | Plus, Optimist comes with .usage() and .demand()!
|
123 | -------------------------------------------------
|
124 |
|
125 | divide.js:
|
126 |
|
127 | ````javascript
|
128 | #!/usr/bin/env node
|
129 | var argv = require('optimist')
|
130 | .usage('Usage: $0 -x [num] -y [num]')
|
131 | .demand(['x','y'])
|
132 | .argv;
|
133 |
|
134 | console.log(argv.x / argv.y);
|
135 | ````
|
136 |
|
137 | ***
|
138 |
|
139 | $ ./divide.js -x 55 -y 11
|
140 | 5
|
141 |
|
142 | $ node ./divide.js -x 4.91 -z 2.51
|
143 | Usage: node ./divide.js -x [num] -y [num]
|
144 |
|
145 | Options:
|
146 | -x [required]
|
147 | -y [required]
|
148 |
|
149 | Missing required arguments: y
|
150 |
|
151 | EVEN MORE HOLY COW
|
152 | ------------------
|
153 |
|
154 | default_singles.js:
|
155 |
|
156 | ````javascript
|
157 | #!/usr/bin/env node
|
158 | var argv = require('optimist')
|
159 | .default('x', 10)
|
160 | .default('y', 10)
|
161 | .argv
|
162 | ;
|
163 | console.log(argv.x + argv.y);
|
164 | ````
|
165 |
|
166 | ***
|
167 |
|
168 | $ ./default_singles.js -x 5
|
169 | 15
|
170 |
|
171 | default_hash.js:
|
172 |
|
173 | ````javascript
|
174 | #!/usr/bin/env node
|
175 | var argv = require('optimist')
|
176 | .default({ x : 10, y : 10 })
|
177 | .argv
|
178 | ;
|
179 | console.log(argv.x + argv.y);
|
180 | ````
|
181 |
|
182 | ***
|
183 |
|
184 | $ ./default_hash.js -y 7
|
185 | 17
|
186 |
|
187 | And if you really want to get all descriptive about it...
|
188 | ---------------------------------------------------------
|
189 |
|
190 | boolean_single.js
|
191 |
|
192 | ````javascript
|
193 | #!/usr/bin/env node
|
194 | var argv = require('optimist')
|
195 | .boolean('v')
|
196 | .argv
|
197 | ;
|
198 | console.dir(argv);
|
199 | ````
|
200 |
|
201 | ***
|
202 |
|
203 | $ ./boolean_single.js -v foo bar baz
|
204 | true
|
205 | [ 'bar', 'baz', 'foo' ]
|
206 |
|
207 | boolean_double.js
|
208 |
|
209 | ````javascript
|
210 | #!/usr/bin/env node
|
211 | var argv = require('optimist')
|
212 | .boolean(['x','y','z'])
|
213 | .argv
|
214 | ;
|
215 | console.dir([ argv.x, argv.y, argv.z ]);
|
216 | console.dir(argv._);
|
217 | ````
|
218 |
|
219 | ***
|
220 |
|
221 | $ ./boolean_double.js -x -z one two three
|
222 | [ true, false, true ]
|
223 | [ 'one', 'two', 'three' ]
|
224 |
|
225 | Optimist is here to help...
|
226 | ---------------------------
|
227 |
|
228 | You can describe parameters for help messages and set aliases. Optimist figures
|
229 | out how to format a handy help string automatically.
|
230 |
|
231 | line_count.js
|
232 |
|
233 | ````javascript
|
234 | #!/usr/bin/env node
|
235 | var argv = require('optimist')
|
236 | .usage('Count the lines in a file.\nUsage: $0')
|
237 | .demand('f')
|
238 | .alias('f', 'file')
|
239 | .describe('f', 'Load a file')
|
240 | .argv
|
241 | ;
|
242 |
|
243 | var fs = require('fs');
|
244 | var s = fs.createReadStream(argv.file);
|
245 |
|
246 | var lines = 0;
|
247 | s.on('data', function (buf) {
|
248 | lines += buf.toString().match(/\n/g).length;
|
249 | });
|
250 |
|
251 | s.on('end', function () {
|
252 | console.log(lines);
|
253 | });
|
254 | ````
|
255 |
|
256 | ***
|
257 |
|
258 | $ node line_count.js
|
259 | Count the lines in a file.
|
260 | Usage: node ./line_count.js
|
261 |
|
262 | Options:
|
263 | -f, --file Load a file [required]
|
264 |
|
265 | Missing required arguments: f
|
266 |
|
267 | $ node line_count.js --file line_count.js
|
268 | 20
|
269 |
|
270 | $ node line_count.js -f line_count.js
|
271 | 20
|
272 |
|
273 | methods
|
274 | =======
|
275 |
|
276 | By itself,
|
277 |
|
278 | ````javascript
|
279 | require('optimist').argv
|
280 | `````
|
281 |
|
282 | will use `process.argv` array to construct the `argv` object.
|
283 |
|
284 | You can pass in the `process.argv` yourself:
|
285 |
|
286 | ````javascript
|
287 | require('optimist')([ '-x', '1', '-y', '2' ]).argv
|
288 | ````
|
289 |
|
290 | or use .parse() to do the same thing:
|
291 |
|
292 | ````javascript
|
293 | require('optimist').parse([ '-x', '1', '-y', '2' ])
|
294 | ````
|
295 |
|
296 | The rest of these methods below come in just before the terminating `.argv`.
|
297 |
|
298 | .alias(key, alias)
|
299 | ------------------
|
300 |
|
301 | Set key names as equivalent such that updates to a key will propagate to aliases
|
302 | and vice-versa.
|
303 |
|
304 | Optionally `.alias()` can take an object that maps keys to aliases.
|
305 |
|
306 | .default(key, value)
|
307 | --------------------
|
308 |
|
309 | Set `argv[key]` to `value` if no option was specified on `process.argv`.
|
310 |
|
311 | Optionally `.default()` can take an object that maps keys to default values.
|
312 |
|
313 | .demand(key)
|
314 | ------------
|
315 |
|
316 | If `key` is a string, show the usage information and exit if `key` wasn't
|
317 | specified in `process.argv`.
|
318 |
|
319 | If `key` is a number, demand at least as many non-option arguments, which show
|
320 | up in `argv._`.
|
321 |
|
322 | If `key` is an Array, demand each element.
|
323 |
|
324 | .describe(key, desc)
|
325 | --------------------
|
326 |
|
327 | Describe a `key` for the generated usage information.
|
328 |
|
329 | Optionally `.describe()` can take an object that maps keys to descriptions.
|
330 |
|
331 | .options(key, opt)
|
332 | ------------------
|
333 |
|
334 | Instead of chaining together `.alias().demand().default()`, you can specify
|
335 | keys in `opt` for each of the chainable methods.
|
336 |
|
337 | For example:
|
338 |
|
339 | ````javascript
|
340 | var argv = require('optimist')
|
341 | .options('f', {
|
342 | alias : 'file',
|
343 | default : '/etc/passwd',
|
344 | })
|
345 | .argv
|
346 | ;
|
347 | ````
|
348 |
|
349 | is the same as
|
350 |
|
351 | ````javascript
|
352 | var argv = require('optimist')
|
353 | .alias('f', 'file')
|
354 | .default('f', '/etc/passwd')
|
355 | .argv
|
356 | ;
|
357 | ````
|
358 |
|
359 | Optionally `.options()` can take an object that maps keys to `opt` parameters.
|
360 |
|
361 | .usage(message)
|
362 | ---------------
|
363 |
|
364 | Set a usage message to show which commands to use. Inside `message`, the string
|
365 | `$0` will get interpolated to the current script name or node command for the
|
366 | present script similar to how `$0` works in bash or perl.
|
367 |
|
368 | .check(fn)
|
369 | ----------
|
370 |
|
371 | Check that certain conditions are met in the provided arguments.
|
372 |
|
373 | If `fn` throws or returns `false`, show the thrown error, usage information, and
|
374 | exit.
|
375 |
|
376 | .boolean(key)
|
377 | -------------
|
378 |
|
379 | Interpret `key` as a boolean. If a non-flag option follows `key` in
|
380 | `process.argv`, that string won't get set as the value of `key`.
|
381 |
|
382 | If `key` never shows up as a flag in `process.arguments`, `argv[key]` will be
|
383 | `false`.
|
384 |
|
385 | If `key` is an Array, interpret all the elements as booleans.
|
386 |
|
387 | .string(key)
|
388 | ------------
|
389 |
|
390 | Tell the parser logic not to interpret `key` as a number or boolean.
|
391 | This can be useful if you need to preserve leading zeros in an input.
|
392 |
|
393 | If `key` is an Array, interpret all the elements as strings.
|
394 |
|
395 | .wrap(columns)
|
396 | --------------
|
397 |
|
398 | Format usage output to wrap at `columns` many columns.
|
399 |
|
400 | .help()
|
401 | -------
|
402 |
|
403 | Return the generated usage string.
|
404 |
|
405 | .showHelp(fn=console.error)
|
406 | ---------------------------
|
407 |
|
408 | Print the usage data using `fn` for printing.
|
409 |
|
410 | .parse(args)
|
411 | ------------
|
412 |
|
413 | Parse `args` instead of `process.argv`. Returns the `argv` object.
|
414 |
|
415 | .argv
|
416 | -----
|
417 |
|
418 | Get the arguments as a plain old object.
|
419 |
|
420 | Arguments without a corresponding flag show up in the `argv._` array.
|
421 |
|
422 | The script name or node command is available at `argv.$0` similarly to how `$0`
|
423 | works in bash or perl.
|
424 |
|
425 | parsing tricks
|
426 | ==============
|
427 |
|
428 | stop parsing
|
429 | ------------
|
430 |
|
431 | Use `--` to stop parsing flags and stuff the remainder into `argv._`.
|
432 |
|
433 | $ node examples/reflect.js -a 1 -b 2 -- -c 3 -d 4
|
434 | { _: [ '-c', '3', '-d', '4' ],
|
435 | '$0': 'node ./examples/reflect.js',
|
436 | a: 1,
|
437 | b: 2 }
|
438 |
|
439 | negate fields
|
440 | -------------
|
441 |
|
442 | If you want to explicity set a field to false instead of just leaving it
|
443 | undefined or to override a default you can do `--no-key`.
|
444 |
|
445 | $ node examples/reflect.js -a --no-b
|
446 | { _: [],
|
447 | '$0': 'node ./examples/reflect.js',
|
448 | a: true,
|
449 | b: false }
|
450 |
|
451 | numbers
|
452 | -------
|
453 |
|
454 | Every argument that looks like a number (`!isNaN(Number(arg))`) is converted to
|
455 | one. This way you can just `net.createConnection(argv.port)` and you can add
|
456 | numbers out of `argv` with `+` without having that mean concatenation,
|
457 | which is super frustrating.
|
458 |
|
459 | duplicates
|
460 | ----------
|
461 |
|
462 | If you specify a flag multiple times it will get turned into an array containing
|
463 | all the values in order.
|
464 |
|
465 | $ node examples/reflect.js -x 5 -x 8 -x 0
|
466 | { _: [],
|
467 | '$0': 'node ./examples/reflect.js',
|
468 | x: [ 5, 8, 0 ] }
|
469 |
|
470 | dot notation
|
471 | ------------
|
472 |
|
473 | When you use dots (`.`s) in argument names, an implicit object path is assumed.
|
474 | This lets you organize arguments into nested objects.
|
475 |
|
476 | $ node examples/reflect.js --foo.bar.baz=33 --foo.quux=5
|
477 | { _: [],
|
478 | '$0': 'node ./examples/reflect.js',
|
479 | foo: { bar: { baz: 33 }, quux: 5 } }
|
480 |
|
481 | short numbers
|
482 | -------------
|
483 |
|
484 | Short numeric `head -n5` style argument work too:
|
485 |
|
486 | $ node reflect.js -n123 -m456
|
487 | { '3': true,
|
488 | '6': true,
|
489 | _: [],
|
490 | '$0': 'node ./reflect.js',
|
491 | n: 123,
|
492 | m: 456 }
|
493 |
|
494 | installation
|
495 | ============
|
496 |
|
497 | With [npm](http://github.com/isaacs/npm), just do:
|
498 | npm install optimist
|
499 |
|
500 | or clone this project on github:
|
501 |
|
502 | git clone http://github.com/substack/node-optimist.git
|
503 |
|
504 | To run the tests with [expresso](http://github.com/visionmedia/expresso),
|
505 | just do:
|
506 |
|
507 | expresso
|
508 |
|
509 | inspired By
|
510 | ===========
|
511 |
|
512 | This module is loosely inspired by Perl's
|
513 | [Getopt::Casual](http://search.cpan.org/~photo/Getopt-Casual-0.13.1/Casual.pm).
|
514 |
|
\ | No newline at end of file |