| 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 |
[](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 |
[](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/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 |
 |
| 54 |
|
| 55 |
But wait! There's more! You can do short options: |
| 56 |
------------------------------------------------- |
| 57 |
|
| 58 |
short.js: |
| •59 |
|
| 60 |
````javascript |
| 61 |
#!/usr/bin/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/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/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/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/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/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/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/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/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). |