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


-- | Streaming component combinators
--   
--   SCC is a layered library of Streaming Component Combinators. The
--   lowest layer defines a Pipe monad transformer that enables building of
--   producer-consumer coroutine pairs. The next layer adds streaming
--   component types, a number of primitive streaming components and a set
--   of component combinators. Finally, there is an executable that exposes
--   all functionality in a command-line shell.
--   
--   The library design is based on paper
--   <a>http://www.idealliance.org/papers/extreme/Proceedings/html/2006/Blazevic01/EML2006Blazevic01.html</a>
--   
--   Mario Blažević, Streaming component combinators, Extreme Markup
--   Languages, 2006.
@package scc
@version 0.1


-- | Module <a>Foundation</a> defines the pipe computations and their basic
--   building blocks.
module Control.Concurrent.SCC.Foundation

-- | <a>Pipe</a> represents the type of monadic computations that can be
--   split into co-routining computations using function <a>pipe</a>. The
--   <i>context</i> type parameter delimits the scope of the computation.
data (Monad m) => Pipe context m r

-- | A <a>Source</a> is the read-only end of a <a>Pipe</a> communication
--   channel.
data Source context x

-- | A <a>Sink</a> is the write-only end of a <a>Pipe</a> communication
--   channel.
data Sink context x

-- | A computation that consumes values from a <a>Source</a> is called
--   <a>Consumer</a>.
type Consumer m x r = forall c. Source c x -> Pipe c m r

-- | A computation that produces values and puts them into a <a>Sink</a> is
--   called <a>Producer</a>.
type Producer m x r = forall c. Sink c x -> Pipe c m r

-- | The <a>pipe</a> function splits the computation into two concurrent
--   parts, <i>producer</i> and <i>consumer</i>. The <i>producer</i> is
--   given a <a>Sink</a> to put values into, and <i>consumer</i> a
--   <a>Source</a> to get those values from. Once producer and consumer
--   both complete, <a>pipe</a> returns their paired results.
pipe :: (Monad m) => Producer m x r1 -> Consumer m x r2 -> Pipe context m (r1, r2)

-- | The <a>pipeD</a> function is same as <a>pipe</a>, with an additional
--   description argument.
pipeD :: (Monad m) => String -> Producer m x r1 -> Consumer m x r2 -> Pipe context m (r1, r2)

-- | Function <a>get</a> tries to get a value from the given <a>Source</a>
--   argument. The intervening <a>Pipe</a> computations suspend all the way
--   to the <a>pipe</a> function invocation that created the source. The
--   result of <a>get</a> is <a>Nothing</a> iff the argument source is
--   empty.
get :: (Monad m, Typeable x) => Source context' x -> Pipe context m (Maybe x)
getSuccess :: (Monad m, Typeable x) => Source context' x -> (x -> Pipe context m ()) -> Pipe context m ()

-- | Function <a>canPut</a> checks if the argument sink accepts values,
--   i.e., whether a <a>put</a> operation would succeed on the sink.
canPut :: (Monad m, Typeable x) => Sink context' x -> Pipe context m Bool

-- | Function <a>put</a> tries to put a value into the given sink. The
--   intervening <a>Pipe</a> computations suspend up to the <a>pipe</a>
--   invocation that has created the argument sink. The result of
--   <a>put</a> indicates whether the operation succeded.
put :: (Monad m, Typeable x) => Sink context' x -> x -> Pipe context m Bool

-- | Function <a>liftPipe</a> lifts a value of the underlying monad type
--   into a <a>Pipe</a> computation.
liftPipe :: (Monad m) => m r -> Pipe context m r

-- | Function <a>runPipes</a> runs the given computation involving pipes
--   and returns the final result. The <i>context</i> argument ensures that
--   no suspended computation can escape its scope.
runPipes :: (Monad m) => (forall context. Pipe context m r) -> m r

-- | A utility function wrapping if-then-else, useful for handling monadic
--   truth values
cond :: a -> a -> Bool -> a

-- | A utility function, useful for handling monadic list values where
--   empty list means success
whenNull :: (Monad m) => m [a] -> [a] -> m [a]

