272 lines
12 KiB
Text
272 lines
12 KiB
Text
-- 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 <a>Process</a>. 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:
|
|
--
|
|
-- <ul>
|
|
-- <li>With the <a>proc</a> smart constructor, which takes a command name
|
|
-- and a list of arguments.</li>
|
|
-- <li>With the <a>shell</a> smart constructor, which takes a shell
|
|
-- string</li>
|
|
-- <li>With the <a>IsString</a> instance via OverloadedStrings. If you
|
|
-- provide it a string with no spaces (e.g., <tt>"date"</tt>), it will
|
|
-- treat it as a raw command with no arguments (e.g., <tt>proc "date"
|
|
-- []</tt>). If it has spaces, it will use <tt>shell</tt>.</li>
|
|
-- </ul>
|
|
--
|
|
-- 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 <i>child process</i>, so that a child's
|
|
-- standard input stream is an <tt>STInput</tt>, 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 <a>ProcessConfig</a> from the given command and arguments.
|
|
proc :: FilePath -> [String] -> ProcessConfig () () ()
|
|
|
|
-- | Create a <a>ProcessConfig</a> from the given shell command.
|
|
shell :: String -> ProcessConfig () () ()
|
|
|
|
-- | Set the child's standard input stream to the given <a>StreamSpec</a>.
|
|
--
|
|
-- Default: <a>inherit</a>
|
|
setStdin :: StreamSpec STInput stdin -> ProcessConfig stdin0 stdout stderr -> ProcessConfig stdin stdout stderr
|
|
|
|
-- | Set the child's standard output stream to the given <a>StreamSpec</a>.
|
|
--
|
|
-- Default: <a>inherit</a>
|
|
setStdout :: StreamSpec STOutput stdout -> ProcessConfig stdin stdout0 stderr -> ProcessConfig stdin stdout stderr
|
|
|
|
-- | Set the child's standard error stream to the given <a>StreamSpec</a>.
|
|
--
|
|
-- Default: <a>inherit</a>
|
|
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 <a>close_fds</a> 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
|
|
-- <a>delegate_ctlc</a>.
|
|
--
|
|
-- Default: False
|
|
setDelegateCtlc :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr
|
|
|
|
-- | Detach console on Windows, see <a>detach_console</a>.
|
|
--
|
|
-- Default: False
|
|
setDetachConsole :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr
|
|
|
|
-- | Create new console on Windows, see <a>create_new_console</a>.
|
|
--
|
|
-- Default: False
|
|
setCreateNewConsole :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr
|
|
|
|
-- | Set a new session with the POSIX <tt>setsid</tt> syscall, does nothing
|
|
-- on non-POSIX. See <a>new_session</a>.
|
|
--
|
|
-- Default: False
|
|
setNewSession :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr
|
|
|
|
-- | Set the child process's group ID with the POSIX <tt>setgid</tt>
|
|
-- syscall, does nothing on non-POSIX. See <a>child_group</a>.
|
|
--
|
|
-- Default: False
|
|
setChildGroup :: GroupID -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr
|
|
|
|
-- | Set the child process's user ID with the POSIX <tt>setuid</tt>
|
|
-- syscall, does nothing on non-POSIX. See <a>child_user</a>.
|
|
--
|
|
-- 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 <a>True</a>, then when <a>stopProcess</a> is called - either
|
|
-- directly or via <a>withProcess</a> or other wrappers - the processes
|
|
-- exit code will be checked. Any exit code besides <a>ExitSuccess</a>
|
|
-- will result in an <a>ExitCodeException</a> being thrown.
|
|
--
|
|
-- Default: <a>False</a>
|
|
setCheckExitCode :: Bool -> ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr
|
|
|
|
-- | Create a new <a>StreamSpec</a> from the given <a>StdStream</a> and a
|
|
-- helper function. This function:
|
|
--
|
|
-- <ul>
|
|
-- <li>Takes as input the raw <tt>Maybe Handle</tt> returned by the
|
|
-- <a>createProcess</a> function. This will be determined by the
|
|
-- <a>StdStream</a> argument.</li>
|
|
-- <li>Returns the actual stream value <tt>a</tt>, as well as a
|
|
-- cleanup</li>
|
|
-- <li>function to be run when calling <a>stopProcess</a>.</li>
|
|
-- </ul>
|
|
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
|
|
-- <a>ByteString</a>. 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 <a>ByteString</a>.
|
|
--
|
|
-- This function will fork a separate thread to consume all input from
|
|
-- the process, and will only make the results available when the
|
|
-- underlying <a>Handle</a> is closed. As this is provided as an
|
|
-- <a>STM</a> 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
|
|
-- <a>Handle</a>, the result of this function will be a <a>Left</a> value
|
|
-- containing a <a>ByteStringOutputException</a>.
|
|
byteStringOutput :: StreamSpec STOutput (STM (Either ByteStringOutputException ByteString))
|
|
|
|
-- | Create a new pipe between this process and the child, and return a
|
|
-- <a>Handle</a> to communicate with the child.
|
|
createPipe :: StreamSpec anyStreamType Handle
|
|
|
|
-- | Use the provided <a>Handle</a> for the child process, and when the
|
|
-- process exits, do <i>not</i> 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 <a>Handle</a> for the child process, and when the
|
|
-- process exits, close it. If you have no reason to keep the
|
|
-- <a>Handle</a> open, you should use this over <a>useHandleOpen</a>.
|
|
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 <a>ProcessConfig</a>. You should
|
|
-- ensure that you close <a>stopProcess</a> on the result. It's usually
|
|
-- better to use one of the functions in this module which ensures
|
|
-- <a>stopProcess</a> is called, such as <a>withProcess</a>.
|
|
startProcess :: MonadIO m => ProcessConfig stdin stdout stderr -> m (Process stdin stdout stderr)
|
|
|
|
-- | Close a process and release any resources acquired. This will ensure
|
|
-- <a>terminateProcess</a> 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 <a>setCheckExitCode</a> was used, this will
|
|
-- throw an exception.
|
|
stopProcess :: MonadIO m => Process stdin stdout stderr -> m ()
|
|
|
|
-- | Use the bracket pattern to call <a>startProcess</a> and ensure
|
|
-- <a>stopProcess</a> 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
|
|
-- <a>ByteString</a>, wait for it to complete, and then return its exit
|
|
-- code, output, and error.
|
|
--
|
|
-- Note that any previously used <a>setStdout</a> or <a>setStderr</a>
|
|
-- 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
|
|
-- <a>ExitCode</a>.
|
|
runProcess :: MonadIO m => ProcessConfig stdin stdout stderr -> m ExitCode
|
|
|
|
-- | Same as <a>runProcess</a>, but ignores the <a>ExitCode</a>.
|
|
runProcess_ :: MonadIO m => ProcessConfig stdin stdout stderr -> m ()
|
|
|
|
-- | Wait for the process to exit and then return its <a>ExitCode</a>.
|
|
waitExitCode :: MonadIO m => Process stdin stdout stderr -> m ExitCode
|
|
|
|
-- | Same as <a>waitExitCode</a>, but in <a>STM</a>.
|
|
waitExitCodeSTM :: Process stdin stdout stderr -> STM ExitCode
|
|
|
|
-- | Check if a process has exited and, if so, return its <a>ExitCode</a>.
|
|
checkExitCode :: MonadIO m => Process stdin stdout stderr -> m (Maybe ExitCode)
|
|
|
|
-- | Same as <a>checkExitCode</a>, but in <a>STM</a>.
|
|
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 <a>stopProcess</a> when <a>setCheckExitCode</a>
|
|
-- is <a>True</a> 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 <a>byteStringOutput</a>.
|
|
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
|