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


-- | Streaming interface to system processes.
--   
@package process-streaming
@version 0.5.0.1


-- | Lenses and traversals for <a>CreateProcess</a> and related types.
module System.Process.Lens

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

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

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

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

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

-- | A lens for the <tt>(std_in,std_out,std_err)</tt> triplet.
--   
--   <pre>
--   streams :: Lens' CreateProcess (StdStream,StdStream,StdStream)
--   </pre>
streams :: Functor f => ((StdStream, StdStream, StdStream) -> f (StdStream, StdStream, StdStream)) -> CreateProcess -> f CreateProcess
_close_fds :: Functor f => (Bool -> f Bool) -> CreateProcess -> f CreateProcess
_create_group :: Functor f => (Bool -> f Bool) -> CreateProcess -> f CreateProcess
_delegate_ctlc :: Functor f => (Bool -> f Bool) -> CreateProcess -> f CreateProcess

-- | A <tt>Lens</tt> for the return value of <a>createProcess</a> that
--   focuses on the handles.
--   
--   <pre>
--   handles :: Lens' (Maybe Handle, Maybe Handle, Maybe Handle,ProcessHandle) (Maybe Handle, Maybe Handle, Maybe Handle)
--   </pre>
handles :: Functor m => ((Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)) -> (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) -> m (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)

-- | A <tt>Prism</tt> that matches when none of the standard streams have
--   been piped.
--   
--   <pre>
--   nohandles :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) ()
--   </pre>
nohandles :: Applicative m => (() -> m ()) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)

-- | A <tt>Prism</tt> that matches when only <tt>stdout</tt> has been
--   piped.
--   
--   <pre>
--   handleso :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) (Handle)
--   </pre>
handleso :: Applicative m => (Handle -> m Handle) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)

-- | A <tt>Prism</tt> that matches when only <tt>stderr</tt> has been
--   piped.
--   
--   <pre>
--   handlese :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) (Handle)
--   </pre>
handlese :: Applicative m => (Handle -> m Handle) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)

-- | A <tt>Prism</tt> that matches when only <tt>stdout</tt> and
--   <tt>stderr</tt> have been piped.
--   
--   <pre>
--   handlesoe :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) (Handle, Handle)
--   </pre>
handlesoe :: Applicative m => ((Handle, Handle) -> m (Handle, Handle)) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)

-- | A <tt>Prism</tt> that matches when only <tt>stdin</tt> has been piped.
--   
--   <pre>
--   handlesi :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) (Handle)
--   </pre>
handlesi :: Applicative m => (Handle -> m Handle) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)
handlesio :: Applicative m => ((Handle, Handle) -> m (Handle, Handle)) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)
handlesie :: Applicative m => ((Handle, Handle) -> m (Handle, Handle)) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)

-- | A <tt>Prism</tt> that matches when all three <tt>stdin</tt>,
--   <tt>stdout</tt> and <tt>stderr</tt> have been piped.
--   
--   <pre>
--   handlesioe :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) (Handle, Handle, Handle)
--   </pre>
handlesioe :: Applicative m => ((Handle, Handle, Handle) -> m (Handle, Handle, Handle)) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)


-- | This module contains helper functions and types built on top of
--   <a>System.Process</a> and <a>Pipes</a>.
--   
--   They provide concurrent, streaming access to the inputs and outputs of
--   system processes.
--   
--   Error conditions that are not directly related to IO are made explicit
--   in the types.
--   
--   Regular <a>Consumer</a>s, <a>Parser</a>s from <tt>pipes-parse</tt> and
--   folds from <a>Pipes.Prelude</a> (also folds from
--   <tt>pipes-bytestring</tt> and <tt>pipes-text</tt>) can be used to
--   consume the output streams of the external processes.
module System.Process.Streaming
execute :: PipingPolicy Void a -> CreateProcess -> IO (ExitCode, a)

-- | Executes an external process. The standard streams are piped and
--   consumed in a way defined by the <a>PipingPolicy</a> argument.
--   
--   This fuction re-throws any <a>IOException</a>s it encounters.
--   
--   If the consumption of the standard streams fails with <tt>e</tt>, the
--   whole computation is immediately aborted and <tt>e</tt> is returned.
--   (An exception is not thrown in this case.).
--   
--   If an error <tt>e</tt> or an exception happens, the external process
--   is terminated.
executeFallibly :: PipingPolicy e a -> CreateProcess -> IO (Either e (ExitCode, a))

-- | A <a>PipingPolicy</a> determines what standard streams will be piped
--   and what to do with them.
--   
--   The user doesn't need to manually set the <a>std_in</a>,
--   <a>std_out</a> and <a>std_err</a> fields of the <a>CreateProcess</a>
--   record to <a>CreatePipe</a>, this is done automatically.
--   
--   A <a>PipingPolicy</a> is parametrized by the type <tt>e</tt> of errors
--   that can abort the processing of the streams.
data PipingPolicy e a

-- | Do not pipe any standard stream.
nopiping :: PipingPolicy e ()

