-- 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 the Coroutine monad transformer. The next few
--   layers add stream abstractions and nested producer-consumer coroutine
--   pairs. On top of that are streaming component types, a number of
--   primitive streaming components and a set of component combinators.
--   Finally, there is an executable that exposes all framework
--   functionality in a command-line shell.
--   
--   The original library design is based on paper
--   <a>http://conferences.idealliance.org/extreme/html/2006/Blazevic01/EML2006Blazevic01.html</a>
--   
--   Mario Blažević, Streaming component combinators, Extreme Markup
--   Languages, 2006.
@package scc
@version 0.4


-- | This module can be used to optimize any complex computation that can
--   be broken down into parallelizable sub-computations. The computations
--   in question may be pure values, monadic values, list or stream
--   transformations or anything else provided that it's parallelizable and
--   has a relatively predictable computation cost. Each elementary
--   sub-computation needs to be packaged as a <a>Component</a> using the
--   constructor <a>atomic</a>. Sub-computations can then be combined into
--   larger computations using the other constructors.
module Control.Concurrent.Configuration

-- | A <a>Component</a> carries a value and metadata about the value. It
--   can be configured to use a specific number of threads.
data Component c
Component :: String -> [AnyComponent] -> Int -> (Int -> Component c) -> Int -> Int -> c -> Component c

-- | Readable component name.
name :: Component c -> String

-- | Returns the list of all children components.
subComponents :: Component c -> [AnyComponent]

-- | Returns the maximum number of threads that can be used by the
--   component.
maxUsableThreads :: Component c -> Int

-- | Configures the component to use the specified number of threads. This
--   function affects <a>usedThreads</a>, <a>cost</a>, and
--   <a>subComponents</a> methods of the result, while <a>name</a> and
--   <a>maxUsableThreads</a> remain the same.
usingThreads :: Component c -> Int -> Component c

-- | The number of threads that the component is configured to use. The
--   default number is usually 1.
usedThreads :: Component c -> Int

-- | The cost of using the component as configured. The cost is a rough
--   approximation of time it would take to do the job given the
--   <a>usedThreads</a>.
cost :: Component c -> Int

-- | The content.
with :: Component c -> c

-- | Show details of the given component's configuration.
showComponentTree :: Component c -> String

-- | Function <a>atomic</a> takes the component name and its cost creates a
--   single-threaded component with no subcomponents.
atomic :: String -> Int -> c -> Component c

-- | Applies a unary <i>combinator</i> to the component payload. The
--   resulting component has the original one as its <a>subComponents</a>,
--   and its <a>cost</a> is the sum of the original component's cost and
--   the <i>combinator cost</i>.
lift :: Int -> String -> (c1 -> c2) -> Component c1 -> Component c2

-- | Combines two components into one, applying <i>combinator</i> to their
--   contents. The <i>combinator</i> takes a flag denoting if its arguments
--   should run in parallel. The <a>cost</a> and <a>usingThreads</a> of the
--   result assume the parallel execution of the argument components.
liftParallelPair :: String -> (Bool -> c1 -> c2 -> c3) -> Component c1 -> Component c2 -> Component c3

-- | Combines two components into one, applying <i>combinator</i> to their
--   contents. The <a>cost</a> and <a>usingThreads</a> of the result assume
--   the sequential execution of the argument components.
liftSequentialPair :: String -> (c1 -> c2 -> c3) -> Component c1 -> Component c2 -> Component c3

-- | Combines three components into one. The first component runs in
--   parallel with the latter two, which are considered alternative to each
--   other.
parallelRouterAndBranches :: String -> (Bool -> c1 -> c2 -> c3 -> c4) -> Component c1 -> Component c2 -> Component c3 -> Component c4

-- | Builds a tree of recursive components. The combinator takes a list of
--   pairs of a boolean flag denoting whether the level should be run in
--   parallel and the value.
recursiveComponentTree :: String -> ([(Bool, c1)] -> c2) -> Component c1 -> Component c2


-- | This module defines the <a>Coroutine</a> monad transformer.
--   
--   A <a>Coroutine</a> monadic computation can <a>suspend</a> its
--   execution at any time, returning to its invoker. The returned
--   coroutine suspension contains the continuation of the coroutine
--   embedded in a functor. Here is an example of a coroutine that suspends
--   computation in the <a>IO</a> monad using the functor <a>Yield</a>:
--   
--   <pre>
--   producer = do yield 1
--                 lift (putStrLn "Produced one, next is four.")
--                 yield 4
--                 return "Finished"
--   </pre>
--   
--   A suspended <a>Coroutine</a> computation can be resumed. The easiest
--   way to run a coroutine is by using the <a>pogoStick</a> function,
--   which keeps resuming the coroutine in trampolined style until it
--   completes. Here is an example of <a>pogoStick</a> applied to the
--   <i>producer</i> above:
--   
--   <pre>
--   printProduce :: Show x =&gt; Coroutine (Yield x) IO r -&gt; IO r
--   printProduce producer = pogoStick (\(Yield x cont) -&gt; lift (print x) &gt;&gt; cont) producer
--   </pre>
--   
--   Multiple concurrent coroutines can be run as well, and this module
--   provides two different ways. The function <a>seesaw</a> can be used to
--   run two interleaved computations. Another possible way is to weave
--   together steps of different coroutines into a single coroutine using
--   the function <a>couple</a>, which can then be executed by
--   <a>pogoStick</a>.
--   
--   Coroutines can be run from within another coroutine. In this case, the
--   nested coroutines would normally suspend to their invoker. Another
--   option is to allow a nested coroutine to suspend both itself and its
--   invoker at once. In this case, the two suspension functors should be
--   grouped into an <a>EitherFunctor</a>. To run nested coroutines of this
--   kind, use functions <a>pogoStickNested</a>, <a>seesawNested</a>, and
--   <a>coupleNested</a>.
--   
--   For other uses of trampoline-style coroutines, see
--   
--   <pre>
--   Trampolined Style - Ganz, S. E. Friedman, D. P. Wand, M, ACM SIGPLAN NOTICES, 1999, VOL 34; NUMBER 9, pages 18-27
--   </pre>
--   
--   and
--   
--   <pre>
--   The Essence of Multitasking - William L. Harrison, Proceedings of the 11th International Conference on Algebraic
--   Methodology and Software Technology, volume 4019 of Lecture Notes in Computer Science, 2006
--   </pre>
module Control.Concurrent.Coroutine

-- | Suspending, resumable monadic computations.
data Coroutine s m r

-- | Suspend the current <a>Coroutine</a>.
suspend :: (Monad m, Functor s) => s (Coroutine s m x) -> Coroutine s m x

-- | Class of monads that can perform two computations in parallel.
class (Monad m) => ParallelizableMonad m
bindM2 :: (ParallelizableMonad m) => (a -> b -> m c) -> m a -> m b -> m c

-- | Class of functors that can be lifted.
class (Functor a, Functor d) => AncestorFunctor a d

-- | Convert a non-suspending <a>Coroutine</a> to the base monad.
runCoroutine :: (Monad m) => Coroutine Naught m x -> m x

-- | Run a <a>Coroutine</a>, using a function that converts suspension to
--   the resumption it wraps.
pogoStick :: (Functor s, Monad m) => (s (Coroutine s m x) -> Coroutine s m x) -> Coroutine s m x -> m x

-- | Run a nested <a>Coroutine</a> that can suspend both itself and the
--   current <a>Coroutine</a>.
pogoStickNested :: (Functor s1, Functor s2, Monad m) => (s2 (Coroutine (EitherFunctor s1 s2) m x) -> Coroutine (EitherFunctor s1 s2) m x) -> Coroutine (EitherFunctor s1 s2) m x -> Coroutine s1 m x

