A module adapting the functions from System.Process to work with io-streams.

This module intends to make the operations of System.Posix.Process available on all platforms.

This module provides functions to run operating system processes as stream producers, consumers or stream transformation functions. Thus OS processes can be used in the same way as Haskell functions and all the streaming combinators in streamly can be used to combine them. This allows you to seamlessly integrate external binary executables into your Haskell program. However, we recommend native Haskell functions with Streamly threads over using system processes whenever possible. This approach offers a simpler programming model compared to system processes, which also have a larger performance overhead. Prefer Streamly.System.Command module as a higher level wrapper over this module.

Executables as functions

Processes can be composed in a streaming pipeline just like a Posix shell command pipeline. Moreover, we can mix processes and Haskell functions seamlessly in a processing pipeline. For example:

>>> :{
Process.toBytes "echo" ["hello world"]
& Process.pipeBytes "tr" ["[a-z]", "[A-Z]"]
& Stream.fold Stdio.write
:}
HELLO WORLD

Of course, you can use a Haskell function instead of "tr":

>>> :{
Process.toBytes "echo" ["hello world"]
& Unicode.decodeLatin1 & fmap toUpper & Unicode.encodeLatin1
& Stream.fold Stdio.write
:}
HELLO WORLD

Shell commands as functions

Using a shell as the command interpreter we can use shell commands in a data processing pipeline:

>>> :{
Process.toBytes "sh" ["-c", "echo hello | tr [a-z] [A-Z]"]
& Stream.fold Stdio.write
:}
HELLO

Running Commands Concurrently

We can run executables or commands concurrently as we would run any other functions in Streamly. For example, the following program greps the word "to" in all the files in the current directory concurrently:

>>> :{
grep file =
Process.toBytes "grep" ["-H", "pattern", file]
& Stream.handle (\(_ :: Process.ProcessFailure) -> Stream.nil)
& Stream.foldMany (Fold.takeEndBy (== 10) Array.write)
:}

>>> :{
pgrep =
Dir.readFiles "."
& Stream.parConcatMap id grep
& Stream.fold Stdio.writeChunks
:}

Experimental APIs

See Streamly.Internal.System.Process for unreleased functions.

Process a list of flags (usually obtained from getArgs/expandArgsAt) with a mode. Returns Left and an error message if the command line fails to parse, or Right and the associated value.

CPU options impacting cryptography implementation and library performance.

This will always come first, before any output or exit code.

An exception that is raised when a process fails.

The exit code of the process.

Process the flags obtained by getArgs and expandArgsAt with a mode. Displays an error and exits with failure if the command line fails to parse, or returns the associated value. Implemented in terms of process. This function makes use of the following environment variables:

• $CMDARGS_COMPLETE - causes the program to produce completions using complete, then exit. Completions are based on the result of getArgs, the index of the current argument is taken from $CMDARGS_COMPLETE (set it to - to complete the last argument), and the index within that argument is taken from $CMDARGS_COMPLETE_POS (if set).
• $CMDARGS_HELPER/$CMDARGS_HELPER_PROG - uses the helper mechanism for entering command line programs as described in System.Console.CmdArgs.Helper.

Process a list of flags (usually obtained from getArgs and expandArgsAt) with a mode. Throws an error if the command line fails to parse, or returns the associated value. Implemeneted in terms of process. This function does not take account of any environment variables that may be set (see processArgs). If you are in IO you will probably get a better user experience by calling processValueIO.

Like processValue but on failure prints to stderr and exits the program.

Options which have been enabled at compile time and are supported by the current CPU.