telltale v1.0.0

telltale

telltale is an unconventional option parser for Node.js.

telltale is unconventional in that it only parses long options, short options and arguments. It does not know about switches, or any other variants of argument parsing.

As a consequence, it's a lot easier to reason about how telltale will parse an argument set.

Terminology

<dt>option</dt>
	<dd>(1) Two adjacent elements of an <a href="#argument-set">argument set</a>: the first is the <a href="#option-key">option key</a>, and the second is the <a href="#option-value">option value</a>.</dd>
	<dd>Example: <code>[..., '--foo', 'bar', ...]</code>.
	</dd>
	<dd>(2) One element of an argument set: the <a href="#option-key">option key</a> and an <a href="#option-value">option value</a> separated by an <code>=</code>.</dd>
	<dd>Example: <code>[..., '-foo=bar', ...]</code>.
	</dd>

<dt>option(al) key</dt>
	<dd>The first part of an <a href="#option">option</a>. An option key is a string literal prefixed by either a '-' or a '--'.</dd>
	<dd>Examples:
			<code>--foo</code>,
			<code>-bar</code>.
	</dd>

<dt>option(al) value</dt>
	<dd>The second part of an <a href="#option">option</a>. An option value is any string literal.</dd>
	<dd>Examples:
			<code>biz</code>,
			<code>bar</code>,
			<code>f</code>,
			<code>--foo</code><a href="special case">*</a>.
	</dd>

<dt>long option</dt>
	<dd>A long option is an <a href="#option">option</a> that has one of the two following forms:
	<ol>
			<li><code>--optionKey optionValue</code></li>
		<li><code>--optionKey=optionValue</code></li>
		</ol>
	</dd>
	<dd>Examples:
		<code>[..., '--foo', 'bar', ...]</code>,
		<code>[..., '--biz=baz', ...]</code>.
	</dd>

<dt>short option</dt>
	<dd>A short option is an <a href="#option">option</a> that has one of the two following forms:
	<ol>
			<li><code>-optionKey optionValue</code></li>
		<li><code>-optionKey=optionValue</code></li>
		</ol>
	</dd>
	<dd>Examples:
		<code>[..., '--foo', 'bar', ...]</code>,
		<code>[..., '--biz=baz', ...]</code>.
	</dd>

<dt>argument</dt>
	<dd>A standalone element in an <a href="#argument-set">argument set</a> that is not preceded by an <a href="#optional-key">optional key</a>. It's value is any string literal.</dd>
	<dd>Examples:
			<code>qux</code>,
			<code>nuz</code>,
			<code>diz</code>,
			<code>b</code>.
	</dd>

Examples

script.js:

'use strict';
var args = require('telltale')(process.argv);
console.log(args);

Example 1

$ node script.js --foo bar arg1 -biz baz arg2 --buz=fuz arg3
{ long: { foo: 'bar', buz: 'fuz' },
  short: { biz: 'baz' },
  args: [ 'arg1', 'arg2', 'arg3' ] }

Optional keys MUST be immediately followed by optional values. Not doing so returns an unspecified result.

Example 2

$ node script.js --foo --bar --boo=--far -f -b buz
{ long: { foo: '--bar', boo: '--far' },
  short: { f: '-b' },
  args: ['buz'] }

telltale is unconditional about argument parsing: an optional value always immediately follows an optional key, no matter what the content of that optional value is.

Think redis, where there's nothing special about the contents of a value. Therefore, --bar or -bar are perfectly valid optional values.

Example 3

$ node script.js -foo -bar -boo=--far -f -b
{ long: {},
  short: { foo: '-bar', boo: '--far', f: '-b' },
  args: [] }

Example 4

$ node script.js foo bar biz -- --foo --biz -buz=faz --fuz -b
{ long: {},
  short: {},
  args: [ 'foo', 'bar', 'biz', '--foo', '--biz', '-buz=faz', '--fuz', '-b' ] }

If telltale encounters a bare -- argument when parsing (and the prior element in the argument set was not an option key), it treats the remaining elements in the argument set as arguments unconditionally.

API

telltale.parse(argumentSet)

Parses an argument set and returns an object that contains the long options, the short options, and the arguments.

Example:

$ node
> var telltale = require('telltale');
> telltale.parse(['-foo', 'bar', 'arg1', '-biz', 'baz', 'arg2', '-b', '--v', '--buz=fuz', 'arg3']);
{ long: { buz: 'fuz' },
  short: { foo: 'bar', biz: 'baz', b: '--v' },
  args: [ 'arg1', 'arg2', 'arg3' ] }

telltale's parser has four rules:

1. Optional keys MUST be immediately followed by optional values. Not doing so returns an unspecified result.
2. An optional value can be any string literal (including literals that start with - or --), so long as it is immediately preceded by an optional key.
3. If telltale encounters a bare -- argument when parsing (and the prior element in the argument set was not an option key), it treats the remaining elements in the argument set as arguments unconditionally.
4. If two or more optional keys with the same name are specified in the argument set, only the lattermost optional key and its corresponding option value are in the returned object.

telltale(argv)

A specialized version of telltale.parse that ignores the first two arguments from the argument set before parsing. This is useful when working directly with process.argv.

Returns the same exact thing telltale.parse does (omitting the first two arguments).

Example:

script.js:

'use strict';
var args = require('telltale')(process.argv);
console.log(args);

Command line:

$ node script.js -foo bar arg1 -biz baz arg2 -b --v --buz=fuz arg3
{ long: { buz: 'fuz' },
  short: { foo: 'bar', biz: 'baz', b: '--v' },
  args: [ 'arg1', 'arg2', 'arg3' ] }