-- 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.5.1


-- | Monadic Stream Functions are synchronized stream functions with side
--   effects.
--   
--   <a>MSF</a>s 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.
--   
--   <a>MSF</a>s are a generalisation of the implementation mechanism used
--   by Yampa, Wormholes and other FRP and reactive implementations.
--   
--   This modules defines only the minimal core. Hopefully, other functions
--   can be defined in terms of the functions in this module without
--   accessing the MSF constuctor.
module Data.MonadicStreamFunction.InternalCore

-- | Stepwise, side-effectful <a>MSF</a>s without implicit knowledge of
--   time.
--   
--   <a>MSF</a>s 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)

-- | Generic lifting of a morphism to the level of <a>MSF</a>s.
--   
--   Natural transformation to the level of <a>MSF</a>s.
--   
--   <b>Mathematical background:</b> The type <tt>a -&gt; m (b, c)</tt> is
--   a functor in <tt>c</tt>, and <tt>MSF m a b</tt> is its greatest
--   fixpoint, i.e. it is isomorphic to the type <tt>a -&gt; m (b, MSF m a
--   b)</tt>, by definition. The types <tt>m</tt>, <tt>a</tt> and
--   <tt>b</tt> are parameters of the functor. Taking a fixpoint is
--   functorial itself, meaning that a morphism (a natural transformation)
--   of two such functors gives a morphism (an ordinary function) of their
--   fixpoints.
--   
--   This is in a sense the most general "abstract" lifting function, i.e.
--   the most general one that only changes input, output and side effect
--   types, and doesn't influence control flow. Other handling functions
--   like exception handling or <tt>ListT</tt> broadcasting necessarily
--   change control flow.
morphGS :: Monad m2 => (forall c. (a1 -> m1 (b1, c)) -> a2 -> m2 (b2, c)) -> MSF m1 a1 b1 -> MSF m2 a2 b2

-- | 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
--   <a>MSF</a> produces <a>Nothing</a> 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.InternalCore.MSF m)


-- | Monadic Stream Functions are synchronized stream functions with side
--   effects.
--   
--   <a>MSF</a>s 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.
--   
--   <a>MSF</a>s 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 <a>Maybe</a> monad, they become
--   transformations that may stop producing outputs (and continuations).
--   The <a>Either</a> monad gives rise to <a>MSF</a>s 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.
--   
--   <a>MSF</a>s 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 <a>MSF</a>s, 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 <a>MSF</a>s without implicit knowledge of
--   time.
--   
--   <a>MSF</a>s 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

-- | Lifts a monadic computation into a Stream.
constM :: Monad m => 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
liftBaseM :: (Monad m2, MonadBase m1 m2) => (a -> m1 b) -> MSF m2 a b

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

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

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

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

-- | Apply trans-monadic actions (in an arbitrary way).
--   
--   This is just a convenience function when you have a function to move
--   across monads, because the signature of <a>morphGS</a> is a bit
--   complex.
morphS :: (Monad m2, Monad m1) => (forall c. m1 c -> m2 c) -> MSF m1 a b -> MSF m2 a b

-- | Generic lifting of a morphism to the level of <a>MSF</a>s.
--   
--   Natural transformation to the level of <a>MSF</a>s.
--   
--   <b>Mathematical background:</b> The type <tt>a -&gt; m (b, c)</tt> is
--   a functor in <tt>c</tt>, and <tt>MSF m a b</tt> is its greatest
--   fixpoint, i.e. it is isomorphic to the type <tt>a -&gt; m (b, MSF m a
--   b)</tt>, by definition. The types <tt>m</tt>, <tt>a</tt> and
--   <tt>b</tt> are parameters of the functor. Taking a fixpoint is
--   functorial itself, meaning that a morphism (a natural transformation)
--   of two such functors gives a morphism (an ordinary function) of their
--   fixpoints.
--   
--   This is in a sense the most general "abstract" lifting function, i.e.
--   the most general one that only changes input, output and side effect
--   types, and doesn't influence control flow. Other handling functions
--   like exception handling or <tt>ListT</tt> broadcasting necessarily
--   change control flow.
morphGS :: Monad m2 => (forall c. (a1 -> m1 (b1, c)) -> a2 -> m2 (b2, c)) -> MSF m1 a1 b1 -> MSF m2 a2 b2

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

