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");
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
rParseResultrequired

the answer of Cli.parse

outStyleStylerequired

how help on standard output is painted

errStyleStylerequired

how the hint's <path> --help on standard error is painted

returnsi32

0, 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.