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


-- | Streaming interface to system processes.
--   
--   Concurrent, streaming access to the input and outputs of system
--   processes.
@package process-streaming
@version 0.9.2


-- | Lenses and traversals for <a>CreateProcess</a> and related types.
--   
--   These are provided as a convenience and aren't at all required to use
--   the other modules of this package.
--   
--   For basic lens functionality with few dependencies, the
--   <tt>microlens</tt> package is a good option.
module System.Process.Lens

-- | <pre>
--   _cmdspec :: Lens' CreateProcess CmdSpec 
--   </pre>
_cmdspec :: forall f. Functor f => (CmdSpec -> f CmdSpec) -> CreateProcess -> f CreateProcess

-- | <pre>
--   _ShellCommand :: Traversal' CmdSpec String
--   </pre>
_ShellCommand :: forall m. Applicative m => (String -> m String) -> CmdSpec -> m CmdSpec

-- | <pre>
--   _RawCommand :: Traversal' CmdSpec (FilePath,[String])
--   </pre>
_RawCommand :: forall m. Applicative m => ((FilePath, [String]) -> m (FilePath, [String])) -> CmdSpec -> m CmdSpec

-- | <pre>
--   _cwd :: Lens' CreateProcess (Maybe FilePath)
--   </pre>
_cwd :: forall f. Functor f => (Maybe FilePath -> f (Maybe FilePath)) -> CreateProcess -> f CreateProcess

-- | <pre>
--   _env :: Lens' CreateProcess (Maybe [(String,String)])
--   </pre>
_env :: forall f. Functor f => (Maybe [(String, String)] -> f (Maybe [(String, String)])) -> CreateProcess -> f CreateProcess

-- | An improper lens to get and insert values in an association list. It
--   assumes that there are no duplicate keys in the list.
envAt :: (Eq k, Applicative f) => k -> (Maybe v -> f (Maybe v)) -> ([(k, v)] -> f [(k, v)])

-- | A lens for the <tt>(std_in,std_out,std_err)</tt> triplet.
--   
--   <pre>
--   std_streams :: Lens' CreateProcess (StdStream,StdStream,StdStream)
--   </pre>
std_streams :: forall f. Functor f => ((StdStream, StdStream, StdStream) -> f (StdStream, StdStream, StdStream)) -> CreateProcess -> f CreateProcess
_std_in :: forall f. Functor f => (StdStream -> f (StdStream)) -> CreateProcess -> f CreateProcess
_std_out :: forall f. Functor f => (StdStream -> f (StdStream)) -> CreateProcess -> f CreateProcess
_std_err :: forall f. Functor f => (StdStream -> f (StdStream)) -> CreateProcess -> f CreateProcess
_close_fds :: forall f. Functor f => (Bool -> f Bool) -> CreateProcess -> f CreateProcess
_create_group :: forall f. Functor f => (Bool -> f Bool) -> CreateProcess -> f CreateProcess
_delegate_ctlc :: forall f. Functor f => (Bool -> f Bool) -> CreateProcess -> f CreateProcess
_detach_console :: forall f. Functor f => (Bool -> f Bool) -> CreateProcess -> f CreateProcess
_create_new_console :: forall f. Functor f => (Bool -> f Bool) -> CreateProcess -> f CreateProcess
_new_session :: forall f. Functor f => (Bool -> f Bool) -> CreateProcess -> f CreateProcess


-- | This module contains helper functions and types built on top of
--   <a>System.Process</a>.
--   
--   They provide concurrent, streaming access to the inputs and outputs of
--   external processes.
--   
--   <a>Consumer</a>s from <tt>pipes</tt>, <tt>Parser</tt>s from
--   <tt>pipes-parse</tt> and <tt>Fold</tt>s from <tt>foldl</tt> can be
--   used to consume the standard streams, by means of the auxiliary
--   <a>Fold1</a> datatype from <tt>pipes-transduce</tt>.
--   
--   The entirety of <a>System.Process</a> and <a>Pipes.Transduce</a> is
--   re-exported for convenience.
module System.Process.Streaming