-- | Run an <a>MSF</a> indefinitely passing a unit-carrying input stream.
reactimate :: Monad m => MSF m () () -> m ()

-- | 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
--   <a>MSF</a> produces <a>Nothing</a> 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]
instance GHC.Base.Monad m => Control.Arrow.Arrow (Data.MonadicStreamFunction.InternalCore.MSF m)
instance GHC.Base.Monad m => GHC.Base.Functor (Data.MonadicStreamFunction.InternalCore.MSF m a)
instance (GHC.Base.Functor m, GHC.Base.Monad m) => GHC.Base.Applicative (Data.MonadicStreamFunction.InternalCore.MSF m a)


-- | Number instances for <a>MSF</a>s that produce numbers. This allows you
--   to use numeric operators with <a>MSF</a>s 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.InternalCore.MSF m a b)
instance (GHC.Base.Monad m, GHC.Real.Fractional b) => GHC.Real.Fractional (Data.MonadicStreamFunction.InternalCore.MSF m a b)
instance (GHC.Base.Monad m, GHC.Float.Floating b) => GHC.Float.Floating (Data.MonadicStreamFunction.InternalCore.MSF m a b)


-- | 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.InternalCore.MSF m)
instance (GHC.Base.Monad m, GHC.Base.MonadPlus m) => Control.Arrow.ArrowPlus (Data.MonadicStreamFunction.InternalCore.MSF m)
instance (GHC.Base.Functor m, GHC.Base.Monad m, GHC.Base.MonadPlus m) => GHC.Base.Alternative (Data.MonadicStreamFunction.InternalCore.MSF m a)


-- | 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 Control.Monad.Fix.MonadFix m => Control.Arrow.ArrowLoop (Data.MonadicStreamFunction.InternalCore.MSF m)


-- | 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.InternalCore.MSF m)


-- | <a>MSF</a>s with a <a>State</a> monadic layer.
--   
--   This module contains functions to work with <a>MSF</a>s that include a
--   <a>State</a> monadic layer. This includes functions to create new
--   <a>MSF</a>s that include an additional layer, and functions to flatten
--   that layer out of the <a>MSF</a>'s transformer stack.
--   
--   It is based on the _strict_ state monad <a>Strict</a>, so when
--   combining it with other modules such as <tt>mtl</tt>'s, the strict
--   version has to be included, i.e. <a>Strict</a> instead of <a>State</a>
--   or <a>Lazy</a>.
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 :: Type -> Type) 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 <a>MSF</a> 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 :: (Functor m, Monad m) => MSF m (s, a) (s, b) -> MSF (StateT s m) a b

-- | Build an <a>MSF</a> 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 :: (Functor m, Monad m) => MSF (StateT s m) a b -> MSF m (s, a) (s, b)

-- | Build an <a>MSF</a> <i>function</i> that takes a fixed state as
--   additional input, from an <a>MSF</a> in the <a>State</a> monad, and
--   outputs the new state with every transformation step.
runStateS_ :: (Functor m, Monad m) => MSF (StateT s m) a b -> s -> MSF m a (s, b)

-- | Build an <a>MSF</a> <i>function</i> that takes a fixed state as
--   additional input, from an <a>MSF</a> in the <a>State</a> monad.
runStateS__ :: (Functor m, Monad m) => MSF (StateT s m) a b -> s -> 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
infixl 5 ^-^
infixl 5 ^+^
infixr 6 *^

-- | 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
infixl 6 ^/

-- | 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.
type Groundfield v = Groundring v

-- | 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
infix 6 `dot`

-- | 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 (Floating (Groundfield v), InnerProductSpace v, VectorSpace v) => NormedSpace v
norm :: NormedSpace v => v -> Groundfield v

