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


-- | Generalised reactive framework supporting classic, arrowized and monadic FRP.
--   
--   Dunai is a DSL for strongly-typed CPS-based composable
--   transformations.
--   
--   Dunai is based on a concept of Monadic Stream Functions (MSFs). MSFs
--   are transformations defined by a function <tt>unMSF :: MSF m a b -&gt;
--   a -&gt; m (b, MSF m a b)</tt> that executes one step of a simulation,
--   and produces an output in a monadic context, and a continuation to be
--   used for future steps.
--   
--   MSFs are a generalisation of the implementation mechanism used by
--   Yampa, Wormholes and other FRP and reactive implementations.
--   
--   When combined with different monads, they produce interesting effects.
--   For example, when combined with the <tt>Maybe</tt> monad, they become
--   transformations that may stop producing outputs (and continuations).
--   The <tt>Either</tt> monad gives rise to MSFs that end with a result
--   (akin to Tasks in Yampa, and Monadic FRP).
--   
--   Flattening, that is, going from some structure <tt>MSF (t m) a b</tt>
--   to <tt>MSF m a b</tt> for a specific transformer <tt>t</tt> often
--   gives rise to known FRP constructs. For instance, flattening with
--   <tt>EitherT</tt> gives rise to switching, and flattening with
--   <tt>ListT</tt> gives rise to parallelism with broadcasting.
--   
--   MSFs can be used to implement many FRP variants, including Arrowized
--   FRP, Classic FRP, and plain reactive programming. Arrowized and
--   applicative syntax are both supported.
--   
--   For a very detailed introduction to MSFs, see:
--   <a>http://dl.acm.org/citation.cfm?id=2976010</a> (mirror:
--   <a>http://www.cs.nott.ac.uk/~psxip1/#FRPRefactored</a>).
@package dunai
@version 0.4.0.0


-- | Monadic Stream Functions are synchronized stream functions with side
--   effects.
--   
--   MSFs are defined by a function <tt>unMSF :: MSF m a b -&gt; a -&gt; m
--   (b, MSF m a b)</tt> that executes one step of a simulation, and
--   produces an output in a monadic context, and a continuation to be used
--   for future steps.
--   
--   MSFs are a generalisation of the implementation mechanism used by
--   Yampa, Wormholes and other FRP and reactive implementations.
--   
--   When combined with different monads, they produce interesting effects.
--   For example, when combined with the <tt>Maybe</tt> monad, they become
--   transformations that may stop producing outputs (and continuations).
--   The <tt>Either</tt> monad gives rise to MSFs that end with a result
--   (akin to Tasks in Yampa, and Monadic FRP).
--   
--   Flattening, that is, going from some structure <tt>MSF (t m) a b</tt>
--   to <tt>MSF m a b</tt> for a specific transformer <tt>t</tt> often
--   gives rise to known FRP constructs. For instance, flattening with
--   <tt>EitherT</tt> gives rise to switching, and flattening with
--   <tt>ListT</tt> gives rise to parallelism with broadcasting.
--   
--   MSFs can be used to implement many FRP variants, including Arrowized
--   FRP, Classic FRP, and plain reactive programming. Arrowized and
--   applicative syntax are both supported.
--   
--   For a very detailed introduction to MSFs, see:
--   <a>http://dl.acm.org/citation.cfm?id=2976010</a> (mirror:
--   <a>http://www.cs.nott.ac.uk/~psxip1/#FRPRefactored</a>).
module Data.MonadicStreamFunction.Core

-- | Stepwise, side-effectful MSFs without implicit knowledge of time.
--   
--   MSFs should be applied to streams or executed indefinitely or until
--   they terminate. See <a>reactimate</a> and <tt>reactimateB</tt> for
--   details. In general, calling the value constructor <a>MSF</a> or the
--   function <a>unMSF</a> is discouraged.
data MSF m a b
MSF :: a -> m (b, MSF m a b) -> MSF m a b
[unMSF] :: MSF m a b -> a -> m (b, MSF m a b)

-- | Apply a monadic transformation to every element of the input stream.
--   
--   Generalisation of <a>arr</a> from <a>Arrow</a> to monadic functions.
arrM :: Monad m => (a -> m b) -> MSF m a b

-- | Monadic lifting from one monad into another
liftS :: (Monad m2, MonadBase m1 m2) => (a -> m1 b) -> MSF m2 a b

-- | Lift inner monadic actions in monad stacks.
liftMSFTrans :: (MonadTrans t, Monad m, Monad (t m)) => MSF m a b -> MSF (t m) a b

-- | Lift innermost monadic actions in a monad stacks (generalisation of
--   <tt>liftIO</tt>).
liftMSFBase :: (Monad m2, MonadBase m1 m2) => MSF m1 a b -> MSF m2 a b

-- | Lifting purer monadic actions (in an arbitrary way)
liftMSFPurer :: (Monad m2, Monad m1) => (forall c. m1 c -> m2 c) -> MSF m1 a b -> MSF m2 a b

-- | Delay a signal by one sample.
iPre :: Monad m => a -> MSF m a a

-- | See <a>iPre</a>.
delay :: Monad m => a -> MSF m a a

-- | Switching applies one MSF until it produces a <a>Just</a> output, and
--   then "turns on" a continuation and runs it.
--   
--   A more advanced and comfortable approach to switching is given by
--   Exceptions in <a>Except</a>
switch :: Monad m => MSF m a (b, Maybe c) -> (c -> MSF m a b) -> MSF m a b

-- | Well-formed looped connection of an output component as a future
--   input.
feedback :: Monad m => c -> MSF m (a, c) (b, c) -> MSF m a b

-- | Apply a monadic stream function to a list.
--   
--   Because the result is in a monad, it may be necessary to traverse the
--   whole list to evaluate the value in the results to WHNF. For example,
--   if the monad is the maybe monad, this may not produce anything if the
--   MSF produces Nothing at any point, so the output stream cannot
--   consumed progressively.
--   
--   To explore the output progressively, use <tt>liftMSF</tt> and
--   '(&gt;&gt;&gt;)'', together with some action that consumes/actuates on
--   the output.
--   
--   This is called <tt>runSF</tt> in Liu, Cheng, Hudak, "Causal
--   Commutative Arrows and Their Optimization"
embed :: Monad m => MSF m a b -> [a] -> m [b]

-- | Run an <a>MSF</a> indefinitely passing a unit-carrying input stream.
reactimate :: Monad m => MSF m () () -> m ()
instance GHC.Base.Monad m => Control.Category.Category (Data.MonadicStreamFunction.Core.MSF m)
instance GHC.Base.Monad m => Control.Arrow.Arrow (Data.MonadicStreamFunction.Core.MSF m)
instance GHC.Base.Functor m => GHC.Base.Functor (Data.MonadicStreamFunction.Core.MSF m a)
instance (GHC.Base.Functor m, GHC.Base.Monad m) => GHC.Base.Applicative (Data.MonadicStreamFunction.Core.MSF m a)


-- | Instance of <a>ArrowChoice</a> for Monadic Stream Functions
--   (<a>MSF</a>).
--   
--   Import this module to include that (orphan) instance.
module Data.MonadicStreamFunction.Instances.ArrowChoice
instance GHC.Base.Monad m => Control.Arrow.ArrowChoice (Data.MonadicStreamFunction.Core.MSF m)