-- | Runs two coroutines concurrently. The first argument is used to run
--   the next step of each coroutine, the next to convert the left, right,
--   or both suspensions into the corresponding resumptions.
seesaw :: (Monad m, Functor s1, Functor s2) => (forall x y r. (x -> y -> m r) -> m x -> m y -> m r) -> SeesawResolver s1 s2 -> Coroutine s1 m x -> Coroutine s2 m y -> m (x, y)

-- | Like <a>seesaw</a>, but for nested coroutines that are allowed to
--   suspend the current coroutine as well as themselves.
seesawNested :: (Monad m, Functor s0, Functor s1, Functor s2) => (forall x y r. (x -> y -> m r) -> m x -> m y -> m r) -> SeesawResolver s1 s2 -> Coroutine (EitherFunctor s0 s1) m x -> Coroutine (EitherFunctor s0 s2) m y -> Coroutine s0 m (x, y)

-- | A simple record containing the resolver functions for all possible
--   coroutine pair suspensions.
data SeesawResolver s1 s2
SeesawResolver :: (forall t. s1 t -> t) -> (forall t. s2 t -> t) -> (forall t1 t2 r. (t1 -> r) -> (t2 -> r) -> (t1 -> t2 -> r) -> s1 t1 -> s2 t2 -> r) -> SeesawResolver s1 s2

-- | resolves the left suspension functor into the resumption it contains
resumeLeft :: SeesawResolver s1 s2 -> forall t. s1 t -> t

-- | resolves the right suspension into its resumption | invoked when both
--   coroutines are suspended, resolves both suspensions or either one
resumeRight :: SeesawResolver s1 s2 -> forall t. s2 t -> t
resumeAny :: SeesawResolver s1 s2 -> forall t1 t2 r. (t1 -> r) -> (t2 -> r) -> (t1 -> t2 -> r) -> s1 t1 -> s2 t2 -> r

-- | The <a>Yield</a> functor instance is equivalent to (,) but more
--   descriptive.
data Yield x y
Yield :: x -> y -> Yield x y

-- | The <a>Await</a> functor instance is equivalent to (-&gt;) but more
--   descriptive.
data Await x y
Await :: !x -> y -> Await x y

-- | The <a>Naught</a> functor instance doesn't contain anything and cannot
--   be constructed. Used for building non-suspendable coroutines.
data Naught x

-- | Suspend yielding a value.
yield :: (Monad m) => x -> Coroutine (Yield x) m ()

-- | Suspend until a value is provided.
await :: (Monad m) => Coroutine (Await x) m x

-- | Combines two values under two functors into a pair of values under a
--   single <a>NestedFunctor</a>.
nest :: (Functor a, Functor b) => a x -> b y -> NestedFunctor a b (x, y)

-- | Weaves two coroutines into one.
couple :: (Monad m, Functor s1, Functor s2) => (forall x y r. (x -> y -> m r) -> m x -> m y -> m r) -> Coroutine s1 m x -> Coroutine s2 m y -> Coroutine (SomeFunctor s1 s2) m (x, y)

-- | Weaves two nested coroutines into one.
coupleNested :: (Monad m, Functor s0, Functor s1, Functor s2) => (forall x y r. (x -> y -> m r) -> m x -> m y -> m r) -> Coroutine (EitherFunctor s0 s1) m x -> Coroutine (EitherFunctor s0 s2) m y -> Coroutine (EitherFunctor s0 (SomeFunctor s1 s2)) m (x, y)

-- | Converts a coroutine into a nested one.
local :: (Functor r, Monad m) => Coroutine r m x -> Coroutine (EitherFunctor l r) m x

-- | Converts a coroutine into one that can contain nested coroutines.
out :: (Functor l, Monad m) => Coroutine l m x -> Coroutine (EitherFunctor l r) m x

-- | Like <a>out</a>, working over multiple functors.
liftOut :: (Monad m, Functor a, AncestorFunctor a d) => Coroutine a m x -> Coroutine d m x

-- | Combines two alternative functors into one, applying one or the other.
--   Used for nested coroutines.
data EitherFunctor l r x
LeftF :: (l x) -> EitherFunctor l r x
RightF :: (r x) -> EitherFunctor l r x

-- | Combines two functors into one, applying both.
newtype NestedFunctor l r x
NestedFunctor :: (l (r x)) -> NestedFunctor l r x

-- | Combines two functors into one, applying either or both of them. Used
--   for coupled coroutines.
data SomeFunctor l r x
LeftSome :: (l x) -> SomeFunctor l r x
RightSome :: (r x) -> SomeFunctor l r x
Both :: (NestedFunctor l r x) -> SomeFunctor l r x
instance [overlap ok] (d ~ EitherFunctor d' s, Functor a, Functor d', Functor d, AncestorFunctor a d') => AncestorFunctor a d
instance [overlap ok] (Functor a) => AncestorFunctor a a
instance [overlap ok] (Functor l, Functor r) => Functor (SomeFunctor l r)
instance [overlap ok] (Functor l, Functor r) => Functor (NestedFunctor l r)
instance [overlap ok] (Functor l, Functor r) => Functor (EitherFunctor l r)
instance [overlap ok] Functor Naught
instance [overlap ok] Functor (Await x)
instance [overlap ok] Functor (Yield x)
instance [overlap ok] (Functor s, MonadIO m) => MonadIO (Coroutine s m)
instance [overlap ok] (Functor s) => MonadTrans (Coroutine s)
instance [overlap ok] (Functor s, ParallelizableMonad m) => ParallelizableMonad (Coroutine s m)
instance [overlap ok] (Functor s, Monad m) => Monad (Coroutine s m)
instance [overlap ok] ParallelizableMonad IO
instance [overlap ok] ParallelizableMonad Maybe
instance [overlap ok] ParallelizableMonad Identity


-- | This module defines <a>Source</a> and <a>Sink</a> types and
--   <a>pipe</a> functions that create them. The method <a>get</a> on
--   <a>Source</a> abstracts away Control.Concurrent.SCC.Coroutine.await,
--   and the method <a>put</a> on <a>Sink</a> is a higher-level abstraction
--   of Control.Concurrent.SCC.Coroutine.yield. With this arrangement, a
--   single coroutine can yield values to multiple sinks and await values
--   from multiple sources with no need to change the
--   Control.Concurrent.SCC.Coroutine.Coroutine functor; the only
--   requirement is for each funtor of the sources and sinks the coroutine
--   uses to be an Control.Concurrent.SCC.Coroutine.AncestorFunctor of the
--   coroutine's functor. For example, coroutine <i>zip</i> that takes two
--   sources and one sink would be declared like this:
--   
--   <pre>
--   zip :: forall m a1 a2 a3 d x y. (Monad m, AncestorFunctor a1 d, AncestorFunctor a2 d, AncestorFunctor a3 d)
--          =&gt; Source m a1 x -&gt; Source m a2 y -&gt; Sink m a3 (x, y) -&gt; Coroutine d m ()
--   </pre>
--   
--   Sources, sinks, and coroutines communicating through them are all
--   created using the <a>pipe</a> function or one of its variants. They
--   effectively split the current coroutine into a producer-consumer
--   coroutine pair. The producer gets a new <a>Sink</a> to write to and
--   the consumer a new <a>Source</a> to read from, in addition to all the
--   streams that are visible in the original coroutine. The following
--   function, for example, uses the <i>zip</i> coroutine above to add
--   together the values from two Integer sources:
--   
--   <pre>
--   add :: forall m a1 a2 a3 d. (Monad m, AncestorFunctor a1 d, AncestorFunctor a2 d, AncestorFunctor a3 d)
--          =&gt; Source m a1 Integer -&gt; Source m a2 Integer -&gt; Sink m a3 Integer -&gt; Coroutine d m ()
--   add source1 source2 sink = do pipe
--                                    (pairSink-&gt; zip source1 source2 pairSink)            -- producer coroutine
--                                    (pairSource-&gt; pourMap (uncurry (+)) pairSource sink) -- consumer coroutine
--                                 return ()
--   </pre>
module Control.Concurrent.SCC.Streams

-- | A <a>Sink</a> can be used to yield values from any nested
--   <a>Coroutine</a> computation whose functor provably descends from the
--   functor <i>a</i>. It's the write-only end of a Pipe communication
--   channel.
data Sink m :: (* -> *) a x

-- | A <a>Source</a> can be used to read values into any nested
--   <a>Coroutine</a> computation whose functor provably descends from the
--   functor <i>a</i>. It's the read-only end of a Pipe communication
--   channel.
data Source m :: (* -> *) a x
type SinkFunctor a x = EitherFunctor a (TryYield x)
type SourceFunctor a x = EitherFunctor a (Await (Maybe x))

-- | 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, Functor a, a1 ~ (SinkFunctor a x), a2 ~ (SourceFunctor a x)) => (Sink m a1 x -> Coroutine a1 m r1) -> (Source m a2 x -> Coroutine a2 m r2) -> Coroutine a m (r1, r2)

