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 whatlevellets through intheme, the source of an error assourceLinesgives 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
--verbosethat 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
messageas 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
questionfor any ofchoices, which must not be empty, answered in the order ofchoices: at leastminof them, at mostmax(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
questionfor one ofchoices, which must not be empty, each shown asdisplaymakes it (itstoStringwithout). -
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);defaultValueis what Enter, or an empty line, answers. -
delayed(
Object? message) → void -
Keeps
messageuntil flush: for what should come after the rest of the output, such as a summary of warnings. -
detail(
Object? message) → void -
Logs
messageat LogLevel.debug, to the output, in the theme's CliTheme.detail (muted). -
err(
Object? message) → void -
Logs
messageat LogLevel.error, to the error output, in the theme's CliTheme.error. -
error(
Object error, StackTrace stack) → void -
Shows
error, thrown atstack, 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
messageat LogLevel.info, to the output, unstyled. -
link(
Uri uri, [String? text]) → String -
text, oruriitself, as a hyperlink touri(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
messagewhile 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, String? validate(String answer)?, FutureOr< List< suggest(String typed)?, String? placeholder}) → Future<String> >String> -
Asks
questionand answers the line typed,defaultValuefor 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
questionfor many values on one line, split onseparatorand trimmed, the blank ones dropped; an empty line answersdefaultValues, or none without them. -
show(
Widget widget, {int? width}) → Future< void> -
Shows
widgetonce, laid out at the terminal's width, orwidthcolumns, as tall as it is there; completes once it is written. -
success(
Object? message) → void -
Logs
messageat 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
runruns, one that reads it itself (sudoasking for a password, a package manager, a pager, an editor, started withProcessStartMode.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
bodywith 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
messageat 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
textto 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
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
bodywith 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-colorand--no-input, wherever they are before a--; the rest, in order and with what follows--as it is, goes tobody. Errors are handled as run handles them.