-- | <a>pour</a> copies all data from the <i>source</i> argument into the
--   <i>sink</i> argument, as long as there is anything to copy and the
--   sink accepts it.
pour :: (Monad m, Typeable x) => Source c1 x -> Sink c2 x -> Pipe c m ()

-- | <a>tee</a> is similar to <a>pour</a> except it distributes every input
--   value from the <i>source</i> arguments into both <i>sink1</i> and
--   <i>sink2</i>.
tee :: (Monad m, Typeable x) => Source c1 x -> Sink c2 x -> Sink c3 x -> Pipe c m ()

-- | <a>getList</a> returns the list of all values generated by the source.
getList :: (Monad m, Typeable x) => Source c1 x -> Pipe c m [x]

-- | <a>putList</a> puts entire list into its <i>sink</i> argument, as long
--   as the sink accepts it. The remainder that wasn't accepted by the sink
--   is the result value.
putList :: (Monad m, Typeable x) => [x] -> Sink c1 x -> Pipe c m [x]

-- | <a>consumeAndSuppress</a> consumes the entire source ignoring the
--   values it generates.
consumeAndSuppress :: (Monad m, Typeable x) => Source c1 x -> Pipe c m ()
instance Show (Suspension context m r)
instance (Monad m) => Monad (Pipe context m)

module Control.Concurrent.SCC.ComponentTypes

-- | The <a>Splitter</a> type represents computations that distribute data
--   acording to some criteria. A splitter should distribute only the
--   original input data, and feed it into the sinks in the same order it
--   has been read from the source. If the two sink arguments of a splitter
--   are the same, the splitter must act as an identity transform.
data (Monad m) => Splitter m x
Splitter :: (forall c1 c2 c3 context. Source c1 x -> Sink c2 x -> Sink c3 x -> Pipe context m [x]) -> (forall c1 c2 c3 context. Source c1 x -> Sink c2 (Maybe x) -> Sink c3 (Maybe x) -> Pipe context m [x]) -> Splitter m x
split :: Splitter m x -> forall c1 c2 c3 context. Source c1 x -> Sink c2 x -> Sink c3 x -> Pipe context m [x]
splitSections :: Splitter m x -> forall c1 c2 c3 context. Source c1 x -> Sink c2 (Maybe x) -> Sink c3 (Maybe x) -> Pipe context m [x]

-- | The <a>Transducer</a> type represents computations that transform data
--   and return no result. A transducer must continue consuming the given
--   source and feeding the sink while there is data.
newtype (Monad m) => Transducer m x y
Transducer :: (forall c1 c2 context. Source c1 x -> Sink c2 y -> Pipe context m [x]) -> Transducer m x y
transduce :: Transducer m x y -> forall c1 c2 context. Source c1 x -> Sink c2 y -> Pipe context m [x]

-- | Function <a>lift121Transducer</a> takes a function that maps one input
--   value to one output value each, and lifts it into a <a>Transducer</a>.
lift121Transducer :: (Monad m, Typeable x, Typeable y) => (x -> y) -> Transducer m x y

-- | Function <a>liftStatelessTransducer</a> takes a function that maps one
--   input value into a list of output values, and lifts it into a
--   <a>Transducer</a>.
liftStatelessTransducer :: (Monad m, Typeable x, Typeable y) => (x -> [y]) -> Transducer m x y

-- | Function <a>liftFoldTransducer</a> creates a stateful transducer that
--   produces only one output value after consuming the entire input.
--   Similar to <tt>Data.List.foldl</tt>
liftFoldTransducer :: (Monad m, Typeable x, Typeable y) => (y -> x -> y) -> y -> Transducer m x y

-- | Function <a>liftStatefulTransducer</a> constructs a <a>Transducer</a>
--   from a state-transition function and the initial state. The transition
--   function may produce arbitrary output at any transition step.
liftStatefulTransducer :: (Monad m, Typeable x, Typeable y) => (state -> x -> (state, [y])) -> state -> Transducer m x y

-- | Function <a>liftSimpleSplitter</a> lifts a simple, non-sectioning
--   splitter function into a full <a>Splitter</a>
liftSimpleSplitter :: (Monad m, Typeable x) => (forall c1 c2 c3 context. Source c1 x -> Sink c2 x -> Sink c3 x -> Pipe context m [x]) -> Splitter m x