-- | The <a>pipeP</a> function is equivalent to <a>pipe</a>, except the
--   <i>producer</i> and <i>consumer</i> are run in parallel.
pipeP :: (ParallelizableMonad m, Functor a, a1 ~ (SinkFunctor a x), a2 ~ (SourceFunctor a x)) => (Sink m a1 x -> Coroutine a1 m r1) -> (Source m a2 x -> Coroutine a2 m r2) -> Coroutine a m (r1, r2)

-- | The <a>pipePS</a> function acts either as <a>pipeP</a> or as
--   <a>pipe</a>, depending on the argument <i>parallel</i>.
pipePS :: (ParallelizableMonad m, Functor a, a1 ~ (SinkFunctor a x), a2 ~ (SourceFunctor a x)) => Bool -> (Sink m a1 x -> Coroutine a1 m r1) -> (Source m a2 x -> Coroutine a2 m r2) -> Coroutine a m (r1, r2)

-- | Function <a>get'</a> assumes that the argument source is not empty and
--   returns the value the source yields. If the source is empty, the
--   function throws an error.
get' :: (Monad m, AncestorFunctor a d) => Source m a x -> Coroutine d m x
getSuccess :: (Monad m, AncestorFunctor a d) => Source m a x -> (x -> Coroutine d m ()) -> Coroutine d m ()

-- | Converts a <a>Sink</a> on the ancestor functor <i>a</i> into a sink on
--   the descendant functor <i>d</i>.
liftSink :: (Monad m, AncestorFunctor a d) => Sink m a x -> Sink m d x

-- | Converts a <a>Source</a> on the ancestor functor <i>a</i> into a
--   source on the descendant functor <i>d</i>.
liftSource :: (Monad m, AncestorFunctor a d) => Source m a x -> Source m d x

-- | <a>consumeAndSuppress</a> consumes the entire source ignoring the
--   values it generates.
consumeAndSuppress :: (Monad m, AncestorFunctor a d) => Source m a x -> Coroutine d 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, AncestorFunctor a1 d, AncestorFunctor a2 d, AncestorFunctor a3 d) => Source m a1 x -> Sink m a2 x -> Sink m a3 x -> Coroutine d m ()

-- | <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, AncestorFunctor a1 d, AncestorFunctor a2 d) => Source m a1 x -> Sink m a2 x -> Coroutine d m ()

-- | <a>pourMap</a> is like <a>pour</a> that applies the function <i>f</i>
--   to each argument before passing it into the <i>sink</i>.
pourMap :: (Monad m, AncestorFunctor a1 d, AncestorFunctor a2 d) => (x -> y) -> Source m a1 x -> Sink m a2 y -> Coroutine d m ()

-- | <a>getList</a> returns the list of all values generated by the source.
getList :: (Monad m, AncestorFunctor a d) => Source m a x -> Coroutine d 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, AncestorFunctor a d) => [x] -> Sink m a x -> Coroutine d m [x]

-- | Like <a>putList</a>, except it puts the contents of the given
--   <a>Seq</a> into the sink.
putQueue :: (Monad m, AncestorFunctor a d) => Seq x -> Sink m a x -> Coroutine d m [x]

-- | 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]


-- | This module defines various Control.Concurrent.SCC.Coroutine.Coroutine
--   types that operate on <a>Sink</a> and <a>Source</a> values. The
--   simplest of the bunch are <a>Consumer</a> and <a>Producer</a> types,
--   which respectively operate on a single source or sink. A
--   <a>Transducer</a> has access both to a <a>Source</a> to read from and
--   a <a>Sink</a> to write into. Finally, a <a>Splitter</a> reads from a
--   single source and writes all input into two sinks of the same type,
--   signalling interesting input boundaries by writing into the third
--   sink.
module Control.Concurrent.SCC.Types

-- | A component that performs a computation with no inputs nor outputs.
newtype Performer m r
Performer :: m r -> Performer m r
perform :: Performer m r -> m r
type OpenConsumer m a d x r = (AncestorFunctor a d) => Source m a x -> Coroutine d m r

-- | A component that consumes values from a <a>Source</a>.
newtype Consumer m x r
Consumer :: (forall a d. OpenConsumer m a d x r) -> Consumer m x r
consume :: Consumer m x r -> forall a d. OpenConsumer m a d x r
type OpenProducer m a d x r = (AncestorFunctor a d) => Sink m a x -> Coroutine d m r

-- | A component that produces values and puts them into a <a>Sink</a>.
newtype Producer m x r
Producer :: (forall a d. OpenProducer m a d x r) -> Producer m x r
produce :: Producer m x r -> forall a d. OpenProducer m a d x r
type OpenTransducer m a1 a2 d x y = (AncestorFunctor a1 d, AncestorFunctor a2 d) => Source m a1 x -> Sink m a2 y -> Coroutine d m [x]

-- | The <a>Transducer</a> type represents computations that transform a
--   data stream. Execution of <a>transduce</a> must continue consuming the
--   given <a>Source</a> and feeding the <a>Sink</a> as long both can be
--   resumed. If the sink dies first, <a>transduce</a> should return the
--   list of all values it has consumed from the source but hasn't managed
--   to process and write into the sink.
newtype Transducer m x y
Transducer :: (forall a1 a2 d. OpenTransducer m a1 a2 d x y) -> Transducer m x y
transduce :: Transducer m x y -> forall a1 a2 d. OpenTransducer m a1 a2 d x y
type OpenSplitter m a1 a2 a3 a4 d x b = (AncestorFunctor a1 d, AncestorFunctor a2 d, AncestorFunctor a3 d, AncestorFunctor a4 d) => Source m a1 x -> Sink m a2 x -> Sink m a3 x -> Sink m a4 b -> Coroutine d m [x]

-- | The SplitterComponent type represents computations that distribute the
--   input stream 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. Furthermore, the input source
--   should be entirely consumed and fed into the first two sinks. The
--   third sink can be used to supply extra information at arbitrary points
--   in the input. If any of the sinks dies before all data is fed to them,
--   <a>split</a> should return the list of all values it has consumed from
--   the source but hasn't managed to write into the sinks.
--   
--   A splitter can be used in two ways: as a predicate to determine which
--   portions of its input stream satisfy a certain property, or as a
--   chunker to divide the input stream into chunks. In the former case,
--   the predicate is considered true for exactly those parts of the input
--   that are written to its <i>true</i> sink. In the latter case, a chunk
--   is a contiguous section of the input stream that is written
--   exclusively to one sink, either true or false. Anything written to the
--   third sink also terminates the chunk.
newtype Splitter m x b
Splitter :: (forall a1 a2 a3 a4 d. OpenSplitter m a1 a2 a3 a4 d x b) -> Splitter m x b
split :: Splitter m x b -> forall a1 a2 a3 a4 d. OpenSplitter m a1 a2 a3 a4 d x b