-- | Pipe <tt>stdout</tt>.
pipeo :: (Show e, Typeable e) => Siphon ByteString e a -> PipingPolicy e a

-- | Pipe <tt>stderr</tt>.
pipee :: (Show e, Typeable e) => Siphon ByteString e a -> PipingPolicy e a

-- | Pipe <tt>stdout</tt> and <tt>stderr</tt>.
pipeoe :: (Show e, Typeable e) => Siphon ByteString e a -> Siphon ByteString e b -> PipingPolicy e (a, b)

-- | Pipe <tt>stdout</tt> and <tt>stderr</tt> and consume them combined as
--   <a>Text</a>.
pipeoec :: (Show e, Typeable e) => LinePolicy e -> LinePolicy e -> Siphon Text e a -> PipingPolicy e a

-- | Pipe <tt>stdin</tt>.
pipei :: (Show e, Typeable e) => Pump ByteString e i -> PipingPolicy e i

-- | Pipe <tt>stdin</tt> and <tt>stdout</tt>.
pipeio :: (Show e, Typeable e) => Pump ByteString e i -> Siphon ByteString e a -> PipingPolicy e (i, a)

-- | Pipe <tt>stdin</tt> and <tt>stderr</tt>.
pipeie :: (Show e, Typeable e) => Pump ByteString e i -> Siphon ByteString e a -> PipingPolicy e (i, a)

-- | Pipe <tt>stdin</tt>, <tt>stdout</tt> and <tt>stderr</tt>.
pipeioe :: (Show e, Typeable e) => Pump ByteString e i -> Siphon ByteString e a -> Siphon ByteString e b -> PipingPolicy e (i, a, b)

-- | Pipe <tt>stdin</tt>, <tt>stdout</tt> and <tt>stderr</tt>, consuming
--   the last two combined as <a>Text</a>.
pipeioec :: (Show e, Typeable e) => Pump ByteString e i -> LinePolicy e -> LinePolicy e -> Siphon Text e a -> PipingPolicy e (i, a)
newtype Pump b e a
Pump :: (Consumer b IO () -> IO (Either e a)) -> Pump b e a
runPump :: Pump b e a -> Consumer b IO () -> IO (Either e a)
fromProducer :: Producer b IO r -> Pump b e ()
fromSafeProducer :: Producer b (SafeT IO) r -> Pump b e ()
fromFallibleProducer :: Producer b (ExceptT e IO) r -> Pump b e ()

-- | A <a>Siphon</a> represents a computation that completely drains a
--   producer, but may fail early with an error of type <tt>e</tt>.
--   
--   <a>pure</a> creates a <a>Siphon</a> that does nothing besides draining
--   the <a>Producer</a>.
--   
--   <a>&lt;*&gt;</a> executes its arguments concurrently. The
--   <a>Producer</a> is forked so that each argument receives its own copy
--   of the data.
data Siphon b e a

-- | Builds a <a>Siphon</a> out of a computation that does something with a
--   <a>Producer</a>, but may fail with an error of type <tt>e</tt>.
--   
--   Even if the original computation doesn't completely drain the
--   <a>Producer</a>, the constructed <a>Siphon</a> will.
siphon :: (Producer b IO () -> IO (Either e a)) -> Siphon b e a

-- | Builds a <a>Siphon</a> out of a computation that drains a
--   <a>Producer</a> completely, but may fail with an error of type
--   <tt>e</tt>.
siphon' :: (forall r. Producer b IO r -> IO (Either e (a, r))) -> Siphon b e a
fromFold :: (Producer b IO () -> IO a) -> Siphon b e a

-- | Builds a <a>Siphon</a> out of a computation that folds a
--   <a>Producer</a> and drains it completely.
fromFold' :: (forall r. Producer b IO r -> IO (a, r)) -> Siphon b e a
fromFold'_ :: (forall r. Producer b IO r -> IO r) -> Siphon b e ()
fromConsumer :: Consumer b IO r -> Siphon b e ()
fromSafeConsumer :: Consumer b (SafeT IO) r -> Siphon b e ()
fromFallibleConsumer :: Consumer b (ExceptT e IO) r -> Siphon b e ()

-- | Turn a <a>Parser</a> from <tt>pipes-parse</tt> into a <tt>Sihpon</tt>.
fromParser :: Parser b IO (Either e a) -> Siphon b e a

-- | Constructs a <a>Siphon</a> that aborts the computation if the
--   underlying <a>Producer</a> produces anything.
unwanted :: a -> Siphon b b a

-- | See the section <i>Non-lens decoding functions</i> in the
--   documentation for the <tt>pipes-text</tt> package.
type DecodingFunction bytes text = forall r. Producer bytes IO r -> Producer text IO (Producer bytes IO r)

-- | Constructs a <a>Siphon</a> that works on encoded values out of a
--   <a>Siphon</a> that works on decoded values.
--   
--   The two first arguments are a decoding function and a <a>Siphon</a>
--   that determines how to handle leftovers. Pass <tt>pure id</tt> to
--   ignore leftovers. Pass <tt>unwanted id</tt> to abort the computation
--   if leftovers remain.
encoded :: (Show e, Typeable e) => DecodingFunction bytes text -> Siphon bytes e (a -> b) -> Siphon text e a -> Siphon bytes e b

