run static method

Future<ScrollingProcessResult> run(
  1. String executable,
  2. List<String> arguments, {
  3. required InlineTerminal terminal,
  4. String? workingDirectory,
  5. Map<String, String>? environment,
  6. bool includeParentEnvironment = true,
  7. bool runInShell = false,
  8. int rows = 5,
  9. bool dim = true,
  10. String? heading,
  11. String? successMessage,
  12. String? failedMessage,
  13. RetainSection? successRetention,
  14. RetainSection? failureRetention,
  15. bool captureOutput = false,
})

Starts executable with arguments and renders its output in a scrolling section of rows visual rows until the process completes.

Returns once the process has exited and all of its output has been rendered. The caller then decides how to ScrollingProcessResult.finish the section.

terminal is supplied and owned by the caller; this method does not dispose it.

Implementation

static Future<ScrollingProcessResult> run(
  String executable,
  List<String> arguments, {
  required InlineTerminal terminal,
  String? workingDirectory,
  Map<String, String>? environment,
  bool includeParentEnvironment = true,
  bool runInShell = false,
  int rows = 5,
  bool dim = true,
  String? heading,
  String? successMessage,
  String? failedMessage,
  RetainSection? successRetention,
  RetainSection? failureRetention,
  bool captureOutput = false,
}) async {
  final section = ScrollingSection(
    terminal: terminal,
    rows: rows,
    dim: dim,
    heading: heading,
    successMessage: successMessage,
    failedMessage: failedMessage,
    successRetention: successRetention,
    failureRetention: failureRetention,
    captureOutput: captureOutput,
  );

  try {
    final process = await Process.start(
      executable,
      arguments,
      workingDirectory: workingDirectory,
      environment: environment,
      includeParentEnvironment: includeParentEnvironment,
      runInShell: runInShell,
    );

    final stdoutDone = _tail(process.stdout, section);
    final stderrDone = _tail(process.stderr, section);

    final exitCode = await process.exitCode;
    // Ensure all buffered output has been rendered before returning.
    await stdoutDone;
    await stderrDone;

    return ScrollingProcessResult(exitCode: exitCode, section: section);
  } on Object {
    // Restore the cursor and keep whatever was rendered so far.
    section.finish(success: false);
    rethrow;
  }
}