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


-- | A fixpoint of a functor that can be annotated
--   
--   This library exposes a type representing the fixpoint of a functor,
--   with an annotation at every node.
@package annotated-fix
@version 0.1.0.0


-- | This modules exposes a type representing the fixpoint of a functor
--   type, paired with an annotation. It exports the recursion-schemes
--   instances for this type and a few specific utility functions.
--   
--   <h1>Motivation</h1>
--   
--   Suppose one has an Abstract Syntax Tree (AST) for the lambda calculus:
--   
--   <pre>
--   data Term = Var String | App Term Term | Lam String Term
--   </pre>
--   
--   Such a type can easily be used with the recursion-schemes library, but
--   it is not always convenient to use this type. It is often the case
--   that one wants to add extra informations to every node of an AST, such
--   as location or type information. In this case, instead of adding those
--   informations as an extra-field to all data constructors, one could
--   prefer to represent terms as a record of a descriptor and the
--   information present at every node, like so:
--   
--   <pre>
--   data TermDesc = Var String | App Term Term | Lam String Term
--   data Term = Term { termDesc :: TermDesc
--                    , termTyp  :: Typ
--                    , termLoc  :: Loc
--                    , ...
--                    }
--   </pre>
--   
--   This library implements this general pattern through the <a>Annot</a>
--   type, representing the fixpoint of a functor type, paired with some
--   annotation. In this setting, the above example would be represented
--   like so:
--   
--   <pre>
--   data TermDesc r = Var String | App r r | Lam String r
--   
--   data TermAnn = TermAnn { termTyp :: Typ
--                          , termLoc :: Loc
--                          , ...
--                          }
--   
--   type Term = Annot TermDesc TermAnn
--   </pre>
module Data.Functor.Annotated

-- | The fixpoint type of functor <tt>f</tt>, with some annotation
--   <tt>a</tt>.
data Annot f a
Annot :: a -> f (Annot f a) -> Annot f a

-- | Strips one level of annotation
strip :: Annot f a -> f (Annot f a)

-- | Extracts the annotation
annotation :: Annot f a -> a

-- | Annotates all the node of a functor's fixpoint value
annotate :: Functor f => (f (Annot f a) -> a) -> Fix f -> Annot f a

-- | Generalized version of <a>annotate</a> for instances of
--   <a>Recursive</a>
annotateRec :: Recursive t => (Base t (Annot (Base t) a) -> a) -> t -> Annot (Base t) a

-- | Strips all annotations
deannotate :: Functor f => Annot f a -> Fix f

-- | Generalized version of <a>deannotate</a> for instances of
--   <a>Corecursive</a>
deannotateCorec :: Corecursive t => Annot (Base t) a -> t

-- | <a>cata</a>morphism with access to the current annotation
cataAnn :: Functor f => (a -> f b -> b) -> Annot f a -> b

-- | <a>para</a>morphism with access to the current annotation
paraAnn :: Functor f => (a -> f (Annot f a, b) -> b) -> Annot f a -> b
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Data.Functor.Annotated.Annot f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Data.Functor.Annotated.Annot f)
instance GHC.Base.Functor f => GHC.Base.Functor (Data.Functor.Annotated.Annot f)
instance GHC.Generics.Generic (Data.Functor.Annotated.Annot f a)
instance GHC.Base.Functor f => Data.Functor.Foldable.Recursive (Data.Functor.Annotated.Annot f a)