-- | A <a>Markup</a> value is produced to mark either a <a>Start</a> and
--   <a>End</a> of a region of data, or an arbitrary <a>Point</a> in data.
--   A <a>Point</a> is semantically equivalent to a <a>Start</a>
--   immediately followed by <a>End</a>. The <a>Content</a> constructor
--   wraps the actual data.
data Boundary y
Start :: y -> Boundary y
End :: y -> Boundary y
Point :: y -> Boundary y
data Markup y x
Content :: x -> Markup y x
Markup :: (Boundary y) -> Markup y x
type Parser m x b = Transducer m x (Markup b x)

-- | <a>Branching</a> is a type class representing all types that can act
--   as consumers, namely <a>Consumer</a>, <a>Transducer</a>, and
--   <a>Splitter</a>.
class Branching c m :: (* -> *) x r | c -> m x
combineBranches :: (Branching c m x r) => (forall d. Bool -> (forall a d'. (AncestorFunctor d d') => OpenConsumer m a d' x r) -> (forall a d'. (AncestorFunctor d d') => OpenConsumer m a d' x r) -> (forall a. OpenConsumer m a d x r)) -> Bool -> c -> c -> c

-- | Creates a proper <a>Consumer</a> from a function that is, but can't be
--   proven to be, an <a>OpenConsumer</a>.
isolateConsumer :: (Monad m) => (forall d. (Functor d) => Source m d x -> Coroutine d m r) -> Consumer m x r

-- | Creates a proper <a>Producer</a> from a function that is, but can't be
--   proven to be, an <a>OpenProducer</a>.
isolateProducer :: (Monad m) => (forall d. (Functor d) => Sink m d x -> Coroutine d m r) -> Producer m x r

-- | Creates a proper <a>Transducer</a> from a function that is, but can't
--   be proven to be, an <a>OpenTransducer</a>.
isolateTransducer :: (Monad m) => (forall d. (Functor d) => Source m d x -> Sink m d y -> Coroutine d m [x]) -> Transducer m x y

-- | Creates a proper <a>Splitter</a> from a function that is, but can't be
--   proven to be, an <a>OpenSplitter</a>.
isolateSplitter :: (Monad m) => (forall d. (Functor d) => Source m d x -> Sink m d x -> Sink m d x -> Sink m d b -> Coroutine d m [x]) -> Splitter m x b

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

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

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

-- | Function <a>statefulTransducer</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.
statefulTransducer :: (Monad m) => (state -> x -> (state, [y])) -> state -> Transducer m x y

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

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

-- | Given a <a>Splitter</a>, a <a>Source</a>, and three consumer
--   functions, <a>splitToConsumers</a> runs the splitter on the source and
--   feeds the splitter's outputs to its <i>true</i>, <i>false</i>, and
--   <i>edge</i> sinks, respectively, to the three consumers.
splitToConsumers :: (Functor d, Monad m, d1 ~ (SinkFunctor d x), AncestorFunctor a (SinkFunctor (SinkFunctor d1 x) b)) => Splitter m x b -> Source m a x -> (Source m (SourceFunctor d x) x -> Coroutine (SourceFunctor d x) m r1) -> (Source m (SourceFunctor d1 x) x -> Coroutine (SourceFunctor d1 x) m r2) -> (Source m (SourceFunctor (SinkFunctor d1 x) b) b -> Coroutine (SourceFunctor (SinkFunctor d1 x) b) m r3) -> Coroutine d m ([x], r1, r2, r3)

-- | Given a <a>Splitter</a>, a <a>Source</a>, and two consumer functions,
--   <a>splitInputToConsumers</a> runs the splitter on the source and feeds
--   the splitter's <i>true</i> and <i>false</i> outputs, respectively, to
--   the two consumers.
splitInputToConsumers :: (ParallelizableMonad m, d1 ~ (SinkFunctor d x), AncestorFunctor a d) => Bool -> Splitter m x b -> Source m a x -> (Source m (SourceFunctor d1 x) x -> Coroutine (SourceFunctor d1 x) m [x]) -> (Source m (SourceFunctor d x) x -> Coroutine (SourceFunctor d x) m [x]) -> Coroutine d m [x]

-- | The <a>pipePS</a> function acts either as <a>pipeP</a> or as
--   <a>pipe</a>, depending on the argument <i>parallel</i>.
pipePS :: (ParallelizableMonad m, Functor a, a1 ~ (SinkFunctor a x), a2 ~ (SourceFunctor a x)) => Bool -> (Sink m a1 x -> Coroutine a1 m r1) -> (Source m a2 x -> Coroutine a2 m r2) -> Coroutine a m (r1, r2)
instance (Eq y, Eq x) => Eq (Markup y x)
instance (Eq y) => Eq (Boundary y)
instance (Show y) => Show (Boundary y)
instance (ParallelizableMonad m) => Branching (Splitter m x b) m x [x]
instance (Monad m) => Branching (Transducer m x y) m x [x]
instance (Monad m) => Branching (Consumer m x ()) m x [x]
instance (Monad m) => Branching (Consumer m x r) m x r
instance (Show y) => Show (Markup y Char)
instance Functor (Markup y)
instance Functor Boundary


-- | The <a>Combinators</a> module defines combinators applicable to values
--   of the <a>Transducer</a> and <a>Splitter</a> types defined in the
--   <a>Control.Concurrent.SCC.Types</a> module.
module Control.Concurrent.SCC.Combinators
splitterToMarker :: (Monad m) => Splitter m x b -> Transducer m x (Either (x, Bool) b)

-- | Converts a <a>Consumer</a> into a <a>Transducer</a> with no output.
consumeBy :: (Monad m) => Consumer m x r -> Transducer m x y

-- | Combinator <a>prepend</a> converts the given producer to transducer
--   that passes all its input through unmodified, except | for prepending
--   the output of the argument producer to it. | <a>prepend</a>
--   <i>prefix</i> = <a>join</a> (<a>substitute</a> <i>prefix</i>) asis
prepend :: (Monad m) => Producer m x r -> Transducer m x x

-- | Combinator <a>append</a> converts the given producer to transducer
--   that passes all its input through unmodified, finally | appending to
--   it the output of the argument producer. | <a>append</a> <i>suffix</i>
--   = <a>join</a> asis (<a>substitute</a> <i>suffix</i>)
append :: (Monad m) => Producer m x r -> Transducer m x x

-- | The <a>substitute</a> combinator converts its argument producer to a
--   transducer that produces the same output, while | consuming its entire
--   input and ignoring it.
substitute :: (Monad m) => Producer m y r -> Transducer m x y

-- | Class <a>PipeableComponentPair</a> applies to any two components that
--   can be combined into a third component with the following properties:
--   
--   <ul>
--   <li>The input of the result, if any, becomes the input of the first
--   component.</li>
--   <li>The output produced by the first child component is consumed by
--   the second child component.</li>
--   <li>The result output, if any, is the output of the second
--   component.</li>
--   </ul>
class PipeableComponentPair m :: (* -> *) w c1 c2 c3 | c1 c2 -> c3, c1 c3 -> c2, c2 c3 -> c2, c1 -> m w, c2 -> m w, c3 -> m
connect :: (PipeableComponentPair m w c1 c2 c3) => Bool -> c1 -> c2 -> c3

