-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Streaming interface to system processes.
--
@package process-streaming
@version 0.7.0.2
-- | Lenses and traversals for CreateProcess and related types.
--
-- These are provided as a convenience and aren't required to use the
-- other modules of the package.
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)
module System.Process.Streaming.Internal
-- | 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
PPNone :: a -> Piping e a
PPOutput :: (Producer ByteString IO () -> IO (Either e a)) -> Piping e a
PPError :: (Producer ByteString IO () -> IO (Either e a)) -> Piping e a
PPOutputError :: ((Producer ByteString IO (), Producer ByteString IO ()) -> IO (Either e a)) -> Piping e a
PPInput :: ((Consumer ByteString IO (), IO ()) -> IO (Either e a)) -> Piping e a
PPInputOutput :: ((Consumer ByteString IO (), IO (), Producer ByteString IO ()) -> IO (Either e a)) -> Piping e a
PPInputError :: ((Consumer ByteString IO (), IO (), Producer ByteString IO ()) -> IO (Either e a)) -> Piping e a
PPInputOutputError :: ((Consumer ByteString IO (), IO (), Producer ByteString IO (), Producer ByteString IO ()) -> IO (Either e a)) -> Piping e a
-- | An alternative to Piping for defining what to do with the
-- standard streams. Piap is an instance of Applicative,
-- unlike Piping.
--
-- With Piap, the standard streams are always piped. The values of
-- std_in, std_out and std_err in the
-- CreateProcess record are ignored.
newtype Piap e a
Piap :: ((Consumer ByteString IO (), IO (), Producer ByteString IO (), Producer ByteString IO ()) -> IO (Either e a)) -> Piap e a
runPiap :: Piap e a -> (Consumer ByteString IO (), IO (), Producer ByteString IO (), Producer ByteString IO ()) -> IO (Either e 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)
-- | A Siphon represents a computation that completely drains a
-- producer, but may fail early with an error of type e.
newtype Siphon b e a
Siphon :: (Lift (Siphon_ b e) a) -> Siphon b e a
runSiphon :: Siphon b e a -> Producer b IO r -> IO (Either e (a, r))
runSiphonDumb :: Siphon b e a -> Producer b IO () -> IO (Either e a)
data Siphon_ b e a
Exhaustive :: (forall r. Producer b IO r -> IO (Either e (a, r))) -> Siphon_ b e a
Nonexhaustive :: (Producer b IO () -> IO (Either e a)) -> Siphon_ b e a
exhaustive :: Siphon_ b e a -> Producer b IO r -> IO (Either e (a, r))
-- | A configuration parameter used in functions that combine lines of text
-- from multiple streams.
data Lines e
Lines :: ((forall r. Producer Text IO r -> Producer Text IO r) -> (FreeT (Producer Text IO) IO (Producer ByteString IO ()) -> IO (Producer ByteString IO ())) -> Producer ByteString IO () -> IO (Either e ())) -> (forall r. Producer Text IO r -> Producer Text IO r) -> Lines e
teardown :: Lines e -> (forall r. Producer Text IO r -> Producer Text IO r) -> (FreeT (Producer Text IO) IO (Producer ByteString IO ()) -> IO (Producer ByteString IO ())) -> Producer ByteString IO () -> IO (Either e ())
lineTweaker :: Lines e -> forall r. Producer Text IO r -> Producer Text IO r
combined :: Lines e -> Lines e -> (Producer Text IO () -> IO (Either e a)) -> Producer ByteString IO () -> Producer ByteString IO () -> IO (Either e a)
manyCombined :: [(FreeT (Producer Text IO) IO (Producer ByteString IO ()) -> IO (Producer ByteString IO ())) -> IO (Either e ())] -> (Producer Text IO () -> IO (Either e a)) -> IO (Either e a)
-- | An individual stage in a process pipeline.
data Stage e
Stage :: CreateProcess -> Lines e -> (ExitCode -> Either e ()) -> (forall r. Producer ByteString IO r -> Producer ByteString (ExceptT e IO) r) -> Stage e
_processDefinition :: Stage e -> CreateProcess
_stderrLines :: Stage e -> Lines e
_exitCodePolicy :: Stage e -> ExitCode -> Either e ()
_inbound :: Stage e -> forall r. Producer ByteString IO r -> Producer ByteString (ExceptT e IO) r
instance Functor (Piping e)
instance Functor (Pump b e)
instance Functor (Piap e)
instance Functor (Siphon_ b e)
instance Functor (Siphon b e)
instance Functor Stage
instance Functor Lines
instance Monoid a => Monoid (Siphon b e a)
instance Bifunctor (Siphon b)
instance Bifunctor (Siphon_ b)
instance Applicative (Siphon_ b e)
instance Applicative (Siphon b e)
instance Applicative (Piap e)
instance Bifunctor Piap
instance Monoid a => Monoid (Pump b e a)
instance Applicative (Pump b e)
instance Bifunctor (Pump b)
instance Bifunctor Piping
-- | 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
-- unifies with 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)
data Pump b 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 ()
fromLazyBytes :: ByteString -> Pump ByteString e ()
-- | A Siphon represents a computation that completely drains a
-- producer, but may fail early with an error of type e.
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.
--
-- This functions incurs in less overhead than siphon.
siphon' :: (forall r. Producer b IO r -> IO (Either e (a, r))) -> Siphon b e a
-- | Useful in combination with folds from the pipes prelude, or more
-- specialized folds like toLazyM from pipes-text and
-- toLazyM from pipes-bytestring.
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 ()
fromConsumer :: Consumer b IO () -> Siphon b e ()
-- | Builds a Siphon out of a Consumer with a polymorphic
-- return type (one example is toHandle from
-- pipes-bytestring).
fromConsumer' :: Consumer b IO Void -> Siphon b e ()
fromConsumerM :: MonadIO m => (m () -> IO (Either e a)) -> Consumer b m () -> Siphon b e a
fromConsumerM' :: MonadIO m => (forall r. m r -> IO (Either e (a, r))) -> Consumer b m Void -> Siphon b e a
fromSafeConsumer :: Consumer b (SafeT IO) Void -> Siphon b e ()
fromFallibleConsumer :: Consumer b (ExceptT e IO) Void -> Siphon b e ()
-- | Turn a Parser from pipes-parse into a Siphon.
fromParser :: Parser b IO (Either e a) -> Siphon b e a
-- | Turn a Parser from pipes-parse into a Siphon.
fromParserM :: MonadIO m => (forall r. m (a, r) -> IO (Either e (c, r))) -> Parser b m a -> Siphon b e c
-- | 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
-- | Collects incoming ByteString values into a lazy
-- ByteString.
intoLazyBytes :: Siphon ByteString e ByteString
-- | Collects incoming Text values into a lazy Text.
intoLazyText :: Siphon Text e Text
-- | Constructs a Siphon that aborts the computation with an
-- explicit error 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
-- | Like unwanted, but throws an exception instead of using the
-- explicit error type.
unwantedX :: Exception ex => (b -> ex) -> a -> Siphon b e a
-- | Exception that carries a message and a sample of the leftover data.
data LeftoverException b
LeftoverException :: String -> b -> LeftoverException b
-- | Throws LeftoverException if any data comes out of the
-- underlying producer, and returns id otherwise.
leftoverX :: String -> Siphon ByteString e (a -> a)
-- | Like leftoverX, but doesn't take an error message.
_leftoverX :: Siphon ByteString e (a -> a)
-- | 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 unified with 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
decodeUtf8 :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
-- | Reduce a byte stream to a corresponding stream of ascii chars,
-- returning the unused ByteString upon hitting an un-ascii byte.
decodeAscii :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
-- | Reduce a byte stream to a corresponding stream of ascii chars,
-- returning the unused ByteString upon hitting the rare
-- un-latinizable byte.
decodeIso8859_1 :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
instance Typeable LeftoverException
instance Functor CreatePipeline
instance Monoid a => Decidable (SiphonOp e a)
instance Monoid a => Divisible (SiphonOp e a)
instance Contravariant (SiphonOp e a)
instance Typeable b => Show (LeftoverException b)
instance Typeable b => Exception (LeftoverException b)
module System.Process.Streaming.Extended
-- | An alternative to Piping for defining what to do with the
-- standard streams. Piap is an instance of Applicative,
-- unlike Piping.
--
-- With Piap, the standard streams are always piped. The values of
-- std_in, std_out and std_err in the
-- CreateProcess record are ignored.
data Piap e a
-- | Do stuff with stdin.
piapi :: Pump ByteString e a -> Piap e a
-- | Do stuff with stdout.
piapo :: Siphon ByteString e a -> Piap e a
-- | Do stuff with stderr.
piape :: Siphon ByteString e a -> Piap e a
-- | Do stuff with stdout and stderr combined as
-- Text.
piapoe :: Lines e -> Lines e -> Siphon Text e a -> Piap e a
-- | Pipe stdin to the created process' stdin.
samei :: Piap e ()
-- | Pipe the created process' stdout to stdout.
sameo :: Piap e ()
-- | Pipe the created process' stderr to stderr.
samee :: Piap e ()
sameioe :: Piap e ()
toPiping :: Piap e a -> Piping e a
pumpFromHandle :: Handle -> Pump ByteString e ()
siphonToHandle :: Handle -> Siphon ByteString e ()
-- | 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