stack-1.4.0: The Haskell Tool Stack

Safe Haskell | None
Language | Haskell2010

System.Process.Read

Description

Reading from external processes.

Synopsis

- readProcessStdout :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch m) => Maybe (Path Abs Dir) -> EnvOverride -> String -> [String] -> m ByteString
- readProcessStderrStdout :: (MonadIO m, MonadLogger m, MonadBaseControl IO m) => Maybe (Path Abs Dir) -> EnvOverride -> String -> [String] -> m (ByteString, ByteString)
- tryProcessStdout :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch m) => Maybe (Path Abs Dir) -> EnvOverride -> String -> [String] -> m (Either ReadProcessException ByteString)
- tryProcessStderrStdout :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch m) => Maybe (Path Abs Dir) -> EnvOverride -> String -> [String] -> m (Either ReadProcessException (ByteString, ByteString))
- sinkProcessStdout :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch m) => Maybe (Path Abs Dir) -> EnvOverride -> String -> [String] -> Sink ByteString IO a -> m a
- sinkProcessStderrStdout :: forall m e o. (MonadIO m, MonadLogger m) => Maybe (Path Abs Dir) -> EnvOverride -> String -> [String] -> Sink ByteString IO e -> Sink ByteString IO o -> m (e, o)
- sinkProcessStderrStdoutHandle :: (MonadIO m, MonadLogger m) => Maybe (Path Abs Dir) -> EnvOverride -> String -> [String] -> Handle -> Handle -> m ()
- logProcessStderrStdout :: (MonadIO m, MonadBaseControl IO m, MonadLogger m) => Maybe (Path Abs Dir) -> String -> EnvOverride -> [String] -> m ()
- readProcess :: FilePath -> [String] -> String -> IO String
- data EnvOverride = EnvOverride {
  - eoTextMap :: Map Text Text
  - eoStringList :: [(String, String)]
  - eoPath :: [FilePath]
  - eoExeCache :: IORef (Map FilePath (Either ReadProcessException (Path Abs File)))
  - eoExeExtensions :: [String]
  - eoPlatform :: Platform
  }
- unEnvOverride :: EnvOverride -> Map Text Text
- mkEnvOverride :: MonadIO m => Platform -> Map Text Text -> m EnvOverride
- modifyEnvOverride :: MonadIO m => EnvOverride -> (Map Text Text -> Map Text Text) -> m EnvOverride
- envHelper :: EnvOverride -> Maybe [(String, String)]
- doesExecutableExist :: MonadIO m => EnvOverride -> String -> m Bool
- findExecutable :: (MonadIO m, MonadThrow n) => EnvOverride -> String -> m (n (Path Abs File))
- getEnvOverride :: MonadIO m => Platform -> m EnvOverride
- envSearchPath :: EnvOverride -> [FilePath]
- preProcess :: MonadIO m => Maybe (Path Abs Dir) -> EnvOverride -> String -> m FilePath
- readProcessNull :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch m) => Maybe (Path Abs Dir) -> EnvOverride -> String -> [String] -> m ()
- data ReadProcessException
  - = ProcessFailed CreateProcess ExitCode ByteString ByteString
  - | NoPathFound
  - | ExecutableNotFound String [FilePath]
  - | ExecutableNotFoundAt FilePath
- augmentPath :: MonadThrow m => [Path Abs Dir] -> Maybe Text -> m Text
- augmentPathMap :: MonadThrow m => [Path Abs Dir] -> Map Text Text -> m (Map Text Text)
- resetExeCache :: MonadIO m => EnvOverride -> m ()

# Documentation

readProcessStdout #

Arguments

:: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch 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

:: (MonadIO m, MonadLogger m, MonadBaseControl IO m) |
=> Maybe (Path Abs Dir) | Optional directory to run in
-> EnvOverride |
-> String | Command
-> [String] | Command line arguments
-> m (ByteString, ByteString) |

Produce strict `ByteString`s from the stderr and stdout of a process.

Throws a `ReadProcessException` exception if the process fails.

tryProcessStdout #

Arguments

:: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch 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

:: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch 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 `ByteString`s from the stderr and stdout of a process.

sinkProcessStdout #

Arguments

:: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch 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 `ByteString`s 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 `ByteString`s 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 `Sink`s.

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

logProcessStderrStdout :: (MonadIO m, MonadBaseControl IO 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

:: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch 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.