-- | Execute an external program described by the <a>CreateProcess</a>
--   record.
--   
--   The <a>Streams</a> Applicative specifies how to handle the standard
--   streams and the exit code. Since <a>Streams</a> is an Applicative, a
--   simple invocation of <a>execute</a> could be
--   
--   <pre>
--   &gt;&gt;&gt; execute (piped (shell "echo foo")) (pure ())
--   </pre>
--   
--   which would discard the program's stdout and stderr, and ignore the
--   exit code. To actually get the exit code:
--   
--   <pre>
--   &gt;&gt;&gt; execute (piped (shell "echo foo")) exitCode
--   ExitSuccess
--   </pre>
--   
--   To collect stdout as a lazy <a>ByteString</a> along with the exit
--   code:
--   
--   <pre>
--   &gt;&gt;&gt; execute (piped (shell "echo foo")) (liftA2 (,) (foldOut intoLazyBytes) exitCode)
--   ("foo\n",ExitSuccess)
--   </pre>
--   
--   <a>execute</a> respects all the fields of the <a>CreateProcess</a>
--   record. If stdout is not piped, but a handler is defined for it, the
--   handler will see an empty stream:
--   
--   <pre>
--   &gt;&gt;&gt; execute ((shell "echo foo"){ std_out = Inherit }) (foldOut intoLazyBytes)
--   foo
--   ""
--   </pre>
--   
--   No effort is made to catch exceptions thrown during execution:
--   
--   <pre>
--   &gt;&gt;&gt; execute (piped (shell "echo foo")) (foldOut (withCont (\_ -&gt; throwIO (userError "oops"))))
--   *** Exception: user error (oops)
--   </pre>
--   
--   However, care is taken to automatically terminate the external process
--   if an exception (including asynchronous ones) or other type of error
--   happens. This means we can terminate the external process by killing
--   the thread that is running <a>execute</a>:
--   
--   <pre>
--   &gt;&gt;&gt; forkIO (execute (piped (shell "sleep infinity")) (pure ())) &gt;&gt;= killThread
--   </pre>
execute :: CreateProcess -> Streams Void a -> IO a

-- | Like <a>execute</a>, but allows the handlers in the <a>Streams</a>
--   Applicative to interrupt the execution of the external process by
--   returning a <a>Left</a> value, in addition to throwing exceptions.
--   This is sometimes more convenient:
--   
--   <pre>
--   &gt;&gt;&gt; executeFallibly (piped (shell "sleep infinity")) (foldOut (withFallibleCont (\_ -&gt; pure (Left "oops"))))
--   Left "oops"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; executeFallibly (piped (shell "exit 1")) validateExitCode
--   Left 1
--   </pre>
--   
--   The first type parameter of <a>Streams</a> is the error type. If it is
--   never used, it remains polymorphic and may unify with <a>Void</a> (as
--   required by <a>execute</a>).
executeFallibly :: CreateProcess -> Streams e a -> IO (Either e a)

-- | Like <a>execute</a>, but <a>std_in</a> will be unbuffered if piped.
executeInteractive :: CreateProcess -> Streams Void a -> IO a

-- | Like <a>executeFallibly</a>, but <a>std_in</a> will be unbuffered if
--   piped.
executeInteractiveFallibly :: CreateProcess -> Streams e a -> IO (Either e a)

-- | Sets <a>std_in</a>, <a>std_out</a> and <a>std_err</a> in the
--   <a>CreateProcess</a> record to <a>CreatePipe</a>.
--   
--   Any unpiped stream will appear to the <a>Streams</a> handlers as
--   empty.
piped :: CreateProcess -> CreateProcess

-- | The type of handlers that write to piped <tt>stdin</tt>, consume piped
--   <tt>stdout</tt> and <tt>stderr</tt>, and work with the process exit
--   code, eventually returning a value of type <tt>r</tt>, except when an
--   error <tt>e</tt> interrups the execution.
--   
--   Example of a complex handler:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       execute (piped (shell "{ cat ; sleep 1 ; echo eee 1&gt;&amp;2 ; }")) $ 
--           (\_ _ o e oe ec -&gt; (o,e,oe,ec)) 
--           &lt;$&gt;
--           feedBytes (Just "aaa") 
--           &lt;*&gt; 
--           feedBytes (Just "bbb") 
--           &lt;*&gt; 
--           foldOut intoLazyBytes 
--           &lt;*&gt;
--           foldErr intoLazyBytes 
--           &lt;*&gt;
--           foldOutErr (combined (PT.lines PT.utf8x) (PT.lines PT.utf8x) PT.intoLazyText)
--           &lt;*&gt;
--           exitCode
--       :}
--   ("aaabbb","eee\n","aaabbb\neee\n",ExitSuccess)
--   </pre>
data Streams e r

