-- 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
--   <a>https://github.com/fpco/typed-process#readme</a>
@package typed-process
@version 0.2.7.0

module System.Process.Typed.Internal

-- | The name of the system null device
nullDevice :: FilePath


-- | The simplest way to get started with this API is to turn on
--   <tt>OverloadedStrings</tt> and call <a>runProcess</a>. The following
--   will write the contents of <tt>/home</tt> to <tt>stdout</tt> and then
--   print the exit code (on a UNIX system).
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   <a>runProcess</a> "ls -l /home" &gt;&gt;= print
--   </pre>
--   
--   Please see the <a>README.md</a> file for more 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
--   <a>setters below</a> for default values.
--   
--   Once you have a <tt>ProcessConfig</tt> you can launch a process from
--   it using the functions in the section <a>Launch a process</a>.
data ProcessConfig stdin stdout stderr

-- | A specification for how to create one of the three standard child
--   streams, <tt>stdin</tt>, <tt>stdout</tt> and <tt>stderr</tt>. A
--   <a>StreamSpec</a> can be thought of as containing
--   
--   <ol>
--   <li>A type safe version of <a>StdStream</a> from
--   <a>System.Process</a>. This determines whether the stream should be
--   inherited from the parent process, piped to or from a <a>Handle</a>,
--   etc.</li>
--   <li>A means of accessing the stream as a value of type <tt>a</tt></li>
--   <li>A cleanup action which will be run on the stream once the process
--   terminates</li>
--   </ol>
--   
--   To create a <tt>StreamSpec</tt> see the section <a>Stream specs</a>.
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.
--   
--   To interact with a <tt>Process</tt> use the functions from the section
--   <a>Interact with a process</a>.
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

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

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

-- | Inherit the user from the parent process.
setChildUserInherit :: ProcessConfig stdin stdout stderr -> ProcessConfig stdin stdout stderr

-- | A stream spec which simply inherits the stream of the parent process.
inherit :: StreamSpec anyStreamType ()

-- | A stream spec which is empty when used for for input and discards
--   output. Note this requires your platform's null device to be available
--   when the process is started.
nullStream :: StreamSpec anyStreamType ()

-- | A stream spec which will close the stream for the child process. You
--   usually do not want to use this, as it will leave the corresponding
--   file descriptor unassigned and hence available for re-use in the child
--   process. Prefer <a>nullStream</a> unless you're certain you want this
--   behavior.
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 ()

-- | 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. The handle will be <tt>Just</tt>
--   <a>Handle</a> if the <a>StdStream</a> argument is <a>CreatePipe</a>
--   and <tt>Nothing</tt> otherwise. See <a>createProcess</a> for more
--   details.</li>
--   <li>Returns the actual stream value <tt>a</tt>, as well as a cleanup
--   function to be run when calling <a>stopProcess</a>.</li>
--   </ul>
mkStreamSpec :: StdStream -> (ProcessConfig () () () -> Maybe Handle -> IO (a, IO ())) -> StreamSpec streamType a

-- | Run the given process, wait for it to exit, and returns its
--   <a>ExitCode</a>.
runProcess :: MonadIO m => ProcessConfig stdin stdout stderr -> m ExitCode

-- | 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 only read the stdout of the process.
--   Original settings for stderr remain.
readProcessStdout :: MonadIO m => ProcessConfig stdin stdoutIgnored stderr -> m (ExitCode, ByteString)

-- | Same as <a>readProcess</a>, but only read the stderr of the process.
--   Original settings for stdout remain.
readProcessStderr :: MonadIO m => ProcessConfig stdin stdout stderrIgnored -> m (ExitCode, ByteString)

-- | Same as <a>readProcess</a>, but interleaves stderr with stdout.
--   
--   Motivation: Use this function if you need stdout interleaved with
--   stderr output (e.g. from an HTTP server) in order to debug failures.
readProcessInterleaved :: MonadIO m => ProcessConfig stdin stdoutIgnored stderrIgnored -> m (ExitCode, ByteString)

