-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Run external processes, with strong typing of streams -- -- Please see the tutorial at -- https://haskell-lang.org/library/typed-process @package typed-process @version 0.2.3.0 -- | Please see the README.md file for examples of using this API. module System.Process.Typed -- | An abstract configuration for a process, which can then be launched -- into an actual running Process. Takes three type parameters, -- providing the types of standard input, standard output, and standard -- error, respectively. -- -- There are three ways to construct a value of this type: -- -- -- -- In all cases, the default for all three streams is to inherit the -- streams from the parent process. For other settings, see the setters -- below for default values. data ProcessConfig stdin stdout stderr -- | A specification for how to create one of the three standard child -- streams. See examples below. data StreamSpec (streamType :: StreamType) a -- | Whether a stream is an input stream or output stream. Note that this -- is from the perspective of the child process, so that a child's -- standard input stream is an STInput, even though the parent -- process will be writing to it. data StreamType STInput :: StreamType STOutput :: StreamType -- | A running process. The three type parameters provide the type of the -- standard input, standard output, and standard error streams. data Process stdin stdout stderr -- | Create a ProcessConfig from the given command and arguments. proc :: FilePath -> [String] -> ProcessConfig () () () -- | Create a ProcessConfig from the given shell command. shell :: String -> ProcessConfig () () () -- | Set the child's standard input stream to the given StreamSpec. -- -- Default: inherit setStdin :: StreamSpec 'STInput stdin -> ProcessConfig stdin0 stdout stderr -> ProcessConfig stdin stdout stderr -- | Set the child's standard output stream to the given StreamSpec. -- -- Default: inherit setStdout :: StreamSpec 'STOutput stdout -> ProcessConfig stdin stdout0 stderr -> ProcessConfig stdin stdout stderr -- | Set the child's standard error stream to the given StreamSpec. -- -- Default: inherit setStderr :: StreamSpec 'STOutput stderr -> ProcessConfig stdin stdout stderr0 -> ProcessConfig stdin stdout stderr -- | Set the working directory of the child process. -- -- Default: current process's working directory. setWorkingDir :: FilePath -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Inherit the working directory from the parent process. setWorkingDirInherit :: ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Set the environment variables of the child process. -- -- Default: current process's environment. setEnv :: [(String, String)] -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Inherit the environment variables from the parent process. setEnvInherit :: ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Should we close all file descriptors besides stdin, stdout, and -- stderr? See close_fds for more information. -- -- Default: False setCloseFds :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Should we create a new process group? -- -- Default: False setCreateGroup :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Delegate handling of Ctrl-C to the child. For more information, see -- delegate_ctlc. -- -- Default: False setDelegateCtlc :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Detach console on Windows, see detach_console. -- -- Default: False setDetachConsole :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Create new console on Windows, see create_new_console. -- -- Default: False setCreateNewConsole :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Set a new session with the POSIX setsid syscall, does nothing -- on non-POSIX. See new_session. -- -- Default: False setNewSession :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Set the child process's group ID with the POSIX setgid -- syscall, does nothing on non-POSIX. See child_group. -- -- Default: False setChildGroup :: GroupID -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Inherit the group from the parent process. setChildGroupInherit :: ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Set the child process's user ID with the POSIX setuid -- syscall, does nothing on non-POSIX. See child_user. -- -- Default: False setChildUser :: UserID -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Inherit the user from the parent process. setChildUserInherit :: ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr -- | Create a new StreamSpec from the given StdStream and a -- helper function. This function: -- -- mkStreamSpec :: StdStream -> (ProcessConfig () () () -> Maybe Handle -> IO (a, IO ())) -> StreamSpec streamType a -- | A stream spec which simply inherits the stream of the parent process. inherit :: StreamSpec anyStreamType () -- | A stream spec which will close the stream for the child process. closed :: StreamSpec anyStreamType () -- | An input stream spec which sets the input to the given -- ByteString. A separate thread will be forked to write the -- contents to the child process. byteStringInput :: ByteString -> StreamSpec 'STInput () -- | Capture the output of a process in a ByteString. -- -- This function will fork a separate thread to consume all input from -- the process, and will only make the results available when the -- underlying Handle is closed. As this is provided as an -- STM action, you can either check if the result is available, or -- block until it's ready. -- -- In the event of any exception occurring when reading from the -- Handle, the STM action will throw a -- ByteStringOutputException. byteStringOutput :: StreamSpec 'STOutput (STM ByteString) -- | Create a new pipe between this process and the child, and return a -- Handle to communicate with the child. createPipe :: StreamSpec anyStreamType Handle -- | Use the provided Handle for the child process, and when the -- process exits, do not close it. This is useful if, for example, -- you want to have multiple processes write to the same log file -- sequentially. useHandleOpen :: Handle -> StreamSpec anyStreamType () -- | Use the provided Handle for the child process, and when the -- process exits, close it. If you have no reason to keep the -- Handle open, you should use this over useHandleOpen. useHandleClose :: Handle -> StreamSpec anyStreamType () -- | Launch a process based on the given ProcessConfig. You should -- ensure that you close stopProcess on the result. It's usually -- better to use one of the functions in this module which ensures -- stopProcess is called, such as withProcess. startProcess :: MonadIO m => ProcessConfig stdin stdout stderr -> m (Process stdin stdout stderr) -- | Close a process and release any resources acquired. This will ensure -- terminateProcess is called, wait for the process to actually -- exit, and then close out resources allocated for the streams. In the -- event of any cleanup exceptions being thrown this will throw an -- exception. stopProcess :: MonadIO m => Process stdin stdout stderr -> m () -- | Uses the bracket pattern to call startProcess and ensures that -- stopProcess is called. -- -- In version 0.2.0.0, this function was monomorphized to IO to -- avoid a dependency on the exceptions package. withProcess :: ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> IO a) -> IO a -- | Same as withProcess, but also calls checkExitCode -- -- In version 0.2.0.0, this function was monomorphized to IO to -- avoid a dependency on the exceptions package. withProcess_ :: ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> IO a) -> IO a -- | Run a process, capture its standard output and error as a -- ByteString, wait for it to complete, and then return its exit -- code, output, and error. -- -- Note that any previously used setStdout or setStderr -- will be overridden. readProcess :: MonadIO m => ProcessConfig stdin stdoutIgnored stderrIgnored -> m (ExitCode, ByteString, ByteString) -- | Same as readProcess, but instead of returning the -- ExitCode, checks it with checkExitCode. readProcess_ :: MonadIO m => ProcessConfig stdin stdoutIgnored stderrIgnored -> m (ByteString, ByteString) -- | Run the given process, wait for it to exit, and returns its -- ExitCode. runProcess :: MonadIO m => ProcessConfig stdin stdout stderr -> m ExitCode -- | Same as runProcess, but instead of returning the -- ExitCode, checks it with checkExitCode. runProcess_ :: MonadIO m => ProcessConfig stdin stdout stderr -> m () -- | Same as readProcess, but only read the stdout of the process. -- Original settings for stderr remain. readProcessStdout :: MonadIO m => ProcessConfig stdin stdoutIgnored stderr -> m (ExitCode, ByteString) -- | Same as readProcessStdout, but instead of returning the -- ExitCode, checks it with checkExitCode. readProcessStdout_ :: MonadIO m => ProcessConfig stdin stdoutIgnored stderr -> m ByteString -- | Same as readProcess, but only read the stderr of the process. -- Original settings for stderr remain. readProcessStderr :: MonadIO m => ProcessConfig stdin stderrIgnored stderr -> m (ExitCode, ByteString) -- | Same as readProcessStderr, but instead of returning the -- ExitCode, checks it with checkExitCode. readProcessStderr_ :: MonadIO m => ProcessConfig stdin stderrIgnored stderr -> m ByteString -- | Wait for the process to exit and then return its ExitCode. waitExitCode :: MonadIO m => Process stdin stdout stderr -> m ExitCode -- | Same as waitExitCode, but in STM. waitExitCodeSTM :: Process stdin stdout stderr -> STM ExitCode -- | Check if a process has exited and, if so, return its ExitCode. getExitCode :: MonadIO m => Process stdin stdout stderr -> m (Maybe ExitCode) -- | Same as getExitCode, but in STM. getExitCodeSTM :: Process stdin stdout stderr -> STM (Maybe ExitCode) -- | Wait for a process to exit, and ensure that it exited successfully. If -- not, throws an ExitCodeException. checkExitCode :: MonadIO m => Process stdin stdout stderr -> m () -- | Same as checkExitCode, but in STM. checkExitCodeSTM :: Process stdin stdout stderr -> STM () -- | Get the child's standard input stream value. getStdin :: Process stdin stdout stderr -> stdin -- | Get the child's standard output stream value. getStdout :: Process stdin stdout stderr -> stdout -- | Get the child's standard error stream value. getStderr :: Process stdin stdout stderr -> stderr -- | Exception thrown by checkExitCode in the event of a non-success -- exit code. Note that checkExitCode is called by other functions -- as well, like runProcess_ or readProcess_. data ExitCodeException ExitCodeException :: ExitCode -> ProcessConfig () () () -> ByteString -> ByteString -> ExitCodeException [eceExitCode] :: ExitCodeException -> ExitCode [eceProcessConfig] :: ExitCodeException -> ProcessConfig () () () [eceStdout] :: ExitCodeException -> ByteString [eceStderr] :: ExitCodeException -> ByteString -- | Wrapper for when an exception is thrown when reading from a child -- process, used by byteStringOutput. data ByteStringOutputException ByteStringOutputException :: SomeException -> (ProcessConfig () () ()) -> ByteStringOutputException -- | Take ProcessHandle out of the Process. This method is -- needed in cases one need to use low level functions from the -- process package. Use cases for this method are: -- --
    --
  1. Send a special signal to the process.
    2. --
  2. Terminate the process group instead of terminating single -- process.
    3. --
  3. Use platform specific API on the underlying process.
    4. --
