nish/cli-flags

A command line's flags, declared once as data and read back by name, with the same declaration writing the --help rows.

import {
  CommandSpec,
  FLAG_BOOLEAN,
  FLAG_ERR_BOOLEAN_VALUE,
  FLAG_ERR_MISSING_VALUE,
  FLAG_ERR_NOT_A_NUMBER,
  FLAG_ERR_REPEATED,
  FLAG_ERR_UNKNOWN,
  FLAG_ERR_UNKNOWN_COMMAND,
  FLAG_NUMBER,
  FLAG_OK,
  FLAG_REPEATABLE,
  FLAG_STRING,
  FlagSpec,
  FlagTable,
  ParsedFlags,
} from "nish/cli-flags";
import { FlagTable } from "nish/cli-flags";

const flags = new FlagTable("git-lite");
flags.command("remote add", "<name> <url>", "add a remote");
flags.string("output", "<file>", "where to write");
flags.number("jobs", "<n>", "parallel jobs");
flags.boolean("verbose", "say more");
flags.repeatable("include", "<dir>", "search here too");
const got = flags.parseFrom(process.argv, 1);
if (!got.ok) { got.exitUsage(); }
got.command;                      // "remote add", or "" for none
got.str("output"); got.num("jobs"); got.bool("verbose"); got.all("include");
No function values

A flag is a name, a kind, a placeholder and a line of help, and the program asks the parse for a value by name afterwards, so the table is plain data the help menu can read too (writeHelp).

The grammar

The grammar is the GNU long-option one without the short options: --name value and --name=value for a string, number or repeatable flag, --name and --no-name for a boolean, -- ending the flags, and a lone - an ordinary word. Words that are not flags may come before, between or after them; the leading ones choose the command, the longest declared path they spell, and the rest are positionals. A flag belongs to the whole table, not to one command: a program that wants --force only under remote add checks command itself.

A usage error is an answer, not a panic

parse stops at the first one and the result carries it as data (code, message, argument), so a program can test it or word it its own way; exitUsage is the usual ending, the message on stderr and exit status 2, the convention nish itself keeps. Asking for a flag the table does not declare, or as the wrong kind, is a bug in the program rather than in its command line, and panics.

What it reaches

Nothing but exitUsage, which reaches exit.

Classes

CommandSpec

One declared command: its path as the words a person types, those words split once so that matching does not split them per parse, and its help.

class CommandSpec
Member
new CommandSpec(path: string, words: string[], shape: string, description: string) A command record as FlagTable stores it. A program declares commands through FlagTable.command instead, which splits and checks the path; this constructor checks nothing.

FlagSpec

One declared flag: its name without the --, its FLAG_* kind and its help.

class FlagSpec
Member
new FlagSpec(name: string, kind: i32, meta: string, description: string) A flag record as FlagTable stores it. A program declares flags through the table's string, number, boolean and repeatable instead, which check the name first; this constructor checks nothing.

FlagTable

The flags and commands of one program, declared in the order its help lists them. Each declaring method panics on a name no command line could match (empty, a leading -, an = or whitespace in a flag name), one declared twice, or a no-x beside a boolean x, because the table is the program's own text and a mistake there is a bug.

class FlagTable
Member
new FlagTable(program: string) An empty table: no flags and no commands until the declaring methods add them.
boolean(name: string, description: string): void A boolean flag: --name sets it, --no-name clears it, once.
command(path: string, shape: string, description: string): void A command: path is one or more words ("remote add"), shape what follows them in the help ("<name> <url>", may be empty). Declaring any command makes leading words that spell none a usage error.
number(name: string, meta: string, description: string): void A number flag, read as an f64: a finite decimal (-2.5, 1e3, .5), the same on every target. Hex, binary, Infinity, padding and "" are usage errors.
parse(args: string[]): ParsedFlags args read against the table, every one of them an argument: parseFrom(args, 0).
parseFrom(args: string[], first: i32): ParsedFlags args from index first on read against the table, so that a program passes process.argv and 1 to skip its own path. Stops at the first usage error, which the answer then carries; the command is still matched on the words read before it, so the usage hint can name it.
repeatable(name: string, meta: string, description: string): void A flag given any number of times, each with a value.
string(name: string, meta: string, description: string): void A string flag: --name value or --name=value, once.
writeHelp(menu: HelpMenu): void The table as help rows: a Commands section when any command is declared (its path, shape and description), then a Flags section, each in declaration order. The menu's header and usage lines are the caller's, written before this.

ParsedFlags

What parse answered: a usage error, or every flag's value. Values sit in arrays parallel to the table's flags: counts says how often each was given, texts and numbers hold a string or number flag's value, bools a boolean's and lists a repeatable flag's values in the order given. A flag that was not given reads as "", 0, false or no values; has tells that apart from one given as such.

class ParsedFlags
Member
new ParsedFlags(table: FlagTable) An answer with no error and every flag unset, which FlagTable.parseFrom then fills in. A program gets one from parse rather than building it.
argument: string The argument the error was found in, as given (--x=1 whole), or for a number flag the bad value alone and for an unknown command the words shown in the message; "" when ok.
bools: boolean[] Each boolean flag's value, false when not given.
code: i32 FLAG_OK, or the FLAG_ERR_* kind of the first usage error.
command: string The path of the command the leading words chose, or "" for none.
counts: i32[] How many times each flag was given, indexed like the table's flags.
lists: string[][] Each repeatable flag's values in the order given; empty when not given.
message: string The usage error in words, such as unknown flag --x; "" when ok.
numbers: f64[] Each number flag's value, 0 when not given.
ok: boolean Whether the parse found no usage error; false means code names one.
positionals: string[] The words that are not flags, values or the command's path, in order, then every argument after --. On a usage error, only those among the arguments read before the parse stopped.
texts: string[] Each string or number flag's value as written, "" when not given.
all(name: string): string[] Every value a repeatable flag was given, in order; empty when it was not given.
bool(name: string): boolean A boolean flag's value: true for --name, false for --no-name or when it was not given.
exitUsage(): void The usage error on stderr, then exit status 2. On a parse that succeeded it panics: there is no error to report.
has(name: string): boolean Whether the flag name, of any kind, was given at all (--no-name counts).
num(name: string): f64 A number flag's value, or 0 when it was not given.
str(name: string): string A string flag's value, or "" when it was not given.
usageError(): string What exitUsage prints: <program>: <message> and the usage line, each ending in a newline.

Constants

2

FLAG_BOOLEAN: i32

A flag that takes no value: --name is true and --no-name false, read with bool.

5

FLAG_ERR_BOOLEAN_VALUE: i32

--name=value (or --no-name=value) on a boolean.

2

FLAG_ERR_MISSING_VALUE: i32

A flag that takes a value, last on the line with no =.

3

FLAG_ERR_NOT_A_NUMBER: i32

A number flag's value that is not one finite number.

4

FLAG_ERR_REPEATED: i32

A flag that is not repeatable, given a second time (for a boolean, in either spelling).

1

FLAG_ERR_UNKNOWN: i32

A --name the table does not declare, or a short option (-v), which the grammar does not have.

6

FLAG_ERR_UNKNOWN_COMMAND: i32

Leading words that spell no declared command, when the table declares any.

1

FLAG_NUMBER: i32

A flag whose one value is a number, read with num.

0

FLAG_OK: i32

ParsedFlags.code for a parse with no usage error.

3

FLAG_REPEATABLE: i32

A flag that takes a value each time it is given, every one kept in order, read with all.

0

FLAG_STRING: i32

A flag that takes one value, read with str.