run<T> static method

Future<T> run<T>(
  1. FutureOr<T> body(
    1. Cli cli
    ), {
  2. bool verbose = false,
  3. bool quiet = false,
  4. bool color = true,
  5. bool input = true,
  6. CliTheme? theme,
  7. SourceLines? sourceLines,
  8. bool handleErrors = true,
  9. int errorExitCode = 1,
  10. CliTerminal open({
    1. bool? ansi,
    2. bool? interactive,
    })?,
})

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.

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.

sourceLines is the console's 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,
  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,
    sourceLines: sourceLines,
  );
  if (!handleErrors) {
    try {
      return await runZoned(
        () => Future<T>.sync(() => body(cli)),
        zoneValues: {_zoneKey: 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,
    zoneValues: {_zoneKey: cli},
  );
  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();
  }
}