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


-- | Composable objects
--   
@package objective
@version 1.0.4


module Control.Object.Object

-- | The type <tt>Object f g</tt> represents objects which can handle
--   messages <tt>f</tt>, perform actions in the environment <tt>g</tt>. It
--   can be thought of as an automaton that transforms effects.
--   <a>Object</a>s can be composed just like functions using
--   <a>@&gt;&gt;@</a>; the identity element is <a>echo</a>. Objects are
--   morphisms of the category of actions.
--   
--   <ul>
--   <li><i><i>Naturality</i></i> <tt>runObject obj . fmap f ≡ fmap f .
--   runObject obj</tt></li>
--   </ul>
newtype Object f g
Object :: (forall x. f x -> g (x, Object f g)) -> Object f g
runObject :: Object f g -> forall x. f x -> g (x, Object f g)

-- | The trivial object
echo :: Functor f => Object f f

-- | The categorical composition of objects.
(@>>@) :: Functor h => Object f g -> Object g h -> Object f h

-- | Reversed '(<tt>&gt;&gt;</tt>)'
(@<<@) :: Functor h => Object g h -> Object f g -> Object f h

-- | Lift a natural transformation into an object.
liftO :: Functor g => (forall x. f x -> g x) -> Object f g

-- | Higher-order profunctors
class HProfunctor k
(^>>@) :: (HProfunctor k, Functor h) => (forall x. f x -> g x) -> k g h -> k f h
(@>>^) :: (HProfunctor k, Functor h) => k f g -> (forall x. g x -> h x) -> k f h

-- | Combine objects so as to handle a <a>Sum</a> of interfaces.
(@||@) :: Functor h => Object f h -> Object g h -> Object (f `Sum` g) h

-- | An unwrapped analog of <a>stateful</a> <tt>id = unfoldO runObject</tt>
--   <tt>iterative = unfoldO iterObject</tt> <tt>cascade = unfoldO
--   cascadeObject</tt>
unfoldO :: Functor g => (forall a. r -> f a -> g (a, r)) -> r -> Object f g

-- | Same as <a>unfoldO</a> but requires <a>Monad</a> instead
unfoldOM :: Monad m => (forall a. r -> f a -> m (a, r)) -> r -> Object f m

-- | Build a stateful object.
--   
--   <pre>
--   stateful t s = t ^&gt;&gt;@ variable s
--   </pre>
stateful :: Monad m => (forall a. t a -> StateT s m a) -> s -> Object t m

-- | Flipped <a>stateful</a>. it is convenient to use with the LambdaCase
--   extension.
(@~) :: Monad m => s -> (forall a. t a -> StateT s m a) -> Object t m

-- | A mutable variable.
--   
--   <pre>
--   variable = stateful id
--   </pre>
variable :: Monad m => s -> Object (StateT s m) m

-- | An infix alias for <a>runObject</a>
(@-) :: Object f g -> f x -> g (x, Object f g)

-- | Cascading
iterObject :: Monad m => Object f m -> Free f a -> m (a, Object f m)

-- | Objects can consume free monads
iterative :: Monad m => Object f m -> Object (Free f) m

-- | Pass zero or more messages to an object.
cascadeObject :: Monad m => Object t m -> Skeleton t a -> m (a, Object t m)

-- | Add capability to handle multiple messages at once.
cascading :: Monad m => Object t m -> Object (Skeleton t) m

-- | Send a message to objects through a traversal.
announcesOf :: (Monad m, Monoid r) => ((Object t m -> WriterT r m (Object t m)) -> s -> WriterT r m s) -> t a -> (a -> r) -> StateT s m r

-- | Send a message to objects in a traversable container.
--   
--   <pre>
--   announce = withBuilder . announcesOf traverse
--   </pre>
announce :: (Traversable t, Monad m) => f a -> StateT (t (Object f m)) m [a]
withBuilder :: Functor f => ((a -> Endo [a]) -> f (Endo [a])) -> f [a]
instance [safe] Typeable Object
instance [safe] HProfunctor Object


module Control.Object.Mortal

-- | A <a>Mortal</a> is an object that may die. A mortal yields a final
--   result upon death. <tt><a>Mortal</a> f g</tt> forms a <a>Monad</a>:
--   <a>return</a> is a dead object and (<a>&gt;&gt;=</a>) prolongs the
--   life of the left object.
--   
--   <pre>
--   Object f g ≡ Mortal f g Void
--   </pre>
newtype Mortal f g a
Mortal :: Object f (EitherT a g) -> Mortal f g a
unMortal :: Mortal f g a -> Object f (EitherT a g)