-- | Divides a vector by its norm, resulting in a vector of norm 1. Throws
--   an error on vectors with norm 0.
normalize :: (Eq (Groundfield v), NormedSpace v) => v -> v
break3Tuple :: (a, b, c) -> ((a, b), c)
join3Tuple :: ((a, b), c) -> (a, b, c)
break4Tuple :: (a, b, c, d) -> ((a, b), (c, d))
join4Tuple :: ((a, b), (c, d)) -> (a, b, c, d)
break5Tuple :: (a, b, c, d, e) -> ((a, b), (c, d, e))
join5Tuple :: ((a, b), (c, d, e)) -> (a, b, c, d, e)

-- | Wrap an arbitrary <a>Fractional</a> in this newtype in order to get
--   <a>VectorSpace</a>, and related instances.
newtype FractionalVectorSpace a
FractionalVectorSpace :: a -> FractionalVectorSpace a
[getFractional] :: FractionalVectorSpace a -> a
instance GHC.Real.Fractional a => GHC.Real.Fractional (Data.VectorSpace.FractionalVectorSpace a)
instance GHC.Num.Num a => GHC.Num.Num (Data.VectorSpace.FractionalVectorSpace a)
instance GHC.Num.Num a => Data.VectorSpace.RModule (Data.VectorSpace.FractionalVectorSpace a)
instance GHC.Real.Fractional a => Data.VectorSpace.VectorSpace (Data.VectorSpace.FractionalVectorSpace a)
instance GHC.Num.Num a => Data.VectorSpace.InnerProductSpace (Data.VectorSpace.FractionalVectorSpace a)
instance GHC.Float.Floating a => Data.VectorSpace.NormedSpace (Data.VectorSpace.FractionalVectorSpace a)
instance (Data.VectorSpace.Groundfield a Data.Type.Equality.~ Data.VectorSpace.Groundfield b, Data.VectorSpace.NormedSpace a, Data.VectorSpace.NormedSpace b) => Data.VectorSpace.NormedSpace (a, b)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.NormedSpace a, Data.VectorSpace.NormedSpace b, Data.VectorSpace.NormedSpace c) => Data.VectorSpace.NormedSpace (a, b, c)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring d, Data.VectorSpace.NormedSpace a, Data.VectorSpace.NormedSpace b, Data.VectorSpace.NormedSpace c, Data.VectorSpace.NormedSpace d) => Data.VectorSpace.NormedSpace (a, b, c, d)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring d, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring e, Data.VectorSpace.NormedSpace a, Data.VectorSpace.NormedSpace b, Data.VectorSpace.NormedSpace c, Data.VectorSpace.NormedSpace d, Data.VectorSpace.NormedSpace e) => Data.VectorSpace.NormedSpace (a, b, c, d, e)
instance (Data.VectorSpace.Groundfield a Data.Type.Equality.~ Data.VectorSpace.Groundfield b, Data.VectorSpace.InnerProductSpace a, Data.VectorSpace.InnerProductSpace b) => Data.VectorSpace.InnerProductSpace (a, b)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.InnerProductSpace a, Data.VectorSpace.InnerProductSpace b, Data.VectorSpace.InnerProductSpace c) => Data.VectorSpace.InnerProductSpace (a, b, c)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring d, Data.VectorSpace.InnerProductSpace a, Data.VectorSpace.InnerProductSpace b, Data.VectorSpace.InnerProductSpace c, Data.VectorSpace.InnerProductSpace d) => Data.VectorSpace.InnerProductSpace (a, b, c, d)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring d, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring e, Data.VectorSpace.InnerProductSpace a, Data.VectorSpace.InnerProductSpace b, Data.VectorSpace.InnerProductSpace c, Data.VectorSpace.InnerProductSpace d, Data.VectorSpace.InnerProductSpace e) => Data.VectorSpace.InnerProductSpace (a, b, c, d, e)
instance Data.VectorSpace.VectorSpace GHC.Types.Double
instance Data.VectorSpace.VectorSpace GHC.Types.Float
instance (Data.VectorSpace.Groundfield a Data.Type.Equality.~ Data.VectorSpace.Groundfield b, Data.VectorSpace.VectorSpace a, Data.VectorSpace.VectorSpace b) => Data.VectorSpace.VectorSpace (a, b)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.VectorSpace a, Data.VectorSpace.VectorSpace b, Data.VectorSpace.VectorSpace c) => Data.VectorSpace.VectorSpace (a, b, c)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring d, Data.VectorSpace.VectorSpace a, Data.VectorSpace.VectorSpace b, Data.VectorSpace.VectorSpace c, Data.VectorSpace.VectorSpace d) => Data.VectorSpace.VectorSpace (a, b, c, d)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring d, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring e, Data.VectorSpace.VectorSpace a, Data.VectorSpace.VectorSpace b, Data.VectorSpace.VectorSpace c, Data.VectorSpace.VectorSpace d, Data.VectorSpace.VectorSpace e) => Data.VectorSpace.VectorSpace (a, b, c, d, e)
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.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.RModule a, Data.VectorSpace.RModule b) => Data.VectorSpace.RModule (a, b)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.RModule a, Data.VectorSpace.RModule b, Data.VectorSpace.RModule c) => Data.VectorSpace.RModule (a, b, c)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring d, Data.VectorSpace.RModule a, Data.VectorSpace.RModule b, Data.VectorSpace.RModule c, Data.VectorSpace.RModule d) => Data.VectorSpace.RModule (a, b, c, d)
instance (Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring b, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring c, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring d, Data.VectorSpace.Groundring a Data.Type.Equality.~ Data.VectorSpace.Groundring e, Data.VectorSpace.RModule a, Data.VectorSpace.RModule b, Data.VectorSpace.RModule c, Data.VectorSpace.RModule d, Data.VectorSpace.RModule e) => Data.VectorSpace.RModule (a, b, c, d, e)


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

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

