# tav

> Brain-free command-line options parser for node.js

Latest version **0.1.0** (published 2013-10-10) · 0 weekly downloads

## Install

```sh
npm install tav
pnpm add tav
yarn add tav
bun add tav
```

## Health

**Score 10/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; low quality score; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.0 |
| Published | 2013-10-10 |
| First published | 2013-10-10 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | * |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Alexander Dorofeev |
| Maintainers | Alexander Dorofeev |

## Links

- npm: https://www.npmjs.com/package/tav
- Repository: http://github.com/akaspin/tav
- npm.io page: https://npm.io/package/tav

## Recent versions

- 0.1.0 (latest) — 2013-10-10

## README

# tav*

Command-line options parser for [node.js](http://nodejs.org/).

*In the Phoenician alphabet letter "tav" indicates mark or sign.

## Installation

You can install *tav* as usual - by copy "tav" directory in your 
`~/.node_libraries` or via *npm*

    npm install tav

## Usage

*tav* was written for brain-free usage. All you need - import it and run a 
single function `set` at least once. 

    var opts = require('tav').set();
    console.log(opts, opts.args);

After that, all command-options will be available as regular `Object`. And all 
arguments - as a regular `Array`. :
    
    $node app.js --host=localhost --port=8080 --debug arg1 arg2
    { host: 'localhost', port: 8080, debug: true } [ 'arg1', 'arg2' ]
    
Note, that `.args` not enumerable.

All the options and arguments are separated by spaces. Order of options and 
arguments is not important. Options should be set in "full" notation in 
following form:

    --option_name[=option_value] 

Option names can't contain spaces and be called `set` . Values are processed 
by the following rules:

* If value represents any number, it be evaluated as `Number`
* Otherwise value will be a `String`. `String` values can contain 
  equal sign(`=`). 
* If option value contains spaces, you will need to enclose it in single (`'`) 
  or double quotes (`"`).
* Options without values assumes as `Boolean` `true`.

Some examples:

    --simple_string=simple
    --string_with_spaces='String with spaces'
    --simple_number=345
    --decimal_number=755.235
    --bool_true

All arguments fall into the `Array` `whatever-it-is-imported.args` in the order 
which they were at the command line.

Also there is a special option `--help`. But we will consider it in the next 
section.

## Options specifications and banners

Naturally, you can describe the options. To do this, simply some specifications
to `set` function. Also you can set *banner*.

    var opts = require('tav').set({
        host: {
            note: 'Hostname'
        },
        port: {
            note: 'Binding port',
            value: 80
        },
        debug : {
            note : 'Debug this',
            value : false
        }
    }, "Very cool app");
    console.log(opts);

If you omit the option "port", it will be set by default value:

    $node app.js --host=localhost --debug arg1 arg2
    { host: 'localhost', port: 80, debug: true } [ 'arg1', 'arg2' ]

But still, how about the option `--help`? Let's do it.

    $node app.js --host=localhost --debug arg1 arg2 --help
    Very cool app

    Hostname
        --host *required
    Binding port
        --port
    Debug this
        --debug
    Help. This message.
        --help

`--help` option prints usage instructions and terminates program with normal
exit code (0).

## Required options

You probably noticed that `--host` option marked as `*required` in usage 
instructions . And if we run "Very cool app" without this option, you will get 
this such a bomb...

    $node app.js --debug arg1 arg2
    Very cool app
    
    Required but not provided:
        --host
    
    Run with --help for more info

Option is considered as `required` if specifications do not specify its 
default value. If required option not provided, `set` prints info about absent 
options and terminates program with error.

## Unexpected options

While our program is guzzled all that it will. Let's try a little bit to 
straighten it. This requires only small changes:

    var opts = require('../tav').set({
        host : {
            note : 'Hostname'
        },
        port : {
            note : 'Binding port',
            value : 80
        }                           // Remove "debug" from specifications
    }, "Very cool app",
    true);                          // And set "true" after banner
    console.log(opts);

Last parameter causes `set` to generate an error if in command line appears
option that not described in the specifications. Let's crash...

    $node app.js --host=localhost --debug arg1 arg2
    Very cool app
    
    Unexpected options:
        --debug
    
    Run with --help for more info
    
... and once more...

    $node app.js --debug arg1 arg2
    Very cool app
    
    Required but not provided:
        --host
    Unexpected options:
        --debug
    
    Run with --help for more info

## Globalization

`tav` stores all options and arguments on first call of `set` function. After
that all of them will be available from other modules without having to call
`set` as regular object. Let's try.

Our tortured *app.js*:

    var opts = require('tav').set({
        host: {
            note: 'Hostname'
        },
        port: {
            note: 'Binding port',
            value: 80
        },
        debug : {
            note : 'Debug this',
            value : false
        }
    }, "Very cool app");
    var nested = require('./nested');
    console.log(nested.report());

And *nested.js*:

    var opts = require('tav');
    exports.report = function() {
        return opts;
    };

Run it:

    $node app.js --host=localhost arg1 arg2
    { port: 80, debug: false, host: 'localhost' }
    
... All good. All in place.

---
_Source: https://npm.io/package/tav · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._