-- | Construct a mortal in a <a>Object</a> construction manner.
mortal :: Monad m => (forall x. f x -> EitherT a m (x, Mortal f m a)) -> Mortal f m a

-- | Restricted <a>Mortal</a> constuctor which can be applied to
--   <tt>transit</tt>, <tt>fromFoldable</tt> without ambiguousness.
mortal_ :: Object f (EitherT () g) -> Mortal f g ()

-- | Send a message to a mortal.
runMortal :: Monad m => Mortal f m a -> f x -> EitherT a m (x, Mortal f m a)

-- | Turn an object into a mortal without death.
immortal :: Monad m => Object f m -> Mortal f m x

-- | Send a message to mortals through a filter.
apprisesOf :: (Monad m, Monoid r) => ((Mortal f m b -> WriterT r m (Maybe (Mortal f m b))) -> s -> WriterT r m s) -> f a -> (a -> r) -> (b -> r) -> StateT s m r

-- | Send a message to mortals in a <a>Witherable</a> container.
--   
--   <pre>
--   apprises = apprisesOf wither
--   </pre>
apprises :: (Witherable t, Monad m, Applicative m, Monoid r) => f a -> (a -> r) -> (b -> r) -> StateT (t (Mortal f m b)) m r

-- | Send a message to mortals in a container.
apprise :: (Witherable t, Monad m, Applicative m) => f a -> StateT (t (Mortal f m r)) m ([a], [r])
instance MonadTrans (Mortal f)
instance Monad m => Monad (Mortal f m)
instance (Functor m, Monad m) => Applicative (Mortal f m)
instance (Functor m, Monad m) => Functor (Mortal f m)


module Control.Object.Instance

-- | TMVar-based instance
data Instance f g
InstRef :: (forall x. e x -> f x) -> (forall x. g x -> h x) -> TMVar (Object f g) -> Instance e h

-- | Create a new instance. This can be used inside
--   <tt>unsafePerformIO</tt> to create top-level instances.
new :: MonadIO m => Object f g -> m (Instance f g)

-- | Create a new instance, having it sitting on the current environment.
newSettle :: MonadIO m => Object f m -> m (Instance f m)

-- | Create a new instance.
newSTM :: MonadSTM m => Object f g -> m (Instance f g)

-- | Invoke a method with an explicit landing function.
invokeOn :: (MonadIO m, MonadMask m) => (forall x. g x -> m x) -> Instance f g -> f a -> m a

-- | Invoke a method with an explicit landing function.
invokeOnSTM :: (forall x. g x -> STM x) -> Instance f g -> f a -> STM a

-- | Invoke a method.
(.-) :: (MonadIO m, MonadMask m) => Instance f m -> f a -> m a

-- | Invoke a method, atomically.
(..-) :: MonadSTM m => Instance f STM -> f a -> m a

-- | Take a snapshot of an instance.
snapshot :: (MonadSTM m, Functor g) => Instance f g -> m (Object f g)
instance [safe] HProfunctor Instance


module Data.Functor.Request

-- | <tt><a>Request</a> a b</tt> is the type of a request that sends
--   <tt>a</tt> to receive <tt>b</tt>.
data Request a b r
Request :: a -> (b -> r) -> Request a b r

-- | Apply a function to the body of <a>Request</a>
mapRequest :: (a -> a') -> Request a b r -> Request a' b r

-- | Create a <a>Request</a>.
request :: a -> Request a b b

-- | Handle a <a>Request</a>, smashing the continuation.
accept :: Functor m => (a -> m b) -> Request a b r -> m r

-- | Add a step as a mealy machine
mealy :: Functor m => (a -> m (b, Object (Request a b) m)) -> Object (Request a b) m

-- | The flyweight object
flyweight :: (Applicative m, Eq k, Hashable k) => (k -> m a) -> Object (Request k a) m

-- | Compose mealy machines
(>~~>) :: Monad m => Object (Request a b) m -> Object (Request b c) m -> Object (Request a c) m
accumulator :: Applicative m => (b -> a -> b) -> b -> Object (Request a b) m

-- | Create a mealy machine from a time-varying action.
--   
--   <pre>
--   animate f ≡ accumulator (+) 0 &gt;~~&gt; liftO (accept f)
--   </pre>
animate :: (Applicative m, Num t) => (t -> m a) -> Object (Request t a) m

-- | Like <a>animate</a>, but the life is limited.
transit :: (Alternative m, Fractional t, Ord t) => t -> (t -> m a) -> Object (Request t a) m
instance [safe] Typeable Request
instance [safe] Functor (Request a b)
instance [safe] Monoid a => Applicative (Request a b)
instance [safe] Profunctor (Request a)


module Control.Object