-- | Function <a>liftSectionSplitter</a> lifts a sectioning splitter
--   function into a full <a>Splitter</a>
liftSectionSplitter :: (Monad m, Typeable x) => (forall c1 c2 c3 context. Source c1 x -> Sink c2 (Maybe x) -> Sink c3 (Maybe x) -> Pipe context m [x]) -> Splitter m x

-- | Function <a>liftStatelessSplitter</a> takes a function that assigns a
--   Boolean value to each input item and lifts it into a <a>Splitter</a>
liftStatelessSplitter :: (Monad m, Typeable x) => (x -> Bool) -> Splitter m x


-- | Module <a>Components</a> defines primitive components of
--   <a>Producer</a>, <a>Consumer</a>, <a>Transducer</a> and
--   <a>Splitter</a> types, defined in the <a>Foundation</a> and
--   <a>ComponentTypes</a> modules.
module Control.Concurrent.SCC.Components

-- | Producer <a>fromFile</a> opens the named file and feeds the given sink
--   from its contents.
fromFile :: String -> Producer IO Char ()

-- | Producer <a>fromHandle</a> feeds the given sink from the open file
--   <i>handle</i>.
fromHandle :: Handle -> Producer IO Char ()

-- | Producer <a>fromStdIn</a> feeds the given sink from the standard
--   input.
fromStdIn :: Producer IO Char ()

-- | Consumer <a>appendFile</a> opens the name file and appends the given
--   source to it.
appendFile :: String -> Consumer IO Char ()

-- | Consumer <a>toFile</a> opens the named file and copies the given
--   source into it.
toFile :: String -> Consumer IO Char ()

-- | Consumer <a>toHandle</a> copies the given source into the open file
--   <i>handle</i>.
toHandle :: Handle -> Consumer IO Char ()

-- | Consumer <a>toStdOut</a> copies the given source into the standard
--   output.
toStdOut :: Consumer IO Char ()
toPrint :: (Show x, Typeable x) => Consumer IO x ()

-- | Transducer <a>asis</a> passes its input through unmodified.
asis :: (Monad m, Typeable x) => Transducer m x x

-- | The <a>suppress</a> transducer suppresses all input it receives. It is
--   equivalent to <a>substitute</a> []
suppress :: (Monad m, Typeable x, Typeable y) => Transducer m x y

-- | The <a>erroneous</a> transducer reports an error if any input reaches
--   it.
erroneous :: (Monad m, Typeable x) => Transducer m x x

-- | Transducer <a>prepend</a> passes its input unmodified, except for
--   prepending contents of the given list parameter before it.
prepend :: (Monad m, Typeable x) => [x] -> Transducer m x x

-- | Transducer <a>append</a> passes its input unmodified, except for
--   appending contents of the given list parameter to its end.
append :: (Monad m, Typeable x) => [x] -> Transducer m x x

-- | The <a>substitute</a> transducer replaces its whole input by its
--   parameter.
substitute :: (Monad m, Typeable x, Typeable y) => [y] -> Transducer m x y

-- | Splitter <a>allTrue</a> feeds its entire input into its <i>true</i>
--   sink.
allTrue :: (Monad m, Typeable x) => Splitter m x

-- | Splitter <a>allFalse</a> feeds its entire input into its <i>false</i>
--   sink.
allFalse :: (Monad m, Typeable x) => Splitter m x

-- | Splitter <a>one</a> feeds all input values to its <i>true</i> sink,
--   treating every value as a separate section.
one :: (Monad m, Typeable x) => Splitter m x

-- | Splitter <a>substring</a> feeds to its <i>true</i> sink all input
--   parts that match the contents of the given list argument. If two
--   overlapping parts of the input both match the argument, only the first
--   one wins.
substring :: (Monad m, Eq x, Typeable x) => [x] -> Splitter m x

-- | Splitter <a>substringMatch</a> feeds to its <i>true</i> sink all input
--   parts that match the contents of the given list argument. If two
--   overlapping parts of the input match the argument, both are considered
--   <i>true</i>.
substringMatch :: (Monad m, Eq x, Typeable x) => [x] -> Splitter m x