-- | A sink is an <a>MSF</a> that consumes inputs, while producing no
--   output. It can consume the values with side effects.
type MSink m a = MSF m a ()

-- | Apply an <a>MSF</a> 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

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

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

-- | Preprends a fixed output to an <a>MSF</a>, 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, outputting the
--   updated 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

-- | Applies a transfer function to the input and an accumulator, returning
--   the updated accumulator and output.
mealy :: Monad m => (a -> s -> (b, s)) -> s -> MSF m a b

-- | 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 = constS $ 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.
--   
--   <a>MSF</a>s 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.
--   
--   <a>MSF</a>s 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 <a>Maybe</a> monad, they become
--   transformations that may stop producing outputs (and continuations).
--   The <a>Either</a> monad gives rise to <a>MSF</a>s 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.
--   
--   <a>MSF</a>s 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 <a>MSF</a>s, 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


-- | <a>ReactHandle</a>s.
--   
--   Sometimes it is beneficial to give control to an external main loop,
--   for example OpenGL or a hardware-clocked audio server like JACK. This
--   module makes Dunai compatible with external main loops.
module Data.MonadicStreamFunction.ReactHandle

-- | A storage for the current state of an <a>MSF</a>. The <a>MSF</a> may
--   not require input or produce output data, all such data must be
--   handled through side effects (such as wormholes).
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 external loop at every
--   cycle.
react :: MonadIO m => ReactHandle m -> m ()


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

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

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


-- | <a>MSF</a>s with a <a>Writer</a> monadic layer.
--   
--   This module contains functions to work with <a>MSF</a>s that include a
--   <a>Writer</a> monadic layer. This includes functions to create new
--   <a>MSF</a>s that include an additional layer, and functions to flatten
--   that layer out of the <a>MSF</a>'s transformer stack.
--   
--   It is based on the _strict_ writer monad <a>Strict</a>, so when
--   combining it with other modules such as <tt>mtl</tt>'s, the strict
--   version has to be included, i.e. <a>Strict</a> instead of
--   <a>Writer</a> or <a>Lazy</a>.
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 :: Type -> Type) 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 <a>MSF</a> 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 :: (Functor m, Monad m, Monoid w) => MSF m a (w, b) -> MSF (WriterT w m) a b

