commandsnamespacenamespace commandsA command tree declared once as data (commons 0001-terminal FR-002): a command of groups and verbs to any depth, each with a name and a summary, and each verb with its options (./args.ts's declaration) and its arguments. From that declaration alone it resolves an argument vector to the verb it names, to the help asked for, or to a typed error that names the word not known, where, the words known there and the nearest of them; and it renders the help of every level, so that help never runs a verb.
A group named with no verb asks for its help, as git remote with no verb would list; --help or -h anywhere before -- asks for the help of the deepest group or verb named before it. Unknown options of a verb are its own parser's business (parseArgs), which the verb runs on the arguments left to it.
import { group, resolveCommand, verb } from "./commands.ts";
const tree = group({ name: "tool", summary: "A tool.", children: [group({ name: "work", summary: "Works.", children: [
verb({ name: "build", summary: "Build.", options: {} }),
] })] });
resolveCommand(tree, ["work", "build", "a"]); // ok: the verb build, with ["a"] left
resolveCommand(tree, ["wrk"]); // err: wrk is not known at the top, did you mean work?commandsnamespacenamespace commandscommands.Exampletypeno test imports ittype Example = { readonly args: readonly string[]; readonly says: string };An example of a verb: the words after the verb, and what it does.
commands.Verbtypeno test imports ittype Verb<S extends Spec = Spec> = {
readonly kind: "verb";
readonly name: string;
readonly summary: string;
readonly options: S;
readonly operands: readonly Operand[];
readonly examples: readonly Example[];
};A verb: a leaf of the tree, with the options and arguments it takes.
commands.Grouptypeno test imports ittype Group = {
readonly kind: "group";
readonly name: string;
readonly summary: string;
readonly children: readonly CommandNode[];
};A group: a word that names more words, groups or verbs.
commands.CommandNodetypeno test imports ittype CommandNode = Group | Verb;One node of a command tree.
commands.verbfunctionno test imports itfunction verb<S extends Spec>(v: { readonly name: string; readonly summary: string; readonly options: S & SpecCheck<S>; readonly operands?: readonly Operand[] | undefined; readonly examples?: readonly Example[] | undefined; }): Verb<S>A verb, declared with its options checked as parseArgs checks them.
commands.groupfunctionno test imports itfunction group(g: { readonly name: string; readonly summary: string; readonly children: readonly CommandNode[]; }): GroupA group of nodes.
commands.validCommandNamefunctionno test imports itfunction validCommandName(name: string): booleanWhether a name is one a command may have: lower case letters, digits and dashes, beginning with a letter.
commands.TreeProblemtypeno test imports ittype TreeProblem =
| { readonly kind: "bad-name"; readonly path: readonly string[]; readonly name: string }
| { readonly kind: "duplicate"; readonly path: readonly string[]; readonly name: string };What is wrong with a declared tree: a name that may not be one, or two children of a group with the same name.
commands.treeProblemsfunctionno test imports itfunction treeProblems(root: CommandNode, path?: readonly string[]): readonly TreeProblem[]Every problem of a tree, in the order of its nodes; none where it is well formed.
commands.Resolvedtypeno test imports ittype Resolved =
| { readonly kind: "verb"; readonly path: readonly string[]; readonly verb: Verb; readonly args: readonly string[] }
| { readonly kind: "help"; readonly path: readonly string[]; readonly node: CommandNode };What an argument vector names: a verb with the arguments left for it, or the help of a node.
commands.CommandErrortypeno test imports ittype CommandError = {
readonly kind: "unknown-command";
readonly path: readonly string[];
readonly word: string;
readonly known: readonly string[];
readonly suggestion: string | undefined;
};Why an argument vector names nothing: a word not known below path, the words known there, and the nearest.
commands.asksForHelpfunctionno test imports itfunction asksForHelp(word: string): booleanWhether a word asks for help.
commands.resolveCommandfunctionno test imports itfunction resolveCommand(root: Group, argv: readonly string[]): Result<Resolved, CommandError>Resolves an argument vector (the words after the program's name) against a tree whose root is the program.
commands.formatCommandErrorfunctionno test imports itfunction formatCommandError(e: CommandError): stringA command error as one sentence, with the help to run next.
commands.commandHelpfunctionno test imports itfunction commandHelp(path: readonly string[], node: CommandNode): stringThe help of a node at path (the words that name it, the program's first), from its declaration alone.
Exampletypeno test imports ittype Example = { readonly args: readonly string[]; readonly says: string };An example of a verb: the words after the verb, and what it does.
Verbtypeno test imports ittype Verb<S extends Spec = Spec> = {
readonly kind: "verb";
readonly name: string;
readonly summary: string;
readonly options: S;
readonly operands: readonly Operand[];
readonly examples: readonly Example[];
};A verb: a leaf of the tree, with the options and arguments it takes.
Grouptypeno test imports ittype Group = {
readonly kind: "group";
readonly name: string;
readonly summary: string;
readonly children: readonly CommandNode[];
};A group: a word that names more words, groups or verbs.
CommandNodetypeno test imports ittype CommandNode = Group | Verb;One node of a command tree.
verbfunctionfunction verb<S extends Spec>(v: { readonly name: string; readonly summary: string; readonly options: S & SpecCheck<S>; readonly operands?: readonly Operand[] | undefined; readonly examples?: readonly Example[] | undefined; }): Verb<S>A verb, declared with its options checked as parseArgs checks them.
groupfunctionfunction group(g: { readonly name: string; readonly summary: string; readonly children: readonly CommandNode[]; }): GroupA group of nodes.
validCommandNamefunctionfunction validCommandName(name: string): booleanWhether a name is one a command may have: lower case letters, digits and dashes, beginning with a letter.
TreeProblemtypeno test imports ittype TreeProblem =
| { readonly kind: "bad-name"; readonly path: readonly string[]; readonly name: string }
| { readonly kind: "duplicate"; readonly path: readonly string[]; readonly name: string };What is wrong with a declared tree: a name that may not be one, or two children of a group with the same name.
treeProblemsfunctionfunction treeProblems(root: CommandNode, path?: readonly string[]): readonly TreeProblem[]Every problem of a tree, in the order of its nodes; none where it is well formed.
Resolvedtypeno test imports ittype Resolved =
| { readonly kind: "verb"; readonly path: readonly string[]; readonly verb: Verb; readonly args: readonly string[] }
| { readonly kind: "help"; readonly path: readonly string[]; readonly node: CommandNode };What an argument vector names: a verb with the arguments left for it, or the help of a node.
CommandErrortypeno test imports ittype CommandError = {
readonly kind: "unknown-command";
readonly path: readonly string[];
readonly word: string;
readonly known: readonly string[];
readonly suggestion: string | undefined;
};Why an argument vector names nothing: a word not known below path, the words known there, and the nearest.
asksForHelpfunctionno test imports itfunction asksForHelp(word: string): booleanWhether a word asks for help.
resolveCommandfunctionfunction resolveCommand(root: Group, argv: readonly string[]): Result<Resolved, CommandError>Resolves an argument vector (the words after the program's name) against a tree whose root is the program.
formatCommandErrorfunctionfunction formatCommandError(e: CommandError): stringA command error as one sentence, with the help to run next.
commandHelpfunctionfunction commandHelp(path: readonly string[], node: CommandNode): stringThe help of a node at path (the words that name it, the program's first), from its declaration alone.