dreamopt v0.8.0

Command-Line Parser With Readable Syntax From Your Sweetest Dreams

Ever wrote crap code to deal with parsing command-line options? No more. Here's how it should look like (in CoffeeScript):

options = require('dreamopt') [
  "Usage: myscript [options] source [destination]"

  "  source           Source file to compile into css #required"
  "  destination      Destination file (defaults to source file with .css extension)", (value, options) ->
    if !value
      return options.source.replace(/\.mess/, '') + '.css'

  "Processing options:"
  "  -n, --dry-run    Don't write anything to disk"
  "  -m, --mode MODE  Set execution mode: easy, medium, hard (defaults to medium)"

  "Connection options:"
  "  -p, --port PORT  Port to connect to (default: 80)"
  "  -h, --host HOST  Host to connect to (default is localhost)"

  "Getting useful information:"
  "  --reporters      Print a list of reporters and exit", ->
    console.log "Reporters: foo, bar, boz"
    process.exit 0
]

console.log JSON.stringify(options, null, 2)

Try to run it as node examples/foo.js:

Error: Missing required argument #1: source

Now run it as node examples/foo.js myfile.mess:

{
  "mode": "medium",
  "port": 80,
  "host": "localhost",
  "source": "myfile.mess",
  "destination": "myfile.css",
  "argv": [
    "myfile.mess",
    "myfile.css"
  ]
}

Installation

npm install dreamopt

Features

Overview:

• readable option specification with no extra punctuation
• comprehensive test suite (221 tests so far)
• returns a simple hash with predicable contents and coerced data types
• mandatory and optional arguments/options
• default values
• optional callback functions
• custom tags and coercion rules
• automatic --help

Option syntax details:

• long options always start with double dashes (--long), short options with a single dash (-s)
• a single dash by itself (-) is considered a positional argument rather than an option (and usually signifies reading from stdin)
• -- ends option processing
• option value can be specified as -sVAL, -s VAL, --long=VAL or --long VAL
• short options can be combined (-xc)
• short option that requires a value consumes the remainder of the combined option if any (-xcfMYFILE, -pi.tmp)

Usage

This module can called with up to three arguments:

options = require('dreamopt')(spec, [customTags], [argv])

where:

• spec is a required array of strings
• customTags is an optional hash with custom tag handlers
• argv is an optional array of arguments to use instead of process.argv.slice(2)

If you leave out customTags but specify argv, you don't need to include an empty argument: require('dreamopt')(spec, argv).

Specification format

Each line of spec can be:

• Usage: blah blag — a banner, it is displayed at the very top of the usage info
• Something: — a header, it is displayed verbatim with appropriate spacing; if you don't define any headers, dreamopt will add the default ones as needed (“Arguments:” and “Options:”)
• -s, --long VALUE Description #tag1 #tag2(val2) — option definition; must start with at least one space; if description or tags are specified, they must be separated from the option itself by at least two spaces; tags must be in the end and may have optional values
• arg Description #tag1 #tag2 — positional argument definition, same format as options
• after an option or an argument, you can include a function to be invoked when the option/argument is encountered
• command Description followed by an array — subcommand definition; these are not functional yet, but should be parsed properly

Any other lines that don't start with whitespace are output verbatim, as a paragraph of text. (Lines that start with whitespace must conform to option, argument or subcommand syntax.)

Coercion, validation and custom tags

Argument values are automatically coerced to numbers if possible, otherwise they are provided as strings. You can specify one of the following tags to change coercion rules:

• #string disables coercion and always returns a string
• #int always coerces to int, giving an error if that's impossible

You can define custom tags to handle coercion, validation or any other processing. For example, to parse a simple YYYY-MM-DD date format, you can do:

options = require('../lib/dreamopt') [
  "-f, --from DATE  Only process records from the given date #date"
], {
  date: (value, options, optionName) ->
    if isNaN(new Date(value))
      throw new Error("Invalid date for option #{optionName}")
    new Date(value)
}

console.log "Year: " + options.from?.getFullYear()

Tag functions are invoked with four arguments (value, options, optionName, tagValue):

• value is the value of the current option
• options is the options hash built so far
• optionName is useful when referring to the current option in an error message
• tagValue is the value of the tag if any; for example, for #date(today) the tagValue would be 'today'

Magic tags

• #required marks a required option or argument
• #var(fieldName) overrides the options field for this option (i.e. the value is stored into options.fieldName)
• #default(value) specifies a default value
• #list marks an option that may be used multiple times; the final value is a JavaScript array
• #fancydefault forces the callback function associated with the current option to be called even when an argument is not provided and no default is set; in this case, the original value will be null and your function is expected to return a better one
• #delayfunc delays invocation of the callback function until all other options and arguments are processed; this is useful for options like --help or --print-reporters, when you want all normal options to be handled and validated before the callback is invoked; the return value of such callback functions is ignored

Additionally, you may encounter the following internal tags in the source code:

• #flag denotes a no-values option (which is always treated as boolean)
• #acceptsno is set for options which use --[no-]something in their definition; all boolean option accept --no-option variant to turn them off, but only options explicitly specified as such are documented as accepting --no variants in usage info

Automatic usage info

If you don't define a --help option, it is provided for you automatically and prints a usage info like this:

Usage: myscript [options] source.mess [destination.css]

Arguments:
  source                Source file to compile into css
  destination           Destination file (defaults to source file with .css extension)

Processing options:
  -n, --dry-run         Don't write anything to disk
  -m, --mode MODE       Set execution mode: easy, medium, hard (defaults to medium)

Connection options:
  -p, --port PORT       Port to connect to (default: 80)
  -h, --host HOST       Host to connect to (default is localhost)

Getting useful information:
      --reporters       Print a list of reporters and exit
  -h, --help            Display this usage information

You can provide customTags.printUsage(usageText) function to customize the way this usage info is printed; the default implementation outputs the argument via console.error and executes process.exit(1).