-- | Instance of <a>ArrowLoop</a> for Monadic Stream Functions
--   (<a>MSF</a>).
--   
--   Import this module to include that (orphan) instance.
--   
--   This is only defined for monads that are instances of <a>MonadFix</a>.
module Data.MonadicStreamFunction.Instances.ArrowLoop
instance (GHC.Base.Monad m, Control.Monad.Fix.MonadFix m) => Control.Arrow.ArrowLoop (Data.MonadicStreamFunction.Core.MSF m)


-- | Instance of <a>ArrowPlus</a> for Monadic Stream Functions
--   (<a>MSF</a>).
--   
--   Import this module to include that (orphan) instance.
--   
--   This is only defined for monads that are instances of
--   <a>MonadPlus</a>.
module Data.MonadicStreamFunction.Instances.ArrowPlus
instance (GHC.Base.Monad m, GHC.Base.MonadPlus m) => Control.Arrow.ArrowZero (Data.MonadicStreamFunction.Core.MSF m)
instance (GHC.Base.Monad m, GHC.Base.MonadPlus m) => Control.Arrow.ArrowPlus (Data.MonadicStreamFunction.Core.MSF m)


-- | Number instances for MSFs that produce numbers. This allows you to use
--   numeric operators with MSFs that output numbers, for example, you can
--   write:
--   
--   <pre>
--   msf1 :: MSF Input Double -- defined however you want
--   msf2 :: MSF Input Double -- defined however you want
--   msf3 :: MSF Input Double
--   msf3 = msf1 + msf2
--   </pre>
--   
--   instead of
--   
--   <pre>
--   msf3 = (msf1 &amp;&amp;&amp; msf2) &gt;&gt;&gt; arr (uncurry (+))
--   </pre>
--   
--   Instances are provided for the type classes <a>Num</a>,
--   <a>Fractional</a> and <a>Floating</a>.
module Data.MonadicStreamFunction.Instances.Num
instance (GHC.Base.Monad m, GHC.Num.Num b) => GHC.Num.Num (Data.MonadicStreamFunction.Core.MSF m a b)
instance (GHC.Base.Monad m, GHC.Real.Fractional b) => GHC.Real.Fractional (Data.MonadicStreamFunction.Core.MSF m a b)
instance (GHC.Base.Monad m, GHC.Float.Floating b) => GHC.Float.Floating (Data.MonadicStreamFunction.Core.MSF m a b)


-- | Vector space type relation and basic instances. Heavily inspired by
--   Yampa's <tt>FRP.Yampa.VectorSpace</tt> module.
module Data.VectorSpace

-- | R-modules. A module <tt>v</tt> over a ring <tt>Groundring v</tt> is an
--   abelian group with a linear multiplication. The hat <tt>^</tt> denotes
--   the side of an operation on which the vector stands, i.e. <tt>a *^
--   v</tt> for <tt>v</tt> a vector.
--   
--   A minimal definition should include the type <a>Groundring</a> and the
--   implementations of <a>zeroVector</a>, <a>^+^</a>, and one of <a>*^</a>
--   or <a>^*</a>.
--   
--   The following laws must be satisfied:
--   
--   <ul>
--   <li><pre>v1 ^+^ v2 == v2 ^+^ v1</pre></li>
--   <li><pre>a *^ zeroVector == zeroVector</pre></li>
--   <li>@a *^ (v1 ^+^ v2) == a *^ v1 ^+^ a*^ v2</li>
--   <li><pre>a *^ v == v ^* a</pre></li>
--   <li><pre>negateVector v == (-1) *^ v</pre></li>
--   <li><pre>v1 ^-^ v2 == v1 ^+^ negateVector v2</pre></li>
--   </ul>
class Num (Groundring v) => RModule v where {
    type family Groundring v;
}
zeroVector :: RModule v => v
(*^) :: RModule v => Groundring v -> v -> v
(^*) :: RModule v => v -> Groundring v -> v
negateVector :: RModule v => v -> v
(^+^) :: RModule v => v -> v -> v
(^-^) :: RModule v => v -> v -> v

-- | A vector space is a module over a field, i.e. a commutative ring with
--   inverses.
--   
--   It needs to satisfy the axiom <tt>v ^<i> a == (1</i>a) *^ v</tt>,
--   which is the default implementation.
class (Fractional (Groundring v), RModule v) => VectorSpace v
(^/) :: VectorSpace v => v -> Groundfield v -> v

-- | The ground ring of a vector space is required to be commutative and to
--   possess inverses. It is then called the "ground field". Commutativity
--   amounts to the law <tt>a * b = b * a</tt>, and the existence of
--   inverses is given by the requirement of the <a>Fractional</a> type
--   class.

-- | An inner product space is a module with an inner product, i.e. a map
--   <tt>dot</tt> satisfying
--   
--   <ul>
--   <li><pre>v1 <a>dot</a> v2 == v2 <a>dot</a> v1</pre></li>
--   <li><pre>(v1 ^+^ v2) <a>dot</a> v3 == v1 <a>dot</a> v3 ^+^ v2
--   <a>dot</a> v3</pre></li>
--   <li><pre>(a *^ v1) <a>dot</a> v2 == a *^ v1 <a>dot</a> v2</pre></li>
--   </ul>
class RModule v => InnerProductSpace v
dot :: InnerProductSpace v => v -> v -> Groundfield v

