<commit_before># Neodoc #

> :warning: This project is nearing completion. It is not yet on npm, and
> some of the information in this README may therefore be ahead of it's time.

[![Build Status](https://travis-ci.org/felixSchl/docopt.svg?branch=development)](https://travis-ci.org/felixSchl/docopt)

This is a revised implementation of the [docopt language][docopt-orig] for
node.  It features **error reporting**, both for users and developers, as well
reading values from **environment variables** with many more [features planned](#post-beta-roadmap)
for the near future.

## Table of contents ##

* [Installation](#installation)
* [Usage](#usage)
* [Project goals](#project-goals)
    * [Deviations from original](#deviations-from-the-original)
* [Project status](#project-status)
    * [Beta target](#beta-target)
    * [Post Beta Roadmap](#post-beta-roadmap)
    * [Wishlist](#wishlist)
* [Contributing](#contributing)
    * [Implementation overview](#implementation-overview)

## Installation ##

```sh
npm install --save neodoc
```

## Usage ##

> Basic usage example. For more detail on what neodoc can do, have a look at
> `testcases.docopt` in the repo.

1. Given this node.js program:
    ```javascript
    #!/usr/bin/env node

    import neodoc from 'neodoc';
    const argv = neodoc(`
      Naval Fate.

      Usage:
        naval_fate ship new <name>...
        naval_fate ship <name> move <x> <y> [--speed=<kn>]
        naval_fate ship shoot <x> <y>
        naval_fate mine (set|remove) <x> <y> [--moored|--drifting]
        naval_fate -h | --help
        naval_fate --version

      Options:
        -h --help     Show this screen.
        --version     Show version.
        --speed=<kn>  Speed in knots [default: 10].
        --moored      Moored (anchored) mine.
        --drifting    Drifting mine.
    `);

    console.log(argv);
    ```
    <sub>file: prog</sub>

2. We can provide various input:

    ```bash
    $ prog ship new foo bar baz
      {'<name>': ['foo', 'bar', 'baz'],
       'NAME': ['foo', 'bar', 'baz'],
       'new': true,
       'ship': true}

    $ prog ship foo move 10 10 --speed
      Naval Fate.

      Usage:
        naval_fate ship new <name>...
        naval_fate ship <name> move <x> <y> [--speed=<kn>]
        naval_fate ship shoot <x> <y>
        naval_fate mine (set|remove) <x> <y> [--moored|--drifting]
        naval_fate -h | --help
        naval_fate --version

      Options:
        -h --help     Show this screen.
        --version     Show version.
        --speed=<kn>  Speed in knots [default: 10].
        --moored      Moored (anchored) mine.
        --drifting    Drifting mine.

      Trailing input: --speed:
      > ship foo move 10 10 --speed
                            ^^^^^^^
    ```

## Project goals ##

> Overview of the short- and longterm goals of this project

* Provide a declarative way to author command lines. Rather than deriving the
  help text from some EDSL, derive the CLI from a human readable, prose-like help
  text, located e.g. in the project's README. **This guarantees documentation and
  implementation never diverge, because they simply can't.**
* Provide **very good error reporting** for users of the CLI and at least decent
  error reporting for developers authoring the docopt text.
* The manually crafted docopt text must be **readable, standardised, yet
  flexible and powerful** enough to handle a fair set of use-cases.
* A solid interface for use in **regular javascript**. Purescript should merely
  be an implementation detail.
* **Solid test coverage**
* Sensible compatibility with original docopt.

### Deviations from the original ###

> This implementation tries to be compatible where sensible, but does cut ties
> when it comes down to it. The universal docopt test suite has been adjusted
> accordingly.

* **Better Error reporting.** Let the user of your utility know why his input
  was rejected.
* **No abbreviations:**
  `--ver` does not match `--verbose`.
  <sub>[(mis-feature in the original implementation)](https://github.com/docopt/docopt/issues/104)</sub>
* **Alias matches.** If `--verbose` yields a value, so will `-v` <sub>(given
  that's the assigned alias)</sub>. Likewise, `FOO` yields value `<foo>` as
  well as `FOO`, and `<foo>` yields `FOO` and `<foo>`.
* **Flags are optional,** always. There's no reason to force the user to
  explicitely pass an option that takes no argument. The absence of the flag
  speaks - the flag will be set to `false`. This is also the case for flags
  inside required groups. E.g.: The group `(-a -b)` will match inputs `-a -b`,
  `-ab`, `-ba`, `-b -a`, `-b`, `-a` and the empty input.
* **All arguments in a group are always required**. This is regardless of
  whether or not the group itself is required or not, i.e.:

  ```sh
  Usage: prog [<name> <type>]
  ```
  
  will fail `prog foo`, but pass `prog foo bar`. The rational being that this is
  more general, since if the opposite behaviour (any match) was desired, it
  could be expressed as such:
  
  ```sh
  Usage: prog [[<name>] [<type>]]
  ```
  
  **note:** this rule excludes flags/switches and options that have default
  values (or other fallback values).
* **There is no `null`** in the resulting value map. `null` simply means not
  matched - so the key is omitted from the resulting value map. <sub>(this is
  still under consideration)</sub>
* **Environment variables**. Options can fall back to environment variables,
  if they are not explicitely defined. The order of evaluation is:<commit_msg>Remove trailing white space<commit_after># Neodoc #

> :warning: This project is nearing completion. It is not yet on npm, and
> some of the information in this README may therefore be ahead of it's time.

[![Build Status](https://travis-ci.org/felixSchl/docopt.svg?branch=development)](https://travis-ci.org/felixSchl/docopt)

This is a revised implementation of the [docopt language][docopt-orig] for
node.  It features **error reporting**, both for users and developers, as well
reading values from **environment variables** with many more [features planned](#post-beta-roadmap)
for the near future.

## Table of contents ##

* [Installation](#installation)
* [Usage](#usage)
* [Project goals](#project-goals)
    * [Deviations from original](#deviations-from-the-original)
* [Project status](#project-status)
    * [Beta target](#beta-target)
    * [Post Beta Roadmap](#post-beta-roadmap)
    * [Wishlist](#wishlist)
* [Contributing](#contributing)
    * [Implementation overview](#implementation-overview)

## Installation ##

```sh
npm install --save neodoc
```

## Usage ##

> Basic usage example. For more detail on what neodoc can do, have a look at
> `testcases.docopt` in the repo.

1. Given this node.js program:
    ```javascript
    #!/usr/bin/env node

    import neodoc from 'neodoc';
    const argv = neodoc(`
      Naval Fate.

      Usage:
        naval_fate ship new <name>...
        naval_fate ship <name> move <x> <y> [--speed=<kn>]
        naval_fate ship shoot <x> <y>
        naval_fate mine (set|remove) <x> <y> [--moored|--drifting]
        naval_fate -h | --help
        naval_fate --version

      Options:
        -h --help     Show this screen.
        --version     Show version.
        --speed=<kn>  Speed in knots [default: 10].
        --moored      Moored (anchored) mine.
        --drifting    Drifting mine.
    `);

    console.log(argv);
    ```
    <sub>file: prog</sub>

2. We can provide various input:

    ```bash
    $ prog ship new foo bar baz
      {'<name>': ['foo', 'bar', 'baz'],
       'NAME': ['foo', 'bar', 'baz'],
       'new': true,
       'ship': true}

    $ prog ship foo move 10 10 --speed
      Naval Fate.

      Usage:
        naval_fate ship new <name>...
        naval_fate ship <name> move <x> <y> [--speed=<kn>]
        naval_fate ship shoot <x> <y>
        naval_fate mine (set|remove) <x> <y> [--moored|--drifting]
        naval_fate -h | --help
        naval_fate --version

      Options:
        -h --help     Show this screen.
        --version     Show version.
        --speed=<kn>  Speed in knots [default: 10].
        --moored      Moored (anchored) mine.
        --drifting    Drifting mine.

      Trailing input: --speed:
      > ship foo move 10 10 --speed
                            ^^^^^^^
    ```

## Project goals ##

> Overview of the short- and longterm goals of this project

* Provide a declarative way to author command lines. Rather than deriving the
  help text from some EDSL, derive the CLI from a human readable, prose-like help
  text, located e.g. in the project's README. **This guarantees documentation and
  implementation never diverge, because they simply can't.**
* Provide **very good error reporting** for users of the CLI and at least decent
  error reporting for developers authoring the docopt text.
* The manually crafted docopt text must be **readable, standardised, yet
  flexible and powerful** enough to handle a fair set of use-cases.
* A solid interface for use in **regular javascript**. Purescript should merely
  be an implementation detail.
* **Solid test coverage**
* Sensible compatibility with original docopt.

### Deviations from the original ###

> This implementation tries to be compatible where sensible, but does cut ties
> when it comes down to it. The universal docopt test suite has been adjusted
> accordingly.

* **Better Error reporting.** Let the user of your utility know why his input
  was rejected.
* **No abbreviations:**
  `--ver` does not match `--verbose`.
  <sub>[(mis-feature in the original implementation)](https://github.com/docopt/docopt/issues/104)</sub>
* **Alias matches.** If `--verbose` yields a value, so will `-v` <sub>(given
  that's the assigned alias)</sub>. Likewise, `FOO` yields value `<foo>` as
  well as `FOO`, and `<foo>` yields `FOO` and `<foo>`.
* **Flags are optional,** always. There's no reason to force the user to
  explicitely pass an option that takes no argument. The absence of the flag
  speaks - the flag will be set to `false`. This is also the case for flags
  inside required groups. E.g.: The group `(-a -b)` will match inputs `-a -b`,
  `-ab`, `-ba`, `-b -a`, `-b`, `-a` and the empty input.
* **All arguments in a group are always required**. This is regardless of
  whether or not the group itself is required or not, i.e.:

  ```sh
  Usage: prog [<name> <type>]
  ```

  will fail `prog foo`, but pass `prog foo bar`. The rational being that this is
  more general, since if the opposite behaviour (any match) was desired, it
  could be expressed as such:

  ```sh
  Usage: prog [[<name>] [<type>]]
  ```

  **note:** this rule excludes flags/switches and options that have default
  values (or other fallback values).
* **There is no `null`** in the resulting value map. `null` simply means not
  matched - so the key is omitted from the resulting value map. <sub>(this is
  still under consideration)</sub>
* **Environment variables**. Options can fall back to environment variables,
  if they are not explicitely defined. The order of evaluation is:
{'fraction_non_alphanumeric': 0.1233074562195342, 'fraction_numerical': 0.003069146055244629, 'mean_word_length': 2.985251798561151, 'pattern_counts': {'":': 0, '<': 75, '<?xml version=': 0, '>': 93, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1101625', 'n_tokens_mistral': 3421, 'n_tokens_neox': 3261, 'n_words': 1360}