{- 
    Copyright 2010 Mario Blazevic

    This file is part of the Streaming Component Combinators (SCC) project.

    The SCC project is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
    License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later
    version.

    SCC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
    of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along with SCC.  If not, see
    <http://www.gnu.org/licenses/>.
-}

{-# LANGUAGE Rank2Types, FlexibleContexts #-}
{-# OPTIONS_HADDOCK hide #-}

-- | This module exports sequential versions of the combinators from the "Control.Concurrent.SCC.Combinators" module.

module Control.Concurrent.SCC.Combinators.Sequential (
   -- * Consumer, producer, and transducer combinators
   Combinators.consumeBy, Combinators.prepend, Combinators.append, Combinators.substitute,
   PipeableComponentPair, (>->), Combinators.JoinableComponentPair (Combinators.sequence), join,
   -- * Splitter combinators
   Combinators.sNot,
   -- ** Pseudo-logic flow combinators
   -- | Combinators '>&' and '>|' are only /pseudo/-logic. While the laws of double negation and De Morgan's laws
   -- hold, 'sAnd' and 'sOr' are in general not commutative, associative, nor idempotent. In the special case when all
   -- argument splitters are stateless, such as those produced by 'Control.Concurrent.SCC.Types.statelessSplitter',
   -- these combinators do satisfy all laws of Boolean algebra.
   (>&), (>|),
   -- ** Zipping logic combinators
   -- | The '&&' and '||' combinators run the argument splitters in parallel and combine their logical outputs using
   -- the corresponding logical operation on each output pair, in a manner similar to 'Data.List.zipWith'. They fully
   -- satisfy the laws of Boolean algebra.
   (&&), (||),
   -- * Flow-control combinators
   -- | The following combinators resemble the common flow-control programming language constructs. Combinators 
   -- 'wherever', 'unless', and 'select' are just the special cases of the combinator 'ifs'.
   --
   --    * /transducer/ ``wherever`` /splitter/ = 'ifs' /splitter/ /transducer/ 'Control.Category.id'
   --
   --    * /transducer/ ``unless`` /splitter/ = 'ifs' /splitter/ 'Control.Category.id' /transducer/
   --
   --    * 'select' /splitter/ = 'ifs' /splitter/ 'Control.Category.id'
   --    'Control.Concurrent.SCC.Primitives.suppress'
   --
   ifs, wherever, unless, Combinators.select,
   -- ** Recursive
   while, nestedIn,
   -- * Section-based combinators
   -- | All combinators in this section use their 'Control.Concurrent.SCC.Splitter' argument to determine the structure
   -- of the input. Every contiguous portion of the input that gets passed to one or the other sink of the splitter is
   -- treated as one section in the logical structure of the input stream. What is done with the section depends on the
   -- combinator, but the sections, and therefore the logical structure of the input stream, are determined by the
   -- argument splitter alone.
   foreach, having, havingOnly, followedBy, Combinators.even,
   -- ** first and its variants
   Combinators.first, Combinators.uptoFirst, Combinators.prefix,
   -- ** last and its variants
   Combinators.last, Combinators.lastAndAfter, Combinators.suffix,
   -- ** positional splitters
   Combinators.startOf, Combinators.endOf, (...),
   -- * Parser support
   Combinators.splitterToMarker, Combinators.parseRegions,
   )
where

import Prelude hiding ((&&), (||), even, last, sequence)
import Data.Monoid (Monoid)
import Data.Text (Text)

import Control.Monad.Coroutine (sequentialBinder)
import Data.Monoid.Null (MonoidNull)
import Data.Monoid.Factorial (FactorialMonoid)

import Control.Concurrent.SCC.Types
import Control.Concurrent.SCC.Coercions (Coercible)
import qualified Control.Concurrent.SCC.Combinators as Combinators
import qualified Control.Concurrent.SCC.XML as XML

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

-- | The 'join' combinator may apply the components in any order.
join :: (Monad m, Combinators.JoinableComponentPair t1 t2 t3 m x y c1 c2 c3) => c1 -> c2 -> c3
join = Combinators.join sequentialBinder

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

-- | A '>|' combinator's input value can reach its /false/ sink only by going through both argument splitters' /false/
-- sinks.
(>|) :: (Monad m, Monoid x) => Splitter m x -> Splitter m x -> Splitter m x 
(>|) =  Combinators.sOr sequentialBinder

-- | Combinator '&&' is a pairwise logical conjunction of two splitters run in parallel on the same input.
(&&) :: (Monad m, FactorialMonoid x) => Splitter m x -> Splitter m x -> Splitter m x
(&&) = Combinators.pAnd sequentialBinder

-- | Combinator '||' is a pairwise logical disjunction of two splitters run in parallel on the same input.
(||) :: (Monad m, FactorialMonoid x) => Splitter m x -> Splitter m x -> Splitter m x
(||) = Combinators.pOr sequentialBinder

ifs :: (Monad m, Monoid x, Branching c m x ()) => Splitter m x -> c -> c -> c
ifs = Combinators.ifs sequentialBinder

wherever :: (Monad m, Monoid x) => Transducer m x x -> Splitter m x -> Transducer m x x
wherever = Combinators.wherever sequentialBinder

unless :: (Monad m, Monoid x) => Transducer m x x -> Splitter m x -> Transducer m x x
unless = Combinators.unless sequentialBinder

-- | The recursive combinator 'while' 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, MonoidNull x) => Transducer m x x -> Splitter m x -> Transducer m x x
while t s = Combinators.while sequentialBinder t s (while t s)

-- | The recursive combinator 'nestedIn' 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 'nestedIn' 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 :: (Monad m, MonoidNull x) => Splitter m x -> Splitter m x -> Splitter m x
nestedIn s1 s2 = Combinators.nestedIn sequentialBinder s1 s2 (nestedIn s1 s2)

-- | The 'foreach' combinator is similar to the combinator 'ifs' 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, MonoidNull x, Branching c m x ()) => Splitter m x -> c -> c -> c
foreach = Combinators.foreach sequentialBinder

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

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

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

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