Dispute
A tool for building command line interfaces.
## Purpose
Dispute is a modern alternative to
[commander](https://www.npmjs.com/package/commander) and
[yargs](https://www.npmjs.com/package/yargs). While it supports all the usual
CLI features (subcommands, validation, help page generation, etc), dispute
focuses on two main qualities:
- **Reusability**: commands are just functions, and can be used outside the framework.
- **Testability**: dispute exposes an interface that makes testing a breeze (both unit & integration style).
## Example
Say you're building a command-line interface that reads and validates a config
file. Here's how it might look with dispute:
```js
#!/usr/bin/env node
import { createCli, ExitCode } from 'dispute'
import pkg from '../package.json'
import fs from 'fs-extra'
const cli = createCli({
commandName: 'validate-config',
packageJson: pkg,
cli: {
args: '[config-file]',
async command(options, configFile = '.config.json') {
const contents = await fs.readFile(configFile, 'utf8')
const validationWarnings = validateFile(contents)
if (!validationWarnings) {
console.log("Hooray, it's valid!")
return
}
console.log('Sorry, that looks invalid :(')
console.log(validationWarnings)
throw new ExitCode(1)
},
},
})
cli.execute()
```
`cli.execute()` is what actually runs your CLI. It parses, validates, & runs
the command using `process.argv`.
For more examples, browse [the `examples/`
folder](https://github.com/PsychoLlama/dispute/tree/master/src/examples).
## API
### Table of Contents
- [`createCli(...)`](#createcli)
- [`.execute(...)`](#createcliexecute)
- [`.createTestInterface(...)`](#createclicreatetestinterface)
- [`.createApi(...)`](#createclicreateapi)
- [`ExitCode(...)`](#exitcode)
### `createCli(...)`
Validates the given config and returns a few different ways to interact with
the CLI. Most of this section is about the config format and how to structure
your commands.
The config consists of two parts: metadata and commands. The metadata is made
up of your package.json file and the name of your command (i.e. how your users
will call it). Those are the only required fields.
```js
// This is the simplest possible config.
createCli({
commandName: 'eslint',
packageJson: require('../package.json'),
})
```
> **Note:** `package.json` is used to print the version number. Other fields
> like `homepage` or `bugs.url` might be used in the future.
Next, you tell dispute what commands are supported using `config.cli`. Every
command has the same format:
```js
{
// This is what gets called.
command: undefined || Function,
// What flags does the command support? e.g. '--port=3000' or '--color'
options: undefined || Object,
// What arguments does the command accept?
args: undefined || string,
// An optional command description printed with the --help flag.
description: undefined || string,
// Any nested commands... more on this later.
subCommands: undefined || Object,
}
```
Most of these are optional. The only exception is `command` and `subCommands`.
You can specify either or both, but at least one must be provided. Let's look
at `.command` first.
Commands take an options object (defined by `.options`) followed by any number
of arguments (defined by `.args`). If no options are defined, `options` will
always be an empty object.
```js
{
command(options, ...args) {
// options: {}
// args: []
}
}
```
Options are a mapping between option names and how they should be parsed.
Here's the high-level structure:
```js
{
// How should the user pass these options?
usage: string,
// If the option accepts an argument, how should it be parsed?
// By default arguments are interpreted as plain strings.
parseValue: undefined || Function
// Optionally show this description in the --help page.
description: undefined || string,
}
```
`usage` defines how the flags are named and whether an argument is allowed. It
looks something like this:
```js
{
usage: '-p, --port 
