-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Streaming interface to system processes.
--
@package process-streaming
@version 0.6.2.2
-- | 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 not directly related to IO 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
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 PipingPolicy argument.
--
-- This function re-throws any IOExceptions it encounters.
--
-- If the consumption of the standard streams fails with e, the
-- whole computation is immediately aborted and e is returned.
-- (An exception is not thrown in this case.).
--
-- If an error e or an exception happens, the external process
-- is terminated.
executeFallibly :: PipingPolicy e a -> CreateProcess -> IO (Either e (ExitCode, a))
-- | A PipingPolicy 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 PipingPolicy is parametrized by the type e of errors
-- that can abort the processing of the streams.
data PipingPolicy e a
-- | Do not pipe any standard stream.
nopiping :: PipingPolicy e ()
-- | Pipe stdout.
pipeo :: Siphon ByteString e a -> PipingPolicy e a
-- | Pipe stderr.
pipee :: Siphon ByteString e a -> PipingPolicy e a
-- | Pipe stdout and stderr.
pipeoe :: Siphon ByteString e a -> Siphon ByteString e b -> PipingPolicy e (a, b)
-- | Pipe stdout and stderr and consume them combined as
-- Text.
pipeoec :: LinePolicy e -> LinePolicy e -> Siphon Text e a -> PipingPolicy e a
-- | Pipe stdin.
pipei :: Pump ByteString e i -> PipingPolicy e i
-- | Pipe stdin and stdout.
pipeio :: Pump ByteString e i -> Siphon ByteString e a -> PipingPolicy e (i, a)
-- | Pipe stdin and stderr.
pipeie :: Pump ByteString e i -> Siphon ByteString e a -> PipingPolicy e (i, a)
-- | Pipe stdin, stdout and stderr.
pipeioe :: Pump ByteString e i -> Siphon ByteString e a -> Siphon ByteString e b -> PipingPolicy e (i, a, b)
-- | Pipe stdin, stdout and stderr, consuming
-- the last two combined as Text.
pipeioec :: 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 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 ()
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 Parser from pipes-parse into a Sihpon.
fromParser :: Parser b IO (Either e a) -> Siphon b e a
-- | 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.
--
-- The two first arguments are a decoding function and a Siphon
-- that determines how to handle leftovers. Pass pure id to
-- ignore leftovers. Pass unwanted id to abort the computation
-- if leftovers remain.
encoded :: DecodingFunction bytes text -> Siphon bytes e (a -> b) -> Siphon text e a -> Siphon bytes e b
-- | A configuration parameter used in functions that combine lines from
-- multiple streams.
data LinePolicy e
-- | Constructs a LinePolicy out of a DecodingFunction and a
-- Siphon that specifies how to handle decoding failures. Passing
-- pure () as the Siphon will ignore any leftovers.
-- Passing unwanted () will abort the computation if leftovers
-- remain.
linePolicy :: DecodingFunction ByteString Text -> Siphon ByteString e () -> LinePolicy e
-- | Specifies a transformation that will be applied to each line of text,
-- represented as a Producer.
--
-- Line prefixes are easy to add using applicative notation:
--
--
-- (\x -> yield "prefix: " *> x)
--
tweakLines :: (forall r. Producer Text IO r -> Producer Text IO r) -> LinePolicy e -> LinePolicy e
executePipeline :: PipingPolicy Void a -> Tree (Stage Void) -> IO a
-- | Similar to executeFallibly, but instead of a single process it
-- executes a (possibly branching) pipeline of external processes.
--
-- The PipingPolicy argument views the pipeline as a synthetic
-- process for which stdin is the stdin of the first
-- stage, stdout is the stdout of the leftmost terminal
-- stage among those closer to the root, and stderr is a
-- combination of the stderr streams of all the stages.
--
-- The combined stderr 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 :: PipingPolicy e a -> Tree (Stage e) -> IO (Either e a)
-- | An individual stage in a process pipeline.
data Stage e
-- | Builds a Stage out of a LinePolicy that specifies how to
-- handle stderr when piped, a function that determines whether
-- an ExitCode represents an error (some programs return
-- non-standard exit codes) and a process definition.
stage :: LinePolicy 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
instance Functor (PipingPolicy e)
instance Functor (Pump b e)
instance Functor (Siphon b e)
instance Functor CreatePipeline
instance Functor Stage
instance Monoid a => Monoid (Siphon b e a)
instance Applicative (Siphon b e)
instance Bifunctor (Siphon b)
instance Monoid a => Monoid (Pump b e a)
instance Applicative (Pump b e)
instance Bifunctor (Pump b)
instance Functor LinePolicy
instance Bifunctor PipingPolicy