IF Commons GitHub

surfaces/cli/help

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-headless-cli FR-010

The documents generated from a program's tree (commons headless 0004-headless-cli FR-010): its help at every level, its completions for bash, zsh, fish and PowerShell, and its man page. They are made from the declaration alone, so a command added to the tree is in all of them with nothing else written, and none can say what the parser does not accept. A verb's help includes the options its effect gives it (--dry-run, --yes) and what its action is: what it may change, whether it is safe to repeat, who it is for.

import { completions } from "./help.ts";
import { programOf, branch } from "@intellectual-frontiers/headless/logical";
completions(programOf({ name: "tool", summary: "A tool.", version: "1", children: [branch({ name: "repo", summary: "Repos.", children: [] })] }), "bash").includes("repo"); // true

Source: commons/headless/src/surfaces/cli/help.ts

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

BUILT_INconstno test imports it
const BUILT_IN: readonly ["help", "explain", "completions", "man", "run"]

The words the surface itself answers, beside the program's commands.

SHELLSconst
const SHELLS: readonly ["bash", "zsh", "fish", "powershell"]

The shells there are completions for.

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

Shelltypeno test imports it
type Shell = (typeof SHELLS)[number];

A shell there are completions for.

isShellfunction
function isShell(word: string): word is "bash" | "fish" | "powershell" | "zsh"

Whether a word names a shell there are completions for.

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

effectLinesfunction
function effectLines(f: ActionFacts): readonly string[]

What an action is, in lines for its help.

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

helpForfunction
function helpFor(program: Program, path: readonly string[]): string | undefined

The help of the node named by path (the words below the program), or undefined where there is none.

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

Completiontypeno test imports it
type Completion = { readonly path: readonly string[]; readonly words: readonly string[] };

What a shell completes after a path of words: the words of that place.

completionTablefunction
function completionTable(program: Program): readonly Completion[]

Every place a shell completes: each branch with its commands, each command with its options. The program's own place is first and holds the built-in words.

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

completionsfunction
function completions(program: Program, shell: "bash" | "fish" | "powershell" | "zsh"): string

The completion script of a program for a shell.

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

manPagefunction
function manPage(program: Program): string

The man page of a program, in roff: its commands with their options and effects, and its exit statuses from the one table. It holds no date, so the same program gives the same bytes.

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

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