optimist

What is optimist?

The optimist npm package is a command-line option parser for Node.js. It allows developers to parse arguments passed to their Node.js applications and use them as options within the application. It provides a simple and fluent API to define and access command-line arguments.

What are optimist's main functionalities?

Option Parsing

This feature allows the parsing of command-line arguments. In the code sample, optimist is used to parse the 'name' argument from the command line and print a greeting message.

const argv = require('optimist').argv;
console.log('Hello, ' + argv.name + '!');

Default Values

This feature allows setting default values for command-line arguments. In the code sample, if the 'name' argument is not provided, it defaults to 'World'.

const argv = require('optimist').default('name', 'World').argv;
console.log('Hello, ' + argv.name + '!');

Demand Options

This feature makes certain command-line arguments mandatory. In the code sample, the 'name' argument is required, and the script will not run without it.

const argv = require('optimist').demand(['name']).argv;
console.log('Hello, ' + argv.name + '!');

Usage Messages

This feature allows developers to provide usage messages for their command-line applications. In the code sample, a usage message is defined to guide the user on how to run the script.

const argv = require('optimist').usage('Usage: $0 --name [name]').argv;
console.log('Hello, ' + argv.name + '!');

Boolean Flags

This feature allows the definition of boolean flags. In the code sample, a 'verbose' flag is defined, which can be turned on or off.

const argv = require('optimist').boolean('verbose').argv;
console.log('Verbose mode is ' + (argv.verbose ? 'on' : 'off'));

Other packages similar to optimist

yargs

Yargs is a modern and feature-rich command-line argument parser that has succeeded optimist. It offers similar functionalities but with additional features like command chaining, advanced parsing, and automatic help generation.

commander

Commander is another popular npm package for command-line interfaces. It provides a high-level API for defining commands, options, and subcommands, making it more suitable for complex CLI applications compared to optimist.

minimist

Minimist is a minimalistic command-line argument parser. It is more lightweight than optimist and focuses on simplicity and performance, with fewer features and a smaller footprint.

argparse

Argparse is a node.js version of the Python argument parsing library. It offers a rich set of features for argument parsing, including subcommands and nested parsers, making it a powerful alternative to optimist.

README

optimist

Optimist is a node.js library for option parsing for people who hate option parsing. More specifically, this module is for people who like all the --bells and -whistlz of program usage but think optstrings are a waste of time.

With optimist, option parsing doesn't have to suck (as much).

With Optimist, the options are just a hash! No optstrings attached.

xup.js:

#!/usr/bin/env node
var argv = require('optimist').argv;

if (argv.rif - 5 * argv.xup > 7.138) {
    console.log('Buy more riffiwobbles');
}
else {
    console.log('Sell the xupptumblers');
}

---

$ ./xup.js --rif=55 --xup=9.52
Buy more riffiwobbles

$ ./xup.js --rif 12 --xup 8.1
Sell the xupptumblers

But wait! There's more! You can do short options:

short.js:

#!/usr/bin/env node
var argv = require('optimist').argv;
console.log('(%d,%d)', argv.x, argv.y);

---

$ ./short.js -x 10 -y 21
(10,21)

And booleans, both long and short (and grouped):

bool.js:

#!/usr/bin/env node
var sys = require('sys');
var argv = require('optimist').argv;

if (argv.s) {
    sys.print(argv.fr ? 'Le chat dit: ' : 'The cat says: ');
}
console.log(
    (argv.fr ? 'miaou' : 'meow') + (argv.p ? '.' : '')
);

---

$ ./bool.js -s
The cat says: meow

$ ./bool.js -sp
The cat says: meow.

$ ./bool.js -sp --fr
Le chat dit: miaou.

And non-hypenated options too! Just use argv._!

nonopt.js:

#!/usr/bin/env node
var argv = require('optimist').argv;
console.log('(%d,%d)', argv.x, argv.y);
console.log(argv._);

---

$ ./nonopt.js -x 6.82 -y 3.35 moo
(6.82,3.35)
[ 'moo' ]

$ ./nonopt.js foo -x 0.54 bar -y 1.12 baz
(0.54,1.12)
[ 'foo', 'bar', 'baz' ]

Plus, Optimist comes with .usage() and .demand()!

divide.js:

#!/usr/bin/env node
var argv = require('optimist')
    .usage('Usage: $0 -x [num] -y [num]')
    .demand(['x','y'])
    .argv;

console.log(argv.x / argv.y);

---

$ ./divide.js -x 55 -y 11
5

$ ./divide.js -x 4.91 -z 2.51
Usage: node ./examples/divide.js -x [num] -y [num]

  -x  [required]

  -y  [required]

Missing required arguments: y

EVEN MORE HOLY COW

default_singles.js:

#!/usr/bin/env node
var argv = require('optimist')
    .default('x', 10)
    .default('y', 10)
    .argv
;
console.log(argv.x + argv.y);

---

$ ./default_singles.js -x 5
15

default_hash.js:

#!/usr/bin/env node
var argv = require('optimist')
    .default({ x : 10, y : 10 })
    .argv
;
console.log(argv.x + argv.y);

---

$ ./default_hash.js -y 7
17

And if you really want to get all descriptive about it...

boolean_single.js

#!/usr/bin/env node
var argv = require('optimist')
    .boolean('v')
    .argv
;
console.dir(argv);

---

$ ./boolean_single.js -v foo bar baz
true
[ 'bar', 'baz', 'foo' ]

boolean_double.js

#!/usr/bin/env node
var argv = require('optimist')
    .boolean(['x','y','z'])
    .argv
;
console.dir([ argv.x, argv.y, argv.z ]);
console.dir(argv._);

---

$ ./boolean_double.js -x -z one two three
[ true, false, true ]
[ 'one', 'two', 'three' ]

Optimist is here to help...

You can describe parameters for help messages and set aliases. Optimist figures out how to format a handy help string automatically.

line_count.js

#!/usr/bin/env node
var argv = require('optimist')
    .usage('Count the lines in a file.\nUsage: $0')
    .demand('f')
    .alias('f', 'file')
    .describe('f', 'Load a file')
    .argv
;

var fs = require('fs');
var s = fs.createReadStream(argv.file);

var lines = 0;
s.on('data', function (buf) {
    lines += buf.toString().match(/\n/g).length;
});

s.on('end', function () {
    console.log(lines);
});

---

$ node line_count.js
Count the lines in a file.
Usage: node ./line_count.js

Options:
  -f, --file  Load a file  [required]

Missing required arguments: f

$ node line_count.js --file line_count.js 
20

$ node line_count.js -f line_count.js 
20

notes

Every argument that looks like a number (!isNaN(Number(arg))) is converted to one. This way you can just net.createConnection(argv.port) and you can add numbers out of argv with + without having that mean concatenation, which is super frustrating.

installation

With npm, just do: npm install optimist

or clone this project on github:

git clone http://github.com/substack/node-optimist.git

To run the tests with expresso, just do:

expresso

inspired By

This module is loosely inspired by Perl's Getopt::Casual.