-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Run external processes, with strong typing of streams
--   
--   Please see README.md
@package typed-process
@version 0.1.1


-- | 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

-- | 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 -> (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
--   <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 <a>STM</a> action will throw a
--   <a>ByteStringOutputException</a>.
byteStringOutput :: StreamSpec STOutput (STM 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.
createSink :: MonadIO m => StreamSpec STInput (ConduitM ByteString o m ())

-- | Read output from a process by read from a conduit.
createSource :: 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 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

-- | Same as <a>withProcess</a>, but also calls <a>checkExitCode</a>
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)

-- | Same as <a>readProcess</a>, but instead of returning the
--   <a>ExitCode</a>, checks it with <a>checkExitCode</a>.
readProcess_ :: MonadIO m => ProcessConfig stdin stdoutIgnored stderrIgnored -> m (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>.
getExitCode :: MonadIO m => Process stdin stdout stderr -> m (Maybe ExitCode)

-- | Same as <a>getExitCode</a>, but in <a>STM</a>.
getExitCodeSTM :: Process stdin stdout stderr -> STM (Maybe ExitCode)

-- | Wait for a process to exit, and ensure that it exited successfully. If
--   not, throws an <a>ExitCodeException</a>.
checkExitCode :: MonadIO m => Process stdin stdout stderr -> m ()

-- | Same as <a>checkExitCode</a>, but in <a>STM</a>.
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 <a>checkExitCode</a> in the event of a non-success
--   exit code. Note that <a>checkExitCode</a> is called by other functions
--   as well, like <a>runProcess_</a> or <a>readProcess_</a>.
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 <a>byteStringOutput</a>.
data ByteStringOutputException
ByteStringOutputException :: SomeException -> (ProcessConfig () () ()) -> ByteStringOutputException

-- | Take <a>ProcessHandle</a> out of the <a>Process</a>. This method is
--   needed in cases one need to use low level functions from the
--   <tt>process</tt> package. Use cases for this method are:
--   
--   <ol>
--   <li>Send a special signal to the process.</li>
--   <li>Terminate the process group instead of terminating single
--   process.</li>
--   <li>Use platform specific API on the underlying process.</li>
--   </ol>
--   
--   This method is considered unsafe because the actions it performs on
--   the underlying process may overlap with the functionality that
--   <tt>typed-process</tt> provides. For example the user should not call
--   <a>waitForProcess</a> on the process handle as eiter
--   <a>waitForProcess</a> or <a>stopProcess</a> will lock. Additionally,
--   even if process was terminated by the <a>terminateProcess</a> or by
--   sending signal, <a>stopProcess</a> should be called either way in
--   order to cleanup resources allocated by the <tt>typed-process</tt>.
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.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
instance GHC.Show.Show (System.Process.Typed.Process stdin stdout stderr)
instance GHC.Exception.Exception System.Process.Typed.ExitCodeException
instance GHC.Show.Show System.Process.Typed.ExitCodeException
instance GHC.Exception.Exception System.Process.Typed.ByteStringOutputException
