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 Timer.run 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.

Implementers
Annotations
  • @sealed

Constructors

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.
factory
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.
factory
Script.fromByteTransformer(StreamTransformer<List<int>, List<int>> transformer, {String? name})
Creates a Script from a StreamTransformer on byte streams.
factory
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.
factory
Script.mapLines(String mapper(String line), {String? name})
Creates a Script from a function that maps strings to strings.
factory
Script.pipeline(Iterable<Object> scripts, {String? name})
Pipes each script's stdout into the next script's stdin.
factory

Properties

done ↔ Future<void>
A future that completes when the script is finished.
latefinal
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.
final
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.
latefinal
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

Methods

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.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited
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.