Script class

A unit of execution that behaves like a process, with stdin, stdout, and stderr streams that ultimately produces an exitCode indicating success or failure.

This is usually a literal subprocess (created using new Script). However, it can also be a block of Dart code (created using Script.capture) or a user-defined custom script (created using Script.fromComponents).

Heads up: If you want to handle a Script's stdout, stderr, or exitCode make sure to set up your handlers synchronously after you create the Script! If you try to listen too late, you'll get "Stream has already been listened to" errors because the streams have already been piped into the parent process's output.

All script types provide the following guarantees:

  • All errors will be emitted through exitCode, success, and/or done (depending on which is accessed). If the underlying stdout or stderr stream would emit an error, it's forwarded to the exit futures. Catching errors on one exit future is sufficient to catch all errors emitted by the Script.

  • Any errors emitted after done completes will be silently ignored, even if done completed successfully.

  • Once done completes, stdout and stderr will emit done events immediately afterwards (modulo a few microtasks).

  • After constructing the Script, the user has one macrotask (that is, until a event fires) to listen to stdout and stderr. After that, they'll be forwarded to the surrounding Stream.capture (if one exists) or to the root script's stdout and stderr streams.

  • Passing error events to stdin is not allowed. If an error is passed, stdin wil close and forward the error to stdin.done.

  • @sealed


Script(String executableAndArgs, {Iterable<String>? args, String? name, String? workingDirectory, Map<String, String>? environment, bool includeParentEnvironment = true, bool runInShell = false})
Creates a Script that runs a subprocess.
Script.capture(FutureOr<void> callback(Stream<List<int>> stdin), {String? name, bool onSignal(ProcessSignal signal)?})
Runs callback and captures the output of Scripts created within it.
Script.fromByteTransformer(StreamTransformer<List<int>, List<int>> transformer, {String? name})
Creates a Script from a StreamTransformer on byte streams.
Script.fromComponents(String name, FutureOr<ScriptComponents> callback(), {bool onSignal(ProcessSignal signal)?})
Creates a script from existing stdin, stdout, stderr, and exitCode objects encapsulated in a ScriptComponents.
Script.fromLineTransformer(StreamTransformer<String, String> transformer, {String? name})
Creates a Script from a StreamTransformer on string streams.
Script.mapLines(String mapper(String line), {String? name})
Creates a Script from a function that maps strings to strings.
Script.pipeline(Iterable<Object> scripts, {String? name})
Pipes each script's stdout into the next script's stdin.


done Future<void>
A future that completes when the script is finished.
exitCode Future<int>
The exit code indicating the status of the script's execution.
no setter
hashCode int
The hash code for this object.
no setterinherited
lines Stream<String>
Returns a stream of lines this prints to stdout.
no setter
name String
A human-readable name of the script.
output Future<String>
Returns this script's stdout, with trailing newlines removed.
no setter
outputBytes Future<Uint8List>
Returns this script's stdout as bytes.
no setter
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
stderr Stream<List<int>>
The script's standard error stream, typically used to emit error messages and diagnostics.
no setter
stdin IOSink
The standard input stream that's used to pass data into the process.
stdout Stream<List<int>>
The script's standard output stream, typically used to emit data it produces.
no setter
success Future<bool>
Whether the script succeeded or failed (that is, whether it emitted an exit code of 0).
no setter


combineOutput() Stream<List<int>>
Returns a stream that combines both stdout and stderr the same way they'd be displayed in a terminal.
kill([ProcessSignal signal = ProcessSignal.sigterm]) bool
Sends a ProcessSignal to terminate the process.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
toString() String
A string representation of this object.


operator ==(Object other) bool
The equality operator.
operator >(StreamConsumer<List<int>> consumer) Future<void>
Shorthand for script.stdout.pipe(consumer).
operator |(Object other) Script
Pipes this script's stdout into other's stdin.