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
--verboseand--quietask for:verboseshows everything (LogLevel.debug),quietonly errors (LogLevel.error), neither keeps LogLevel.info. Given both,verbosewins:-qtends to sit in an alias or a script, and-vis 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 ontostyle.
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, Esc,
Ctrl+D, or input ended. What the prompt showed is gone by the time it
is thrown, and in the interactive mode
✗ questionis committed in its place. - PromptException
- Why a prompt returned no answer.