-- | Uses the bracket pattern to call <a>startProcess</a>. Unlike
--   <a>withProcessTerm</a>, this function will wait for the child process
--   to exit, and only kill it with <a>stopProcess</a> in the event that
--   the inner function throws an exception.
--   
--   To interact with a <tt>Process</tt> use the functions from the section
--   <a>Interact with a process</a>.
withProcessWait :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | Uses the bracket pattern to call <a>startProcess</a> and ensures that
--   <a>stopProcess</a> is called.
--   
--   This function is usually <i>not</i> what you want. You're likely
--   better off using <a>withProcessWait</a>. See
--   <a>https://github.com/fpco/typed-process/issues/25</a>.
withProcessTerm :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | Launch a process based on the given <a>ProcessConfig</a>. You should
--   ensure that you call <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>withProcessWait</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 ()

-- | Same as <a>runProcess</a>, but instead of returning the
--   <a>ExitCode</a>, checks it with <a>checkExitCode</a>.
runProcess_ :: MonadIO m => ProcessConfig stdin stdout stderr -> m ()

-- | Same as <a>readProcess</a>, but instead of returning the
--   <a>ExitCode</a>, checks it with <a>checkExitCode</a>.
--   
--   Exceptions thrown by this function will include stdout and stderr.
readProcess_ :: MonadIO m => ProcessConfig stdin stdoutIgnored stderrIgnored -> m (ByteString, ByteString)

-- | Same as <a>readProcessStdout</a>, but instead of returning the
--   <a>ExitCode</a>, checks it with <a>checkExitCode</a>.
--   
--   Exceptions thrown by this function will include stdout.
readProcessStdout_ :: MonadIO m => ProcessConfig stdin stdoutIgnored stderr -> m ByteString

-- | Same as <a>readProcessStderr</a>, but instead of returning the
--   <a>ExitCode</a>, checks it with <a>checkExitCode</a>.
--   
--   Exceptions thrown by this function will include stderr.
readProcessStderr_ :: MonadIO m => ProcessConfig stdin stdout stderrIgnored -> m ByteString

-- | Same as <a>readProcessInterleaved</a>, but instead of returning the
--   <a>ExitCode</a>, checks it with <a>checkExitCode</a>.
--   
--   Exceptions thrown by this function will include stdout.
readProcessInterleaved_ :: MonadIO m => ProcessConfig stdin stdoutIgnored stderrIgnored -> m ByteString

-- | Same as <a>withProcessWait</a>, but also calls <a>checkExitCode</a>
withProcessWait_ :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | Same as <a>withProcessTerm</a>, but also calls <a>checkExitCode</a>
--   
--   To interact with a <tt>Process</tt> use the functions from the section
--   <a>Interact with a process</a>.
withProcessTerm_ :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | 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>.
--   
--   Exceptions thrown by this function will not include stdout or stderr
--   (This prevents unbounded memory usage from reading them into memory).
--   However, some callers such as <a>readProcess_</a> catch the exception,
--   add the stdout and stderr, and rethrow.
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>.
--   
--   Note that several functions that throw an <a>ExitCodeException</a>
--   intentionally do not populate <a>eceStdout</a> or <a>eceStderr</a>.
--   This prevents unbounded memory usage for large stdout and stderrs.
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

-- | Deprecated synonym for <a>withProcessTerm</a>.

-- | <i>Deprecated: Please consider using withProcessWait, or instead use
--   withProcessTerm</i>
withProcess :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a

-- | Deprecated synonym for <a>withProcessTerm_</a>.

-- | <i>Deprecated: Please consider using withProcessWait_, or instead use
--   withProcessTerm_</i>
withProcess_ :: MonadUnliftIO m => ProcessConfig stdin stdout stderr -> (Process stdin stdout stderr -> m a) -> m a
instance GHC.Base.Functor System.Process.Typed.Cleanup
instance GHC.Base.Functor (System.Process.Typed.StreamSpec streamType)
instance GHC.Show.Show System.Process.Typed.ByteStringOutputException
instance GHC.Exception.Type.Exception System.Process.Typed.ByteStringOutputException
instance GHC.Exception.Type.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 GHC.Types.~ (), stdout GHC.Types.~ (), stderr GHC.Types.~ ()) => Data.String.IsString (System.Process.Typed.ProcessConfig stdin stdout stderr)
instance (streamType GHC.Types.~ 'System.Process.Typed.STInput, res GHC.Types.~ ()) => Data.String.IsString (System.Process.Typed.StreamSpec streamType res)
instance GHC.Base.Applicative System.Process.Typed.Cleanup