Cli class final

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).

Everything goes through one terminal, whose mode says how:

  • CliMode.interactive: somebody answers at a terminal that redraws. The first time something needs it (a widget shown, a prompt, a progress) the console opens one inline twk app on the terminal and keeps it until close (CliSession): what is live is in its region, finished output, lines logged included, is committed to the terminal's history above it. Until then, lines are written as they are elsewhere.
  • CliMode.plain and CliMode.nonInteractive: nothing is opened; output is written as lines, a widget as the lines of its text, with escapes only where the terminal takes them.

err, alert and warn write to the error output, so a pipe carries results only; the rest goes to the output. A message is written when level lets its channel through: detail at LogLevel.debug, info and success at LogLevel.info, warn at LogLevel.warning, err and alert at LogLevel.error, the quiet threshold (--quiet): a person who silenced the output still sees the run fail.

A message is a String, styled text (Span, 'x'.bold.fg(Color.red)) or a list of both: see messageLines. Its channel's style (CliTheme) is merged under its own.

Cli.run and Cli.runWithArgs are the front door of a program: they set the console up from its flags, hand it to the body and close it on the way out. A program's helpers take it as a parameter.

Future<void> main(List<String> args) =>
    Cli.runWithArgs(args, (cli, rest) async {
      cli.detail('building ${rest.join(' ')}');
      await build();
      cli.success('Built.');
    });

Constructors

Cli({CliTerminal? terminal, LogLevel level = LogLevel.info, CliTheme? theme, TwkStrings strings = const TwkStrings(), SourceLines? sourceLines})
A console on terminal, the process's stdio unless given one, showing what level lets through in theme, in the words strings, the source of an error as sourceLines gives it.

Properties

hashCode → int
The hash code for this object.
no setterinherited
level ↔ LogLevel
The threshold a channel is written at or above; mutable, for a --verbose that comes late.
getter/setter pair
mode → CliMode
How the console talks to the terminal (CliTerminal.mode).
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sourceLines → SourceLines?
The lines of code an error's traceback shows of the source it was thrown in, as Cli.error and Cli.run show it: their text without, highlighted as Dart with twk_rich's dartSourceLines.
final
strings → TwkStrings
The words the console writes on its own (answer y or n, in 3 s), English unless given others; widgets it shows are given them too (TwkLocalizations).
final
terminal → CliTerminal
The terminal output goes to and input comes from.
final
theme ↔ CliTheme
The style of each channel, and what widgets are shown in.
getter/setter pair

Methods

