IF Commons GitHub

commands

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-terminal FR-002

A 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?

Source: commons/terminal/src/commands.ts

7 of 30 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

commandsnamespace
namespace commands
commands.Exampletypeno test imports it
type 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 it
type 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 it
type 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 it
type CommandNode = Group | Verb;

One node of a command tree.

commands.verbfunctionno test imports it
function 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 it
function group(g: { readonly name: string; readonly summary: string; readonly children: readonly CommandNode[]; }): Group

A group of nodes.

commands.validCommandNamefunctionno test imports it
function validCommandName(name: string): boolean

Whether a name is one a command may have: lower case letters, digits and dashes, beginning with a letter.

commands.TreeProblemtypeno test imports it
type 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 it
function 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 it
type 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 it
type 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 it
function asksForHelp(word: string): boolean

Whether a word asks for help.

commands.resolveCommandfunctionno test imports it
function 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 it
function formatCommandError(e: CommandError): string

A command error as one sentence, with the help to run next.

commands.commandHelpfunctionno test imports it
function commandHelp(path: readonly string[], node: CommandNode): string

The help of a node at path (the words that name it, the program's first), from its declaration alone.

Exampletypeno test imports it
type 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 it
type 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 it
type 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 it
type CommandNode = Group | Verb;

One node of a command tree.

verbfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

groupfunction
function group(g: { readonly name: string; readonly summary: string; readonly children: readonly CommandNode[]; }): Group

A group of nodes.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

validCommandNamefunction
function validCommandName(name: string): boolean

Whether a name is one a command may have: lower case letters, digits and dashes, beginning with a letter.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

TreeProblemtypeno test imports it
type 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.

treeProblemsfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Resolvedtypeno test imports it
type 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 it
type 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 it
function asksForHelp(word: string): boolean

Whether a word asks for help.

resolveCommandfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

formatCommandErrorfunction
function formatCommandError(e: CommandError): string

A command error as one sentence, with the help to run next.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

commandHelpfunction
function commandHelp(path: readonly string[], node: CommandNode): string

The help of a node at path (the words that name it, the program's first), from its declaration alone.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.