opt-md

opt-md

Document-based option parsing.

Main entry point

The contents of the main function will only be run when called directly from the command line:

// demo.js
exports.foo = function() { return 'bar'; }

require('opt-md').run(module, function($) {
    console.log('Hello ' + $('name'));
});

_{Note: The variable module is required.}

Argument Parsing

With no configuration

Out of the box, we can get arguments with no configuration. In our first example, demo.js, if we were to call it with

./demo.js --name World foo bar baz

it would print out "Hello World". Positional arguments can be fetched by their position:

$(0) // "foo"
$(2) // "baz"

With configuration

There will be no JavaScript options for configuration. Markdown is used instead.

See the Documentation section for more information on why. The following document will go over the options that you can use in your application:

demo.md

# demo -- A demonstration of the features & formatting

## SYNOPSIS

sample [flags] `<first>` `<last>` `[pet]`

## OPTIONS

### -f, --flag
This is a boolean flag as there is no values that follow the flag.
It can be accessed with $('f') or $('flag')

### --anything ANYTHING
This flag expects a value to come after it. It can be a number, a string,
etc. The type will be auto detected and the value of $('anything') will
be that value.

### -s "VALUE", --string "VALUE"
Same as above, except that the value placeholder is in quotes meaning
that no type detection is performed, and it is kept as a string. Give
it `000123` and it will remain `000123` vs. converting it to a number
resulting in `123`.

### --default=SOMETHING, -d SOMETHING (default=foo)
It is also possible to set default values.

### --home (default=$HOME)
And use environment variables to set those defaults. Any default value
beginning with a `$` will be treated as an environment variable.

### --demand (required)
We can also demand that a flag should be set.

### --pghost (required, default=$PGHOST)
Combining required and using environment variables as defaults is a
good way to ensure that the value will be set one way or another.

## AUTHORS
... Another section

## BUGS
... Another section. Add as many sections as you want.

To use it, specify the path to the markdown document:

require('opt-md').run(module, './demo.md', function($) {
    console.log($('default') + ' ' + $('d')); // prints "foo foo"
});

Documentation

The reason we don't put our flags within our script is so we can use marked-man for man pages & HTML documentation, and have npm install our man pages automatically.

In a nutshell, with our markdown:

marked-man demo.md > man/demo.1

And then in your package.json, reference the man page that was created:

{
    "name" : "demo",
    "version" : "1.2.3",
    "description" : "A demo package",
    "main" : "demo.js",
    "bin": {
        "demo": "demo.js"
    }
    "man" : "./man/doc.1"
}

When your package is installed globally, the man page will also be installed.

Windows

Use marked-man --format=html for html-based documentation.

Extras

In addition to the argument fetching, a very minimal set of functions & getters have been attached to the $ object. Some of them are chainable and will be indicated as such. View the example directory for more more information.

Arguments

• $.all - An object containing all the arguments given.
• $.pos - An array containing all the positional arguments given.

IO

• $.cout() - Alias for console.log, chainable.
• $.cerr() - Alias for console.error, chainable.
• $.out - Alias for process.stdout
• $.err - Alias for process.stderr

Assert

• $.assert

Exports Node's assert library to this variable. Useful for argument checking, argument lengths, etc.

Misc.

• $.exit() - Alias for process.exit