-- | A normed space is a module with a norm, i.e. a function <tt>norm</tt>
--   satisfying
--   
--   <ul>
--   <li><pre>norm (a ^* v) = a ^* norm v</pre></li>
--   <li><tt>norm (v1 ^+^ v2) &lt;= norm v1 ^+^ norm v2</tt> (the "triangle
--   inequality")</li>
--   </ul>
--   
--   A typical example is <tt>sqrt (v <a>dot</a> v)</tt>, for an inner
--   product space.
class RModule v => NormedSpace v
norm :: NormedSpace v => v -> Groundfield v


-- | Useful auxiliary functions and definitions.
module Data.MonadicStreamFunction.Util

-- | A stream is an MSF that produces outputs ignoring the input. It can
--   obtain the values from a monadic context.
type MStream m a = MSF m () a

-- | A stream is an MSF that produces outputs producing no output. It can
--   consume the values with side effects.
type MSink m a = MSF m a ()

-- | Pre-inserts an input sample.

-- | <i>Deprecated: Don't use this. arrM id instead</i>
insert :: Monad m => MSF m (m a) a

-- | Lifts a computation into a Stream.
arrM_ :: Monad m => m b -> MSF m a b

-- | Lift the first MSF into the monad of the second.
(^>>>) :: MonadBase m1 m2 => MSF m1 a b -> MSF m2 b c -> MSF m2 a c

-- | Lift the second MSF into the monad of the first.
(>>>^) :: MonadBase m1 m2 => MSF m2 a b -> MSF m1 b c -> MSF m2 a c

-- | Apply an MSF to every input.
mapMSF :: Monad m => MSF m a b -> MSF m [a] [b]

-- | Apply an MSF to every input. Freezes temporarily if the input is
--   <a>Nothing</a>, and continues as soon as a <a>Just</a> is received.
mapMaybeS :: Monad m => MSF m a b -> MSF m (Maybe a) (Maybe b)

-- | Applies a function to produce an additional side effect and passes the
--   input unchanged.
withSideEffect :: Monad m => (a -> m b) -> MSF m a a

-- | Produces an additional side effect and passes the input unchanged.
withSideEffect_ :: Monad m => m b -> MSF m a a

-- | Preprends a fixed output to an MSF. The first input is completely
--   ignored.
iPost :: Monad m => b -> MSF m a b -> MSF m a b

-- | Preprends a fixed output to an MSF, shifting the output.
next :: Monad m => b -> MSF m a b -> MSF m a b

-- | Buffers and returns the elements in FIFO order, returning
--   <a>Nothing</a> whenever the buffer is empty.
fifo :: Monad m => MSF m [a] (Maybe a)

-- | Count the number of simulation steps. Produces 1, 2, 3,...
count :: (Num n, Monad m) => MSF m a n

-- | Sums the inputs, starting from zero.
sumS :: (RModule v, Monad m) => MSF m v v

-- | Sums the inputs, starting from an initial vector.
sumFrom :: (RModule v, Monad m) => v -> MSF m v v

-- | Accumulate the inputs, starting from <a>mempty</a>.
mappendS :: (Monoid n, Monad m) => MSF m n n

-- | Accumulate the inputs, starting from an initial monoid value.
mappendFrom :: (Monoid n, Monad m) => n -> MSF m n n

-- | Applies a function to the input and an accumulator, outputing the
--   accumulator. Equal to <tt>f s0 -&gt; feedback s0 $ arr (uncurry f
--   &gt;&gt;&gt; dup)</tt>.
accumulateWith :: Monad m => (a -> s -> s) -> s -> MSF m a s

-- | Generate outputs using a step-wise generation function and an initial
--   value.
unfold :: Monad m => (a -> (b, a)) -> a -> MSF m () b

-- | Generate outputs using a step-wise generation function and an initial
--   value. Version of <a>unfold</a> in which the output and the new
--   accumulator are the same. Should be equal to <tt>f a -&gt; unfold (f
--   &gt;&gt;&gt; dup) a</tt>.
repeatedly :: Monad m => (a -> a) -> a -> MSF m () a

-- | Outputs every input sample, with a given message prefix.
trace :: Show a => String -> MSF IO a a

-- | Outputs every input sample, with a given message prefix, using an
--   auxiliary printing function.
traceWith :: (Monad m, Show a) => (String -> m ()) -> String -> MSF m a a

-- | Outputs every input sample, with a given message prefix, using an
--   auxiliary printing function, when a condition is met.
traceWhen :: (Monad m, Show a) => (a -> Bool) -> (String -> m ()) -> String -> MSF m a a

-- | Outputs every input sample, with a given message prefix, when a
--   condition is met, and waits for some input / enter to continue.
pauseOn :: Show a => (a -> Bool) -> String -> MSF IO a a


-- | This module contains operations on monadic streams that are
--   asynchronous, i.e. that change the speed at which data enters or
--   leaves the <a>MSF</a>.
module Data.MonadicStreamFunction.Async

-- | Concatenates a monadic stream of lists to a monadic stream. The stream
--   of lists will be called exactly when new data is needed.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; let intstream = arrM_ $ putStrLn "Enter a list of Ints:" &gt;&gt; readLn :: MStream IO [Int]
--   
--   &gt;&gt;&gt; reactimate $ concatS intstream &gt;&gt;&gt; arrM print
--   Enter a list of Ints:
--   [1,2,33]
--   1
--   2
--   33
--   Enter a list of Ints:
--   []
--   Enter a list of Ints:
--   []
--   Enter a list of Ints:
--   [1,2]
--   1
--   2
--   Enter a list of Ints:
--   ...
--   </pre>
--   
--   Beware that <tt>concatS msf</tt> becomes unproductive when
--   <tt>msf</tt> starts outputting empty lists forever. This is ok:
--   
--   <pre>
--   &gt;&gt;&gt; let boolToList b = if b then ["Yes"] else []
--   
--   &gt;&gt;&gt; let everyOddEmpty = count &gt;&gt;&gt; arr (even &gt;&gt;&gt; boolToList)
--   
--   &gt;&gt;&gt; reactimate $ concatS everyOddEmpty &gt;&gt;&gt; arrM print
--   "Yes"
--   "Yes"
--   "Yes"
--   "Yes"
--   "Yes"
--   ...
--   </pre>
--   
--   But this will be caught in a loop:
--   
--   <pre>
--   &gt;&gt;&gt; let after3Empty = count &gt;&gt;&gt; arr ((&lt;= 3) &gt;&gt;&gt; boolToList)
--   
--   &gt;&gt;&gt; reactimate $ concatS after3Empty  &gt;&gt;&gt; arrM print
--   "Yes"
--   "Yes"
--   "Yes"
--   ^CInterrupted.
--   </pre>
concatS :: Monad m => MStream m [b] -> MStream m b


-- | Monadic Stream Functions are synchronized stream functions with side
--   effects.
--   
--   MSFs are defined by a function <tt>unMSF :: MSF m a b -&gt; a -&gt; m
--   (b, MSF m a b)</tt> that executes one step of a simulation, and
--   produces an output in a monadic context, and a continuation to be used
--   for future steps.
--   
--   See the module <a>Data.MonadicStreamFunction.Core</a> for details.
--   
--   MSFs are a generalisation of the implementation mechanism used by
--   Yampa, Wormholes and other FRP and reactive implementations.
--   
--   When combined with different monads, they produce interesting effects.
--   For example, when combined with the <tt>Maybe</tt> monad, they become
--   transformations that may stop producing outputs (and continuations).
--   The <tt>Either</tt> monad gives rise to MSFs that end with a result
--   (akin to Tasks in Yampa, and Monadic FRP).
--   
--   Flattening, that is, going from some structure <tt>MSF (t m) a b</tt>
--   to <tt>MSF m a b</tt> for a specific transformer <tt>t</tt> often
--   gives rise to known FRP constructs. For instance, flattening with
--   <tt>EitherT</tt> gives rise to switching, and flattening with
--   <tt>ListT</tt> gives rise to parallelism with broadcasting.
--   
--   MSFs can be used to implement many FRP variants, including Arrowized
--   FRP, Classic FRP, and plain reactive programming. Arrowized and
--   applicative syntax are both supported.
--   
--   For a very detailed introduction to MSFs, see:
--   <a>http://dl.acm.org/citation.cfm?id=2976010</a> (mirror:
--   <a>http://www.cs.nott.ac.uk/~psxip1/#FRPRefactored</a>).
--   
--   Apart from the modules exported, this module exports instances from:
--   
--   <ul>
--   <li><a>Data.MonadicStreamFunction.Instances.ArrowChoice</a></li>
--   <li><a>Data.MonadicStreamFunction.Instances.ArrowLoop</a></li>
--   <li><a>Data.MonadicStreamFunction.Instances.ArrowPlus</a></li>
--   </ul>
module Data.MonadicStreamFunction


-- | ReactHandle
module Data.MonadicStreamFunction.ReactHandle

-- | A storage for the current state of an MSF
type ReactHandle m = IORef (MSF m () ())

-- | Needs to be called before the external main loop is dispatched
reactInit :: MonadIO m => MSF m () () -> m (ReactHandle m)

-- | The callback that needs to be called by the main loop at every cycle
react :: MonadIO m => ReactHandle m -> m ()

-- | Creates two ends of a synchronisation wormhole
createWormhole :: MonadIO m => a -> m (MSF m a (), MSF m () a)


-- | Versions of arrow combinators that run things in parallel using
--   <a>par</a>, if possible.
module Data.MonadicStreamFunction.Parallel

-- | Run two MSFs in parallel, taking advantage of parallelism if possible.
--   This is the parallel version of '(***)'.
(*|*) :: Monad m => MSF m a b -> MSF m c d -> MSF m (a, c) (b, d)

-- | Parallel version of '(&amp;&amp;&amp;)'.
(&|&) :: Monad m => MSF m a b -> MSF m a c -> MSF m a (b, c)

module Control.Monad.Trans.MSF.Random

-- | Updates the generator every step
runRandS :: (RandomGen g, Monad m) => MSF (RandT g m) a b -> g -> MSF m a (g, b)

-- | Updates the generator every step but discharges the generator
evalRandS :: (RandomGen g, Monad m) => MSF (RandT g m) a b -> g -> MSF m a b
getRandomS :: (MonadRandom m, Random b) => MSF m a b
getRandomsS :: (MonadRandom m, Random b) => MSF m a [b]
getRandomRS :: (MonadRandom m, Random b) => (b, b) -> MSF m a b
getRandomRS_ :: (MonadRandom m, Random b) => MSF m (b, b) b
getRandomsRS :: (MonadRandom m, Random b) => (b, b) -> MSF m a [b]
getRandomsRS_ :: (MonadRandom m, Random b) => MSF m (b, b) [b]


-- | More generic lifting combinators.
--   
--   This module contains more generic lifting combinators. It includes
--   several implementations, and obviously should be considered work in
--   progress. The goal is to make this both simple and conceptually
--   understandable.
module Control.Monad.Trans.MSF.GenLift

-- | Lifting combinator to move from one monad to another, if one has a
--   function to run computations in one monad into another. Note that,
--   unlike a polymorphic lifting function <tt>forall a . m a -&gt; m1
--   a</tt>, this auxiliary function needs to be a bit more structured.
lifterS :: (Monad m, Monad m1) => ((a1 -> m1 (b1, MSF m1 a1 b1)) -> a -> m (b, MSF m1 a1 b1)) -> MSF m1 a1 b1 -> MSF m a b

-- | Lifting combinator to move from one monad to another, if one has a
--   function to run computations in one monad into another. Note that,
--   unlike a polymorphic lifting function <tt>forall a . m a -&gt; m1
--   a</tt>, this auxiliary function needs to be a bit more structured,
--   although less structured than <a>lifterS</a>.
transS :: (Monad m1, Monad m2) => (a2 -> m1 a1) -> (forall c. a2 -> m1 (b1, c) -> m2 (b2, c)) -> MSF m1 a1 b1 -> MSF m2 a2 b2

-- | Lifting combinator to move from one monad to another, if one has a
--   function to run computations in one monad into another. Note that,
--   unlike a polymorphic lifting function <tt>forall a . m a -&gt; m1
--   a</tt>, this auxiliary function needs to be a bit more structured,
--   although less structured than <a>lifterS</a>.
transG1 :: (Monad m1, Functor m2, Monad m2) => (a2 -> m1 a1) -> (forall c. a2 -> m1 (b1, c) -> m2 (b2, c)) -> MSF m1 a1 b1 -> MSF m2 a2 b2

-- | More general lifting combinator that enables recovery. Note that,
--   unlike a polymorphic lifting function <tt>forall a . m a -&gt; m1
--   a</tt>, this auxiliary function needs to be a bit more structured, and
--   produces a Maybe value. The previous MSF is used if a new one is not
--   produced.
transG :: (Monad m1, Monad m2) => (a2 -> m1 a1) -> (forall c. a2 -> m1 (b1, c) -> m2 (b2, Maybe c)) -> MSF m1 a1 b1 -> MSF m2 a2 b2


-- | MSFs with a Writer monadic layer.
--   
--   This module contains functions to work with MSFs that include a
--   <a>Writer</a> monadic layer. This includes functions to create new
--   MSFs that include an additional layer, and functions to flatten that
--   layer out of the MSF's transformer stack.
module Control.Monad.Trans.MSF.Writer

-- | A writer monad parameterized by:
--   
--   <ul>
--   <li><tt>w</tt> - the output to accumulate.</li>
--   <li><tt>m</tt> - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function produces the output <a>mempty</a>, while
--   <tt>&gt;&gt;=</tt> combines the outputs of the subcomputations using
--   <a>mappend</a>.
newtype WriterT w (m :: * -> *) a
WriterT :: m (a, w) -> WriterT w a
[runWriterT] :: WriterT w a -> m (a, w)

-- | A writer monad parameterized by the type <tt>w</tt> of output to
--   accumulate.
--   
--   The <a>return</a> function produces the output <a>mempty</a>, while
--   <tt>&gt;&gt;=</tt> combines the outputs of the subcomputations using
--   <a>mappend</a>.
type Writer w = WriterT w Identity

-- | Unwrap a writer computation as a (result, output) pair. (The inverse
--   of <a>writer</a>.)
runWriter :: () => Writer w a -> (a, w)

-- | Extract the output from a writer computation.
--   
--   <ul>
--   <li><pre><a>execWriter</a> m = <a>snd</a> (<a>runWriter</a>
--   m)</pre></li>
--   </ul>
execWriter :: () => Writer w a -> w

-- | Map both the return value and output of a computation using the given
--   function.
--   
--   <ul>
--   <li><pre><a>runWriter</a> (<a>mapWriter</a> f m) = f (<a>runWriter</a>
--   m)</pre></li>
--   </ul>
mapWriter :: () => (a, w) -> (b, w') -> Writer w a -> Writer w' b

-- | Extract the output from a writer computation.
--   
--   <ul>
--   <li><pre><a>execWriterT</a> m = <a>liftM</a> <a>snd</a>
--   (<a>runWriterT</a> m)</pre></li>
--   </ul>
execWriterT :: Monad m => WriterT w m a -> m w

-- | Map both the return value and output of a computation using the given
--   function.
--   
--   <ul>
--   <li><pre><a>runWriterT</a> (<a>mapWriterT</a> f m) = f
--   (<a>runWriterT</a> m)</pre></li>
--   </ul>
mapWriterT :: () => m (a, w) -> n (b, w') -> WriterT w m a -> WriterT w' n b

-- | <tt><a>censor</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and applies the function <tt>f</tt> to its output, leaving
--   the return value unchanged.
--   
--   <ul>
--   <li><pre><a>censor</a> f m = <a>pass</a> (<a>liftM</a> (\ x -&gt;
--   (x,f)) m)</pre></li>
--   <li><pre><a>runWriterT</a> (<a>censor</a> f m) = <a>liftM</a> (\ (a,
--   w) -&gt; (a, f w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
censor :: Monad m => w -> w -> WriterT w m a -> WriterT w m a

-- | <tt><a>listens</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and adds the result of applying <tt>f</tt> to the output to
--   the value of the computation.
--   
--   <ul>
--   <li><pre><a>listens</a> f m = <a>liftM</a> (id *** f) (<a>listen</a>
--   m)</pre></li>
--   <li><pre><a>runWriterT</a> (<a>listens</a> f m) = <a>liftM</a> (\ (a,
--   w) -&gt; ((a, f w), w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
listens :: Monad m => w -> b -> WriterT w m a -> WriterT w m (a, b)

-- | <tt><a>listen</a> m</tt> is an action that executes the action
--   <tt>m</tt> and adds its output to the value of the computation.
--   
--   <ul>
--   <li><pre><a>runWriterT</a> (<a>listen</a> m) = <a>liftM</a> (\ (a, w)
--   -&gt; ((a, w), w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
listen :: Monad m => WriterT w m a -> WriterT w m (a, w)

-- | <tt><a>tell</a> w</tt> is an action that produces the output
--   <tt>w</tt>.
tell :: Monad m => w -> WriterT w m ()

-- | Construct a writer computation from a (result, output) pair. (The
--   inverse of <a>runWriter</a>.)
writer :: Monad m => (a, w) -> WriterT w m a

-- | Build an MSF in the <a>Writer</a> monad from one that produces the log
--   as an extra output. This is the opposite of <a>runWriterS</a>.
writerS :: (Monad m, Monoid s) => MSF m a (s, b) -> MSF (WriterT s m) a b

-- | Build an MSF that produces the log as an extra output from one on the
--   <a>Writer</a> monad. This is the opposite of <a>writerS</a>.
runWriterS :: Monad m => MSF (WriterT s m) a b -> MSF m a (s, b)

-- | Alternative implementation of <a>writerS</a> using <a>lifterS</a>.
writerS' :: (Monad m, Monoid s) => MSF m a (s, b) -> MSF (WriterT s m) a b

-- | Alternative implementation of <a>runWriterS</a> using <a>lifterS</a>.
runWriterS' :: (Monoid s, Functor m, Monad m) => MSF (WriterT s m) a b -> MSF m a (s, b)

-- | Alternative implementation of <a>writerS</a> using <a>transS</a>.
writerS'' :: (Monad m, Monoid w) => MSF m a (w, b) -> MSF (WriterT w m) a b

-- | Alternative implementation of <a>runWriterS</a> using <a>transS</a>.
runWriterS'' :: (Monoid s, Functor m, Monad m) => MSF (WriterT s m) a b -> MSF m a (s, b)


-- | MSFs with a State monadic layer.
--   
--   This module contains functions to work with MSFs that include a
--   <a>State</a> monadic layer. This includes functions to create new MSFs
--   that include an additional layer, and functions to flatten that layer
--   out of the MSF's transformer stack.
module Control.Monad.Trans.MSF.State

-- | A state transformer monad parameterized by:
--   
--   <ul>
--   <li><tt>s</tt> - The state.</li>
--   <li><tt>m</tt> - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
newtype StateT s (m :: * -> *) a
StateT :: s -> m (a, s) -> StateT s a
[runStateT] :: StateT s a -> s -> m (a, s)

-- | A state monad parameterized by the type <tt>s</tt> of the state to
--   carry.
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
type State s = StateT s Identity

-- | Unwrap a state monad computation as a function. (The inverse of
--   <a>state</a>.)
runState :: () => State s a -> s -> (a, s)

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalState</a> m s = <a>fst</a> (<a>runState</a> m
--   s)</pre></li>
--   </ul>
evalState :: () => State s a -> s -> a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execState</a> m s = <a>snd</a> (<a>runState</a> m
--   s)</pre></li>
--   </ul>
execState :: () => State s a -> s -> s

-- | Map both the return value and final state of a computation using the
--   given function.
--   
--   <ul>
--   <li><pre><a>runState</a> (<a>mapState</a> f m) = f . <a>runState</a>
--   m</pre></li>
--   </ul>
mapState :: () => (a, s) -> (b, s) -> State s a -> State s b

-- | <tt><a>withState</a> f m</tt> executes action <tt>m</tt> on a state
--   modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>withState</a> f m = <a>modify</a> f &gt;&gt; m</pre></li>
--   </ul>
withState :: () => s -> s -> State s a -> State s a

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalStateT</a> m s = <a>liftM</a> <a>fst</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
evalStateT :: Monad m => StateT s m a -> s -> m a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execStateT</a> m s = <a>liftM</a> <a>snd</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
execStateT :: Monad m => StateT s m a -> s -> m s

-- | Map both the return value and final state of a computation using the
--   given function.
--   
--   <ul>
--   <li><pre><a>runStateT</a> (<a>mapStateT</a> f m) = f .
--   <a>runStateT</a> m</pre></li>
--   </ul>
mapStateT :: () => m (a, s) -> n (b, s) -> StateT s m a -> StateT s n b

-- | <tt><a>withStateT</a> f m</tt> executes action <tt>m</tt> on a state
--   modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>withStateT</a> f m = <a>modify</a> f &gt;&gt; m</pre></li>
--   </ul>
withStateT :: () => s -> s -> StateT s m a -> StateT s m a

-- | In-situ lifting of a <tt>callCC</tt> operation to the new monad. This
--   version uses the current state on entering the continuation. It does
--   not satisfy the uniformity property (see
--   <a>Control.Monad.Signatures</a>).
liftCallCC' :: () => CallCC m (a, s) (b, s) -> CallCC StateT s m a b

-- | Get a specific component of the state, using a projection function
--   supplied.
--   
--   <ul>
--   <li><pre><a>gets</a> f = <a>liftM</a> f <a>get</a></pre></li>
--   </ul>
gets :: Monad m => s -> a -> StateT s m a

-- | A variant of <a>modify</a> in which the computation is strict in the
--   new state.
--   
--   <ul>
--   <li><pre><a>modify'</a> f = <a>get</a> &gt;&gt;= ((<a>$!</a>)
--   <a>put</a> . f)</pre></li>
--   </ul>
modify' :: Monad m => s -> s -> StateT s m ()

-- | <tt><a>modify</a> f</tt> is an action that updates the state to the
--   result of applying <tt>f</tt> to the current state.
--   
--   <ul>
--   <li><pre><a>modify</a> f = <a>get</a> &gt;&gt;= (<a>put</a> .
--   f)</pre></li>
--   </ul>
modify :: Monad m => s -> s -> StateT s m ()

-- | <tt><a>put</a> s</tt> sets the state within the monad to <tt>s</tt>.
put :: Monad m => s -> StateT s m ()

-- | Fetch the current value of the state within the monad.
get :: Monad m => StateT s m s

-- | Construct a state monad computation from a function. (The inverse of
--   <a>runState</a>.)
state :: Monad m => s -> (a, s) -> StateT s m a

-- | Build an MSF in the <a>State</a> monad from one that takes the state
--   as an extra input. This is the opposite of <a>runStateS</a>.
stateS :: Monad m => MSF m (s, a) (s, b) -> MSF (StateT s m) a b

-- | Build an MSF that takes a state as an extra input from one on the
--   <a>State</a> monad. This is the opposite of <a>stateS</a>.
runStateS :: Monad m => MSF (StateT s m) a b -> MSF m (s, a) (s, b)

-- | Build an MSF <i>function</i> that takes a fixed state as additional
--   input, from an MSF in the <a>State</a> monad, and outputs the new
--   state with every transformation step.
--   
--   This should be always equal to:
--   
--   <pre>
--   runStateS_ msf s = feedback s $ runStateS msf &gt;&gt;&gt; arr ((s,b) -&gt; ((s,b), s))
--   </pre>
--   
--   although possibly more efficient.
runStateS_ :: Monad m => MSF (StateT s m) a b -> s -> MSF m a (s, b)

-- | Build an MSF <i>function</i> that takes a fixed state as additional
--   input, from an MSF in the <a>State</a> monad.
--   
--   This should be always equal to:
--   
--   <pre>
--   runStateS__ msf s = feedback s $ runStateS msf &gt;&gt;&gt; arr ((s,b) -&gt; (b, s))
--   </pre>
--   
--   although possibly more efficient.
runStateS__ :: Monad m => MSF (StateT s m) a b -> s -> MSF m a b

-- | Alternative implementation of <a>stateS</a> using <a>lifterS</a>.
stateS' :: (Functor m, Monad m) => MSF m (s, a) (s, b) -> MSF (StateT s m) a b

-- | Alternative implementation of <a>runStateS</a> using <a>lifterS</a>.
runStateS' :: (Functor m, Monad m) => MSF (StateT s m) a b -> MSF m (s, a) (s, b)

-- | Alternative implementation of <a>runStateS</a> using <a>transS</a>.
runStateS'' :: (Functor m, Monad m) => MSF (StateT s m) a b -> MSF m (s, a) (s, b)

-- | Alternative implementation of <a>runStateS</a> using <a>transG</a>.
runStateS''' :: (Functor m, Monad m) => MSF (StateT s m) a b -> MSF m (s, a) (s, b)


-- | MSFs with a Reader monadic layer.
--   
--   This module contains functions to work with MSFs that include a
--   <a>Reader</a> monadic layer. This includes functions to create new
--   MSFs that include an additional layer, and functions to flatten that
--   layer out of the MSF's transformer stack.
module Control.Monad.Trans.MSF.Reader

-- | The reader monad transformer, which adds a read-only environment to
--   the given monad.
--   
--   The <a>return</a> function ignores the environment, while
--   <tt>&gt;&gt;=</tt> passes the inherited environment to both
--   subcomputations.
newtype ReaderT r (m :: k -> *) (a :: k) :: forall k. () => * -> k -> * -> k -> *
ReaderT :: r -> m a -> ReaderT r
[runReaderT] :: ReaderT r -> r -> m a

-- | The parameterizable reader monad.
--   
--   Computations are functions of a shared environment.
--   
--   The <a>return</a> function ignores the environment, while
--   <tt>&gt;&gt;=</tt> passes the inherited environment to both
--   subcomputations.
type Reader r = ReaderT r Identity

-- | Runs a <tt>Reader</tt> and extracts the final value from it. (The
--   inverse of <a>reader</a>.)
runReader :: () => Reader r a -> r -> a

-- | Transform the value returned by a <tt>Reader</tt>.
--   
--   <ul>
--   <li><pre><a>runReader</a> (<a>mapReader</a> f m) = f .
--   <a>runReader</a> m</pre></li>
--   </ul>
mapReader :: () => a -> b -> Reader r a -> Reader r b

-- | Execute a computation in a modified environment (a specialization of
--   <a>withReaderT</a>).
--   
--   <ul>
--   <li><pre><a>runReader</a> (<a>withReader</a> f m) = <a>runReader</a> m
--   . f</pre></li>
--   </ul>
withReader :: () => r' -> r -> Reader r a -> Reader r' a

-- | Transform the computation inside a <tt>ReaderT</tt>.
--   
--   <ul>
--   <li><pre><a>runReaderT</a> (<a>mapReaderT</a> f m) = f .
--   <a>runReaderT</a> m</pre></li>
--   </ul>
mapReaderT :: () => m a -> n b -> ReaderT r m a -> ReaderT r n b

-- | Execute a computation in a modified environment (a more general
--   version of <a>local</a>).
--   
--   <ul>
--   <li><pre><a>runReaderT</a> (<a>withReaderT</a> f m) =
--   <a>runReaderT</a> m . f</pre></li>
--   </ul>
withReaderT :: () => r' -> r -> ReaderT r m a -> ReaderT r' m a

-- | Retrieve a function of the current environment.
--   
--   <ul>
--   <li><pre><a>asks</a> f = <a>liftM</a> f <a>ask</a></pre></li>
--   </ul>
asks :: Monad m => r -> a -> ReaderT r m a

-- | Execute a computation in a modified environment (a specialization of
--   <a>withReaderT</a>).
--   
--   <ul>
--   <li><pre><a>runReaderT</a> (<a>local</a> f m) = <a>runReaderT</a> m .
--   f</pre></li>
--   </ul>
local :: () => r -> r -> ReaderT r m a -> ReaderT r m a

-- | Fetch the value of the environment.
ask :: Monad m => ReaderT r m r

-- | Constructor for computations in the reader monad (equivalent to
--   <a>asks</a>).
reader :: Monad m => r -> a -> ReaderT r m a

-- | Build an MSF in the <a>Reader</a> monad from one that takes the reader
--   environment as an extra input. This is the opposite of
--   <a>runReaderS</a>.
readerS :: Monad m => MSF m (s, a) b -> MSF (ReaderT s m) a b

-- | Build an MSF that takes an environment as an extra input from one on
--   the <a>Reader</a> monad. This is the opposite of <a>readerS</a>.
runReaderS :: Monad m => MSF (ReaderT s m) a b -> MSF m (s, a) b

-- | Build an MSF <i>function</i> that takes a fixed environment as
--   additional input, from an MSF in the <a>Reader</a> monad.
--   
--   This should be always equal to:
--   
--   <pre>
--   runReaderS_ msf s = arr (a -&gt; (s,a)) &gt;&gt;&gt; runReaderS msf
--   </pre>
--   
--   although possibly more efficient.
runReaderS_ :: Monad m => MSF (ReaderT s m) a b -> s -> MSF m a b

-- | Alternative version of <a>readerS</a>.
readerS' :: Monad m => MSF m (s, a) b -> MSF (ReaderT s m) a b

-- | Alternative version of <a>runReaderS</a> wrapping/unwrapping
--   functions.
runReaderS' :: Monad m => MSF (ReaderT s m) a b -> MSF m (s, a) b

-- | Alternative version of <a>runReaderS</a>.
runReaderS'' :: Monad m => MSF (ReaderT s m) a b -> MSF m (s, a) b


-- | <a>MSF</a>s in the <a>ExceptT</a> monad are monadic stream functions
--   that can throw exceptions, i.e. return an exception value instead of a
--   continuation. This module gives ways to throw exceptions in various
--   ways, and to handle them through a monadic interface.
module Control.Monad.Trans.MSF.Except

-- | The empty type. As an exception type, it encodes "no exception
--   possible".
data Empty

-- | <a>MSF</a>s with an <a>ExceptT</a> transformer layer are in fact
--   monads <i>in the exception type</i>.
--   
--   <ul>
--   <li><a>return</a> corresponds to throwing an exception
--   immediately.</li>
--   <li>'(&gt;&gt;=)' is exception handling: The first value throws an
--   exception, while the Kleisli arrow handles the exception and produces
--   a new signal function, which can throw exceptions in a different
--   type.</li>
--   </ul>
newtype MSFExcept m a b e
MSFExcept :: MSF (ExceptT e m) a b -> MSFExcept m a b e
[runMSFExcept] :: MSFExcept m a b e -> MSF (ExceptT e m) a b

-- | Throw the exception <tt>e</tt> whenever the function evaluates to
--   <a>True</a>.
throwOnCond :: Monad m => (a -> Bool) -> e -> MSF (ExceptT e m) a a

-- | Variant of <a>throwOnCond</a> for Kleisli arrows. | Throws the
--   exception when the input is <a>True</a>.
throwOnCondM :: Monad m => (a -> m Bool) -> e -> MSF (ExceptT e m) a a

-- | Throw the exception when the input is <a>True</a>.
throwOn :: Monad m => e -> MSF (ExceptT e m) Bool ()

-- | Variant of <a>throwOn</a>, where the exception may change every tick.
throwOn' :: Monad m => MSF (ExceptT e m) (Bool, e) ()

-- | When the input is 'Just e', throw the exception <tt>e</tt>. (Does not
--   output any actual data.)
throwMaybe :: Monad m => MSF (ExceptT e m) (Maybe e) (Maybe a)

-- | Immediately throw the incoming exception.
throwS :: Monad m => MSF (ExceptT e m) e a

-- | Immediately throw the given exception.
throw :: Monad m => e -> MSF (ExceptT e m) a b

-- | Do not throw an exception.
pass :: Monad m => MSF (ExceptT e m) a a

-- | Whenever <a>Nothing</a> is thrown, throw '()' instead.
maybeToExceptS :: (Functor m, Monad m) => MSF (MaybeT m) a b -> MSF (ExceptT () m) a b

-- | Catch an exception in an <a>MSF</a>. As soon as an exception occurs,
--   the current continuation is replaced by a new <a>MSF</a>, the
--   exception handler, based on the exception value. For exception
--   catching where the handler can throw further exceptions, see
--   <a>MSFExcept</a> further below.
catchS :: Monad m => MSF (ExceptT e m) a b -> (e -> MSF m a b) -> MSF m a b

-- | Similar to Yampa's delayed switching. Looses a <tt>b</tt> in case of
--   an exception.
untilE :: Monad m => MSF m a b -> MSF m b (Maybe e) -> MSF (ExceptT e m) a b

-- | Escape an <a>ExceptT</a> layer by outputting the exception whenever it
--   occurs. If an exception occurs, the current <a>MSF</a> continuation is
--   tested again on the next input.
exceptS :: Monad m => MSF (ExceptT e m) a b -> MSF m a (Either e b)

-- | Embed an <a>ExceptT</a> value inside the <a>MSF</a>. Whenever the
--   input value is an ordinary value, it is passed on. If it is an
--   exception, it is raised.
inExceptT :: Monad m => MSF (ExceptT e m) (ExceptT e m a) a

-- | In case an exception occurs in the first argument, replace the
--   exception by the second component of the tuple.
tagged :: Monad m => MSF (ExceptT e1 m) a b -> MSF (ExceptT e2 m) (a, e2) b

-- | An alias for the |MSFExcept| constructor, used to enter the
--   |MSFExcept| monad context. Execute an <a>MSF</a> in <a>ExceptT</a>
--   until it raises an exception.
try :: MSF (ExceptT e m) a b -> MSFExcept m a b e

-- | Immediately throw the current input as an exception.
currentInput :: Monad m => MSFExcept m e b e

-- | If no exception can occur, the <a>MSF</a> can be executed without the
--   <a>ExceptT</a> layer.
safely :: Monad m => MSFExcept m a b Empty -> MSF m a b

-- | An <a>MSF</a> without an <a>ExceptT</a> layer never throws an
--   exception, and can thus have an arbitrary exception type.
safe :: Monad m => MSF m a b -> MSFExcept m a b e

-- | Inside the <a>MSFExcept</a> monad, execute an action of the wrapped
--   monad. This passes the last input value to the action, but doesn't
--   advance a tick.
once :: Monad m => (a -> m e) -> MSFExcept m a b e

-- | Variant of <a>once</a> without input.
once_ :: Monad m => m e -> MSFExcept m a b e

-- | Advances a single tick with the given Kleisli arrow, and then throws
--   an exception.
step :: Monad m => (a -> m (b, e)) -> MSFExcept m a b e

-- | Extract MSF from a monadic action.
--   
--   Runs a monadic action that produces an MSF on the first
--   iteration/step, and uses that MSF as the main signal function for all
--   inputs (including the first one).
performOnFirstSample :: Monad m => m (MSF m a b) -> MSF m a b

-- | Reactimates an <a>MSFExcept</a> until it throws an exception.
reactimateExcept :: Monad m => MSFExcept m () () e -> m e

-- | Reactimates an <a>MSF</a> until it returns <a>True</a>.
reactimateB :: Monad m => MSF m () Bool -> m ()

-- | A monad transformer that adds exceptions to other monads.
--   
--   <tt>ExceptT</tt> constructs a monad parameterized over two things:
--   
--   <ul>
--   <li>e - The exception type.</li>
--   <li>m - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function yields a computation that produces the
--   given value, while <tt>&gt;&gt;=</tt> sequences two subcomputations,
--   exiting on the first exception.
newtype ExceptT e (m :: * -> *) a
ExceptT :: m Either e a -> ExceptT e a

-- | The parameterizable exception monad.
--   
--   Computations are either exceptions or normal values.
--   
--   The <a>return</a> function returns a normal value, while
--   <tt>&gt;&gt;=</tt> exits on the first exception. For a variant that
--   continues after an error and collects all the errors, see
--   <a>Errors</a>.
type Except e = ExceptT e Identity

-- | Extractor for computations in the exception monad. (The inverse of
--   <a>except</a>).
runExcept :: () => Except e a -> Either e a

-- | Map the unwrapped computation using the given function.
--   
--   <ul>
--   <li><pre><a>runExcept</a> (<a>mapExcept</a> f m) = f (<a>runExcept</a>
--   m)</pre></li>
--   </ul>
mapExcept :: () => Either e a -> Either e' b -> Except e a -> Except e' b

-- | Transform any exceptions thrown by the computation using the given
--   function (a specialization of <a>withExceptT</a>).
withExcept :: () => e -> e' -> Except e a -> Except e' a

-- | The inverse of <a>ExceptT</a>.
runExceptT :: () => ExceptT e m a -> m Either e a

-- | Map the unwrapped computation using the given function.
--   
--   <ul>
--   <li><pre><a>runExceptT</a> (<a>mapExceptT</a> f m) = f
--   (<a>runExceptT</a> m)</pre></li>
--   </ul>
mapExceptT :: () => m Either e a -> n Either e' b -> ExceptT e m a -> ExceptT e' n b

-- | Transform any exceptions thrown by the computation using the given
--   function.
withExceptT :: Functor m => e -> e' -> ExceptT e m a -> ExceptT e' m a

-- | Handle an exception.
--   
--   <ul>
--   <li><pre><a>catchE</a> h (<a>lift</a> m) = <a>lift</a> m</pre></li>
--   <li><pre><a>catchE</a> h (<a>throwE</a> e) = h e</pre></li>
--   </ul>
catchE :: Monad m => ExceptT e m a -> e -> ExceptT e' m a -> ExceptT e' m a

-- | Signal an exception value <tt>e</tt>.
--   
--   <ul>
--   <li><pre><a>runExceptT</a> (<a>throwE</a> e) = <a>return</a>
--   (<a>Left</a> e)</pre></li>
--   <li><pre><a>throwE</a> e &gt;&gt;= m = <a>throwE</a> e</pre></li>
--   </ul>
throwE :: Monad m => e -> ExceptT e m a

-- | Constructor for computations in the exception monad. (The inverse of
--   <a>runExcept</a>).
except :: () => Either e a -> Except e a
instance GHC.Base.Monad m => GHC.Base.Functor (Control.Monad.Trans.MSF.Except.MSFExcept m a b)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.Trans.MSF.Except.MSFExcept m a b)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Trans.MSF.Except.MSFExcept m a b)


-- | The <a>Maybe</a> monad is very versatile. It can stand for default
--   arguments, for absent values, and for (nondescript) exceptions. The
--   latter viewpoint is most natural in the context of <a>MSF</a>s.
module Control.Monad.Trans.MSF.Maybe

-- | Throw the exception immediately.
exit :: Monad m => MSF (MaybeT m) a b

-- | Throw the exception when the condition becomes true on the input.
exitWhen :: Monad m => (a -> Bool) -> MSF (MaybeT m) a a

-- | Exit when the incoming value is <a>True</a>.
exitIf :: Monad m => MSF (MaybeT m) Bool ()

-- | <tt>Just a</tt> is passed along, <a>Nothing</a> causes the whole
--   <a>MSF</a> to exit.
maybeExit :: Monad m => MSF (MaybeT m) (Maybe a) a

-- | Embed a <a>Maybe</a> value in the <a>MaybeT</a> layer. Identical to
--   <a>maybeExit</a>.
inMaybeT :: Monad m => MSF (MaybeT m) (Maybe a) a

-- | Run the first <tt>msf</tt> until the second one produces <a>True</a>
--   from the output of the first.
untilMaybe :: Monad m => MSF m a b -> MSF m b Bool -> MSF (MaybeT m) a b

-- | When an exception occurs in the first <tt>msf</tt>, the second
--   <tt>msf</tt> is executed from there.
catchMaybe :: (Functor m, Monad m) => MSF (MaybeT m) a b -> MSF m a b -> MSF m a b

-- | Converts a list to an <a>MSF</a> in <a>MaybeT</a>, which outputs an
--   element of the list at each step, throwing <a>Nothing</a> when the
--   list ends.
listToMaybeS :: Monad m => [b] -> MSF (MaybeT m) a b

-- | Remove the <a>MaybeT</a> layer by outputting <a>Nothing</a> when the
--   exception occurs. The continuation in which the exception occurred is
--   then tested on the next input.
runMaybeS :: Monad m => MSF (MaybeT m) a b -> MSF m a (Maybe b)

-- | Different implementation, to study performance.
runMaybeS'' :: Monad m => MSF (MaybeT m) a b -> MSF m a (Maybe b)

-- | Reactimates an <a>MSF</a> in the <a>MaybeT</a> monad until it throws
--   <a>Nothing</a>.
reactimateMaybe :: (Functor m, Monad m) => MSF (MaybeT m) () () -> m ()

-- | Run an MSF fed from a list, discarding results. Useful when one needs
--   to combine effects and streams (i.e., for testing purposes).
embed_ :: (Functor m, Monad m) => MSF m a () -> [a] -> m ()

-- | Convert a <a>ExceptT</a> computation to <a>MaybeT</a>, discarding the
--   value of any exception.
exceptToMaybeT :: Functor m => ExceptT e m a -> MaybeT m a

-- | Convert a <a>MaybeT</a> computation to <a>ExceptT</a>, with a default
--   exception value.
maybeToExceptT :: Functor m => e -> MaybeT m a -> ExceptT e m a

-- | Transform the computation inside a <tt>MaybeT</tt>.
--   
--   <ul>
--   <li><pre><a>runMaybeT</a> (<a>mapMaybeT</a> f m) = f (<a>runMaybeT</a>
--   m)</pre></li>
--   </ul>
mapMaybeT :: () => m Maybe a -> n Maybe b -> MaybeT m a -> MaybeT n b

-- | The parameterizable maybe monad, obtained by composing an arbitrary
--   monad with the <a>Maybe</a> monad.
--   
--   Computations are actions that may produce a value or exit.
--   
--   The <a>return</a> function yields a computation that produces that
--   value, while <tt>&gt;&gt;=</tt> sequences two subcomputations, exiting
--   if either computation does.
newtype MaybeT (m :: * -> *) a
MaybeT :: m Maybe a -> MaybeT a
[runMaybeT] :: MaybeT a -> m Maybe a

-- | Whenever <a>Nothing</a> is thrown, throw '()' instead.
maybeToExceptS :: (Functor m, Monad m) => MSF (MaybeT m) a b -> MSF (ExceptT () m) a b


-- | This module reexports nearly all submodules. RWS is not exported since
--   names collide with Reader, State and Writer.
module Control.Monad.Trans.MSF


-- | <a>VectorSpace</a> instances for MSFs that produce vector spaces. This
--   allows you to use vector operators with MSFs that output vectors, for
--   example, you can write:
--   
--   <pre>
--   msf1 :: MSF Input (Double, Double) -- defined however you want
--   msf2 :: MSF Input (Double, Double) -- defined however you want
--   msf3 :: MSF Input (Double, Double)
--   msf3 = msf1 ^+^ msf2
--   </pre>
--   
--   instead of
--   
--   <pre>
--   msf3 = (msf1 &amp;&amp;&amp; msf2) &gt;&gt;&gt; arr (uncurry (^+^))
--   </pre>
--   
--   Instances are provided for the type classes <a>RModule</a> and
--   <a>VectorSpace</a>.
module Data.MonadicStreamFunction.Instances.VectorSpace
instance (GHC.Base.Monad m, Data.VectorSpace.RModule v) => Data.VectorSpace.RModule (Data.MonadicStreamFunction.Core.MSF m a v)
instance (GHC.Base.Monad m, Data.VectorSpace.VectorSpace v) => Data.VectorSpace.VectorSpace (Data.MonadicStreamFunction.Core.MSF m a v)


-- | VectorSpace instances for Num/Fractional types.
--   
--   This module includes instances for:
--   
--   <ul>
--   <li><a>InnerProductSpace</a> and <a>RModule</a> for <a>Num</a></li>
--   <li><a>VectorSpace</a> for <a>Fractional</a>s</li>
--   </ul>
module Data.VectorSpace.Fractional
instance GHC.Num.Num a => Data.VectorSpace.RModule a
instance GHC.Real.Fractional a => Data.VectorSpace.VectorSpace a
instance GHC.Num.Num a => Data.VectorSpace.InnerProductSpace a


-- | Vector space instances for concrete/specific types.
--   
--   This module contains:
--   
--   <ul>
--   <li><a>RModule</a> instances for <a>Int</a>, <a>Integer</a>,
--   <a>Double</a> and <a>Float</a>.</li>
--   <li><a>VectorSpace</a> for <a>Double</a> and <a>Float</a>.</li>
--   </ul>
module Data.VectorSpace.Specific
instance Data.VectorSpace.RModule GHC.Types.Int
instance Data.VectorSpace.RModule GHC.Integer.Type.Integer
instance Data.VectorSpace.RModule GHC.Types.Double
instance Data.VectorSpace.RModule GHC.Types.Float
instance Data.VectorSpace.VectorSpace GHC.Types.Double
instance Data.VectorSpace.VectorSpace GHC.Types.Float


-- | Vector space instances for small tuples of <a>Fractional</a>.
--   
--   This module contains <a>RModule</a>, <a>VectorSpace</a> and
--   <a>InnerProductSpace</a> for tuples of up to five elements.
module Data.VectorSpace.Tuples
instance (Data.VectorSpace.Groundring a ~ Data.VectorSpace.Groundring b, Data.VectorSpace.RModule a, Data.VectorSpace.RModule b) => Data.VectorSpace.RModule (a, b)
instance (Data.VectorSpace.Groundfield a ~ Data.VectorSpace.Groundfield b, Data.VectorSpace.VectorSpace a, Data.VectorSpace.VectorSpace b) => Data.VectorSpace.VectorSpace (a, b)
instance (Data.VectorSpace.Groundfield a ~ Data.VectorSpace.Groundfield b, Data.VectorSpace.InnerProductSpace a, Data.VectorSpace.InnerProductSpace b) => Data.VectorSpace.InnerProductSpace (a, b)
instance GHC.Num.Num a => Data.VectorSpace.RModule (a, a, a)
instance GHC.Real.Fractional a => Data.VectorSpace.VectorSpace (a, a, a)
instance GHC.Num.Num a => Data.VectorSpace.InnerProductSpace (a, a, a)
instance GHC.Num.Num a => Data.VectorSpace.RModule (a, a, a, a)
instance GHC.Real.Fractional a => Data.VectorSpace.VectorSpace (a, a, a, a)
instance GHC.Num.Num a => Data.VectorSpace.InnerProductSpace (a, a, a, a)
instance GHC.Num.Num a => Data.VectorSpace.RModule (a, a, a, a, a)
instance GHC.Real.Fractional a => Data.VectorSpace.VectorSpace (a, a, a, a, a)
instance GHC.Num.Num a => Data.VectorSpace.InnerProductSpace (a, a, a, a, a)