-- | Class <a>JoinableComponentPair</a> applies to any two components that
--   can be combined into a third component with the following properties:
--   
--   <ul>
--   <li>if both argument components consume input, the input of the
--   combined component gets distributed to both components in
--   parallel,</li>
--   <li>if both argument components produce output, the output of the
--   combined component is a concatenation of the complete output from the
--   first component followed by the complete output of the second
--   component, and</li>
--   <li>the <a>join</a> method may apply the components in any order, the
--   <a>sequence</a> method makes sure its first argument has completed
--   before using the second one.</li>
--   </ul>
class (Monad m, CompatibleSignature c1 t1 m x y, CompatibleSignature c2 t2 m x y, CompatibleSignature c3 t3 m x y) => JoinableComponentPair t1 t2 t3 m x y c1 c2 c3 | c1 c2 -> c3, c1 -> t1 m, c2 -> t2 m, c3 -> t3 m x y, t1 m x y -> c1, t2 m x y -> c2, t3 m x y -> c3
join :: (JoinableComponentPair t1 t2 t3 m x y c1 c2 c3) => Bool -> c1 -> c2 -> c3
sequence :: (JoinableComponentPair t1 t2 t3 m x y c1 c2 c3) => c1 -> c2 -> c3

-- | The snot (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) => Splitter m x b -> Splitter m x b

-- | The &gt;&amp; 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.
sAnd :: (ParallelizableMonad m) => Bool -> Splitter m x b1 -> Splitter m x b2 -> Splitter m x (b1, b2)

-- | A &gt;| combinator's input value can reach its <i>false</i> sink only
--   by going through both argument splitters' <i>false</i> sinks.
sOr :: (ParallelizableMonad m) => Bool -> Splitter m x b1 -> Splitter m x b2 -> Splitter m x (Either b1 b2)

-- | Combinator &amp;&amp; is a pairwise logical conjunction of two
--   splitters run in parallel on the same input.
pAnd :: (ParallelizableMonad m) => Bool -> Splitter m x b1 -> Splitter m x b2 -> Splitter m x (b1, b2)

-- | Combinator || is a pairwise logical disjunction of two splitters run
--   in parallel on the same input.
pOr :: (ParallelizableMonad m) => Bool -> Splitter m x b1 -> Splitter m x b2 -> Splitter m x (Either b1 b2)
ifs :: (ParallelizableMonad m, Branching c m x [x]) => Bool -> Splitter m x b -> c -> c -> c
wherever :: (ParallelizableMonad m) => Bool -> Transducer m x x -> Splitter m x b -> Transducer m x x
unless :: (ParallelizableMonad m) => Bool -> Transducer m x x -> Splitter m x b -> Transducer m x x
select :: (Monad m) => Splitter m x b -> 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 :: (ParallelizableMonad m) => [(Bool, (Transducer m x x, Splitter m x b))] -> 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, an input value would either
--   not loop at all or it would loop forever.
nestedIn :: (ParallelizableMonad m) => [(Bool, (Splitter m x b, Splitter m x b))] -> Splitter m x b

-- | 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 :: (ParallelizableMonad m, Branching c m x [x]) => Bool -> Splitter m x b -> c -> c -> c

-- | 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 :: (ParallelizableMonad m) => Bool -> Splitter m x b1 -> Splitter m x b2 -> Splitter m x b1

-- | 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 :: (ParallelizableMonad m) => Bool -> Splitter m x b1 -> Splitter m x b2 -> Splitter m x b1

-- | 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 :: (ParallelizableMonad m) => Bool -> Splitter m x b1 -> Splitter m x b2 -> Splitter m x (b1, b2)

-- | The <a>even</a> combinator takes every input section that its argument
--   <i>splitter</i> 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) => Splitter m x b -> Splitter m x b

-- | 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) => Splitter m x b -> Splitter m x b

-- | 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>first</a> and <a>uptoFirst</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) => Splitter m x b -> Splitter m x b

-- | 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) => Splitter m x b -> Splitter m x b

-- | 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) => Splitter m x b -> Splitter m x b

-- | 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) => Splitter m x b -> Splitter m x b

-- | 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) => Splitter m x b -> Splitter m x b

-- | Splitter <a>startOf</a> issues an empty <i>true</i> section at the
--   beginning of every section considered <i>true</i> by its argument
--   splitter, otherwise the entire input goes into its <i>false</i> sink.
startOf :: (Monad m) => Splitter m x b -> Splitter m x (Maybe b)

-- | Splitter <a>endOf</a> issues an empty <i>true</i> section at the end
--   of every section considered <i>true</i> by its argument splitter,
--   otherwise the entire input goes into its <i>false</i> sink.
endOf :: (Monad m) => Splitter m x b -> Splitter m x (Maybe b)

-- | Combinator ... tracks the running balance of difference between the
--   number of preceding starts of sections considered <i>true</i>
--   according to its first argument and the ones according to its second
--   argument. The combinator passes to <i>true</i> all input values for
--   which the difference balance is positive. This combinator is typically
--   used with <a>startOf</a> and <a>endOf</a> in order to count entire
--   input sections and ignore their lengths.
between :: (ParallelizableMonad m) => Bool -> Splitter m x b1 -> Splitter m x b2 -> Splitter m x b1

-- | Converts a splitter into a parser.
parseRegions :: (Monad m) => Splitter m x b -> Parser m x b

-- | Converts a boundary-marking splitter into a parser.
parseNestedRegions :: (Monad m) => Splitter m x (Boundary b) -> Parser m x b

-- | Runs the second argument on every contiguous region of input source
--   (typically produced by <a>splitterToMarker</a>) whose all values
--   either match <tt>Left (_, True)</tt> or <tt>Left (_, False)</tt>.
groupMarks :: (Monad m, AncestorFunctor a d, AncestorFunctor a (SinkFunctor d x)) => Source m a (Either (x, Bool) b) -> (Maybe (Maybe b) -> Source m (SourceFunctor d x) x -> Coroutine (SourceFunctor d x) m r) -> Coroutine d m ()
instance (ParallelizableMonad m) => JoinableComponentPair (ConsumerType ()) (ProducerType ()) TransducerType m [x] [y] (Consumer m x ()) (Producer m y ()) (Transducer m x y)
instance (ParallelizableMonad m) => JoinableComponentPair (ProducerType ()) (ConsumerType ()) TransducerType m [x] [y] (Producer m y ()) (Consumer m x ()) (Transducer m x y)
instance (ParallelizableMonad m) => JoinableComponentPair TransducerType (ConsumerType ()) TransducerType m [x] [y] (Transducer m x y) (Consumer m x ()) (Transducer m x y)
instance (ParallelizableMonad m) => JoinableComponentPair (ConsumerType ()) TransducerType TransducerType m [x] [y] (Consumer m x ()) (Transducer m x y) (Transducer m x y)
instance (ParallelizableMonad m) => JoinableComponentPair TransducerType (ProducerType ()) TransducerType m [x] [y] (Transducer m x y) (Producer m y ()) (Transducer m x y)
instance (ParallelizableMonad m) => JoinableComponentPair (ProducerType ()) TransducerType TransducerType m [x] [y] (Producer m y ()) (Transducer m x y) (Transducer m x y)
instance (ParallelizableMonad m) => JoinableComponentPair TransducerType (PerformerType r) TransducerType m [x] [y] (Transducer m x y) (Performer m r) (Transducer m x y)
instance (ParallelizableMonad m) => JoinableComponentPair (PerformerType r) TransducerType TransducerType m [x] [y] (Performer m r) (Transducer m x y) (Transducer m x y)
instance (ParallelizableMonad m) => JoinableComponentPair (ConsumerType r1) (PerformerType r2) (ConsumerType r2) m [x] () (Consumer m x r1) (Performer m r2) (Consumer m x r2)
instance (ParallelizableMonad m) => JoinableComponentPair (PerformerType r1) (ConsumerType r2) (ConsumerType r2) m [x] () (Performer m r1) (Consumer m x r2) (Consumer m x r2)
instance (ParallelizableMonad m) => JoinableComponentPair (ProducerType r1) (PerformerType r2) (ProducerType r2) m () [x] (Producer m x r1) (Performer m r2) (Producer m x r2)
instance (ParallelizableMonad m) => JoinableComponentPair (PerformerType r1) (ProducerType r2) (ProducerType r2) m () [x] (Performer m r1) (Producer m x r2) (Producer m x r2)
instance (ParallelizableMonad m) => JoinableComponentPair (PerformerType r1) (PerformerType r2) (PerformerType r2) m () () (Performer m r1) (Performer m r2) (Performer m r2)
instance (ParallelizableMonad m) => JoinableComponentPair TransducerType TransducerType TransducerType m [x] [y] (Transducer m x y) (Transducer m x y) (Transducer m x y)
instance (ParallelizableMonad m) => JoinableComponentPair (ConsumerType ()) (ConsumerType ()) (ConsumerType ()) m [x] () (Consumer m x ()) (Consumer m x ()) (Consumer m x ())
instance (Monad m) => JoinableComponentPair (ProducerType r1) (ProducerType r2) (ProducerType r2) m () [x] (Producer m x r1) (Producer m x r2) (Producer m x r2)
instance CompatibleSignature (Transducer m x y) TransducerType m [x] [y]
instance (AnyListOrUnit y) => CompatibleSignature (Producer m x r) (ProducerType r) m y [x]
instance (AnyListOrUnit y) => CompatibleSignature (Consumer m x r) (ConsumerType r) m [x] y
instance (AnyListOrUnit x, AnyListOrUnit y) => CompatibleSignature (Performer m r) (PerformerType r) m x y
instance AnyListOrUnit ()
instance AnyListOrUnit [x]
instance (ParallelizableMonad m) => PipeableComponentPair m y (Transducer m x y) (Transducer m y z) (Transducer m x z)
instance (ParallelizableMonad m) => PipeableComponentPair m x (Producer m x r) (Transducer m x y) (Producer m y r)
instance (ParallelizableMonad m) => PipeableComponentPair m y (Transducer m x y) (Consumer m y r) (Consumer m x r)
instance (ParallelizableMonad m) => PipeableComponentPair m x (Producer m x ()) (Consumer m x ()) (Performer m ())


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