-- | Transducer <a>group</a> collects all its input values into a single
--   list.
group :: (Monad m, Typeable x) => Transducer m x [x]

-- | Transducer <a>concatenate</a> flattens the input stream of lists of
--   values into the output stream of values.
concatenate :: (Monad m, Typeable x) => Transducer m [x] x
concatSeparate :: (Monad m, Typeable x) => [x] -> Transducer m [x] x

-- | The <a>lowercase</a> transforms all uppercase letters in the input to
--   lowercase, leaving the rest unchanged.
lowercase :: (Monad m) => Transducer m Char Char

-- | The <a>uppercase</a> transforms all lowercase letters in the input to
--   uppercase, leaving the rest unchanged.
uppercase :: (Monad m) => Transducer m Char Char

-- | Splitter <a>whitespace</a> feeds all white-space characters into its
--   <i>true</i> sink, all others into <i>false</i>.
whitespace :: (Monad m) => Splitter m Char

-- | Splitter <a>letters</a> feeds all alphabetical characters into its
--   <i>true</i> sink, all other characters into <i>false</i>.
letters :: (Monad m) => Splitter m Char

-- | Splitter <a>digits</a> feeds all digits into its <i>true</i> sink, all
--   other characters into <i>false</i>.
digits :: (Monad m) => Splitter m Char

-- | The sectioning splitter <a>line</a> feeds line-ends into its
--   <i>false</i> sink, and line contents into <i>true</i>. A single
--   line-end can be formed by any of the character sequences "\n", "\r",
--   "\r\n", or "\n\r".
line :: (Monad m) => Splitter m Char

-- | Splitter <a>nonEmptyLine</a> feeds line-ends into its <i>false</i>
--   sink, and all other characters into <i>true</i>.
nonEmptyLine :: (Monad m) => Splitter m Char

-- | The <a>count</a> transducer counts all its input values and outputs
--   the final tally.
count :: (Monad m, Typeable x) => Transducer m x Integer
toString :: (Monad m, Show x, Typeable x) => Transducer m x String


-- | The <a>Combinators</a> module defines combinators applicable to
--   <a>Transducer</a> and <a>Splitter</a> components defined in the
--   <a>ComponentTypes</a> module.
module Control.Concurrent.SCC.Combinators

-- | The result of combinator <a>-&gt;&gt;</a> is a consumer that acts as a
--   composition of the given transducer and consumer arguments.
(->>) :: (Monad m, Typeable x, Typeable y) => Transducer m x y -> Consumer m y r -> Consumer m x r

-- | The result of combinator <a>&lt;&lt;-</a> is a producer that acts as a
--   composition of the given transducer and producer arguments.
(<<-) :: (Monad m, Typeable x, Typeable y) => Transducer m x y -> Producer m x r -> Producer m y r

-- | The <a>&gt;-&gt;</a> combinator composes its argument transducers. The
--   resulting composition <i>t1 &gt;-&gt; t2</i> passes its input through
--   the first transducer <i>t1</i>, the output of <i>t1</i> is passed to
--   the other transducer <i>t2</i>, and its output becomes the output of
--   the composition.
(>->) :: (Monad m) => Transducer m x y -> Transducer m y z -> Transducer m x z

-- | The <a>join</a> combinator arranges the two transducer arguments in
--   parallel. The input of the resulting transducer is replicated to both
--   component transducers in parallel, and the output of the resulting
--   transducer is a concatenation of the two component transducers'
--   outputs.
join :: (Monad m, Typeable x) => Transducer m x y -> Transducer m x y -> Transducer m x y

-- | The <a>snot</a> (streaming not) combinator simply reverses the outputs
--   of the argument splitter. In other words, data that the argument
--   splitter sends to its <i>true</i> sink goes to the <i>false</i> sink
--   of the result, and vice versa.
snot :: (Monad m, Typeable x) => Splitter m x -> Splitter m x