alert(Object? message) → void
Logs message as an alert, to the error output, in the theme's CliTheme.alert (bold white on red): critical, shown wherever err is.
chooseAny<T>(String question, {required List<T> choices, List<T>? defaultValues, String display(T choice)?, bool? filter, int min = 0, int? max}) → Future<List<T>>
Asks question for any of choices, which must not be empty, answered in the order of choices: at least min of them, at most max (no limit when null); a choice of fewer or more is refused with a message and asked again.
chooseOne<T>(String question, {required List<T> choices, T? defaultValue, String display(T choice)?, bool? filter}) → Future<T>
Asks question for one of choices, which must not be empty, each shown as display makes it (its toString without).
close() → Future<void>
Ends the inline session where one is open, what write left without a line break written first, so the terminal is restored with the cursor below the output; then flushes the terminal and closes it (CliTerminal.close): stdin is let go of where a plain prompt read it, so the process can end. Calling it again does nothing more. Cli.run calls it.
confirm(String question, {bool? defaultValue}) → Future<bool>
Asks question, answered yes (true) or no (false); defaultValue is what Enter, or an empty line, answers.
delayed(Object? message) → void
Keeps message until flush: for what should come after the rest of the output, such as a summary of warnings.
detail(Object? message) → void
Logs message at LogLevel.debug, to the output, in the theme's CliTheme.detail (muted).
err(Object? message) → void
Logs message at LogLevel.error, to the error output, in the theme's CliTheme.error.
error(Object error, StackTrace stack) → void
Shows error, thrown at stack, as Cli.run shows what its body throws, for an error the program caught: its traceback on the error output at LogLevel.error, committed above what is live while an inline session holds the screen; every frame at LogLevel.debug (--verbose), those of the app's own code alone otherwise.
flush() → void
Writes the messages delayed kept, in order, through info, and forgets them.
info(Object? message) → void
Logs message at LogLevel.info, to the output, unstyled.
text, or uri itself, as a hyperlink to uri (OSC 8) where the terminal takes them, else the label alone; a message reads it back as a span with that link.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
progress(String message) → CliProgress
Shows message while an operation goes on, until the progress is closed (CliProgress.complete, CliProgress.fail, CliProgress.cancel), CliProgress.run closing it on the outcome of a body.
prompt(String question, {String? defaultValue, bool hidden = false, String? validate(String answer)?, FutureOr<List<String>> suggest(String typed)?, String? placeholder}) → Future<String>
Asks question and answers the line typed, defaultValue for an empty one (the empty string without one).
promptAny(String question, {String separator = ',', List<String>? defaultValues, String? validate(List<String> answer)?, String? placeholder}) → Future<List<String>>
Asks question for many values on one line, split on separator and trimmed, the blank ones dropped; an empty line answers defaultValues, or none without them.
session() → Future<CliSession>
The inline session of the interactive mode, opened the first time it is asked for and kept until close: what the prompts and progress of this package mount their widgets in, and where a program mounts a live widget (CliSession.mount) to show it below the lines it logs, which are committed above it.
show(Widget widget, {int? width}) → Future<void>
Shows widget once, laid out at the terminal's width, or width columns, as tall as it is there; completes once it is written.
success(Object? message) → void
Logs message at LogLevel.info, to the output, in the theme's CliTheme.success.
suspend<T>(Future<T> run()) → Future<T>
Hands the terminal to another program while run runs, one that reads it itself (sudo asking for a password, a package manager, a pager, an editor, started with ProcessStartMode.inheritStdio), and takes it back after.
tasks<T>(FutureOr<T> body(ProgressTracker tracker), {List<ProgressColumn>? columns, bool hideFinished = false, ProgressBarShape barShape = ProgressBarShape.line, int? maxBarWidth = 30, ByteUnits byteUnits = ByteUnits.decimal}) → Future<T>
Runs body with a ProgressTracker whose tasks are shown as the output allows, and completes with what the body does, its error thrown again; the tracker is disposed once it has ended.
toString() → String
A string representation of this object.
inherited
warn(Object? message) → void
Logs message at LogLevel.warning, to the error output, in the theme's CliTheme.warning: a warning is a diagnostic, not a result.
write(String text) → void
Writes text to the output as it is: no level, no style, no line break. While an inline session holds the screen, text goes above what is live line by line, as each line break ends one; what is left goes when the console is closed.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

run<T>(FutureOr<T> body(Cli cli), {bool verbose = false, bool quiet = false, bool color = true, bool input = true, CliTheme? theme, TwkStrings strings = const TwkStrings(), SourceLines? sourceLines, bool handleErrors = true, int errorExitCode = 1, CliTerminal open({bool? ansi, bool? interactive})?}) → Future<T>
Runs body with a console set up from a command line's flags, which is closed when it ends, by an error too.
runWithArgs<T>(List<String> args, FutureOr<T> body(Cli cli, List<String> rest), {CliTheme? theme, TwkStrings strings = const TwkStrings(), SourceLines? sourceLines, bool handleErrors = true, int errorExitCode = 1, CliTerminal open({bool? ansi, bool? interactive})?}) → Future<T>
run with its flags taken off args: -v/--verbose, -q/--quiet, --no-color and --no-input, wherever they are before a --; the rest, in order and with what follows -- as it is, goes to body. Errors are handled as run handles them.