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