-- | The <a>&gt;&amp;</a> combinator sends the <i>true</i> sink output of
--   its left operand to the input of its right operand for further
--   splitting. Both operands' <i>false</i> sinks are connected to the
--   <i>false</i> sink of the combined splitter, but any input value to
--   reach the <i>true</i> sink of the combined component data must be
--   deemed true by both splitters.
(>&) :: (Monad m, Typeable x) => Splitter m x -> Splitter m x -> Splitter m x

-- | A <a>&gt;|</a> combinator's input value can reach its <i>false</i>
--   sink only by going through both argument splitters' <i>false</i>
--   sinks.
(>|) :: (Monad m, Typeable x) => Splitter m x -> Splitter m x -> Splitter m x

-- | Combinator <a>&amp;&amp;</a> is a pairwise logical conjunction of two
--   splitters run in parallel on the same input.
(&&) :: (Monad m, Typeable x) => Splitter m x -> Splitter m x -> Splitter m x

-- | Combinator <a>||</a> is a pairwise logical disjunction of two
--   splitters run in parallel on the same input.
(||) :: (Monad m, Typeable x) => Splitter m x -> Splitter m x -> Splitter m x

-- | The result of the combinator <a>ifs</a> is a transducer that applies
--   one argument transducer to one portion of the input and the other
--   transducer to the other portion of input, depending on where the
--   splitter argument routes the data.
ifs :: (Monad m, Typeable x) => Splitter m x -> Transducer m x y -> Transducer m x y -> Transducer m x y
wherever :: (Monad m, Typeable x) => Transducer m x x -> Splitter m x -> Transducer m x x
unless :: (Monad m, Typeable x) => Transducer m x x -> Splitter m x -> Transducer m x x
select :: (Monad m, Typeable x) => Splitter m x -> Transducer m x x

-- | The recursive combinator <a>while</a> feeds the true sink of the
--   argument splitter back to itself, modified by the argument transducer.
--   Data fed to the splitter's false sink is passed on unmodified.
while :: (Monad m, Typeable x) => Transducer m x x -> Splitter m x -> Transducer m x x

-- | The recursive combinator <a>nestedIn</a> combines two splitters into a
--   mutually recursive loop acting as a single splitter. The true sink of
--   one of the argument splitters and false sink of the other become the
--   true and false sinks of the loop. The other two sinks are bound to the
--   other splitter's source. The use of <a>nestedIn</a> makes sense only
--   on hierarchically structured streams. If we gave it some input
--   containing a flat sequence of values, and assuming both component
--   splitters are deterministic and stateless, a value would either not
--   loop at all or it would loop forever.
nestedIn :: (Monad m, Typeable x) => Splitter m x -> Splitter m x -> Splitter m x

-- | The <a>foreach</a> combinator is similar to the combinator <a>ifs</a>
--   in that it combines a splitter and two transducers into another
--   transducer. However, in this case the transducers are re-instantiated
--   for each consecutive portion of the input as the splitter chunks it
--   up. Each contiguous portion of the input that the splitter sends to
--   one of its two sinks gets transducered through the appropriate
--   argument transducer as that transducer's whole input. As soon as the
--   contiguous portion is finished, the transducer gets terminated.
foreach :: (Monad m, Typeable x, Typeable y) => Splitter m x -> Transducer m x y -> Transducer m x y -> Transducer m x y

-- | The <a>having</a> combinator combines two pure splitters into a pure
--   splitter. One splitter is used to chunk the input into contiguous
--   portions. Its <i>false</i> sink is routed directly to the <i>false</i>
--   sink of the combined splitter. The second splitter is instantiated and
--   run on each portion of the input that goes to first splitter's
--   <i>true</i> sink. If the second splitter sends any output at all to
--   its <i>true</i> sink, the whole input portion is passed on to the
--   <i>true</i> sink of the combined splitter, otherwise it goes to its
--   <i>false</i> sink.
having :: (Monad m, Typeable x) => Splitter m x -> Splitter m x -> Splitter m x

-- | The <a>havingOnly</a> combinator is analogous to the <a>having</a>
--   combinator, but it succeeds and passes each chunk of the input to its
--   <i>true</i> sink only if the second splitter sends no part of it to
--   its <i>false</i> sink.
havingOnly :: (Monad m, Typeable x) => Splitter m x -> Splitter m x -> Splitter m x