-- | Build an <a>MSF</a> 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 :: (Functor m, Monad m) => MSF (WriterT s m) a b -> MSF m a (s, b)


-- | <a>MSF</a>s with a <a>Reader</a> monadic layer.
--   
--   This module contains functions to work with <a>MSF</a>s that include a
--   <a>Reader</a> monadic layer. This includes functions to create new
--   <a>MSF</a>s that include an additional layer, and functions to flatten
--   that layer out of the <a>MSF</a>'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 :: Type -> Type) a
ReaderT :: (r -> m a) -> ReaderT r a
[runReaderT] :: ReaderT r a -> 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 <a>MSF</a> 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 (r, a) b -> MSF (ReaderT r m) a b

-- | Build an <a>MSF</a> 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 r m) a b -> MSF m (r, a) b

-- | Build an <a>MSF</a> <i>function</i> that takes a fixed environment as
--   additional input, from an MSF in the <a>Reader</a> monad.
runReaderS_ :: Monad m => MSF (ReaderT s m) a b -> s -> MSF m a b


-- | In this module, <a>MSF</a>s in a monad supporting random number
--   generation (i.e. having the <a>RandT</a> layer in its stack) can be
--   run. Running means supplying an initial random number generator, where
--   the update of the generator at every random number generation is
--   already taken care of.
--   
--   Under the hood, <a>RandT</a> is basically just <a>StateT</a>, with the
--   current random number generator as mutable state.
module Control.Monad.Trans.MSF.Random

-- | Run an <a>MSF</a> in the <a>RandT</a> random number monad transformer
--   by supplying an initial random generator. Updates the generator every
--   step.
runRandS :: (RandomGen g, Functor m, Monad m) => MSF (RandT g m) a b -> g -> MSF m a (g, b)

-- | Evaluate an <a>MSF</a> in the <a>RandT</a> transformer, i.e. extract
--   possibly random values by supplying an initial random generator.
--   Updates the generator every step but discharges the generator.
evalRandS :: (RandomGen g, Functor m, Monad m) => MSF (RandT g m) a b -> g -> MSF m a b

-- | Create a stream of random values.
getRandomS :: (MonadRandom m, Random b) => MSF m a b

-- | Create a stream of lists of random values.
getRandomsS :: (MonadRandom m, Random b) => MSF m a [b]

-- | Create a stream of random values in a given fixed range.
getRandomRS :: (MonadRandom m, Random b) => (b, b) -> MSF m a b

-- | Create a stream of random values in a given range, where the range is
--   specified on every tick.
getRandomRS_ :: (MonadRandom m, Random b) => MSF m (b, b) b

-- | Create a stream of lists of random values in a given fixed range.
getRandomsRS :: (MonadRandom m, Random b) => (b, b) -> MSF m a [b]

-- | Create a stream of lists of random values in a given range, where the
--   range is specified on every tick.
getRandomsRS_ :: (MonadRandom m, Random b) => MSF m (b, b) [b]


-- | This module combines the wrapping and running functions for the
--   <tt>Reader</tt>, <tt>Writer</tt> and <tt>State</tt> monad layers in a
--   single layer.
--   
--   It is based on the _strict_ <a>RWS</a> monad <a>Strict</a>, so when
--   combining it with other modules such as <tt>mtl</tt>'s, the strict
--   version has to be included, i.e. <a>Strict</a> instead of <a>RWS</a>
--   or <a>Lazy</a>.
module Control.Monad.Trans.MSF.RWS

-- | Wrap an <a>MSF</a> with explicit state variables in <a>RWST</a> monad.
rwsS :: (Functor m, Monad m, Monoid w) => MSF m (r, s, a) (w, s, b) -> MSF (RWST r w s m) a b

