-- 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 Ref 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
--   unsafePerformIO 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 MuRef is the mechanism for allowing a
--   structure to be reified into a graph, and several examples of this are
--   provided.
--   
--   © 2009 Andy Gill; BSD3 license.
@package data-reify
@version 0.6.4

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

-- | Graph is a basic graph structure over nodes of the higher kind
--   e, 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 Array, IntMap, or into a
--   Martin Erwig's Functional Graph, as required.
data Graph (e :: Type -> Type)
Graph :: [(Unique, e Unique)] -> Unique -> Graph (e :: Type -> Type)
type Unique = Int
instance GHC.Internal.Show.Show (e Data.Reify.Graph.Unique) => GHC.Internal.Show.Show (Data.Reify.Graph.Graph e)

module Data.Reify

-- | MuRef 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 DeRef a :: Type -> Type;
}
mapDeRef :: (MuRef a, Applicative f) => (forall b. (MuRef b, DeRef a ~ DeRef b) => b -> f u) -> a -> f (DeRef a u)

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

-- | reifyGraphs takes a Traversable container 't s' of a
--   data structure s admitting MuRef, and returns a 't
--   (Graph (DeRef s))' with the graph nodes resolved within the same
--   context.
--   
--   This allows for, e.g., a list of mutually recursive structures.
reifyGraphs :: (MuRef s, Traversable t) => t s -> IO (t (Graph (DeRef s)))
instance GHC.Classes.Eq Data.Reify.DynStableName
instance Data.Hashable.Class.Hashable Data.Reify.DynStableName
