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");
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.
FlagSpec
One declared flag: its name without the --, its FLAG_* kind and its help.
FlagTable
The flags and commands of one program, declared in the order its help lists them.
ParsedFlags
What parse answered: a usage error, or every flag's value.
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.

