-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Alternative API for processes, featuring more type safety
--
-- Please see README.md
@package typed-process
@version 0.1.0.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:
--
--
-- - With the proc smart constructor, which takes a command name
-- and a list of arguments.
-- - With the shell smart constructor, which takes a shell
-- string
-- - With the IsString instance via OverloadedStrings. If you
-- provide it a string with no spaces (e.g., "date"), it will
-- treat it as a raw command with no arguments (e.g., proc "date"
-- []). If it has spaces, it will use shell.
--
--
-- 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
-- | Set the environment variables of the child process.
--
-- Default: current process's environment.
setEnv :: [(String, String)] -> 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
-- | 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
-- | Should we throw an exception when the process exits with a non-success
-- code?
--
-- If set to True, then when stopProcess is called - either
-- directly or via withProcess or other wrappers - the processes
-- exit code will be checked. Any exit code besides ExitSuccess
-- will result in an ExitCodeException being thrown.
--
-- Default: False
setCheckExitCode :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr
-- | Create a new StreamSpec from the given StdStream and a
-- helper function. This function:
--
--
-- - Takes as input the raw Maybe Handle returned by the
-- createProcess function. This will be determined by the
-- StdStream argument.
-- - Returns the actual stream value a, as well as a
-- cleanup
-- - function to be run when calling stopProcess.
--
mkStreamSpec :: StdStream -> (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 result of this function will be a Left value
-- containing a ByteStringOutputException.
byteStringOutput :: StreamSpec STOutput (STM (Either ByteStringOutputException 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 ()
-- | Provide input to a process by writing to a conduit.
sink :: MonadIO m => StreamSpec STInput (ConduitM ByteString o m ())
-- | Read output from a process by read from a conduit.
source :: MonadIO m => StreamSpec STOutput (ConduitM i ByteString m ())
-- | 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, or if a non-success exit
-- code was received and setCheckExitCode was used, this will
-- throw an exception.
stopProcess :: MonadIO m => Process stdin stdout stderr -> m ()
-- | Use the bracket pattern to call startProcess and ensure
-- stopProcess is called.
withProcess :: (MonadIO m, MonadMask m) => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m 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)
-- | 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 ignores the ExitCode.
runProcess_ :: MonadIO m => ProcessConfig stdin stdout stderr -> m ()
-- | 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.
checkExitCode :: MonadIO m => Process stdin stdout stderr -> m (Maybe ExitCode)
-- | Same as checkExitCode, but in STM.
checkExitCodeSTM :: Process stdin stdout stderr -> STM (Maybe ExitCode)
-- | 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
-- | Exit code generated by stopProcess when setCheckExitCode
-- is True and a process exits with a non-success code. Contains
-- the non-success code, and if any other exceptions occur during
-- cleanup, that exception.
data ExitCodeException
ExitCodeException :: ExitCode -> (Maybe SomeException) -> ExitCodeException
-- | Wrapper for when an exception is thrown when reading from a child
-- process, used by byteStringOutput.
newtype ByteStringOutputException
ByteStringOutputException :: SomeException -> ByteStringOutputException
instance GHC.Show.Show System.Process.Typed.ByteStringOutputException
instance GHC.Show.Show System.Process.Typed.ExitCodeException
instance GHC.Base.Functor (System.Process.Typed.StreamSpec streamType)
instance GHC.Base.Functor System.Process.Typed.Cleanup
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
instance GHC.Exception.Exception System.Process.Typed.ExitCodeException
instance GHC.Exception.Exception System.Process.Typed.ByteStringOutputException