-- | Used by <a>parseSubstring</a> to distinguish between overlapping
--   substrings.
data OccurenceTag

-- | <a>fromList</a> produces the contents of the given list argument.
fromList :: (Monad m) => [x] -> Producer m x [x]

-- | Consumer <a>toList</a> copies the given source into a list.
toList :: (Monad m) => Consumer m x [x]

-- | 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>. The argument <i>doClose</i> determines | if
--   <i>handle</i> should be closed when the handle is consumed or the sink
--   closed.
fromHandle :: Handle -> Bool -> 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>. The argument <i>doClose</i> determines | if
--   <i>handle</i> should be closed once the entire source is consumed and
--   copied.
toHandle :: Handle -> Bool -> Consumer IO Char ()

-- | Consumer <a>toStdOut</a> copies the given source into the standard
--   output.
toStdOut :: Consumer IO Char ()

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

-- | The <a>erroneous</a> consumer reports an error if any input reaches
--   it.
erroneous :: (Monad m) => String -> Consumer m x ()

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

-- | Transducer <a>parse</a> prepares input content for subsequent parsing.
parse :: (Monad m) => Transducer m x (Markup y x)

-- | Transducer <a>unparse</a> removes all markup from its input and passes
--   the content through.
unparse :: (Monad m) => Transducer m (Markup y x) x

-- | Performs the same task as the <a>substring</a> splitter, but instead
--   of splitting it outputs the input as <tt><a>Markup</a> x
--   <a>OccurenceTag</a></tt> in order to distinguish overlapping strings.
parseSubstring :: (Monad m, Eq x) => [x] -> Parser m x OccurenceTag

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

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

-- | Splitter <a>marked</a> passes all marked-up input sections to its
--   <i>true</i> sink, and all unmarked input to its <i>false</i> sink.
marked :: (Monad m, Eq y) => Splitter m (Markup y x) ()

-- | Splitter <a>markedContent</a> passes the content of all marked-up
--   input sections to its <i>true</i> sink, while the outermost tags and
--   all unmarked input go to its <i>false</i> sink.
markedContent :: (Monad m, Eq y) => Splitter m (Markup y x) ()

-- | Splitter <a>markedWith</a> passes input sections marked-up with the
--   appropriate tag to its <i>true</i> sink, and the rest of the input to
--   its <i>false</i> sink. The argument <i>select</i> determines if the
--   tag is appropriate.
markedWith :: (Monad m, Eq y) => (y -> Bool) -> Splitter m (Markup y x) ()

-- | Splitter <a>contentMarkedWith</a> passes the content of input sections
--   marked-up with the appropriate tag to its <i>true</i> sink, and the
--   rest of the input to its <i>false</i> sink. The argument <i>select</i>
--   determines if the tag is appropriate.
contentMarkedWith :: (Monad m, Eq y) => (y -> Bool) -> Splitter m (Markup y 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) => 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, both are sent
--   to <i>true</i> and each is preceded by an edge.
substring :: (Monad m, Eq x) => [x] -> Splitter m x ()

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

-- | Same as <a>concatenate</a> except it inserts the given separator list
--   between every two input lists.
concatSeparate :: (Monad m) => [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) => Transducer m x Integer

-- | Converts each input value <tt>x</tt> to <tt>show x</tt>.
toString :: (Monad m, Show x) => Transducer m x String
instance Eq OccurenceTag
instance Show OccurenceTag
instance Enum OccurenceTag


-- | Module <a>XML</a> defines primitives and combinators for parsing and
--   manipulating XML.
module Control.Concurrent.SCC.XML
data Token
StartTag :: Token
EndTag :: Token
EmptyTag :: Token
ElementName :: Token
AttributeName :: Token
AttributeValue :: Token
EntityReferenceToken :: Token
EntityName :: Token
ProcessingInstruction :: Token
ProcessingInstructionText :: Token
Comment :: Token
CommentText :: Token
StartMarkedSectionCDATA :: Token
EndMarkedSection :: Token
ErrorToken :: String -> Token

-- | The <a>tokens</a> splitter distinguishes XML markup from data content.
--   It is used by <a>parseTokens</a>.
tokens :: (Monad m) => Splitter m Char (Boundary Token)

-- | The XML token parser. This parser converts plain text to parsed text,
--   which is a precondition for using the remaining XML components.
parseTokens :: (Monad m) => Parser m Char Token

-- | Converts an XML entity name into the text value it represents:
--   <tt>expandEntity "lt" = "&lt;"</tt>.
expandEntity :: String -> String

-- | Escapes a character for inclusion into an XML attribute value.
escapeAttributeCharacter :: Char -> String

-- | Escapes a character for inclusion into the XML data content.
escapeContentCharacter :: Char -> String

-- | Splits all top-level elements with all their content to <i>true</i>,
--   all other input to <i>false</i>.
element :: (Monad m) => Splitter m (Markup Token Char) ()

-- | Splits the content of all top-level elements to <i>true</i>, their
--   tags and intervening input to <i>false</i>.
elementContent :: (Monad m) => Splitter m (Markup Token Char) ()

-- | Splits every element name, including the names of nested elements and
--   names in end tags, to <i>true</i>, all the rest of input to
--   <i>false</i>.
elementName :: (Monad m) => Splitter m (Markup Token Char) ()

-- | Splits every attribute specification to <i>true</i>, everything else
--   to <i>false</i>.
attribute :: (Monad m) => Splitter m (Markup Token Char) ()

-- | Splits every attribute name to <i>true</i>, all the rest of input to
--   <i>false</i>.
attributeName :: (Monad m) => Splitter m (Markup Token Char) ()

-- | Splits every attribute value, excluding the quote delimiters, to
--   <i>true</i>, all the rest of input to <i>false</i>.
attributeValue :: (Monad m) => Splitter m (Markup Token Char) ()