-- | Run the <a>RWST</a> layer by making the state variables explicit.
runRWSS :: (Functor m, Monad m, Monoid w) => MSF (RWST r w s m) a b -> MSF m (r, s, a) (w, s, b)

-- | A monad transformer adding reading an environment of type <tt>r</tt>,
--   collecting an output of type <tt>w</tt> and updating a state of type
--   <tt>s</tt> to an inner monad <tt>m</tt>.
newtype RWST r w s (m :: Type -> Type) a
RWST :: (r -> s -> m (a, s, w)) -> RWST r w s a
[runRWST] :: RWST r w s a -> r -> s -> m (a, s, w)

-- | A monad containing an environment of type <tt>r</tt>, output of type
--   <tt>w</tt> and an updatable state of type <tt>s</tt>.
type RWS r w s = RWST r w s Identity

-- | Construct an RWS computation from a function. (The inverse of
--   <a>runRWS</a>.)
rws :: () => (r -> s -> (a, s, w)) -> RWS r w s a

-- | Unwrap an RWS computation as a function. (The inverse of <a>rws</a>.)
runRWS :: () => RWS r w s a -> r -> s -> (a, s, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final value and output, discarding the final state.
evalRWS :: () => RWS r w s a -> r -> s -> (a, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final state and output, discarding the final value.
execRWS :: () => RWS r w s a -> r -> s -> (s, w)

-- | Map the return value, final state and output of a computation using
--   the given function.
--   
--   <ul>
--   <li><pre><a>runRWS</a> (<a>mapRWS</a> f m) r s = f (<a>runRWS</a> m r
--   s)</pre></li>
--   </ul>
mapRWS :: () => ((a, s, w) -> (b, s, w')) -> RWS r w s a -> RWS r w' s b

-- | <tt><a>withRWS</a> f m</tt> executes action <tt>m</tt> with an initial
--   environment and state modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>runRWS</a> (<a>withRWS</a> f m) r s = <a>uncurry</a>
--   (<a>runRWS</a> m) (f r s)</pre></li>
--   </ul>
withRWS :: () => (r' -> s -> (r, s)) -> RWS r w s a -> RWS r' w s a

-- | Evaluate a computation with the given initial state and environment,
--   returning the final value and output, discarding the final state.
evalRWST :: Monad m => RWST r w s m a -> r -> s -> m (a, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final state and output, discarding the final value.
execRWST :: Monad m => RWST r w s m a -> r -> s -> m (s, w)

-- | Map the inner computation using the given function.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>mapRWST</a> f m) r s = f (<a>runRWST</a> m
--   r s)</pre></li>
--   </ul>
mapRWST :: () => (m (a, s, w) -> n (b, s, w')) -> RWST r w s m a -> RWST r w' s n b

-- | <tt><a>withRWST</a> f m</tt> executes action <tt>m</tt> with an
--   initial environment and state modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>withRWST</a> f m) r s = <a>uncurry</a>
--   (<a>runRWST</a> m) (f r s)</pre></li>
--   </ul>
withRWST :: () => (r' -> s -> (r, s)) -> RWST r w s m a -> RWST r' w 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.
liftCallCC' :: Monoid w => CallCC m (a, s, w) (b, s, w) -> CallCC (RWST r w 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 :: (Monoid w, Monad m) => (s -> a) -> RWST r w s m a

-- | <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 :: (Monoid w, Monad m) => (s -> s) -> RWST r w s m ()

-- | <tt><a>put</a> s</tt> sets the state within the monad to <tt>s</tt>.
put :: (Monoid w, Monad m) => s -> RWST r w s m ()

-- | Fetch the current value of the state within the monad.
get :: (Monoid w, Monad m) => RWST r w s m s

-- | Construct a state monad computation from a state transformer function.
state :: (Monoid w, Monad m) => (s -> (a, s)) -> RWST r w s m a

-- | <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>runRWST</a> (<a>censor</a> f m) r s = <a>liftM</a> (\ (a,
--   w) -&gt; (a, f w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
censor :: Monad m => (w -> w) -> RWST r w s m a -> RWST r w s m a

-- | <tt><a>pass</a> m</tt> is an action that executes the action
--   <tt>m</tt>, which returns a value and a function, and returns the
--   value, applying the function to the output.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>pass</a> m) r s = <a>liftM</a> (\ ((a, f),
--   w) -&gt; (a, f w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
pass :: Monad m => RWST r w s m (a, w -> w) -> RWST r w s 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>runRWST</a> (<a>listens</a> f m) r s = <a>liftM</a> (\ (a,
--   w) -&gt; ((a, f w), w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
listens :: Monad m => (w -> b) -> RWST r w s m a -> RWST r w s 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>runRWST</a> (<a>listen</a> m) r s = <a>liftM</a> (\ (a, w)
--   -&gt; ((a, w), w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
listen :: Monad m => RWST r w s m a -> RWST r w s m (a, w)

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

-- | Construct a writer computation from a (result, output) pair.
writer :: Monad m => (a, w) -> RWST r w s 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 :: (Monoid w, Monad m) => (r -> a) -> RWST r w s m a

-- | Execute a computation in a modified environment
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>local</a> f m) r s = <a>runRWST</a> m (f
--   r) s</pre></li>
--   </ul>
local :: () => (r -> r) -> RWST r w s m a -> RWST r w s m a

-- | Fetch the value of the environment.
ask :: (Monoid w, Monad m) => RWST r w s m r

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


-- | <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><a>&gt;&gt;=</a> 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>
--   <li><tt>m</tt>: The monad that the <a>MSF</a> may take side effects
--   in.</li>
--   <li><tt>a</tt>: The input type</li>
--   <li><tt>b</tt>: The output type</li>
--   <li><tt>e</tt>: The type of exceptions that can be thrown</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 <tt>Just e</tt>, 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

-- | Converts an <a>MSF</a> in <a>MaybeT</a> to an <a>MSF</a> in
--   <a>ExceptT</a>. Whenever <a>Nothing</a> is thrown, throw <tt>()</tt>
--   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. Loses 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 :: (Functor m, 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 <a>MSFExcept</a> constructor, used to enter the
--   <a>MSFExcept</a> 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
handleExceptT :: Monad m => MSF (ExceptT e1 m) a b -> (e1 -> MSF (ExceptT e2 m) a b) -> MSF (ExceptT e2 m) a b

-- | 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 an <a>MSF</a> from a monadic action.
--   
--   Runs a monadic action that produces an <a>MSF</a> on the first
--   iteration/step, and uses that <a>MSF</a> 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 ()
switch :: Monad m => MSF m a (b, Maybe c) -> (c -> MSF m a b) -> MSF m a b

-- | 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 <a>MSF</a> 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
handleGen :: (a -> m1 (b1, MSF m1 a b1) -> m2 (b2, MSF m2 a b2)) -> MSF m1 a b1 -> MSF m2 a b2

-- | 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 :: Type -> Type) 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> (<a>lift</a> m) h = <a>lift</a> m</pre></li>
--   <li><pre><a>catchE</a> (<a>throwE</a> e) h = 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 :: Monad m => Either e a -> ExceptT e m 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 :: (Functor m, 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 <a>MSF</a> 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 :: Type -> Type) a
MaybeT :: m (Maybe a) -> MaybeT a
[runMaybeT] :: MaybeT a -> m (Maybe a)

-- | Converts an <a>MSF</a> in <a>MaybeT</a> to an <a>MSF</a> in
--   <a>ExceptT</a>. Whenever <a>Nothing</a> is thrown, throw <tt>()</tt>
--   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 <a>MSF</a>s that produce vector
--   spaces. This allows you to use vector operators with <a>MSF</a>s 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.InternalCore.MSF m a v)
instance (GHC.Base.Monad m, Data.VectorSpace.VectorSpace v) => Data.VectorSpace.VectorSpace (Data.MonadicStreamFunction.InternalCore.MSF m a v)
