io

Contains utilities for the Dart VM's dart:io.

Usage - io.dart

Files

isExecutable

Returns whether a provided file path is considered executable on the host operating system.

Processes

ExitCode

An enum-like class that contains known exit codes.

ProcessManager

A higher-level service for spawning and communicating with processes.

Use spawn to create a process with std[in|out|err] forwarded by default

Future<void> main() async {
                  final manager = ProcessManager();
                
                  // Print `dart` tool version to stdout.
                  print('** Running `dart --version`');
                  var spawn = await manager.spawn('dart', ['--version']);
                  await spawn.exitCode;
                
                  // Check formatting and print the result to stdout.
                  print('** Running `dart format --output=none .`');
                  spawn = await manager.spawn('dart', ['format', '--output=none', '.']);
                  await spawn.exitCode;
                
                  // Check if a package is ready for publishing.
                  // Upon hitting a blocking stdin state, you may directly
                  // output to the processes's stdin via your own, similar to how a bash or
                  // shell script would spawn a process.
                  print('** Running pub publish');
                  spawn = await manager.spawn('dart', ['pub', 'publish', '--dry-run']);
                  await spawn.exitCode;
                
                  // Closes stdin for the entire program.
                  await sharedStdIn.terminate();
                }
                

sharedStdIn

A safer version of the default stdin stream from dart:io that allows a subscriber to cancel their subscription, and then allows a new subscriber to start listening. This differs from the default behavior where only a single listener is ever allowed in the application lifecycle:

test('should allow multiple subscribers', () async {
                  final logs = <String>[];
                  final asUtf8 = sharedStdIn.transform(UTF8.decoder);
                  // Wait for input for the user.
                  logs.add(await asUtf8.first);
                  // Wait for more input for the user.
                  logs.add(await asUtf8.first);
                  expect(logs, ['Hello World', 'Goodbye World']);
                });
                

For testing, an instance of SharedStdIn may be created directly.

Usage - ansi.dart

import 'dart:io' as io;
                import 'package:io/ansi.dart';
                
                void main() {
                  // To use one style, call the `wrap` method on one of the provided top-level
                  // values.
                  io.stderr.writeln(red.wrap("Bad error!"));
                
                  // To use multiple styles, call `wrapWith`.
                  print(wrapWith('** Important **', [red, styleBold, styleUnderlined]));
                
                  // The wrap functions will simply return the provided value unchanged if
                  // `ansiOutputEnabled` is false.
                  //
                  // You can override the value `ansiOutputEnabled` by wrapping code in
                  // `overrideAnsiOutput`.
                  overrideAnsiOutput(false, () {
                    assert('Normal text' == green.wrap('Normal text'));
                  });
                }
                

Publishing automation

For information about our publishing automation and release process, see https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.

1.1.0

• Add a deepCopyLinks argument to copyPath and copyPathSync.
• Remove the @visibleForTesting annotation from SharedStdIn.
• Potentially Breaking Make the stream parameter required for SharedStdIn.new.
  • This is treated as non-breaking because the class was marked as visible for testing only.
• Potentially Breaking AnsiCode and AnsiCodeType marked final. These were never intended to support subclasses and were already closed for extension with private generative constructors. They are now marked final and statically restricted from use as an interface.

1.0.5

• Require Dart 3.4.
• Move to dart-lang/tools monorepo.

1.0.4

• Updates to the readme.

1.0.3

• Revert meta constraint to ^1.3.0.

1.0.2

• Update meta constraint to >=1.3.0 <3.0.0.

1.0.1

• Update code examples to call the unified dart developer tool.

1.0.0

• Migrate this package to null-safety.
• Require Dart >=2.12.

0.3.5

• Require Dart >=2.1.
• Remove dependency on package:charcode.

0.3.4

• Fix a number of issues affecting the package score on pub.dev.

0.3.3

• Updates for Dart 2 constants. Require at least Dart 2.0.0-dev.54.

• Fix the type of StartProcess typedef to match Process.start from dart:io.

0.3.2+1

• ansi.dart

  • The "forScript" code paths now ignore the ansiOutputEnabled value. Affects the escapeForScript property on AnsiCode and the wrap and wrapWith functions when forScript is true.

0.3.2

• ansi.dart

  • Added forScript named argument to top-level wrapWith function.

  • AnsiCode

    • Added String get escapeForScript property.

    • Added forScript named argument to wrap function.

0.3.1

• Added SharedStdIn.nextLine (similar to readLineSync) and lines:

main() async {
                  // Prints the first line entered on stdin.
                  print(await sharedStdIn.nextLine());
                
                  // Prints all remaining lines.
                  await for (final line in sharedStdIn.lines) {
                    print(line);
                  }
                }
                

• Added a copyPath and copyPathSync function, similar to cp -R.

• Added a dependency on package:path.

• Added the remaining missing arguments to ProcessManager.spawnX which forward to Process.start. It is now an interchangeable function for running a process.

0.3.0

• BREAKING CHANGE: The arguments argument to ProcessManager.spawn is now positional (not named) and required. This makes it more similar to the built-in Process.start, and easier to use as a drop in replacement:

main() {
                  processManager.spawn('dart', ['--version']);
                }
                

• Fixed a bug where processes created from ProcessManager.spawn could not have their stdout/stderr read through their respective getters (a runtime error was always thrown).

• Added ProcessMangaer#spawnBackground, which does not forward stdin.

• Added ProcessManager#spawnDetached, which does not forward any I/O.

• Added the shellSplit() function, which parses a list of arguments in the same manner as the POSIX shell.

0.2.0

• Initial commit of...
  • FutureOr<bool> String isExecutable(path).
  • ExitCode
  • ProcessManager and Spawn
  • sharedStdIn and SharedStdIn
  • ansi.dart library with support for formatting terminal output