-- | Similiar to <tt>(Control.Concurrent.SCC.Combinators.having
--   <a>element</a>)</tt>, except it runs the argument splitter only on
--   each element's start tag, not on the entire element with its content.
elementHavingTag :: (ParallelizableMonad m) => Splitter m (Markup Token Char) b -> Splitter m (Markup Token Char) b

-- | Behaves like Control.Concurrent.SCC.Combinators.having, but the
--   right-hand splitter works on plain instead of marked-up text. This
--   allows regular <a>Char</a> splitters to be applied to parsed XML.
havingText :: (ParallelizableMonad m) => Bool -> Splitter m (Markup Token Char) b1 -> Splitter m Char b2 -> Splitter m (Markup Token Char) b1

-- | Behaves like Control.Concurrent.SCC.Combinators.havingOnly, but the
--   right-hand splitter works on plain instead of marked-up text. This
--   allows regular <a>Char</a> splitters to be applied to parsed XML.
havingOnlyText :: (ParallelizableMonad m) => Bool -> Splitter m (Markup Token Char) b1 -> Splitter m Char b2 -> Splitter m (Markup Token Char) b1
instance Eq Token
instance Show Token


-- | The <a>Components</a> module defines thin wrappers around the
--   <a>Transducer</a> and <a>Splitter</a> primitives and combinators,
--   relying on the <a>Control.Concurrent.SCC.ComponentTypes</a> module.
module Control.Concurrent.SCC.Components

-- | A component that performs a computation with no inputs nor outputs is
--   a <a>PerformerComponent</a>.
type PerformerComponent m r = Component (Performer m r)

-- | A component that consumes values from a Source is called
--   <a>ConsumerComponent</a>.
type ConsumerComponent m x r = Component (Consumer m x r)

-- | A component that produces values and puts them into a Sink is called
--   <a>ProducerComponent</a>.
type ProducerComponent m x r = Component (Producer m x r)

-- | The <a>TransducerComponent</a> type represents computations that
--   transform a data stream.
type TransducerComponent m x y = Component (Transducer m x y)
type ParserComponent m x y = Component (Parser m x y)

-- | The <a>SplitterComponent</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 c x'
--   arguments of a splitter are the same, the splitter must act as an
--   identity transform.
type SplitterComponent m x b = Component (Splitter m x b)

-- | The constant cost of each I/O-performing component.
ioCost :: Int

-- | ConsumerComponent <a>toList</a> copies the given source into a list.
toList :: (Monad m) => ConsumerComponent m x [x]

-- | <a>fromList</a> produces the contents of the given list argument.
fromList :: (Monad m) => [x] -> ProducerComponent m x [x]

-- | ConsumerComponent <a>toStdOut</a> copies the given source into the
--   standard output.
toStdOut :: ConsumerComponent IO Char ()

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

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

-- | ProducerComponent <a>fromHandle</a> feeds the given sink from the open
--   file <i>handle</i>. The argument <i>doClose</i> determines | if
--   <i>handle</i> should be closed when the handle is consumed or the sink
--   closed.
fromHandle :: Handle -> Bool -> ProducerComponent IO Char ()

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

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

-- | ConsumerComponent <a>toHandle</a> copies the given source into the
--   open file <i>handle</i>. The argument <i>doClose</i> determines | if
--   <i>handle</i> should be closed once the entire source is consumed and
--   copied.
toHandle :: Handle -> Bool -> ConsumerComponent IO Char ()

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

-- | TransducerComponent <a>unparse</a> removes all markup from its input
--   and passes the content through.
unparse :: (Monad m) => TransducerComponent m (Markup y x) x

-- | TransducerComponent <a>parse</a> prepares input content for subsequent
--   parsing.
parse :: (Monad m) => TransducerComponent m x (Markup y x)

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

-- | The <a>erroneous</a> consumer reports an error if any input reaches
--   it.
erroneous :: (Monad m) => String -> ConsumerComponent m x ()

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

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

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

-- | Converts each input value <tt>x</tt> to <tt>show x</tt>.
toString :: (Monad m, Show x) => TransducerComponent m x String

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

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

-- | Same as <a>concatenate</a> except it inserts the given separator list
--   between every two input lists.
concatSeparate :: (Monad m) => [x] -> TransducerComponent m [x] x

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

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

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

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

-- | SplitterComponent <a>everything</a> feeds its entire input into its
--   <i>true</i> sink.
everything :: (Monad m) => SplitterComponent m x ()

-- | SplitterComponent <a>nothing</a> feeds its entire input into its
--   <i>false</i> sink.
nothing :: (Monad m) => SplitterComponent m x ()

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

-- | SplitterComponent <a>marked</a> passes all marked-up input sections to
--   its <i>true</i> sink, and all unmarked input to its <i>false</i> sink.
marked :: (Monad m, Eq y) => SplitterComponent m (Markup y x) ()

-- | SplitterComponent <a>markedContent</a> passes the content of all
--   marked-up input sections to its <i>true</i> sink, while the outermost
--   tags and all unmarked input go to its <i>false</i> sink.
markedContent :: (Monad m, Eq y) => SplitterComponent m (Markup y x) ()

-- | SplitterComponent <a>markedWith</a> passes input sections marked-up
--   with the appropriate tag to its <i>true</i> sink, and the rest of the
--   input to its <i>false</i> sink. The argument <i>select</i> determines
--   if the tag is appropriate.
markedWith :: (Monad m, Eq y) => (y -> Bool) -> SplitterComponent m (Markup y x) ()

-- | SplitterComponent <a>contentMarkedWith</a> passes the content of input
--   sections marked-up with the appropriate tag to its <i>true</i> sink,
--   and the rest of the input to its <i>false</i> sink. The argument
--   <i>select</i> determines if the tag is appropriate.
contentMarkedWith :: (Monad m, Eq y) => (y -> Bool) -> SplitterComponent m (Markup y x) ()

-- | Performs the same task as the <a>substring</a> splitter, but instead
--   of splitting it outputs the input as <tt><a>Markup</a> x
--   <a>OccurenceTag</a></tt> in order to distinguish overlapping strings.
parseSubstring :: (Monad m, Eq x) => [x] -> ParserComponent m x OccurenceTag

-- | SplitterComponent <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, both are sent
--   to <i>true</i> and each is preceded by an edge.
substring :: (Monad m, Eq x) => [x] -> SplitterComponent m x ()

-- | Converts a <a>ConsumerComponent</a> into a <a>TransducerComponent</a>
--   with no output.
consumeBy :: (Monad m) => ConsumerComponent m x r -> TransducerComponent m x y

-- | Class PipeableComponentPair applies to any two components that can be
--   combined into a third component with the following properties:
--   
--   <ul>
--   <li>The input of the result, if any, becomes the input of the first
--   component.</li>
--   <li>The output produced by the first child component is consumed by
--   the second child component.</li>
--   <li>The result output, if any, is the output of the second
--   component.</li>
--   </ul>
(>->) :: (PipeableComponentPair m w c1 c2 c3) => Component c1 -> Component c2 -> Component c3
class CompatibleSignature c cons m :: (* -> *) input output | c -> cons m
class AnyListOrUnit c
data PerformerType r
data ConsumerType r
data ProducerType r
data TransducerType

-- | Class JoinableComponentPair applies to any two components that can be
--   combined into a third component with the following properties:
--   
--   <ul>
--   <li>if both argument components consume input, the input of the
--   combined component gets distributed to both components in
--   parallel,</li>
--   <li>if both argument components produce output, the output of the
--   combined component is a concatenation of the complete output from the
--   first component followed by the complete output of the second
--   component, and</li>
--   <li>the <a>join</a> method may apply the components in any order, the
--   <a>sequence</a> method makes sure its first argument has completed
--   before using the second one.</li>
--   </ul>
join :: (JoinableComponentPair t1 t2 t3 m x y c1 c2 c3) => Component c1 -> Component c2 -> Component c3
sequence :: (JoinableComponentPair t1 t2 t3 m x y c1 c2 c3) => Component c1 -> Component c2 -> Component c3

