-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Streaming interface to system processes.
--
@package process-streaming
@version 0.6.8.0
-- | Lenses and traversals for CreateProcess and related types.
module System.Process.Lens
-- |
-- _cmdspec :: Lens' CreateProcess CmdSpec
--
_cmdspec :: Functor f => (CmdSpec -> f CmdSpec) -> CreateProcess -> f CreateProcess
-- |
-- _ShellCommand :: Prism' CmdSpec String
--
_ShellCommand :: Applicative m => (String -> m String) -> CmdSpec -> m CmdSpec
-- |
-- _RawCommand :: Prism' CmdSpec (FilePath,[String])
--
_RawCommand :: Applicative m => ((FilePath, [String]) -> m (FilePath, [String])) -> CmdSpec -> m CmdSpec
-- |
-- _cwd :: Lens' CreateProcess (Maybe FilePath)
--
_cwd :: Functor f => (Maybe FilePath -> f (Maybe FilePath)) -> CreateProcess -> f CreateProcess
-- |
-- _env :: Lens' CreateProcess (Maybe [(String,String)])
--
_env :: Functor f => (Maybe [(String, String)] -> f (Maybe [(String, String)])) -> CreateProcess -> f CreateProcess
-- | A lens for the (std_in,std_out,std_err) triplet.
--
--
-- streams :: Lens' CreateProcess (StdStream,StdStream,StdStream)
--
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 Lens for the return value of createProcess that
-- focuses on the handles.
--
--
-- handles :: Lens' (Maybe Handle, Maybe Handle, Maybe Handle,ProcessHandle) (Maybe Handle, Maybe Handle, Maybe Handle)
--
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 Prism that matches when none of the standard streams have
-- been piped.
--
--
-- nohandles :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) ()
--
nohandles :: Applicative m => (() -> m ()) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)
-- | A Prism that matches when only stdout has been
-- piped.
--
--
-- handleso :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) (Handle)
--
handleso :: Applicative m => (Handle -> m Handle) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)
-- | A Prism that matches when only stderr has been
-- piped.
--
--
-- handlese :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) (Handle)
--
handlese :: Applicative m => (Handle -> m Handle) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)
-- | A Prism that matches when only stdout and
-- stderr have been piped.
--
--
-- handlesoe :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) (Handle, Handle)
--
handlesoe :: Applicative m => ((Handle, Handle) -> m (Handle, Handle)) -> (Maybe Handle, Maybe Handle, Maybe Handle) -> m (Maybe Handle, Maybe Handle, Maybe Handle)
-- | A Prism that matches when only stdin has been piped.
--
--
-- handlesi :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) (Handle)
--
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 Prism that matches when all three stdin,
-- stdout and stderr have been piped.
--
--
-- handlesioe :: Prism' (Maybe Handle, Maybe Handle, Maybe Handle) (Handle, Handle, Handle)
--
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
-- System.Process and Pipes.
--
-- They provide concurrent, streaming access to the inputs and outputs of
-- system processes.
--
-- Error conditions other than IOExceptions are made explicit in
-- the types.
--
-- Regular Consumers, Parsers from pipes-parse and
-- various folds can be used to consume the output streams of the
-- external processes.
module System.Process.Streaming
-- | Executes an external process. The standard streams are piped and
-- consumed in a way defined by the Piping argument.
--
-- This function re-throws any IOExceptions it encounters.
--
-- Besides exceptions, if the consumption of the standard streams fails
-- with e, the whole computation is immediately aborted and
-- e is returned.
--
-- If an exception or an error e happen, the external process is
-- terminated.
executeFallibly :: Piping e a -> CreateProcess -> IO (Either e (ExitCode, a))
-- | A simplified version of executeFallibly for when the error type
-- is Void. Note however that this function may still throw
-- exceptions.
execute :: Piping Void a -> CreateProcess -> IO (ExitCode, a)
-- | A Piping determines what standard streams will be piped and
-- what to do with them.
--
-- The user doesn't need to manually set the std_in,
-- std_out and std_err fields of the CreateProcess
-- record to CreatePipe, this is done automatically.
--
-- A Piping is parametrized by the type e of errors that
-- can abort the processing of the streams.
data Piping e a
-- | Do not pipe any standard stream.
nopiping :: Piping e ()
-- | Pipe stdout.
pipeo :: Siphon ByteString e a -> Piping e a
-- | Pipe stderr.
pipee :: Siphon ByteString e a -> Piping e a
-- | Pipe stdout and stderr.
pipeoe :: Siphon ByteString e a -> Siphon ByteString e b -> Piping e (a, b)
-- | Pipe stdout and stderr and consume them combined as
-- Text.
pipeoec :: Lines e -> Lines e -> Siphon Text e a -> Piping e a
-- | Pipe stdin.
pipei :: Pump ByteString e i -> Piping e i
-- | Pipe stdin and stdout.
pipeio :: Pump ByteString e i -> Siphon ByteString e a -> Piping e (i, a)
-- | Pipe stdin and stderr.
pipeie :: Pump ByteString e i -> Siphon ByteString e a -> Piping e (i, a)
-- | Pipe stdin, stdout and stderr.
pipeioe :: Pump ByteString e i -> Siphon ByteString e a -> Siphon ByteString e b -> Piping e (i, a, b)
-- | Pipe stdin, stdout and stderr, consuming
-- the last two combined as Text.
pipeioec :: Pump ByteString e i -> Lines e -> Lines e -> Siphon Text e a -> Piping 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 ()
fromProducerM :: MonadIO m => (m () -> IO (Either e a)) -> Producer b m r -> Pump b e a
fromSafeProducer :: Producer b (SafeT IO) r -> Pump b e ()
fromFallibleProducer :: Producer b (ExceptT e IO) r -> Pump b e ()
fromFoldable :: Foldable f => f b -> Pump b e ()
fromEnumerable :: Enumerable t => t IO b -> Pump b e ()
-- | A Siphon represents a computation that completely drains a
-- producer, but may fail early with an error of type e.
--
-- pure creates a Siphon that does nothing besides draining
-- the Producer.
--
-- <*> executes its arguments concurrently. The
-- Producer is forked so that each argument receives its own copy
-- of the data.
data Siphon b e a
-- | Builds a Siphon out of a computation that does something with a
-- Producer, but may fail with an error of type e.
--
-- Even if the original computation doesn't completely drain the
-- Producer, the constructed Siphon will.
siphon :: (Producer b IO () -> IO (Either e a)) -> Siphon b e a
-- | Builds a Siphon out of a computation that drains a
-- Producer completely, but may fail with an error of type
-- e.
siphon' :: (forall r. Producer b IO r -> IO (Either e (a, r))) -> Siphon b e a
-- | Useful in combination with toLazyM from pipes-text and
-- toLazyM from pipes-bytestring, when the user wants to
-- collect all the output.
fromFold :: (Producer b IO () -> IO a) -> Siphon b e a
-- | Builds a Siphon out of a computation that folds a
-- Producer 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 ()
-- | Builds a Siphon out of a pure fold from the foldl
-- package.
fromFoldl :: Fold b a -> Siphon b e a
-- | Builds a Siphon out of a monadic fold from the foldl
-- package that works in the IO monad.
fromFoldlIO :: FoldM IO b a -> Siphon b e a
-- | Builds a Siphon out of a monadic fold from the foldl
-- package.
fromFoldlM :: MonadIO m => (forall r. m (a, r) -> IO (Either e (c, r))) -> FoldM m b a -> Siphon b e c
fromConsumer :: Consumer b IO r -> Siphon b e ()
fromConsumerM :: MonadIO m => (m () -> IO (Either e a)) -> Consumer b m r -> Siphon b e a
fromSafeConsumer :: Consumer b (SafeT IO) r -> Siphon b e ()
fromFallibleConsumer :: Consumer b (ExceptT e IO) r -> Siphon b e ()
-- | Turn a Parser from pipes-parse into a Sihpon.
fromParser :: Parser b IO (Either e a) -> Siphon b e a
-- | Turn a Parser from pipes-parse into a Sihpon.
fromParserM :: MonadIO m => (forall r. m (a, r) -> IO (Either e (c, r))) -> Parser b m a -> Siphon b e c
-- | Constructs a Siphon that aborts the computation if the
-- underlying Producer produces anything.
unwanted :: a -> Siphon b b a
-- | See the section Non-lens decoding functions in the
-- documentation for the pipes-text package.
type DecodingFunction bytes text = forall r. Producer bytes IO r -> Producer text IO (Producer bytes IO r)
-- | Constructs a Siphon that works on encoded values out of a
-- Siphon that works on decoded values.
encoded :: DecodingFunction bytes text -> Siphon bytes e (a -> b) -> Siphon text e a -> Siphon bytes e b
newtype SiphonOp e a b
SiphonOp :: Siphon b e a -> SiphonOp e a b
getSiphonOp :: SiphonOp e a b -> Siphon b e a
-- | A configuration parameter used in functions that combine lines of text
-- from multiple streams.
data Lines e
-- | Constructs a Lines value.
toLines :: DecodingFunction ByteString Text -> Siphon ByteString e () -> Lines e
-- | Specifies a transformation that will be applied to each line of text,
-- represented as a Producer.
tweakLines :: (forall r. Producer Text IO r -> Producer Text IO r) -> Lines e -> Lines e
-- | Specifies a prefix that will be calculated and appended for each line
-- of text.
prefixLines :: IO Text -> Lines e -> Lines e
-- | Similar to executeFallibly, but instead of a single process it
-- executes a (possibly branching) pipeline of external processes.
--
-- 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 :: Piping e a -> Tree (Stage e) -> IO (Either e a)
-- | A simplified version of executePipelineFallibly for when the
-- error type is Void. Note however that this function may still
-- throw exceptions.
executePipeline :: Piping Void a -> Tree (Stage Void) -> IO a
-- | An individual stage in a process pipeline.
data Stage e
-- | Builds a Stage.
stage :: Lines e -> (ExitCode -> Either e ()) -> CreateProcess -> Stage e
-- | Converts any ExitFailure to the left side of an Either.
pipefail :: ExitCode -> Either Int ()
-- | Applies a transformation to the stream of bytes flowing into a stage
-- from previous stages.
--
-- This function is ignored for first stages.
inbound :: (forall r. Producer ByteString (ExceptT e IO) r -> Producer ByteString (ExceptT e IO) r) -> Stage e -> Stage e
-- | Deprecated: Use Piping instead
type PipingPolicy e a = Piping e a
-- | Deprecated: Use Lines instead
type LinePolicy e = Lines e
-- | Deprecated: Use toLines instead
linePolicy :: DecodingFunction ByteString Text -> Siphon ByteString e () -> Lines e
instance Functor (Piping e)
instance Functor (Pump b e)
instance Functor (Siphon_ b e)
instance Functor (Siphon b e)
instance Applicative (Siphon b e)
instance Functor CreatePipeline
instance Functor Stage
instance Functor Lines
instance Monoid a => Decidable (SiphonOp e a)
instance Monoid a => Divisible (SiphonOp e a)
instance Contravariant (SiphonOp e a)
instance Monoid a => Monoid (Siphon b e a)
instance Bifunctor (Siphon b)
instance Bifunctor (Siphon_ b)
instance Applicative (Siphon_ b e)
instance IsString (Pump ByteString e ())
instance Monoid a => Monoid (Pump b e a)
instance Applicative (Pump b e)
instance Bifunctor (Pump b)
instance Bifunctor Piping
-- | process-streaming uses the CreateProcess record to
-- describe the program to be executed. The user doesn't need to set the
-- std_in, std_out and std_err fields, as these are
-- set automatically according to the Piping.
--
-- Piping is a datatype that specifies what standard streams to
-- pipe and what to do with them. It has several constructors, one for
-- each possible combination of streams.
--
-- Constructors for Piping usually take Siphons as
-- parameters. A Siphon specifies what to do with a particular
-- standard stream.
--
-- Siphons can be built from each of the typical ways of consuming
-- a Producer in the pipes ecosystem:
--
--
--
-- Siphons have an explicit error type; when a Siphon
-- reading one of the standard streams fails, the external program is
-- immediately terminated and the error value is returned.
--
-- A Siphon reading a stream always consumes the whole stream. If
-- the user wants to interrupt the computation early, he can return a
-- failure (or throw an exception).
--
-- Siphons have an Applicative instance. pure
-- creates a Siphon that drains a stream but does nothing with the
-- data.
module System.Process.Streaming.Tutorial