xargs function
Executes callback
with arguments from standard input.
This converts each line of standard input into a separate argument that's
then passed to callback
. Note: for consistency with other string
transformations in cli_script
, this only splits on newlines, unlike the
UNIX xargs
command which splits on any whitespace.
The callback
is invoked within a Script.capture block, so any stdout or
stderr it emits will be piped into the returned Script's stdout and stderr
streams. If any callback
throws an error or starts a Script that fails
with a non-zero exit code, the returned Script will fail as well.
Waits for each callback
to complete before executing the next one. While
it's possible for callbacks to run in parallel by returning before the
processing is complete, this is not recommended, as it will cause error and
output streams from multiple callbacks to become mangled and could cause
later callbacks to be executed even if earlier ones failed.
If maxArgs
is passed, this invokes callback
multiple times, passing at
most maxArgs
arguments to each invocation. Otherwise, it passes all
arguments to a single invocation.
If name
is passed, it's used as the name of the spawned script.
Script.kill closes the input stream. It returns true
if the stream was
interrupted and the script exits with Script.exitCode 143
, or false
if the stream was already closed.
The callback
can't be interrupted by calling kill
, but the onSignal
callback allows capturing those signals so the callback may react
appropriately. Calling kill
returns true
even without an onSignal
callback if the stream is interrupted.
See also LineStreamExtensions.xargs, which takes arguments directly from an existing string stream rather than stdin.
Implementation
Script xargs(FutureOr<void> callback(List<String> args),
{int? maxArgs, String? name, void onSignal(ProcessSignal signal)?}) {
if (maxArgs != null && maxArgs < 1) {
throw RangeError.range(maxArgs, 1, null, 'maxArgs');
}
late Script script;
return Script.capture((stdin) async {
script = stdin.lines
.xargs(callback, maxArgs: maxArgs, name: name, onSignal: onSignal);
await script.done;
}, onSignal: (signal) => script.kill(signal));
}