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


-- | Provides a nice API for rendering data types that change
--   over time.
--   
--   Instances of Renderable conform to a simple API that makes their
--   visual representations composable through hashing and cacheing. Also
--   provided are some convenience functions for writing Renderable
--   instances, as well as top level rendering functions.
@package renderable
@version 0.0.0.2

module Data.Renderable

-- | Any element is decomposable by returning a list consisting of itself.

-- | Any Element is renderable by rendering its contained datatype.

-- | A tuple is renderable when it is a pairing of a transform and another
--   renderable datatype.

-- | A Maybe is renderable by rendering the datatype contained in the Just
--   constructor or by rendering nothing.

-- | A list of renderable instances is renderable by rendering each
--   instance.

-- | Render a datatype using renderings stored in the given cache.
renderData :: (Monad m, Renderable a, Monoid (RenderTfrm a)) => Cache m (RenderTfrm a) -> a -> m ()

-- | Render only the hidden layers of a datatype using renderings stored in
--   the given cache. This is sometimes useful for debugging.
renderDataHidden :: (Renderable a, Monad m, Monoid (RenderTfrm a)) => Cache m (RenderTfrm a) -> (RenderTfrm a) -> a -> m ()

-- | Render the composite of a datatype using renderings stored in the
--   given cache.
renderComposite :: (Monad m, Monoid t) => Cache m t -> t -> Composite t -> m ()

-- | If needed, create a new rendering given some resources, insert it in
--   the cache and return the new cache.
attachIfNeeded :: (Renderable a, Monad (RenderMonad a), Monoid (RenderTfrm a), Hashable a) => RenderRsrc a -> Cache (RenderMonad a) (RenderTfrm a) -> a -> (RenderMonad a) (Cache (RenderMonad a) (RenderTfrm a))

-- | Detach any renderings that are not needed to render the given data.
detachUnused :: (Monad m, Renderable a) => Cache m t -> a -> m (Cache m t)

-- | Remove a rendering from a cache and clean up the resources allocated
--   for that rendering.
detach :: Monad m => Cache m t -> Int -> m (Cache m t)

-- | An instance of Decomposable can be broken down into a number of
--   elements.
class Decomposable a m r t
decompose :: Decomposable a m r t => a -> [Element m r t]

-- | Element is a generic existential type that can be used to enclose
--   instances of Renderable in order to contain them all in a
--   heterogeneous list. <tt>m</tt>, <tt>r</tt> and <tt>t</tt> must be
--   shared with all Renderable instances stored in a heterogeneous list of
--   Elements.
data Element m r t
Element :: a -> Element m r t
class Renderable a where {
    type family RenderMonad a :: * -> *;
    type family RenderTfrm a :: *;
    type family RenderRsrc a :: *;
}

-- | The name of a renderable datatype. This is mostly for debugging.
nameOf :: Renderable a => a -> String

-- | Store the rendering of a datatype in a cache keyed by the hash of that
--   datatype. Returns the new cache.
cache :: (Renderable a, Monad (RenderMonad a), Monoid (RenderTfrm a)) => RenderRsrc a -> Cache (RenderMonad a) (RenderTfrm a) -> a -> (RenderMonad a) (Cache (RenderMonad a) (RenderTfrm a))

-- | The entire composite list of renderings for a given datatype.
composite :: Renderable a => a -> Composite (RenderTfrm a)

-- | A cache of renderings.
type Cache m t = IntMap (Rendering m t)

-- | A rendering is a type that contains some effectful computation for
--   displaying something given a transform. It also contains an effectful
--   computation for cleaning up any resources allocated during its
--   creation.
data Rendering m t
Rendering :: (t -> m ()) -> m () -> Rendering m t
[render] :: Rendering m t -> t -> m ()
[clean] :: Rendering m t -> m ()

-- | A composite is a representation of the entire rendered datatype. It is
--   a flattened list of all the renderings (denoted by hash), along with
--   that rendering's local transformation. If a rendering is explicitly
--   run by another rendering (as in a Renderable class definition) then
--   the transformation for that rendering should be Nothing, which will
--   keep <a>renderComposite</a> from running that rendering in addition to
--   the rendering its included in. For example: <tt> [(0, Just $ Transform
--   (10,10) (0.5,0.5) 0) ,(1, Nothing) ] </tt> The above is a composite of
--   two renderings, the first will be rendered by <a>renderComposite</a>
--   using the given transform while the second is effectively hidden but
--   present. Being present in the composite will keep <a>detachUnused</a>
--   from detaching and cleaning the rendering.
type Composite a = [(Int, Maybe a)]
instance Data.Renderable.Decomposable (Data.Renderable.Element m r t) m r t
instance Data.Renderable.Renderable (Data.Renderable.Element m r t)
instance (t ~ Data.Renderable.RenderTfrm a, GHC.Show.Show t, GHC.Base.Monoid t, Data.Hashable.Class.Hashable a, Data.Renderable.Renderable a) => Data.Renderable.Renderable (t, a)
instance (Data.Renderable.Renderable a, Data.Hashable.Class.Hashable a, GHC.Show.Show a) => Data.Renderable.Renderable (GHC.Base.Maybe a)
instance (Data.Renderable.Renderable a, Data.Hashable.Class.Hashable a) => Data.Renderable.Renderable [a]
instance Data.Hashable.Class.Hashable (Data.Renderable.Element m r t)
instance GHC.Classes.Eq (Data.Renderable.Element m r t)
instance GHC.Show.Show (Data.Renderable.Element m r t)
instance GHC.Base.Monad m => GHC.Base.Monoid (Data.Renderable.Rendering m t)