System.Process.Read

Reading from external processes.

Documentation

readProcessStdout

Arguments

:: (MonadUnliftIO m, MonadLogger m)

=> Maybe (Path Abs Dir)

Optional directory to run in

-> EnvOverride

-> String

Command

-> [String]

Command line arguments

-> m ByteString

Produce a strict ByteString from the stdout of a process.

Throws a ReadProcessException exception if the process fails.

readProcessStderrStdout

Arguments

:: (MonadUnliftIO m, MonadLogger m)

=> Maybe (Path Abs Dir)

Optional directory to run in

-> EnvOverride

-> String

Command

-> [String]

Command line arguments

-> m (ByteString, ByteString)

Produce strict ByteStrings from the stderr and stdout of a process.

Throws a ReadProcessException exception if the process fails.

tryProcessStdout

Arguments

:: (MonadUnliftIO m, MonadLogger m)

=> Maybe (Path Abs Dir)

Optional directory to run in

-> EnvOverride

-> String

Command

-> [String]

Command line arguments

-> m (Either ReadProcessException ByteString)

Try to produce a strict ByteString from the stdout of a process.

tryProcessStderrStdout

Arguments

:: (MonadUnliftIO m, MonadLogger m)

=> Maybe (Path Abs Dir)

Optional directory to run in

-> EnvOverride

-> String

Command

-> [String]

Command line arguments

-> m (Either ReadProcessException (ByteString, ByteString))

Try to produce strict ByteStrings from the stderr and stdout of a process.

sinkProcessStdout

Arguments

:: (MonadUnliftIO m, MonadLogger m)

=> Maybe (Path Abs Dir)

Optional directory to run in

-> EnvOverride

-> String

Command

-> [String]

Command line arguments

-> Sink ByteString IO a

Sink for stdout

-> m a

Consume the stdout of a process feeding strict ByteStrings to a consumer. If the process fails, spits out stdout and stderr as error log level. Should not be used for long-running processes or ones with lots of output; for that use sinkProcessStdoutLogStderr.

Throws a ReadProcessException if unsuccessful.

sinkProcessStderrStdout

Arguments

:: (MonadIO m, MonadLogger m)

=> Maybe (Path Abs Dir)

Optional directory to run in

-> EnvOverride

-> String

Command

-> [String]

Command line arguments

-> Sink ByteString IO e

Sink for stderr

-> Sink ByteString IO o

Sink for stdout

-> m (e, o)

Consume the stdout and stderr of a process feeding strict ByteStrings to the consumers.

Throws a ReadProcessException if unsuccessful in launching, or ProcessExitedUnsuccessfully if the process itself fails.

sinkProcessStderrStdoutHandle

Arguments

:: (MonadIO m, MonadLogger m)

=> Maybe (Path Abs Dir)

Optional directory to run in

-> EnvOverride

-> String

Command

-> [String]

Command line arguments

-> Handle

-> Handle

-> m ()

Like sinkProcessStderrStdout, but receives Handles for stderr and stdout instead of Sinks.

Throws a ReadProcessException if unsuccessful in launching, or ProcessExitedUnsuccessfully if the process itself fails.

logProcessStderrStdout :: (HasCallStack, MonadUnliftIO m, MonadLogger m) => Maybe (Path Abs Dir) -> String -> EnvOverride -> [String] -> m ()

readProcess

Arguments

:: FilePath

Filename of the executable (see RawCommand for details)

-> [String]

any arguments

-> String

standard input

-> IO String

stdout

readProcess forks an external process, reads its standard output strictly, blocking until the process terminates, and returns the output string. The external process inherits the standard error.

If an asynchronous exception is thrown to the thread executing readProcess, the forked process will be terminated and readProcess will wait (block) until the process has been terminated.

Output is returned strictly, so this is not suitable for interactive applications.

This function throws an IOError if the process ExitCode is anything other than ExitSuccess. If instead you want to get the ExitCode then use readProcessWithExitCode.

