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


-- | Generic programming library for regular datatypes.
--   
--   This package provides generic functionality for regular datatypes.
--   Regular datatypes are recursive datatypes such as lists, binary trees,
--   etc. This library cannot be used with mutually recursive datatypes or
--   with nested datatypes. The multirec library [1] can deal with mutually
--   recursive datatypes.
--   
--   This library has been described in the paper:
--   
--   <ul>
--   <li><i>A Lightweight Approach to Datatype-Generic Rewriting.</i>
--   Thomas van Noort, Alexey Rodriguez, Stefan Holdermans, Johan Jeuring,
--   Bastiaan Heeren. ACM SIGPLAN Workshop on Generic Programming
--   2008.</li>
--   </ul>
--   
--   More information about this library can be found at
--   <a>http://www.cs.uu.nl/wiki/GenericProgramming/Regular</a>.
--   
--   [1]
--   <a>http://hackage.haskell.org/cgi-bin/hackage-scripts/package/multirec</a>
@package regular
@version 0.1


-- | Summary: Representation for constructors.
module Generics.Regular.Constructor

-- | Class for datatypes that represent data constructors. For non-symbolic
--   constructors, only <a>conName</a> has to be defined. The weird
--   argument is supposed to be instantiated with C from base, hence the
--   complex kind.
class Constructor c
conName :: (Constructor c) => t c (f :: * -> *) r -> String
conFixity :: (Constructor c) => t c (f :: * -> *) r -> Fixity

-- | Datatype to represent the fixity of a constructor. An infix
--   declaration directly corresponds to an application of <a>Infix</a>.
data Fixity
Prefix :: Fixity
Infix :: Associativity -> Int -> Fixity
data Associativity
LeftAssociative :: Associativity
RightAssociative :: Associativity
NotAssociative :: Associativity
instance Eq Associativity
instance Show Associativity
instance Ord Associativity
instance Read Associativity
instance Eq Fixity
instance Show Fixity
instance Ord Fixity
instance Read Fixity


-- | Summary: Types for structural representation.
module Generics.Regular.Base

-- | Structure type for constant values.
data K a r
K :: a -> K a r
unK :: K a r -> a

-- | Structure type for recursive values.
data I r
I :: r -> I r
unI :: I r -> r

-- | Structure type for empty constructors.
data U r
U :: U r

-- | Structure type for alternatives in a type.
data (:+:) f g r
L :: (f r) -> :+: f g r
R :: (g r) -> :+: f g r

-- | Structure type for fields of a constructor.
data (:*:) f g r
(:*:) :: f r -> g r -> :*: f g r

-- | Structure type to store the name of a constructor.
data C c f r
C :: f r -> C c f r
unC :: C c f r -> f r

-- | Class for datatypes that represent data constructors. For non-symbolic
--   constructors, only <a>conName</a> has to be defined. The weird
--   argument is supposed to be instantiated with C from base, hence the
--   complex kind.
class Constructor c
conName :: (Constructor c) => t c (f :: * -> *) r -> String
conFixity :: (Constructor c) => t c (f :: * -> *) r -> Fixity

-- | Datatype to represent the fixity of a constructor. An infix
--   declaration directly corresponds to an application of <a>Infix</a>.
data Fixity
Prefix :: Fixity
Infix :: Associativity -> Int -> Fixity
data Associativity
LeftAssociative :: Associativity
RightAssociative :: Associativity
NotAssociative :: Associativity

-- | The well-known fixed-point type.
newtype Fix f
In :: (f (Fix f)) -> Fix f

-- | The type class <tt>Regular</tt> captures the structural representation
--   of a type and the corresponding embedding-projection pairs.
--   
--   To be able to use the generic functions, the user is required to
--   provide an instance of this type class.
class Regular a
from :: (Regular a) => a -> PF a a
to :: (Regular a) => PF a a -> a

-- | The type family <tt>PF</tt> represents the pattern functor of a
--   datatype.
--   
--   To be able to use the generic functions, the user is required to
--   provide an instance of this type family.
instance (Functor f) => Functor (C c f)
instance (Functor f, Functor g) => Functor (f :*: g)
instance (Functor f, Functor g) => Functor (f :+: g)
instance Functor U
instance Functor (K a)
instance Functor I


-- | Summary: Generic functionality for regular dataypes: mapM, flatten,
--   zip, equality, show, value generation and fold.
module Generics.Regular.Functions

-- | The <tt>GMap</tt> class defines a monadic functorial map.
class GMap f
fmapM :: (GMap f, Monad m) => (a -> m b) -> f a -> m (f b)

-- | The <tt>CrushR</tt> class defines a right-associative crush on
--   functorial values.
class CrushR f
crushr :: (CrushR f) => (a -> b -> b) -> b -> f a -> b

-- | Flatten a structure by collecting all the elements present.
flatten :: (CrushR f) => f a -> [a]

-- | The <tt>Zip</tt> class defines a monadic zip on functorial values.
class Zip f
fzipM :: (Zip f, Monad m) => (a -> b -> m c) -> f a -> f b -> m (f c)

