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


-- | Reify a recursive data structure into an explicit graph.
--   
--   'data-reify' provided the ability to turn recursive structures into
--   explicit graphs. Many (implicitly or explicitly) recursive data
--   structure can be given this ability, via a type class instance. This
--   gives an alternative to using <a>Ref</a> for observable sharing.
--   
--   Observable sharing in general is unsafe, so we use the IO monad to
--   bound this effect, but can be used safely even with
--   <a>unsafePerformIO</a> if some simple conditions are met. Typically
--   this package will be used to tie the knot with DSL's that depend of
--   observable sharing, like Lava.
--   
--   Providing an instance for <a>MuRef</a> is the mechanism for allowing a
--   structure to be reified into a graph, and several examples of this are
--   provided.
--   
--   Version 0.2 of 'data-reify' used <a>StableName</a>s, and was much
--   faster. Version 0.3 provided two versions of <a>MuRef</a>, the
--   mono-typed version, for trees of a single type, and the dynamic-typed
--   version, for trees of different types. Version 0.4 uses <a>Int</a> as
--   a synonym for <a>Unique</a> rather than <a>Data.Unique</a> for node
--   ids, by popular demand.
--   
--   © 2009 Andy Gill; BSD3 license.
@package data-reify
@version 0.4


-- | This is the shared definition of a <a>Graph</a> in Data.Reify.
module Data.Reify.Graph

-- | <a>Graph</a> is a basic graph structure over nodes of the higher kind
--   <tt>e</tt>, with a single root. There is an assumption that there is
--   no Unique used in a node which does not have a corresponding entry is
--   the association list. The idea with this structure is that it is
--   trivial to convert into an <tt>Array</tt>, <tt>IntMap</tt>, or into a
--   Martin Erwig's Functional Graph, as required.
data Graph e
Graph :: [(Unique, e Unique)] -> Unique -> Graph e
type Unique = Int
instance (Show (e Int)) => Show (Graph e)


-- | This is a <a>Dynamic</a> version of <tt>Data.Reify</tt>, that can
--   reify nodes of different types inside a sigle graph, provided they
--   unify to a common representation.
module Data.Dynamic.Reify

-- | <a>MuRef</a> is a class that provided a way to reference into a
--   specific type, and a way to map over the deferenced internals.
class MuRef a where { type family DeRef a :: * -> *; }
mapDeRef :: (MuRef a, Applicative f) => (forall b. (MuRef b, Typeable b, (DeRef a) ~ (DeRef b)) => b -> f u) -> a -> f (DeRef a u)

-- | <a>reifyGraph</a> takes a data structure that admits <a>MuRef</a>, and
--   returns a <a>Graph</a> that contains the dereferenced nodes, with
--   their children as <a>Int</a> rather than recursive values.
reifyGraph :: (MuRef s, Typeable s) => s -> IO (Graph (DeRef s))

module Data.Reify

-- | <a>MuRef</a> is a class that provided a way to reference into a
--   specific type, and a way to map over the deferenced internals.
class MuRef a where { type family DeRef a :: * -> *; }
mapDeRef :: (MuRef a, Applicative m) => (a -> m u) -> a -> m (DeRef a u)

-- | <a>reifyGraph</a> takes a data structure that admits <a>MuRef</a>, and
--   returns a <a>Graph</a> that contains the dereferenced nodes, with
--   their children as <a>Int</a> rather than recursive values.
reifyGraph :: (MuRef s) => s -> IO (Graph (DeRef s))