-- -- This method is considered unsafe because the actions it performs on -- the underlying process may overlap with the functionality that -- typed-process provides. For example the user should not call -- waitForProcess on the process handle as eiter -- waitForProcess or stopProcess will lock. Additionally, -- even if process was terminated by the terminateProcess or by -- sending signal, stopProcess should be called either way in -- order to cleanup resources allocated by the typed-process. unsafeProcessHandle :: Process stdin stdout stderr -> ProcessHandle instance GHC.Show.Show System.Process.Typed.ByteStringOutputException instance GHC.Base.Functor (System.Process.Typed.StreamSpec streamType) instance GHC.Base.Functor System.Process.Typed.Cleanup instance GHC.Exception.Exception System.Process.Typed.ByteStringOutputException instance GHC.Exception.Exception System.Process.Typed.ExitCodeException instance GHC.Show.Show System.Process.Typed.ExitCodeException instance GHC.Show.Show (System.Process.Typed.Process stdin stdout stderr) instance GHC.Show.Show (System.Process.Typed.ProcessConfig stdin stdout stderr) instance (stdin ~ (), stdout ~ (), stderr ~ ()) => Data.String.IsString (System.Process.Typed.ProcessConfig stdin stdout stderr) instance (streamType ~ 'System.Process.Typed.STInput, res ~ ()) => Data.String.IsString (System.Process.Typed.StreamSpec streamType res) instance GHC.Base.Applicative System.Process.Typed.Cleanup