run<T> static method
- 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({})?,
Runs body with a console set up from a command line's flags, which
is closed when it ends, by an error too.
verbose and quiet pick the level (levelFromFlags). false for
color is --no-color: no escapes whatever the terminal takes.
false for input is --no-input: nothing is asked. Left true,
both are detected (NO_COLOR, CI, whether stdio is a terminal).
With handleErrors, what body throws, and what is thrown in it
that nothing catches (a future nobody awaits), ends the run as a
command line ends: the traceback on the error output (error),
every frame under --verbose; the terminal restored; the
CliTerminal.exitCode errorExitCode. A PromptException ends it
quietly, with its question and no traceback: a prompt cancelled with
✗ question (the interactive prompt shows it itself), and 130, the
code of an interrupt, for Ctrl+C; one nobody can answer with what it
needs, and errorExitCode. The run then completes with null where
its result may be null (a void body's), and with the error
otherwise: a value it has none of. An error left uncaught once the
run has ended is shown, and sets the code, all the same. Without
handleErrors what the body throws is the run's, as it is.
strings and sourceLines are the console's Cli.strings and
Cli.sourceLines.
open makes the terminal from what the flags leave to detection
(null) and what they decide: CliTerminal.system unless a test of
the program passes one that makes a fake terminal.
Implementation
static Future<T> run<T>(
FutureOr<T> Function(Cli cli) body, {
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 Function({bool? ansi, bool? interactive})? open,
}) async {
final terminal = (open ?? CliTerminal.system)(
ansi: color ? null : false,
interactive: input ? null : false,
);
final cli = Cli(
terminal: terminal,
level: levelFromFlags(verbose: verbose, quiet: quiet),
theme: theme,
strings: strings,
sourceLines: sourceLines,
);
if (!handleErrors) {
try {
return await body(cli);
} finally {
await cli.close();
}
}
// made outside the zone, so that its error reaches the await below
final done = Completer<T>();
void failed(Object error, StackTrace stack) {
if (done.isCompleted) {
unawaited(cli._failed(error, stack, errorExitCode));
} else {
done.completeError(error, stack);
}
}
runZonedGuarded(
() {
unawaited(
Future<T>.sync(() => body(cli)).then((value) {
if (!done.isCompleted) {
done.complete(value);
}
}, onError: failed),
);
},
failed,
);
try {
return await done.future;
} on Object catch (error, stack) {
await cli._failed(error, stack, errorExitCode);
if (null is T) {
return null as T;
}
rethrow;
} finally {
await cli.close();
}
}