# `nupp.cli`
Command-line arguments, from raw tokens up to a whole application.
The usual way in is a record: the types decide the conversion, the doc comments
become the help text.
```nupp
local cli = require("nupp.cli")
@derive(cli.Arguments)
local record Options
--- Print more detail.
@cli(short = "v")
verbose: boolean = false
--- Output path.
@cli(short = "o", value = "PATH")
output: string?
--- Input files.
@cli(positional = "FILE")
files: {string} = {}
end
const options, problem = Options.fromCLI(arg)
assert(options ~= nil, problem and problem.message)
```
`@derive(cli.Command)` goes further and adds metadata, help, and shell
completion, with a parent naming its children in `subcommands` so the tree reads
from the top down. Underneath both, `optParser` and `getopt` are the
syntax-only foundation: a token stream with no types attached, for when the
shape of the command line is not a record.
This module also holds the terminal side of a command-line program -- color
modes, styles, and tables -- so what a command prints lines up with what it
parsed.
See
[Command-line applications](../../../learn/projects/command-line-applications/index.html).
## Types
### `Alignment` _type_
```nupp
type Alignment = "left" | "right"
```
How a cell sits in its column.
### `Application` _record_
```nupp
record Application ...
```
A finite tree of derived command types.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`root`](#nupp.cli.Application.root) | field | |
| [`commands`](#nupp.cli.Application.commands) | field | |
| [`byParent`](#nupp.cli.Application.byParent) | field | |
| [`options`](#nupp.cli.Application.options) | field | |
| [`resolve`](#nupp.cli.Application.resolve) | method | Resolves and decodes argv, without writing output or invoking run. |
| [`help`](#nupp.cli.Application.help) | method | Renders the application's top-level help. |
| [`commandHelp`](#nupp.cli.Application.commandHelp) | method | Renders help for a command path, or returns nil when it is unknown. |
| [`complete`](#nupp.cli.Application.complete) | method | Produces shell-neutral candidates for one cursor position. |
| [`completion`](#nupp.cli.Application.completion) | method | Renders a Bash, Zsh, or Fish completion script from this schema. |
| [`main`](#nupp.cli.Application.main) | method | Handles framework options, renders failures, and invokes a typed command. |
#### `root` _field_
```nupp
root: Descriptor
```
`@private`
#### `commands` _field_
```nupp
commands: {Descriptor}
```
`@private`
#### `byParent` _field_
```nupp
byParent: {[any]: {[string]: Descriptor}}
```
`@private`
#### `options` _field_
```nupp
options: ApplicationOptions
```
`@private`
#### `resolve` _method_
```nupp
resolve: function resolve(self, argv: {string}): Invocation?, any?
```
Resolves and decodes argv, without writing output or invoking `run`.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `argv` | `{string}` | |
##### Returns
| Type | Description |
| --- | --- |
| `Invocation?` | |
| `any?` | |
#### `help` _method_
```nupp
help: function help(self): string
```
Renders the application's top-level help.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `commandHelp` _method_
```nupp
commandHelp: function commandHelp(self, path: {string}): string?
```
Renders help for a command path, or returns nil when it is unknown.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `path` | `{string}` | |
##### Returns
| Type | Description |
| --- | --- |
| `string?` | |
#### `complete` _method_
```nupp
complete: function complete(self, request: any): {any}, string?
```
Produces shell-neutral candidates for one cursor position.
The second result is `"files"` or `"dirs"` when the slot is a path the shell
should complete itself.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `request` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `{any}` | |
| `string?` | |
#### `completion` _method_
```nupp
completion: function completion(self, shell: "bash" | "zsh" | "fish"): string
```
Renders a Bash, Zsh, or Fish completion script from this schema.
The script asks the program itself, through the hidden `__complete` command,
so what it offers depends on where the cursor is: one command's options rather
than every command's, and a value's choices rather than every word the grammar
knows. A reply whose first line is `:files` or `:dirs` hands the word to the
shell's own path completion.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `shell` | `"bash" | "zsh" | "fish"` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `main` _method_
```nupp
main: function main(self, argv: {string}): integer
```
Handles framework options, renders failures, and invokes a typed command.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `argv` | `{string}` | |
##### Returns
| Type | Description |
| --- | --- |
| `integer` | |
### `ApplicationOptions` _type_
```nupp
type ApplicationOptions = {
name: string?,
version: string?,
stdout: LuaFile?,
stderr: LuaFile?,
cwd: string?,
environment: {[string]: string}?,
width: integer?,
indent: string?,
labelLimit: integer?
}
```
Runtime-only settings for a CLI application.
### `ArgumentRecord` _interface_
```nupp
interface cliModule.ArgumentRecord
```
Marker implemented by a record deriving `Arguments`.
### `Cell` _record_
```nupp
record Cell ...
```
One cell.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`text`](#nupp.cli.Cell.text) | field | What the cell says. |
| [`paint`](#nupp.cli.Cell.paint) | field | Paints the text, overriding the column's painter for this cell alone. |
| [`note`](#nupp.cli.Cell.note) | field | An aside after the text, in its own color: a default a project moved off, a unit, a "(default)" beside the name it... |
| [`notePaint`](#nupp.cli.Cell.notePaint) | field | Paints the note. |
#### `text` _field_
```nupp
text: string
```
What the cell says.
#### `paint` _field_
```nupp
paint: (function(string): string)?
```
Paints the text, overriding the column's painter for this cell alone. How one
row reports a level in its own severity color while its neighbors do not.
#### `note` _field_
```nupp
note: string?
```
An aside after the text, in its own color: a default a project moved off, a
unit, a "(default)" beside the name it belongs to. Written separately because
it is painted separately, and measured with the text rather than after it, so
a column carrying one still lines up with the column beside it.
#### `notePaint` _field_
```nupp
notePaint: (function(string): string)?
```
Paints the note. Defaults to the style's `faint`, which is what an aside is.
### `ColorMode` _type_
```nupp
type ColorMode = "auto" | "always" | "never"
```
How terminal styling is selected.
### `Column` _record_
```nupp
record Column ...
```
One column.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`heading`](#nupp.cli.Column.heading) | field | What prints above it. |
| [`align`](#nupp.cli.Column.align) | field | Which side the padding goes on. |
| [`paint`](#nupp.cli.Column.paint) | field | Paints every cell in this column that does not paint itself. |
| [`minimumWidth`](#nupp.cli.Column.minimumWidth) | field | A floor on the width, for a column whose contents are shorter than what they will be once a row appears that fills it. |
#### `heading` _field_
```nupp
heading: string
```
What prints above it. An empty heading still reserves the column's width.
#### `align` _field_
```nupp
align: Alignment?
```
Which side the padding goes on. Numbers read as a column when they are
right aligned and as noise when they are not.
#### `paint` _field_
```nupp
paint: (function(string): string)?
```
Paints every cell in this column that does not paint itself.
#### `minimumWidth` _field_
```nupp
minimumWidth: integer?
```
A floor on the width, for a column whose contents are shorter than what
they will be once a row appears that fills it.
### `CommandType` _type_
```nupp
type cliModule.CommandType = Type
```
A record type deriving `Command`.
### `Completer` _interface_
```nupp
interface cliModule.Completer ...
```
A lazily invoked source of dynamic values for one CLI field.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`complete`](#nupp.cli.Completer.complete) | method | |
#### `complete` _method_
```nupp
complete: function(self, request: cliModule.CompletionRequest): {cliModule.CompletionCandidate}
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `self` | |
| `request` | `cliModule.CompletionRequest` | |
##### Returns
| Type | Description |
| --- | --- |
| `{cliModule.CompletionCandidate}` | |
### `CompletionCandidate` _record_
```nupp
record cliModule.CompletionCandidate ...
```
One shell-neutral completion candidate.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`value`](#nupp.cli.CompletionCandidate.value) | field | |
| [`description`](#nupp.cli.CompletionCandidate.description) | field | |
| [`kind`](#nupp.cli.CompletionCandidate.kind) | field | |
#### `value` _field_
```nupp
value: string
```
#### `description` _field_
```nupp
description: string?
```
#### `kind` _field_
```nupp
kind: "value" | "file" | "directory"?
```
### `CompletionRequest` _record_
```nupp
record cliModule.CompletionRequest ...
```
Context supplied to a dynamic field completion provider.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`prefix`](#nupp.cli.CompletionRequest.prefix) | field | |
| [`argv`](#nupp.cli.CompletionRequest.argv) | field | |
| [`wordIndex`](#nupp.cli.CompletionRequest.wordIndex) | field | |
| [`commandPath`](#nupp.cli.CompletionRequest.commandPath) | field | |
| [`field`](#nupp.cli.CompletionRequest.field) | field | |
| [`cwd`](#nupp.cli.CompletionRequest.cwd) | field | |
| [`environment`](#nupp.cli.CompletionRequest.environment) | field | |
#### `prefix` _field_
```nupp
prefix: string
```
#### `argv` _field_
```nupp
argv: {string}
```
#### `wordIndex` _field_
```nupp
wordIndex: integer
```
#### `commandPath` _field_
```nupp
commandPath: {string}
```
#### `field` _field_
```nupp
field: string
```
#### `cwd` _field_
```nupp
cwd: string
```
#### `environment` _field_
```nupp
environment: {[string]: string}
```
### `DecodeError` _type_
```nupp
type DecodeError = {
@readonly kind: string,
@readonly message: string,
@readonly index: integer?,
@readonly raw: string?,
@readonly option: string?,
@readonly field: string?,
@readonly destination: string?
}
```
### `Invocation` _record_
```nupp
record Invocation ...
```
A command type resolved and decoded without executing it.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`commandType`](#nupp.cli.Invocation.commandType) | field | |
| [`options`](#nupp.cli.Invocation.options) | field | |
| [`argv`](#nupp.cli.Invocation.argv) | field | |
| [`commandPath`](#nupp.cli.Invocation.commandPath) | field | |
#### `commandType` _field_
```nupp
commandType: any
```
#### `options` _field_
```nupp
options: any
```
#### `argv` _field_
```nupp
argv: {string}
```
#### `commandPath` _field_
```nupp
commandPath: {string}
```
### `OptParser` _record_
```nupp
record OptParser ...
```
An incremental command-line option parser.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`argv`](#nupp.cli.OptParser.argv) | field | |
| [`config`](#nupp.cli.OptParser.config) | field | |
| [`nextIndex`](#nupp.cli.OptParser.nextIndex) | field | |
| [`literal`](#nupp.cli.OptParser.literal) | field | |
| [`currentKind`](#nupp.cli.OptParser.currentKind) | field | |
| [`currentKey`](#nupp.cli.OptParser.currentKey) | field | |
| [`currentValue`](#nupp.cli.OptParser.currentValue) | field | |
| [`currentRaw`](#nupp.cli.OptParser.currentRaw) | field | |
| [`currentIndex`](#nupp.cli.OptParser.currentIndex) | field | |
| [`currentAttached`](#nupp.cli.OptParser.currentAttached) | field | |
| [`currentPattern`](#nupp.cli.OptParser.currentPattern) | field | |
| [`next`](#nupp.cli.OptParser.next) | method | Advances to the next token and returns its kind, or a syntax error. |
| [`kind`](#nupp.cli.OptParser.kind) | method | Returns the current token kind. |
| [`key`](#nupp.cli.OptParser.key) | method | Returns the current option's normalized key. |
| [`value`](#nupp.cli.OptParser.value) | method | Returns the current option's value, when it has one. |
| [`raw`](#nupp.cli.OptParser.raw) | method | Returns the original argv word for the current token. |
| [`index`](#nupp.cli.OptParser.index) | method | Returns the one-based argv index of the current token. |
| [`attached`](#nupp.cli.OptParser.attached) | method | Reports whether the current option carried an attached value. |
| [`pattern`](#nupp.cli.OptParser.pattern) | method | Reports whether the current option matched a configured whole-word form. |
| [`remaining`](#nupp.cli.OptParser.remaining) | method | Returns the unclassified suffix in its original order. |
| [`original`](#nupp.cli.OptParser.original) | method | Returns the original argv table. |
#### `argv` _field_
```nupp
argv: {string}
```
`@private`
#### `config` _field_
```nupp
config: OptParserConfig
```
`@private`
#### `nextIndex` _field_
```nupp
nextIndex: integer
```
`@private`
#### `literal` _field_
```nupp
literal: boolean
```
`@private`
#### `currentKind` _field_
```nupp
currentKind: TokenKind?
```
`@private`
#### `currentKey` _field_
```nupp
currentKey: string?
```
`@private`
#### `currentValue` _field_
```nupp
currentValue: string?
```
`@private`
#### `currentRaw` _field_
```nupp
currentRaw: string?
```
`@private`
#### `currentIndex` _field_
```nupp
currentIndex: integer
```
`@private`
#### `currentAttached` _field_
```nupp
currentAttached: boolean
```
`@private`
#### `currentPattern` _field_
```nupp
currentPattern: boolean
```
`@private`
#### `next` _method_
```nupp
next: function next(self): TokenKind?, SyntaxError?
```
Advances to the next token and returns its kind, or a syntax error.
Token data remains on this parser until the next call to `next`.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `TokenKind?` | |
| `SyntaxError?` | |
#### `kind` _method_
```nupp
kind: function kind(self): TokenKind
```
Returns the current token kind.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `TokenKind` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the parser has no current token |
#### `key` _method_
```nupp
key: function key(self): string
```
Returns the current option's normalized key.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the parser has no current token or it is not an option |
#### `value` _method_
```nupp
value: function value(self): string?
```
Returns the current option's value, when it has one.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `string?` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the parser has no current token or it is not an option |
#### `raw` _method_
```nupp
raw: function raw(self): string
```
Returns the original argv word for the current token.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the parser has no current token |
#### `index` _method_
```nupp
index: function index(self): integer
```
Returns the one-based argv index of the current token.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `integer` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the parser has no current token |
#### `attached` _method_
```nupp
attached: function attached(self): boolean
```
Reports whether the current option carried an attached value.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `boolean` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the parser has no current token or it is not an option |
#### `pattern` _method_
```nupp
pattern: function pattern(self): boolean
```
Reports whether the current option matched a configured whole-word form.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `boolean` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the parser has no current token or it is not an option |
#### `remaining` _method_
```nupp
remaining: function remaining(self): {string}
```
Returns the unclassified suffix in its original order.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `{string}` | |
#### `original` _method_
```nupp
original: function original(self): {string}
```
Returns the original argv table.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `{string}` | |
### `OptParserConfig` _type_
```nupp
type OptParserConfig = {
--- Value arity by normalized option name, without leading hyphens.
arity: {[string]: ValueArity}?,
--- Whole-word forms tried before ordinary short-option classification.
patterns: {Pattern}?,
--- Once the first argument is seen, expose every later word as an argument.
stopAtFirstArgument: boolean?,
--- Whether `--` itself is returned before its following arguments.
exposeTerminator: boolean?
}
```
Syntax policy supplied to `optParser`.
### `Pattern` _type_
```nupp
type Pattern = {
--- Lua pattern matched against the complete argv word.
pattern: string,
--- The normalized key exposed by the token.
key: string
}
```
One whole-word option form, such as `-O2`.
### `Runnable` _interface_
```nupp
interface cliModule.Runnable ...
```
The instance contract of a derived executable command.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`run`](#nupp.cli.Runnable.run) | method | |
#### `run` _method_
```nupp
run: function(self): integer
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `self` | |
##### Returns
| Type | Description |
| --- | --- |
| `integer` | |
### `Style` _record_
```nupp
record Style ...
```
Generic terminal styles shared by CLI applications and their commands.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`strong`](#nupp.cli.Style.strong) | method | |
| [`faint`](#nupp.cli.Style.faint) | method | |
| [`heading`](#nupp.cli.Style.heading) | method | A column heading, a section title: text that names what is beneath it rather than saying anything itself. |
| [`red`](#nupp.cli.Style.red) | method | |
| [`yellow`](#nupp.cli.Style.yellow) | method | |
| [`green`](#nupp.cli.Style.green) | method | |
| [`cyan`](#nupp.cli.Style.cyan) | method | |
| [`blue`](#nupp.cli.Style.blue) | method | |
| [`path`](#nupp.cli.Style.path) | method | |
| [`gutter`](#nupp.cli.Style.gutter) | method | |
| [`severity`](#nupp.cli.Style.severity) | field | |
#### `strong` _method_
```nupp
strong: function(string): string
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `string` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `faint` _method_
```nupp
faint: function(string): string
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `string` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `heading` _method_
```nupp
heading: function(string): string
```
A column heading, a section title: text that names what is beneath it rather
than saying anything itself. Named as a role rather than as a colour so the
one decision lives here instead of at every table that prints one.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `string` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `red` _method_
```nupp
red: function(string): string
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `string` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `yellow` _method_
```nupp
yellow: function(string): string
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `string` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `green` _method_
```nupp
green: function(string): string
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `string` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `cyan` _method_
```nupp
cyan: function(string): string
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `string` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `blue` _method_
```nupp
blue: function(string): string
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `string` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `path` _method_
```nupp
path: function(string): string
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `string` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `gutter` _method_
```nupp
gutter: function(string): string
```
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `string` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
#### `severity` _field_
```nupp
severity: {[string]: function(string): string}
```
### `SyntaxError` _record_
```nupp
record SyntaxError ...
```
A syntax failure found while consuming argv.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`kind`](#nupp.cli.SyntaxError.kind) | field | |
| [`index`](#nupp.cli.SyntaxError.index) | field | |
| [`raw`](#nupp.cli.SyntaxError.raw) | field | |
| [`key`](#nupp.cli.SyntaxError.key) | field | |
| [`message`](#nupp.cli.SyntaxError.message) | field | |
#### `kind` _field_
```nupp
kind: "missingValue" | "needsAttachedValue"
```
#### `index` _field_
```nupp
index: integer
```
#### `raw` _field_
```nupp
raw: string
```
#### `key` _field_
```nupp
key: string
```
#### `message` _field_
```nupp
message: string
```
### `TableOptions` _record_
```nupp
record TableOptions ...
```
What to render.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`columns`](#nupp.cli.TableOptions.columns) | field | |
| [`rows`](#nupp.cli.TableOptions.rows) | field | Rows, each as many cells as there are columns. |
| [`style`](#nupp.cli.TableOptions.style) | field | Where the heading color and any cell colors come from. |
| [`headingPaint`](#nupp.cli.TableOptions.headingPaint) | field | Paints the heading row. |
| [`gap`](#nupp.cli.TableOptions.gap) | field | Printed between columns. |
| [`indent`](#nupp.cli.TableOptions.indent) | field | Printed before every line, heading included. |
| [`showHeading`](#nupp.cli.TableOptions.showHeading) | field | Whether to print the heading row at all. |
| [`width`](#nupp.cli.TableOptions.width) | field | Columns available on screen. |
#### `columns` _field_
```nupp
columns: {Column}
```
#### `rows` _field_
```nupp
rows: {{Cell}}
```
Rows, each as many cells as there are columns. A short row is padded with
blanks rather than refused, so a caller may leave a trailing cell out.
#### `style` _field_
```nupp
style: Style?
```
Where the heading color and any cell colors come from. Supply the style
selected for the stream being written to; omit it and nothing is painted.
#### `headingPaint` _field_
```nupp
headingPaint: (function(string): string)?
```
Paints the heading row. Defaults to the style's `heading` role.
#### `gap` _field_
```nupp
gap: string?
```
Printed between columns. Two spaces unless a caller says otherwise.
#### `indent` _field_
```nupp
indent: string?
```
Printed before every line, heading included.
#### `showHeading` _field_
```nupp
showHeading: boolean?
```
Whether to print the heading row at all.
#### `width` _field_
```nupp
width: integer?
```
Columns available on screen. The last column is cut to fit rather than left
to wrap. Nil cuts nothing, which is what a pipe wants.
### `TokenKind` _type_
```nupp
type TokenKind = "shortOption" | "longOption" | "argument" | "terminator"
```
The kind of one classified argv word.
### `ValueArity` _type_
```nupp
type ValueArity = "none" | "required" | "optionalAttached" | "attachedOnly"
```
How an option obtains a value.
## Functions
### `cliModule.annotatedCell` _function_
```nupp
function cliModule.annotatedCell(value: string, note: string, paint: (function(string): string)?): cliModule.Cell
```
A table cell carrying an aside, measured with the cell and painted apart
from it.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | |
| `note` | `string` | |
| `paint` | `(function(string): string)?` | |
#### Returns
| Type | Description |
| --- | --- |
| `cliModule.Cell` | |
### `cliModule.application` _function_
```nupp
function cliModule.application(rootType: Type, options: cliModule.ApplicationOptions?): cliModule.Application
```
Builds an application from a command type and its `subcommands` tree.
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `rootType` | `Type\` | |
| `options` | `cliModule.ApplicationOptions?` | |
#### Returns
| Type | Description |
| --- | --- |
| `cliModule.Application` | |
### `cliModule.Arguments` _comptime function_
```nupp
@comptime function cliModule.Arguments(info: nupp.derive.Info): nupp.derive.Result
```
`@comptime`
Derives typed argv decoding for a record.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `info` | `nupp.derive.Info` | |
#### Returns
| Type | Description |
| --- | --- |
| `nupp.derive.Result\` | |
### `cliModule.cell` _function_
```nupp
function cliModule.cell(value: string): cliModule.Cell
```
A plain table cell.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | |
#### Returns
| Type | Description |
| --- | --- |
| `cliModule.Cell` | |
### `cliModule.colorEnabled` _function_
```nupp
function cliModule.colorEnabled(stream: LuaFile): boolean
```
Reports whether escapes should be written to one stream.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `stream` | `LuaFile` | |
#### Returns
| Type | Description |
| --- | --- |
| `boolean` | |
### `cliModule.columns` _function_
```nupp
function cliModule.columns(stream: LuaFile): integer?
```
Reports how many columns one stream's terminal has, when it has one.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `stream` | `LuaFile` | |
#### Returns
| Type | Description |
| --- | --- |
| `integer?` | |
### `cliModule.Command` _comptime function_
```nupp
@comptime function cliModule.Command(info: nupp.derive.Info): nupp.derive.Result
```
`@comptime`
Derives typed argv decoding and a self-describing executable command.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `info` | `nupp.derive.Info` | |
#### Returns
| Type | Description |
| --- | --- |
| `nupp.derive.Result\` | |
### `cliModule.command` _function_
```nupp
function cliModule.command(subject: Type): table?, string?
```
Returns the descriptor generated for a command type.
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `subject` | `Type\` | |
#### Returns
| Type | Description |
| --- | --- |
| `table?` | |
| `string?` | |
### `cliModule.decodeAs` _function_
```nupp
function cliModule.decodeAs(subject: Type, argv: {string}): T?, cliModule.DecodeError?
```
Decodes argv as a record deriving `Arguments` or `Command`.
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `subject` | `Type\` | |
| `argv` | `{string}` | |
#### Returns
| Type | Description |
| --- | --- |
| `T?` | |
| `cliModule.DecodeError?` | |
### `cliModule.isTerminal` _function_
```nupp
function cliModule.isTerminal(stream: LuaFile): boolean
```
Reports whether one stream is connected to a terminal.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `stream` | `LuaFile` | |
#### Returns
| Type | Description |
| --- | --- |
| `boolean` | |
### `cliModule.paintedCell` _function_
```nupp
function cliModule.paintedCell(value: string, paint: function(string): string): cliModule.Cell
```
A table cell that paints itself, whatever its column says.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | |
| `paint` | `function(string): string` | |
#### Returns
| Type | Description |
| --- | --- |
| `cliModule.Cell` | |
### `cliModule.schema` _function_
```nupp
function cliModule.schema(subject: Type): table?
```
Returns the CLI schema carried by a derived type.
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `subject` | `Type\` | |
#### Returns
| Type | Description |
| --- | --- |
| `table?` | |
### `cliModule.setColorMode` _function_
```nupp
function cliModule.setColorMode(wanted: cliModule.ColorMode): nil
```
Sets the process-wide default color policy.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `wanted` | `cliModule.ColorMode` | |
#### Returns
| Type | Description |
| --- | --- |
| `nil` | |
### `cliModule.severity` _function_
```nupp
function cliModule.severity(styles: cliModule.Style, name: string?): function(string): string
```
Selects the color associated with a diagnostic severity.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `styles` | `cliModule.Style` | |
| `name` | `string?` | |
#### Returns
| Type | Description |
| --- | --- |
| `function(string): string` | |
### `cliModule.style` _function_
```nupp
function cliModule.style(stream: LuaFile): cliModule.Style
```
Returns the generic styles selected for one stream.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `stream` | `LuaFile` | |
#### Returns
| Type | Description |
| --- | --- |
| `cliModule.Style` | |
### `cliModule.table` _function_
```nupp
function cliModule.table(options: cliModule.TableOptions): string
```
Renders aligned columns, painting each cell after it is padded.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `options` | `cliModule.TableOptions` | |
#### Returns
| Type | Description |
| --- | --- |
| `string` | |
### `cliModule.withColorMode` _function_
```nupp
function cliModule.withColorMode(wanted: cliModule.ColorMode, body: function(): nil): nil
```
Runs a body under one color policy and restores the previous policy.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `wanted` | `cliModule.ColorMode` | |
| `body` | `function(): nil` | |
#### Returns
| Type | Description |
| --- | --- |
| `nil` | |
### `cliModule.writeTable` _function_
```nupp
function cliModule.writeTable(stream: LuaFile, options: cliModule.TableOptions): nil
```
Renders aligned columns straight to a stream.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `stream` | `LuaFile` | |
| `options` | `cliModule.TableOptions` | |
#### Returns
| Type | Description |
| --- | --- |
| `nil` | |