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