-- | Combinator <a>followedBy</a> treats its argument <a>Splitter</a>s as
--   patterns components and returns a <a>Splitter</a> that matches their
--   concatenation. A section of input is considered <i>true</i> by the
--   result iff its prefix is considered <i>true</i> by argument <i>s1</i>
--   and the rest of the section is considered <i>true</i> by <i>s2</i>.
--   The splitter <i>s2</i> is started anew after every section split to
--   <i>true</i> sink by <i>s1</i>.
followedBy :: (Monad m, Typeable x) => Splitter m x -> Splitter m x -> Splitter m x

-- | The <a>even</a> combinator takes every input section that its argument
--   splitters deems <i>true</i>, and feeds even ones into its <i>true</i>
--   sink. The odd sections and parts of input that are <i>false</i>
--   according to its argument splitter are fed to <a>even</a> splitter's
--   <i>false</i> sink.
even :: (Monad m, Typeable x) => Splitter m x -> Splitter m x

-- | The result of combinator <a>first</a> behaves the same as the argument
--   splitter up to and including the first portion of the input which goes
--   into the argument's <i>true</i> sink. All input following the first
--   true portion goes into the <i>false</i> sink.
first :: (Monad m, Typeable x) => Splitter m x -> Splitter m x

-- | The result of combinator <a>uptoFirst</a> takes all input up to and
--   including the first portion of the input which goes into the
--   argument's <i>true</i> sink and feeds it to the result splitter's
--   <i>true</i> sink. All the rest of the input goes into the <i>false</i>
--   sink. The only difference between <a>last</a> and <a>lastAndAfter</a>
--   combinators is in where they direct the <i>false</i> portion of the
--   input preceding the first <i>true</i> part.
uptoFirst :: (Monad m, Typeable x) => Splitter m x -> Splitter m x

-- | The <a>prefix</a> combinator feeds its <i>true</i> sink only the
--   prefix of the input that its argument feeds to its <i>true</i> sink.
--   All the rest of the input is dumped into the <i>false</i> sink of the
--   result.
prefix :: (Monad m, Typeable x) => Splitter m x -> Splitter m x

-- | The result of the combinator <a>last</a> is a splitter which directs
--   all input to its <i>false</i> sink, up to the last portion of the
--   input which goes to its argument's <i>true</i> sink. That portion of
--   the input is the only one that goes to the resulting component's
--   <i>true</i> sink. The splitter returned by the combinator <a>last</a>
--   has to buffer the previous two portions of its input, because it
--   cannot know if a true portion of the input is the last one until it
--   sees the end of the input or another portion succeeding the previous
--   one.
last :: (Monad m, Typeable x) => Splitter m x -> Splitter m x

-- | The result of the combinator <a>lastAndAfter</a> is a splitter which
--   directs all input to its <i>false</i> sink, up to the last portion of
--   the input which goes to its argument's <i>true</i> sink. That portion
--   and the remainder of the input is fed to the resulting component's
--   <i>true</i> sink. The difference between <a>last</a> and
--   <a>lastAndAfter</a> combinators is where they feed the <i>false</i>
--   portion of the input, if any, remaining after the last <i>true</i>
--   part.
lastAndAfter :: (Monad m, Typeable x) => Splitter m x -> Splitter m x

-- | The <a>suffix</a> combinator feeds its <i>true</i> sink only the
--   suffix of the input that its argument feeds to its <i>true</i> sink.
--   All the rest of the input is dumped into the <i>false</i> sink of the
--   result.
suffix :: (Monad m, Typeable x) => Splitter m x -> Splitter m x

-- | Combinator <a>between</a> passes to its <i>true</i> sink all input
--   that follows a section considered true by its first argument splitter
--   but not a section considered true by its second argument. The section
--   delimiter pairs can nest to arbitrary depth.
between :: (Monad m, Typeable x) => Splitter m x -> Splitter m x -> Splitter m x

-- | Combinator <a>...</a> is similar to <a>between</a>, except it passes
--   to <i>true</i> the delimiting sections as well as all input between
--   them.
(...) :: (Monad m, Typeable x) => Splitter m x -> Splitter m x -> Splitter m x