nish/cli-args
A command tree for a large command-line tool: declared once with a builder, parsed in one walk over the arguments, and answered as the matched command's id and every value with where it came from.
import {
Cli,
PARSE_ERROR,
PARSE_HELP,
PARSE_OK,
PARSE_VERSION,
ParseResult,
ROOT,
SOURCE_ARGV,
SOURCE_DEFAULT,
SOURCE_UNSET,
finish,
} from "nish/cli-args";
import { Cli, ROOT, finish } from "nish/cli-args";
import { Style } from "nish/cli";
const cli = new Cli("api", "1.4.0", "Talk to the Example API");
const raw = cli.globalFlag("-r, --raw-output", "print JSON as it arrives");
const users = cli.group(ROOT, "users", "Manage users");
const list = cli.command(users, "list", 1, "List users");
const limit = cli.flag(list, "-l, --limit <n>", "at most n users");
const r = cli.parse(process.argv, 1);
finish(r, new Style(false, false), new Style(false, false));
if (r.id === 1) console.log(r.value(limit) ?? "all");
finish
Acts on r for a program: help (painted with outStyle) or the version on standard output and exit 0; an error line and the hint on standard error and exit 2, the hint's command painted with errStyle, the error never; answers 0 for PARSE_OK, which the program goes on to run.
Cli
A command tree: groups, which only hold commands, and leaf commands, which a program runs, each with its flags and positional arguments.
ParseResult
What Cli.parse found: the command the arguments name and every value they set, or that they ask for help or the version, or what is wrong with them.
A builder, not a table
Nish has no function values, so a command cannot carry its handler; what a builder gives instead is a handle for every command, flag and argument, so the program reads a value by the handle it declared rather than by a name a typo can miss, and every declaration mistake panics at the call that made it.
What it costs
Declaring is linear in the declarations and builds no help text. Parsing walks the arguments once, with one map lookup per token, and keeps only what the arguments set; help text, did-you-mean and the error wording are built only on the help and error paths.
What it reaches
Nothing: parse reads only the array it is given,
and only finish writes (to standard output or standard error) and exits.
Functions
finish
Acts on r for a program: help (painted with outStyle) or the version on
standard output and exit 0; an error line and the hint on standard error
and exit 2, the hint's command painted with errStyle, the error never;
answers 0 for PARSE_OK, which the program goes on to run.
const finish: (
r: ParseResult,
outStyle: Style,
errStyle: Style,
) => i32
rParseResultrequiredthe answer of Cli.parse
outStyleStylerequiredhow help on standard output is painted
errStyleStylerequired
how the hint's <path> --help on standard error is
painted
returnsi320, and only for PARSE_OK: every other kind exits instead
Classes
Cli
A command tree: groups, which only hold commands, and leaf commands, which
a program runs, each with its flags and positional arguments. Every
declaration answers a handle (an i32) that parse's answer is read by.
class Cli
| Member | |
|---|---|
new Cli(name: string, version: string, description: string) |
A tree with only its root, the program name at version, for description. |
alias(handle: i32, name: string): void |
Another name for the command or group handle, in the same scope. |
argument(cmd: i32, spec: string, description: string): i32 |
A positional argument of the command cmd: <name> required, [name] optional, <name...> or [name...] taking every one left, last only. |
command(parent: i32, name: string, id: i32, description: string): i32 |
A command under parent that the program runs, answered by id in ParseResult.id: not negative, which is a group's, and no other command's. |
defaultValue(f: i32, value: string): void |
The value flag f answers when it is not given. |
epilog(handle: i32, text: string): void |
Text shown at the end of the help of handle (a command or group), as given. |
flag(cmd: i32, spec: string, description: string): i32 |
A flag the command or group cmd takes, and no other. |
globalFlag(spec: string, description: string): i32 |
A flag every command takes, before, between or after the command names. |
group(parent: i32, name: string, description: string): i32 |
A group under parent: it holds commands, and naming it without one is an error. |
helpText(handle: i32, style: Style): string |
The help of the command or group handle, painted with style. |
negatable(f: i32): void |
Adds --no-x to the boolean flag --x, which turns it back off. |
parse(argv: string[], start: i32): ParseResult |
Parses argv from index start (1 for process.argv, past the program's path) in one walk over it. |
repeatable(f: i32): void |
Makes f gather every value it is given, in order, for ParseResult.values. |
required(f: i32): void |
Makes f an error to leave out, for the command that owns it (every command, for a global); a group's flag cannot be, as no parse ends at one. |
ParseResult
What Cli.parse found: the command the arguments name and every value
they set, or that they ask for help or the version, or what is wrong with
them. Values are read by the handles the tree was declared with.
class ParseResult
| Member | |
|---|---|
new ParseResult(cli: Cli) |
An answer that has read nothing: kind PARSE_OK at ROOT with no values. Cli.parse makes one and fills it in; a program gets its answer from there rather than building one. |
command: i32 |
The handle of the deepest command the arguments reached. |
errorPath: string |
The command line of the command an error was found at; empty without one. |
exitCode: i32 |
The status to exit with: 2 for an error, 0 otherwise. |
hint: string |
The line after an error that says where the usage is; empty without one. |
id: i32 |
That command's id, or -1 for a group. |
kind: i32 |
PARSE_OK, PARSE_HELP, PARSE_VERSION or PARSE_ERROR. |
message: string |
The error line for PARSE_ERROR, the version line for PARSE_VERSION, else empty. |
path: string |
The command line that names it: api users keys list. |
flag(f: i32): boolean |
Whether flag f is on: a boolean's value (true by default for one declared --no-x), or for a flag with a value, whether it was given. |
help(style: Style): string |
The help of the command the arguments reached, painted with style. |
positional(a: i32): string | null |
The argument a's value, or null when it was not given or belongs to another command. |
positionals(a: i32): string[] |
Every value from argument a on: all a variadic one took, or the one value of any other. |
rest(): string[] |
The tokens after --, in order. They are positionals too, so an argument may also have taken them. |
source(f: i32): i32 |
Where flag f's value came from: SOURCE_ARGV, SOURCE_DEFAULT or SOURCE_UNSET. |
value(f: i32): string | null |
The value of flag f: the last one given (empty for [value] given none), else its default, else null. |
values(f: i32): string[] |
Every value of flag f in order for a repeatable one, the last alone for any other, else its default alone, else none. |
Constants
3
PARSE_ERROR: i32
ParseResult.kind: the arguments are wrong; message says how.
1
PARSE_HELP: i32
ParseResult.kind: -h, --help or help <path> asked for help.
0
PARSE_OK: i32
ParseResult.kind: the arguments name a command to run.
2
PARSE_VERSION: i32
ParseResult.kind: -v or --version at the root asked for the version.
0
ROOT: i32
The handle of the tree's root, the program itself.
0
SOURCE_ARGV: i32
ParseResult.source: the value was given on the command line.
1
SOURCE_DEFAULT: i32
ParseResult.source: the value is the declared default.
2
SOURCE_UNSET: i32
ParseResult.source: the flag was not given and has no default.