Users of this function should compile with -threaded if they want other Haskell threads to keep running while waiting on the result of readProcess.

 > readProcess "date" [] []
 "Thu Feb  7 10:03:39 PST 2008\n"

The arguments are:

• The command to run, which must be in the $PATH, or an absolute or relative path
• A list of separate command line arguments to the program
• A string to pass on standard input to the forked process.

data EnvOverride

Override the environment received by a child process.

Constructors

EnvOverride

Fields

• eoTextMap :: Map Text Text

  Environment variables as map

• eoStringList :: [(String, String)]

  Environment variables as association list

• eoPath :: [FilePath]

  List of directories searched for executables (PATH)

• eoExeCache :: IORef (Map FilePath (Either ReadProcessException (Path Abs File)))
• eoExeExtensions :: [String]

  [""] on non-Windows systems, ["", ".exe", ".bat"] on Windows

• eoPlatform :: Platform

unEnvOverride :: EnvOverride -> Map Text Text

Get the environment variables from an EnvOverride.

mkEnvOverride :: MonadIO m => Platform -> Map Text Text -> m EnvOverride

Create a new EnvOverride.

modifyEnvOverride :: MonadIO m => EnvOverride -> (Map Text Text -> Map Text Text) -> m EnvOverride

Modify the environment variables of an EnvOverride.

envHelper :: EnvOverride -> Maybe [(String, String)]

Helper conversion function.

doesExecutableExist

Arguments

:: MonadIO m

=> EnvOverride

How to override environment

-> String

Name of executable

-> m Bool

Check if the given executable exists on the given PATH.

findExecutable

Arguments

:: (MonadIO m, MonadThrow n)

=> EnvOverride

How to override environment

-> String

Name of executable

-> m (n (Path Abs File))

Full path to that executable on success

Find the complete path for the executable.

Throws a ReadProcessException if unsuccessful.

getEnvOverride :: MonadIO m => Platform -> m EnvOverride

Load up an EnvOverride from the standard environment.

envSearchPath :: EnvOverride -> [FilePath]

Get the list of directories searched (PATH).

preProcess

Arguments

:: MonadIO m

=> Maybe (Path Abs Dir)

Optional directory to create if necessary

-> EnvOverride

How to override environment

-> String

Command name

-> m FilePath

Perform pre-call-process tasks. Ensure the working directory exists and find the executable path.

Throws a ReadProcessException if unsuccessful.

readProcessNull

Arguments

:: (MonadUnliftIO m, MonadLogger m)

=> Maybe (Path Abs Dir)

Optional working directory

-> EnvOverride

-> String

Command

-> [String]

Command line arguments

-> m ()

Read from the process, ignoring any output.

Throws a ReadProcessException exception if the process fails.

data ReadProcessException

An exception while trying to read from process.

Constructors

ProcessFailed CreateProcess ExitCode ByteString ByteString

ProcessFailed createProcess exitCode stdout stderr

NoPathFound

ExecutableNotFound String [FilePath]

ExecutableNotFoundAt FilePath

Instances

Show ReadProcessException

Methods

showsPrec :: Int -> ReadProcessException -> ShowS

show :: ReadProcessException -> String

showList :: [ReadProcessException] -> ShowS

Exception ReadProcessException

Methods

toException :: ReadProcessException -> SomeException

fromException :: SomeException -> Maybe ReadProcessException

displayException :: ReadProcessException -> String

augmentPath :: MonadThrow m => [Path Abs Dir] -> Maybe Text -> m Text

Augment the PATH environment variable with the given extra paths.

augmentPathMap :: MonadThrow m => [Path Abs Dir] -> Map Text Text -> m (Map Text Text)

Apply augmentPath on the PATH value in the given Map.

resetExeCache :: MonadIO m => EnvOverride -> m ()

Reset the executable cache.