argument-parser/README.md

# argument-parser

This module parses the command line arguments into a JavaScript object, and verifies that they match the given specification. It checks that all required options are set, that no unknown options are used, and optionally that the arguments match a given pattern.

The main goal is to keep all the complexity and error handling inside this module, so that all command line applications only need to provide a couple lines of specification and do not have to worry about verifying the input or checking for `undefined`.

## Installation

For this tool to work, the TypeScript compiler must be globally installed:

```bash
sudo npm install -g typescript
```

In the project where you want to use this library, add the following to your `package.json` file:

```json
{
  "dependencies": {
    "argument-parser": "git+https://git.jedipedia.net/swtor/argument-parser.git"
  }
}
```

Then run:

```bash
npm install
```

## Usage

This example shows how to use this module to check the arguments against a specification.

```ts
#!/usr/bin/env node

import parseArguments from 'argument-parser';

/**
 * Check that arguments match the specification and stop execution on error.
 * Then parse the arguments into the `args` object.
 * The `fail()` function can be used to print an error message and will then
 * terminate execution.
 * Two options are allowed: --input and --size, or their short forms -i and -s.
 * --input is required, while --size is optional and defaults to "0".
 */
const { args, fail } = parseArguments({
  input: {
    short: 'i',
    description: 'Path to the input file'
  },
  size: {
    default: '0',
    short: 's',
    description: 'Size of the file, must be a non-negative integer',
    verify: str => str.match(/^[0-9]+$/) !== null
  }
});

try {
  console.log(args.input, args.size);
  //Do something based on the arguments...
} catch (error) {
  fail(`Error during execution: ${String(error)}`);
}
```

When called correctly from the command line, it prints the following:

```bash
$ ./index.js --input data.bin --size 1024
data.bin 1024
```

In case of an error, it prints an error message as well as the correct usage instructions, and then terminates with a non-zero exit code.

```bash
$ node index.js --wrong-option foobar
Error: Unknown option "--wrong-option".
Usage: ./index.js [options]
OPTIONS
  -i, --input <value>
      Path to the input file
  [-s, --s <value>], defaults to "0"
      Size of the file, must be a non-negative integer
```

## License

Copyright (C) 2018-2019 Jedipedia.net

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.