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, make it Cli.current for the body and close it on the way out.

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, SourceLines? sourceLines})
A console on terminal, the process's stdio unless given one, showing what level lets through in theme, 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
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.
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 Properties

current → Cli
The console of the Cli.run the caller runs in, else one on the process's stdio, made the first time it is asked for.
no setter

Static Methods

run<T>(FutureOr<T> body(Cli cli), {bool verbose = false, bool quiet = false, bool color = true, bool input = true, CliTheme? theme, 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 Cli.current for the whole of it, its asynchronous continuations included, and is closed when it ends, by an error too.
runWithArgs<T>(List<String> args, FutureOr<T> body(Cli cli, List<String> rest), {CliTheme? theme, 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.