-- | Combinator <a>prepend</a> converts the given producer to transducer
--   that passes all its input through unmodified, except | for prepending
--   the output of the argument producer to it. | <a>prepend</a>
--   <i>prefix</i> = <a>join</a> (<a>substitute</a> <i>prefix</i>)
--   <a>asis</a>
prepend :: (Monad m) => ProducerComponent m x r -> TransducerComponent m x x

-- | Combinator <a>append</a> converts the given producer to transducer
--   that passes all its input through unmodified, finally | appending to
--   it the output of the argument producer. | <a>append</a> <i>suffix</i>
--   = <a>join</a> <a>asis</a> (<a>substitute</a> <i>suffix</i>)
append :: (Monad m) => ProducerComponent m x r -> TransducerComponent m x x

-- | The <a>substitute</a> combinator converts its argument producer to a
--   transducer that produces the same output, while | consuming its entire
--   input and ignoring it.
substitute :: (Monad m) => ProducerComponent m y r -> TransducerComponent 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) => SplitterComponent m x b -> SplitterComponent m x b

-- | 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.
(>&) :: (ParallelizableMonad m) => SplitterComponent m x b1 -> SplitterComponent m x b2 -> SplitterComponent m x (b1, b2)

-- | 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.
(>|) :: (ParallelizableMonad m) => SplitterComponent m x b1 -> SplitterComponent m x b2 -> SplitterComponent m x (Either b1 b2)

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

-- | Combinator <a>||</a> is a pairwise logical disjunction of two
--   splitters run in parallel on the same input.
(||) :: (ParallelizableMonad m) => SplitterComponent m x b1 -> SplitterComponent m x b2 -> SplitterComponent m x (Either b1 b2)
ifs :: (ParallelizableMonad m, Branching c m x [x]) => SplitterComponent m x b -> Component c -> Component c -> Component c
wherever :: (ParallelizableMonad m) => TransducerComponent m x x -> SplitterComponent m x b -> TransducerComponent m x x
unless :: (ParallelizableMonad m) => TransducerComponent m x x -> SplitterComponent m x b -> TransducerComponent m x x
select :: (Monad m) => SplitterComponent m x b -> TransducerComponent m x x

-- | Converts a splitter into a parser.
parseRegions :: (Monad m) => SplitterComponent m x b -> ParserComponent m x b

-- | Converts a boundary-marking splitter into a parser.
parseNestedRegions :: (ParallelizableMonad m) => SplitterComponent m x (Boundary b) -> ParserComponent m x b

-- | 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 :: (ParallelizableMonad m) => TransducerComponent m x x -> SplitterComponent m x b -> TransducerComponent 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, an input value would either
--   not loop at all or it would loop forever.
nestedIn :: (ParallelizableMonad m) => SplitterComponent m x b -> SplitterComponent m x b -> SplitterComponent m x b

-- | 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 :: (ParallelizableMonad m, Branching c m x [x]) => SplitterComponent m x b -> Component c -> Component c -> Component c

-- | 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 :: (ParallelizableMonad m) => SplitterComponent m x b1 -> SplitterComponent m x b2 -> SplitterComponent m x b1

-- | 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 :: (ParallelizableMonad m) => SplitterComponent m x b1 -> SplitterComponent m x b2 -> SplitterComponent m x b1

-- | 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) => SplitterComponent m x b -> SplitterComponent m x b

-- | 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>first</a> and <a>uptoFirst</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) => SplitterComponent m x b -> SplitterComponent m x b

-- | 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) => SplitterComponent m x b -> SplitterComponent m x b

-- | 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) => SplitterComponent m x b -> SplitterComponent m x b

-- | 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) => SplitterComponent m x b -> SplitterComponent m x b

-- | 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) => SplitterComponent m x b -> SplitterComponent m x b

-- | The <a>even</a> combinator takes every input section that its argument
--   <i>splitter</i> 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) => SplitterComponent m x b -> SplitterComponent m x b

-- | SplitterComponent <a>startOf</a> issues an empty <i>true</i> section
--   at the beginning of every section considered <i>true</i> by its
--   argument splitter, otherwise the entire input goes into its
--   <i>false</i> sink.
startOf :: (Monad m) => SplitterComponent m x b -> SplitterComponent m x (Maybe b)

-- | SplitterComponent <a>endOf</a> issues an empty <i>true</i> section at
--   the end of every section considered <i>true</i> by its argument
--   splitter, otherwise the entire input goes into its <i>false</i> sink.
endOf :: (ParallelizableMonad m) => SplitterComponent m x b -> SplitterComponent m x (Maybe b)

-- | Combinator <a>followedBy</a> treats its argument
--   <a>SplitterComponent</a>s as patterns components and returns a
--   <a>SplitterComponent</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 :: (ParallelizableMonad m) => SplitterComponent m x b1 -> SplitterComponent m x b2 -> SplitterComponent m x (b1, b2)

-- | Combinator <a>...</a> tracks the running balance of difference between
--   the number of preceding starts of sections considered <i>true</i>
--   according to its first argument and the ones according to its second
--   argument. The combinator passes to <i>true</i> all input values for
--   which the difference balance is positive. This combinator is typically
--   used with <a>startOf</a> and <a>endOf</a> in order to count entire
--   input sections and ignore their lengths.
(...) :: (ParallelizableMonad m) => SplitterComponent m x b1 -> SplitterComponent m x b2 -> SplitterComponent m x b1
xmlTokens :: (Monad m) => SplitterComponent m Char (Boundary Token)
xmlParseTokens :: (Monad m) => ParserComponent m Char Token
xmlElement :: (Monad m) => SplitterComponent m (Markup Token Char) ()
xmlElementContent :: (Monad m) => SplitterComponent m (Markup Token Char) ()

-- | Similiar to <tt>(Control.Concurrent.SCC.Combinators.having
--   element)</tt>, except it runs the argument splitter only on each
--   element's start tag, not on the entire element with its content.
xmlElementHavingTag :: (ParallelizableMonad m) => SplitterComponent m (Markup Token Char) b -> SplitterComponent m (Markup Token Char) b

-- | Splits every attribute specification to <i>true</i>, everything else
--   to <i>false</i>.
xmlAttribute :: (Monad m) => SplitterComponent m (Markup Token Char) ()

-- | Splits every element name, including the names of nested elements and
--   names in end tags, to <i>true</i>, all the rest of input to
--   <i>false</i>.
xmlElementName :: (Monad m) => SplitterComponent m (Markup Token Char) ()

-- | Splits every attribute name to <i>true</i>, all the rest of input to
--   <i>false</i>.
xmlAttributeName :: (Monad m) => SplitterComponent m (Markup Token Char) ()

-- | Splits every attribute value, excluding the quote delimiters, to
--   <i>true</i>, all the rest of input to <i>false</i>.
xmlAttributeValue :: (Monad m) => SplitterComponent m (Markup Token Char) ()
xmlHavingText :: (ParallelizableMonad m) => SplitterComponent m (Markup Token Char) b1 -> SplitterComponent m Char b2 -> SplitterComponent m (Markup Token Char) b1
xmlHavingOnlyText :: (ParallelizableMonad m) => SplitterComponent m (Markup Token Char) b1 -> SplitterComponent m Char b2 -> SplitterComponent m (Markup Token Char) b1
instance CompatibleSignature (Transducer m x y) TransducerType m [x] [y]
instance (AnyListOrUnit y) => CompatibleSignature (Producer m x r) (ProducerType r) m y [x]
instance (AnyListOrUnit y) => CompatibleSignature (Consumer m x r) (ConsumerType r) m [x] y
instance (AnyListOrUnit x, AnyListOrUnit y) => CompatibleSignature (Performer m r) (PerformerType r) m x y
instance AnyListOrUnit ()
instance AnyListOrUnit [x]