-- | Functorial zip with a non-monadic function, resulting in a monadic
--   value.
fzip :: (Zip f, Monad m) => (a -> b -> c) -> f a -> f b -> m (f c)

-- | Partial functorial zip with a non-monadic function.
fzip' :: (Zip f) => (a -> b -> c) -> f a -> f b -> f c

-- | Equality on values based on their structural representation.
geq :: (b ~ (PF a), Regular a, CrushR b, Zip b) => a -> a -> Bool

-- | The <tt>GShow</tt> class defines a show on values.
class GShow f
gshowf :: (GShow f) => (a -> ShowS) -> f a -> ShowS
gshow :: (Regular a, GShow (PF a)) => a -> ShowS

-- | The <tt>LRBase</tt> class defines two functions, <tt>leftb</tt> and
--   <tt>rightb</tt>, which should produce different values.
class LRBase a
leftb :: (LRBase a) => a
rightb :: (LRBase a) => a

-- | The <tt>LR</tt> class defines two functions, <tt>leftf</tt> and
--   <tt>rightf</tt>, which should produce different functorial values.
class LR f
leftf :: (LR f) => a -> f a
rightf :: (LR f) => a -> f a

-- | Produces a value which should be different from the value returned by
--   <tt>right</tt>.
left :: (Regular a, LR (PF a)) => a

-- | Produces a value which should be different from the value returned by
--   <tt>left</tt>.
right :: (Regular a, LR (PF a)) => a
type Algebra a r = Alg (PF a) r

-- | The class fold explains how to convert an algebra <a>Alg</a> into a
--   function from functor to result.
class Fold f :: (* -> *)
alg :: (Fold f) => Alg f r -> f r -> r

-- | Fold with convenient algebras.
fold :: (Regular a, Fold (PF a), Functor (PF a)) => Algebra a r -> a -> r

-- | For constructing algebras it is helpful to use this pairing
--   combinator.
(&) :: a -> b -> (a, b)
instance (Fold f) => Fold (C c f)
instance (Fold g) => Fold (I :*: g)
instance (Fold g) => Fold (K a :*: g)
instance (Fold f, Fold g) => Fold (f :+: g)
instance Fold I
instance Fold U
instance Fold (K a)
instance (LR f) => LR (C c f)
instance (LR f, LR g) => LR (f :*: g)
instance (LR f, LR g) => LR (f :+: g)
instance LR U
instance (LRBase a) => LR (K a)
instance LR I
instance (LRBase a) => LRBase [a]
instance LRBase Char
instance LRBase Integer
instance LRBase Int
instance (Constructor c, GShow f) => GShow (C c f)
instance (GShow f, GShow g) => GShow (f :*: g)
instance (GShow f, GShow g) => GShow (f :+: g)
instance GShow U
instance (Show a) => GShow (K a)
instance GShow I
instance (Zip f) => Zip (C c f)
instance (Zip f, Zip g) => Zip (f :*: g)
instance (Zip f, Zip g) => Zip (f :+: g)
instance Zip U
instance (Eq a) => Zip (K a)
instance Zip I
instance (CrushR f) => CrushR (C c f)
instance (CrushR f, CrushR g) => CrushR (f :*: g)
instance (CrushR f, CrushR g) => CrushR (f :+: g)
instance CrushR U
instance CrushR (K a)
instance CrushR I
instance (GMap f) => GMap (C c f)
instance (GMap f, GMap g) => GMap (f :*: g)
instance (GMap f, GMap g) => GMap (f :+: g)
instance GMap U
instance GMap (K a)
instance GMap I


-- | This module contains Template Haskell code that can be used to
--   automatically generate the boilerplate code for the regular library.
module Generics.Regular.TH

-- | Given a datatype name, derive datatypes and instances of class
--   <a>Constructor</a>.
deriveConstructors :: Name -> Q [Dec]

-- | Given the type and the name (as string) for the pattern functor to
--   derive, generate the <a>Regular</a> instance.
deriveRegular :: Name -> String -> Q [Dec]

-- | Derive only the <a>PF</a> instance. Not needed if <a>deriveRegular</a>
--   is used.
derivePF :: String -> Name -> Q [Dec]
instance Lift Associativity
instance Lift Fixity


-- | Summary: Top-level module for this library. By importing this module,
--   the user is able to use all the generic functionality. The user is
--   only required to provide an instance of <tt>Regular</tt> for the
--   datatype.
--   
--   Consider a datatype representing logical expressions:
--   
--   <pre>
--   data Logic = Var String
--              | Logic :-&gt;:  Logic  -- implication
--              | Logic :&lt;-&gt;: Logic  -- equivalence
--              | Logic :&amp;&amp;:  Logic  -- and (conjunction)
--              | Logic :||:  Logic  -- or (disjunction)
--              | Not Logic          -- not
--              | T                  -- true
--              | F                  -- false
--   </pre>
--   
--   An instance of <tt>Regular</tt> is derived with TH by invoking:
--   
--   <pre>
--   $(deriveConstructors ''Logic)
--   $(deriveRegular ''Logic "PFLogic")
--   type instance PF Logic = PFLogic
--   </pre>
module Generics.Regular