Safe Haskell | None |
---|---|
Language | Haskell2010 |
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 IOException
s are made explicit
in the types.
Regular Consumer
s, Parser
s from pipes-parse
and various folds can
be used to consume the output streams of the external processes.
- executeFallibly :: Piping e a -> CreateProcess -> IO (Either e (ExitCode, a))
- execute :: Piping Void a -> CreateProcess -> IO (ExitCode, a)
- data Piping e a
- nopiping :: Piping e ()
- pipeo :: Siphon ByteString e a -> Piping e a
- pipee :: Siphon ByteString e a -> Piping e a
- pipeoe :: Siphon ByteString e a -> Siphon ByteString e b -> Piping e (a, b)
- pipeoec :: Lines e -> Lines e -> Siphon Text e a -> Piping e a
- pipei :: Pump ByteString e i -> Piping e i
- pipeio :: Pump ByteString e i -> Siphon ByteString e a -> Piping e (i, a)
- pipeie :: Pump ByteString e i -> Siphon ByteString e a -> Piping e (i, a)
- pipeioe :: Pump ByteString e i -> Siphon ByteString e a -> Siphon ByteString e b -> Piping e (i, a, b)
- 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 ()
- data Siphon b e a
- siphon :: (Producer b IO () -> IO (Either e a)) -> Siphon b e a
- 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
- 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 ()
- 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 ()
- fromParser :: Parser b IO (Either e a) -> Siphon b e a
- fromParserM :: MonadIO m => (forall r. m (a, r) -> IO (Either e (c, r))) -> Parser b m a -> Siphon b e c
- fromFoldl :: Fold b a -> Siphon b e a
- fromFoldlIO :: FoldM IO b a -> Siphon b e a
- fromFoldlM :: MonadIO m => (forall r. m (a, r) -> IO (Either e (c, r))) -> FoldM m b a -> Siphon b e c
- intoLazyBytes :: Siphon ByteString e ByteString
- intoLazyText :: Siphon Text e Text
- intoList :: Siphon b e [b]
- unwanted :: a -> Siphon b b a
- type DecodingFunction bytes text = forall r. Producer bytes IO r -> Producer text IO (Producer bytes IO r)
- encoded :: DecodingFunction bytes text -> Siphon bytes e (a -> b) -> Siphon text e a -> Siphon bytes e b
- newtype SiphonOp e a b = SiphonOp {
- getSiphonOp :: Siphon b e a
- contramapFoldable :: Foldable f => (a -> f b) -> SiphonOp e r b -> SiphonOp e r a
- contramapEnumerable :: Enumerable t => (a -> t IO b) -> SiphonOp e r b -> SiphonOp e r a
- contraproduce :: (forall r. Producer a IO r -> Producer b IO r) -> SiphonOp e r b -> SiphonOp e r a
- contraencoded :: DecodingFunction bytes text -> Siphon bytes e (a -> b) -> SiphonOp e a text -> SiphonOp e b bytes
- data Splitter b
- splitter :: (forall r. Producer b IO r -> FreeT (Producer b IO) IO r) -> Splitter b
- splitIntoLines :: Splitter Text
- tweakSplits :: (forall r. Producer b IO r -> Producer b IO r) -> Splitter b -> Splitter b
- rejoin :: forall b r. Splitter b -> Producer b IO r -> Producer b IO r
- nest :: Splitter b -> Siphon b Void a -> SiphonOp e r a -> SiphonOp e r b
- data Lines e
- toLines :: DecodingFunction ByteString Text -> Siphon ByteString e (() -> ()) -> Lines e
- tweakLines :: (forall r. Producer Text IO r -> Producer Text IO r) -> Lines e -> Lines e
- prefixLines :: IO Text -> Lines e -> Lines e
- unwantedX :: Exception ex => (b -> ex) -> a -> Siphon b e a
- data LeftoverException b = LeftoverException String b
- leftoverX :: String -> Siphon ByteString e (a -> a)
- _leftoverX :: Siphon ByteString e (a -> a)
- executePipelineFallibly :: Piping e a -> Tree (Stage e) -> IO (Either e a)
- executePipeline :: Piping Void a -> Tree (Stage Void) -> IO a
- data Stage e
- stage :: Lines e -> (ExitCode -> Either e ()) -> CreateProcess -> Stage e
- pipefail :: ExitCode -> Either Int ()
- inbound :: (forall r. Producer ByteString (ExceptT e IO) r -> Producer ByteString (ExceptT e IO) r) -> Stage e -> Stage e
- module System.Process
- decodeUtf8 :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
- decodeAscii :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
- decodeIso8859_1 :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
Execution
executeFallibly :: Piping e a -> CreateProcess -> IO (Either e (ExitCode, a)) Source
Executes an external process. The standard streams are piped and consumed in
a way defined by the Piping
argument.
This function re-throws any IOException
s 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.
execute :: Piping Void a -> CreateProcess -> IO (ExitCode, a) Source
A simplified version of executeFallibly
for when the error type unifies
with Void
. Note however that this function may still throw exceptions.
Piping the standard streams
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.
pipeo :: Siphon ByteString e a -> Piping e a Source
Pipe stdout
.
pipee :: Siphon ByteString e a -> Piping e a Source
Pipe stderr
.
pipeoe :: Siphon ByteString e a -> Siphon ByteString e b -> Piping e (a, b) Source
Pipe stdout
and stderr
.
pipeoec :: Lines e -> Lines e -> Siphon Text e a -> Piping e a Source
Pipe stdout
and stderr
and consume them combined as Text
.
pipei :: Pump ByteString e i -> Piping e i Source
Pipe stdin
.
pipeio :: Pump ByteString e i -> Siphon ByteString e a -> Piping e (i, a) Source
Pipe stdin
and stdout
.
pipeie :: Pump ByteString e i -> Siphon ByteString e a -> Piping e (i, a) Source
Pipe stdin
and stderr
.
pipeioe :: Pump ByteString e i -> Siphon ByteString e a -> Siphon ByteString e b -> Piping e (i, a, b) Source
Pipe stdin
, stdout
and stderr
.
pipeioec :: Pump ByteString e i -> Lines e -> Lines e -> Siphon Text e a -> Piping e (i, a) Source
Pipe stdin
, stdout
and stderr
, consuming the last two combined as Text
.
Pumping bytes into stdin
Pump
s are actions that write data into a process' stdin
.
fromProducer :: Producer b IO r -> Pump b e () Source
fromFoldable :: Foldable f => f b -> Pump b e () Source
fromEnumerable :: Enumerable t => t IO b -> Pump b e () Source
fromLazyBytes :: ByteString -> Pump ByteString e () Source
Siphoning bytes out of stdout/stderr
A Siphon
represents a computation that completely drains
a Producer
, but which may fail early with an error of type e
.
Bifunctor (Siphon b) |
|
Functor (Siphon b e) | |
Applicative (Siphon b e) |
|
Monoid a => Monoid (Siphon b e a) |
fromConsumer :: Consumer b IO () -> Siphon b e () Source
fromConsumerM' :: MonadIO m => (forall r. m r -> IO (Either e (a, r))) -> Consumer b m Void -> Siphon b e a Source
fromParserM :: MonadIO m => (forall r. m (a, r) -> IO (Either e (c, r))) -> Parser b m a -> Siphon b e c Source
fromFoldl :: Fold b a -> Siphon b e a Source
Builds a Siphon
out of a pure fold from the foldl
package.
fromFoldlIO :: FoldM IO b a -> Siphon b e a Source
Builds a Siphon
out of a monadic fold from the foldl
package that
works in the IO monad.
fromFoldlM :: MonadIO m => (forall r. m (a, r) -> IO (Either e (c, r))) -> FoldM m b a -> Siphon b e c Source
Builds a Siphon
out of a monadic fold from the foldl
package.
intoLazyBytes :: Siphon ByteString e ByteString Source
Collects incoming ByteString
values into a lazy ByteString
.
type DecodingFunction bytes text = forall r. Producer bytes IO r -> Producer text IO (Producer bytes IO r) Source
See the section Non-lens decoding functions in the documentation for the
pipes-text
package.
:: DecodingFunction bytes text | A decoding function. |
-> Siphon bytes e (a -> b) | A |
-> Siphon text e a | |
-> Siphon bytes e b |
A newtype wrapper with functions for working on the inputs of
a Siphon
, instead of the outputs.
SiphonOp | |
|
Monoid a => Divisible (SiphonOp e a) |
|
Monoid a => Decidable (SiphonOp e a) |
|
Contravariant (SiphonOp e a) |
|
contramapFoldable :: Foldable f => (a -> f b) -> SiphonOp e r b -> SiphonOp e r a Source
Useful to weed out unwanted inputs to a Siphon
, by returning []
.
contramapEnumerable :: Enumerable t => (a -> t IO b) -> SiphonOp e r b -> SiphonOp e r a Source
contraproduce :: (forall r. Producer a IO r -> Producer b IO r) -> SiphonOp e r b -> SiphonOp e r a Source
:: DecodingFunction bytes text | A decoding function. |
-> Siphon bytes e (a -> b) | A |
-> SiphonOp e a text | |
-> SiphonOp e b bytes |
Like encoded, but works on SiphonOp
s.
tweakSplits :: (forall r. Producer b IO r -> Producer b IO r) -> Splitter b -> Splitter b Source
Specifies a transformation that will be applied to each individual
split, represented as a Producer
.
rejoin :: forall b r. Splitter b -> Producer b IO r -> Producer b IO r Source
Flattens the Splitter
, returning a function from Producer
to
Producer
which can be passed to functions like contraproduce
.
Handling lines
A configuration parameter used in functions that combine lines of text from multiple streams.
:: DecodingFunction ByteString Text | A decoding function for lines of text. |
-> Siphon ByteString e (() -> ()) | A |
-> Lines e |
Constructs a Lines
value.
tweakLines :: (forall r. Producer Text IO r -> Producer Text IO r) -> Lines e -> Lines e Source
Specifies a transformation that will be applied to each line of text,
represented as a Producer
.
prefixLines :: IO Text -> Lines e -> Lines e Source
Specifies a prefix that will be calculated and appended for each line of text.
Throwing exceptions
unwantedX :: Exception ex => (b -> ex) -> a -> Siphon b e a Source
Like unwanted
, but throws an exception instead of using the explicit
error type.
data LeftoverException b Source
Exception that carries a message and a sample of the leftover data.
Typeable * b => Show (LeftoverException b) | |
Typeable * b => Exception (LeftoverException b) | |
Typeable (* -> *) LeftoverException |
:: String | Error message |
-> Siphon ByteString e (a -> a) |
Throws LeftoverException
if any data comes out of the underlying
producer, and returns id
otherwise.
_leftoverX :: Siphon ByteString e (a -> a) Source
Like leftoverX
, but doesn't take an error message.
Pipelines
executePipelineFallibly Source
:: Piping e a | Views the pipeline as a single process
for which |
-> Tree (Stage e) | A (possibly branching) pipeline of processes. Each process' stdin is fed with the stdout of its parent in the tree. |
-> IO (Either e 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.
executePipeline :: Piping Void a -> Tree (Stage Void) -> IO a Source
A simplified version of executePipelineFallibly
for when the error type
unifies with Void
. Note however that this function may still throw
exceptions.
:: Lines e | How to handle lines coming from stderr for this |
-> (ExitCode -> Either e ()) | Does the |
-> CreateProcess | A process definition. |
-> Stage e |
Builds a Stage
.
inbound :: (forall r. Producer ByteString (ExceptT e IO) r -> Producer ByteString (ExceptT e IO) r) -> Stage e -> Stage e Source
Applies a transformation to the stream of bytes flowing into a stage from previous stages.
This function is ignored for first stages.
Re-exports
System.Process is re-exported for convenience.
module System.Process
decodeUtf8 :: Monad m => Producer ByteString m r -> Producer Text m (Producer ByteString m r)
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 an un-ascii byte.
decodeIso8859_1 :: 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.