-- | Defines how to decode a stream of bytes into text, including what to
--   do in presence of leftovers. Also defines how to manipulate each
--   individual line of text.
data LinePolicy e

-- | Constructs a <a>LinePolicy</a>.
--   
--   The second argument is a <a>Siphon</a> value that specifies how to
--   handle decoding failures. Passing <tt>pure ()</tt> will ignore any
--   leftovers. Passing <tt>unwanted ()</tt> will abort the computation if
--   leftovers remain.
--   
--   The third argument is a function that modifies each individual line.
--   The line is represented as a <a>Producer</a> to avoid having to keep
--   it wholly in memory. If you want the lines unmodified, just pass
--   <tt>id</tt>. Line prefixes are easy to add using applicative notation:
--   
--   <pre>
--   (\x -&gt; yield "prefix: " *&gt; x)
--   </pre>
linePolicy :: (Show e, Typeable e) => DecodingFunction ByteString Text -> Siphon ByteString e () -> (forall r. Producer Text IO r -> Producer Text IO r) -> LinePolicy e
executePipeline :: PipingPolicy Void a -> CreatePipeline Void -> IO a

-- | Similar to <a>executeFallibly</a>, but instead of a single process it
--   executes a (possibly branching) pipeline of external processes.
--   
--   The <a>PipingPolicy</a> argument views the pipeline as a synthetic
--   process for which <tt>stdin</tt> is the <tt>stdin</tt> of the first
--   stage, <tt>stdout</tt> is the <tt>stdout</tt> of the leftmost terminal
--   stage among those closer to the root, and <tt>stderr</tt> is a
--   combination of the <tt>stderr</tt> streams of all the stages.
--   
--   The combined <tt>stderr</tt> stream always has UTF-8 encoding.
--   
--   This function has a limitation compared to the standard UNIX
--   pipelines. If a downstream process terminates early without error, the
--   upstream processes are not notified and keep going. There is no
--   SIGPIPE-like functionality, in other words.
executePipelineFallibly :: (Show e, Typeable e) => PipingPolicy e a -> CreatePipeline e -> IO (Either e a)
data CreatePipeline e
CreatePipeline :: (Stage e) -> (NonEmpty (Tree (SubsequentStage e))) -> CreatePipeline e

-- | Builds a (possibly branching) pipeline assuming that <tt>stderr</tt>
--   has the same encoding in all the stages, that no computation is
--   perfored between the stages, and that any exit code besides
--   <a>ExitSuccess</a> in a stage actually represents an error.
simplePipeline :: DecodingFunction ByteString Text -> CreateProcess -> NonEmpty (Tree (CreateProcess)) -> CreatePipeline String

-- | An individual stage in a process pipeline.
--   
--   The <a>LinePolicy</a> field defines how to handle <tt>stderr</tt> when
--   <tt>stderr</tt> is piped.
--   
--   Also required is a function that determines if the returned exit code
--   represents an error or not. This is necessary because some programs
--   use non-standard exit codes.
data Stage e
Stage :: CreateProcess -> LinePolicy e -> (Int -> Maybe e) -> Stage e
processDefinition :: Stage e -> CreateProcess
stderrLinePolicy :: Stage e -> LinePolicy e
exitCodePolicy :: Stage e -> Int -> Maybe e

-- | Any stage beyond the first in a process pipeline.
--   
--   Incoming data is passed through the <a>Pipe</a> before being fed to
--   the process.
--   
--   Use <a>cat</a> (the identity <a>Pipe</a> from <tt>Pipes</tt>) if no
--   pre-processing is required.
data SubsequentStage e
SubsequentStage :: (forall a. Pipe ByteString ByteString (ExceptT e IO) a) -> (Stage e) -> SubsequentStage e
instance Typeable WrappedError
instance Functor (PipingPolicy e)
instance Show e => Show (WrappedError e)
instance Functor (Siphon b e)
instance Functor Stage
instance Functor CreatePipeline
instance Functor SubsequentStage
instance (Show e, Typeable e, Monoid a) => Monoid (Siphon b e a)
instance (Show e, Typeable e) => Applicative (Siphon b e)
instance Bifunctor (Siphon b)
instance (Show e, Typeable e, Monoid a) => Monoid (Pump b e a)
instance (Show e, Typeable e) => Applicative (Pump b e)
instance Bifunctor (Pump b)
instance Functor (Pump b e)
instance (Show e, Typeable e, Monoid a) => Monoid (Conceit e a)
instance (Show e, Typeable e) => Alternative (Conceit e)
instance (Show e, Typeable e) => Applicative (Conceit e)
instance Bifunctor Conceit
instance Functor (Conceit e)
instance (Show e, Typeable e) => Exception (WrappedError e)
instance Functor LinePolicy
instance Bifunctor PipingPolicy