cli library

A console for command-line tools on twk: messages by channel and level, styled as the terminal takes them, any twk widget shown in the output, and, in the interactive mode, one inline twk app that prompts and progress are live in while finished output is committed above them.

Its prompts (Cli.prompt, Cli.promptAny, Cli.confirm, Cli.chooseOne, Cli.chooseAny) ask as the mode allows: a widget in the inline session, a line read, or the default taken where nobody can answer (PromptException where there is none). Its progress (Cli.progress, Cli.tasks) is a spinner or a list of tasks with bars, rate and time left where the terminal redraws, lines where it does not, the outcome alone in a log.

What Cli.run's body throws ends the run with its traceback and an exit code, as Cli.error shows an error the program caught, its source as Cli.sourceLines gives it.

Cli is the console, Cli.run and Cli.runWithArgs its front door; CliTerminal is what it talks through and CliMode how. A fake terminal for tests is twk_test's, in package:twk_test/cli.dart. The library is apart from package:twk/twk.dart, which it builds on: a program imports both.

Classes

Cli
The console of a command-line tool: messages by channel and level, styled as the terminal takes them, and any twk widget shown in the output (show).
CliCapabilities
What a terminal can do, fixed when it is detected.
CliClock
Where a Cli's time comes from and where the timers of its inline session run: the wall clock (CliClock.system), or one a test moves by hand (the fake terminal's, package:twk_test/cli.dart).
CliLive
A widget mounted in the region of a CliSession (CliSession.mount).
CliProgress
An operation going on, shown until it ends in one line saying how it went: Cli.progress starts one.
CliSession
One inline twk app on a CliTerminal for the life of a Cli: stdin is single-subscription, so the interactive mode opens it the first time something needs it and keeps it until close.
CliTerminal
The terminal a Cli talks through: where lines go (out, err), where a plain prompt reads them (readLine), what both can do (capabilities, mode), and, in the interactive mode, the terminal an inline twk app runs on (openInline).
CliTheme
The style of each channel of a Cli, merged under the styles of the message itself, and the ThemeData the widgets it shows are shown in (data).

Enums

CliMode
How a program may talk to the person at a terminal, derived from CliCapabilities (CliCapabilities.mode).
PromptCancelReason
How a person left a prompt without answering.

Functions

levelFromFlags({bool verbose = false, bool quiet = false}) → LogLevel
The level a command line's --verbose and --quiet ask for: verbose shows everything (LogLevel.debug), quiet only errors (LogLevel.error), neither keeps LogLevel.info. Given both, verbose wins: -q tends to sit in an alias or a script, and -v is added by hand to see why something went wrong.
messageLines(Object? message, Style style) → List<List<Span>>
The lines of message, each a list of spans, every span's style merged onto style.

Exceptions / Errors

PromptAnswerRequiredException
Nobody can answer (the Cli's mode is non-interactive: a pipe, CI, --no-input) and the prompt has no default to take instead, or one its validation refuses (invalidDefault says why).
PromptCancelledException
The person left the prompt without answering (reason): Ctrl+C, Ctrl+D, or input ended. What the prompt showed is gone by the time it is thrown, and in the interactive mode ✗ question is committed in its place.
PromptException
Why a prompt returned no answer.