RIO.Process

Reading from external processes.

Documentation

withProcess :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

Same as withProcess, but generalized to MonadUnliftIO.

withProcess_ :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

Same as withProcess_, but generalized to MonadUnliftIO.

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 FilePath))
• eoExeExtensions :: [String]

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

• eoWorkingDir :: !(Maybe FilePath)

unEnvOverride :: EnvOverride -> Map Text Text

Get the environment variables from an EnvOverride.

mkEnvOverride :: MonadIO m => 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 -> [(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 FilePath)

Full path to that executable on success

Find the complete path for the executable.

Throws a ReadProcessException if unsuccessful.

getEnvOverride :: MonadIO m => m EnvOverride

Load up an EnvOverride from the standard environment.

envSearchPath :: EnvOverride -> [FilePath]

Get the list of directories searched (PATH).

preProcess

Arguments

:: HasEnvOverride env

=> String

Command name

-> RIO env FilePath

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

Throws a ReadProcessException if unsuccessful.

readProcessNull

Arguments

:: HasEnvOverride env

=> String

Command

-> [String]

Command line arguments

-> RIO env ()

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

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 => [FilePath] -> Maybe Text -> m Text

Augment the PATH environment variable with the given extra paths.

augmentPathMap :: MonadThrow m => [FilePath] -> 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.

class HasLogFunc env => HasEnvOverride env where

Minimal complete definition

envOverrideL

Methods

envOverrideL :: Lens' env EnvOverride

workingDirL :: HasEnvOverride env => Lens' env (Maybe FilePath)

withProc

Arguments

:: HasEnvOverride env

=> FilePath

command to run

-> [String]

command line arguments

-> (ProcessConfig () () () -> RIO env a)

-> RIO env a

Provide a ProcessConfig based on the EnvOverride in scope. Deals with resolving the full path, setting the child process's environment variables, setting the working directory, and wrapping the call with withProcessTimeLog for debugging output.

withEnvOverride :: HasEnvOverride env => EnvOverride -> RIO env a -> RIO env a

Set a new EnvOverride in the child reader. Note that this will keep the working directory set in the parent with withWorkingDir.

withModifyEnvOverride :: HasEnvOverride env => (Map Text Text -> Map Text Text) -> RIO env a -> RIO env a

Apply the given function to the modified environment variables. For more details, see withEnvOverride.

withWorkingDir :: HasEnvOverride env => FilePath -> RIO env a -> RIO env a

Set the working directory to be used by child processes.

runEnvNoLogging :: RIO EnvNoLogging a -> IO a

withProcessTimeLog :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Maybe FilePath -> String -> [String] -> m a -> m a

Log running a process with its arguments, for debugging (-v).

This logs one message before running the process and one message after.

showProcessArgDebug :: String -> Text

Show a process arg including speechmarks when necessary. Just for debugging purposes, not functionally important.

exec :: HasEnvOverride env => String -> [String] -> RIO env b

Execute a process within the Stack configured environment.

Execution will not return, because either:

1) On non-windows, execution is taken over by execv of the sub-process. This allows signals to be propagated (#527)

2) On windows, an ExitCode exception will be thrown.

execSpawn :: HasEnvOverride env => String -> [String] -> RIO env a

Like exec, but does not use execv on non-windows. This way, there is a sub-process, which is helpful in some cases (#1306)

This function only exits by throwing ExitCode.

execObserve :: HasEnvOverride env => String -> [String] -> RIO env String

module System.Process.Typed