-- | Feed any <a>Foldable</a> container of strict <a>ByteString</a>s to
--   <tt>stdin</tt>.
feedBytes :: Foldable f => f ByteString -> Streams e ()

-- | Feed a lazy <a>ByteString</a> to <tt>stdin</tt>.
feedLazyBytes :: ByteString -> Streams e ()

-- | Feed any <a>Foldable</a> container of strict <a>Texts</a>s to
--   <tt>stdin</tt>, encoding the texts as UTF8.
feedUtf8 :: Foldable f => f Text -> Streams e ()

-- | Feed a lazy <a>Text</a> to <tt>stdin</tt>, encoding it as UTF8.
feedLazyUtf8 :: Text -> Streams e ()
feedProducer :: Producer ByteString IO () -> Streams e ()
feedProducerM :: MonadIO m => (m () -> IO (Either e a)) -> Producer ByteString m r -> Streams e a
feedSafeProducer :: Producer ByteString (SafeT IO) () -> Streams e ()
feedFallibleProducer :: Producer ByteString (ExceptT e IO) () -> Streams e ()

-- | Feed <tt>stdin</tt> by running a pipes <a>Consumer</a>. This allows
--   bracketing functions like <a>withFile</a> inside the handler.
feedCont :: (Consumer ByteString IO () -> IO (Either e a)) -> Streams e a

-- | Consume standard output.
foldOut :: Fold1 ByteString e r -> Streams e r

-- | Consume standard error.
foldErr :: Fold1 ByteString e r -> Streams e r

-- | Collect strict <a>ByteString</a>s into a lazy <a>ByteString</a>.
--   
--   <pre>
--   &gt;&gt;&gt; PT.fold1  intoLazyBytes (mapM_ yield ["aa","bb","cc"])
--   ("aabbcc",())
--   </pre>
intoLazyBytes :: () => Fold1 ByteString e ByteString

-- | Consume standard output and error together. See also the
--   <tt>combine</tt> function re-exported from <a>Pipes.Transduce</a>.
foldOutErr :: Fold2 ByteString ByteString e r -> Streams e r

-- | Simply returns the <a>ExitCode</a>.
exitCode :: Streams e ExitCode

-- | Fails with the error code when <a>ExitCode</a> is not
--   <a>ExitSuccess</a>.
validateExitCode :: Streams Int ()
withExitCode :: (ExitCode -> IO (Either e a)) -> Streams e a
instance GHC.Base.Functor (System.Process.Streaming.Streams e)
instance GHC.Base.Functor (System.Process.Streaming.Feed1 b e)
instance GHC.Base.Functor (System.Process.Streaming.Feed1_ b e)
instance Data.Bifunctor.Bifunctor System.Process.Streaming.Streams
instance GHC.Base.Applicative (System.Process.Streaming.Streams e)
instance GHC.Base.Monoid a => GHC.Base.Monoid (System.Process.Streaming.Streams e a)
instance Data.Bifunctor.Bifunctor (System.Process.Streaming.Feed1 b)
instance GHC.Base.Applicative (System.Process.Streaming.Feed1 b e)
instance GHC.Base.Monoid a => GHC.Base.Monoid (System.Process.Streaming.Feed1 b e a)
instance Data.Bifunctor.Bifunctor (System.Process.Streaming.Feed1_ b)
instance GHC.Base.Applicative (System.Process.Streaming.Feed1_ b e)


-- | This module re-exports the entirety of <a>Pipes.Transduce.Text</a>
--   from the <tt>pipes-transduce</tt> package. It provides functions
--   useful for treating the <tt>stdout</tt> and <tt>stderr</tt> streams as
--   text.
--   
--   It is better to import it qualified:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified System.Process.Streaming.Text as PT
--   </pre>
module System.Process.Streaming.Text