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


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


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
infixr 1 @>>@

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

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

-- | 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><tt>iterative</tt> = unfoldO <tt>iterObject</tt></tt>
--   <tt><a>cascading</a> = unfoldO <a>cascadeObject</a></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 super convenient to use with the
--   LambdaCase extension.
(@~) :: Monad m => s -> (forall a. t a -> StateT s m a) -> Object t m
infix 1 @~

-- | 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)
infixr 3 @-

-- | 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
data Fallible t a
[Fallible] :: t a -> Fallible t (Maybe a)
filteredO :: Monad m => (forall x. t x -> Bool) -> Object t m -> Object (Fallible t) m
filterO :: (forall x. t x -> Bool) -> Object (Fallible t) (Skeleton t)

-- | Send a message to an object through a lens.
invokesOf :: Monad m => ((Object t m -> WriterT r m (Object t m)) -> s -> WriterT r m s) -> t a -> (a -> r) -> StateT s m r
invokes :: (Traversable t, Monad m, Monoid r) => f a -> (a -> r) -> StateT (t (Object f m)) m r

-- | A method invocation operator on <a>StateT</a>.
(@!=) :: Monad m => ((Object t m -> WriterT a m (Object t m)) -> s -> WriterT a m s) -> t a -> StateT s m a

-- | Send a message to objects in a traversable container.
--   
--   <pre>
--   announce = withBuilder . invokesOf 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]


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 (ExceptT a g) -> Mortal f g a
[unMortal] :: Mortal f g a -> Object f (ExceptT a g)

-- | Construct a mortal in a <a>Object</a> construction manner.
mortal :: Monad m => (forall x. f x -> ExceptT 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 (ExceptT () g) -> Mortal f g ()

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

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

-- | Send a message to mortals through a filter.
apprisesOf :: Monad m => WitherLike' (WriterT r m) s (Mortal f m b) -> 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 (GHC.Base.Functor m, GHC.Base.Monad m) => GHC.Base.Functor (Control.Object.Mortal.Mortal f m)
instance (GHC.Base.Functor m, GHC.Base.Monad m) => GHC.Base.Applicative (Control.Object.Mortal.Mortal f m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Object.Mortal.Mortal f m)
instance Control.Monad.Trans.Class.MonadTrans (Control.Object.Mortal.Mortal f)


module Control.Object.Instance
type Instance f g = MVar (Object f g)

-- | 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)
invokeOnUsing :: (MonadIO m, MonadMask m) => (Object f g -> t a -> g (a, Object f g)) -> (forall x. g x -> m x) -> Instance f g -> t a -> m a

-- | Invoke a method with an explicit landing function. In case of
--   exception, the original object will be set.
invokeOn :: (MonadIO m, MonadMask m) => (forall x. g x -> m x) -> Instance f g -> f a -> m a

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

-- | Try to invoke a method. If the instance is unavailable, it returns
--   Nothing.
(?-) :: (MonadIO m, MonadMask m) => Instance f m -> f a -> m (Maybe a)


module Control.Object