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


-- | Nicer interface for reified information about data types
--   
--   This package normalizes variations in the interface for inspecting
--   datatype information via Template Haskell so that packages and support
--   a single, easier to use informational datatype while supporting many
--   versions of Template Haskell.
@package th-abstraction
@version 0.2.3.0


-- | This module provides a flattened view of information about data types
--   and newtypes that can be supported uniformly across multiple versions
--   of the template-haskell package.
--   
--   Sample output for <tt><a>reifyDatatype</a> ''Maybe</tt>
--   
--   <pre>
--   <a>DatatypeInfo</a>
--    { <a>datatypeContext</a> = []
--    , <a>datatypeName</a>    = GHC.Base.Maybe
--    , <a>datatypeVars</a>    = [ <a>SigT</a> (<a>VarT</a> a_3530822107858468866) <a>StarT</a> ]
--    , <a>datatypeVariant</a> = <a>Datatype</a>
--    , <a>datatypeCons</a>    =
--        [ <a>ConstructorInfo</a>
--            { <a>constructorName</a>       = GHC.Base.Nothing
--            , <a>constructorVars</a>       = []
--            , <a>constructorContext</a>    = []
--            , <a>constructorFields</a>     = []
--            , <a>constructorStrictness</a> = []
--            , <a>constructorVariant</a>    = <a>NormalConstructor</a>
--            }
--        , <a>ConstructorInfo</a>
--            { <a>constructorName</a>       = GHC.Base.Just
--            , <a>constructorVars</a>       = []
--            , <a>constructorContext</a>    = []
--            , <a>constructorFields</a>     = [ <a>VarT</a> a_3530822107858468866 ]
--            , <a>constructorStrictness</a> = [ <a>FieldStrictness</a>
--                                            <a>UnspecifiedUnpackedness</a>
--                                            <a>Lazy</a>
--                                        ]
--            , <a>constructorVariant</a>    = <a>NormalConstructor</a>
--            }
--        ]
--    }
--   </pre>
--   
--   Datatypes declared with GADT syntax are normalized to constructors
--   with existentially quantified type variables and equality constraints.
module Language.Haskell.TH.Datatype

-- | Normalized information about newtypes and data types.
--   
--   <a>datatypeVars</a> types will have an outermost <a>SigT</a> to
--   indicate the parameter's kind. These types will be simple variables
--   for <i>ADT</i>s declared with <tt>data</tt> and <tt>newtype</tt>, but
--   can be more complex for types declared with <tt>data instance</tt> and
--   <tt>newtype instance</tt>.
data DatatypeInfo
DatatypeInfo :: Cxt -> Name -> [Type] -> DatatypeVariant -> [ConstructorInfo] -> DatatypeInfo

-- | Data type context (deprecated)
[datatypeContext] :: DatatypeInfo -> Cxt

-- | Type constructor
[datatypeName] :: DatatypeInfo -> Name

-- | Type parameters
[datatypeVars] :: DatatypeInfo -> [Type]

-- | Extra information
[datatypeVariant] :: DatatypeInfo -> DatatypeVariant

-- | Normalize constructor information
[datatypeCons] :: DatatypeInfo -> [ConstructorInfo]

-- | Normalized information about constructors associated with newtypes and
--   data types.
data ConstructorInfo
ConstructorInfo :: Name -> [TyVarBndr] -> Cxt -> [Type] -> [FieldStrictness] -> ConstructorVariant -> ConstructorInfo

-- | Constructor name
[constructorName] :: ConstructorInfo -> Name

-- | Constructor type parameters
[constructorVars] :: ConstructorInfo -> [TyVarBndr]

-- | Constructor constraints
[constructorContext] :: ConstructorInfo -> Cxt

-- | Constructor fields
[constructorFields] :: ConstructorInfo -> [Type]

-- | Constructor fields' strictness (Invariant: has the same length as
--   constructorFields)
[constructorStrictness] :: ConstructorInfo -> [FieldStrictness]

-- | Extra information
[constructorVariant] :: ConstructorInfo -> ConstructorVariant

-- | Possible variants of data type declarations.
data DatatypeVariant

-- | Type declared with <tt>data</tt>
Datatype :: DatatypeVariant

-- | Type declared with <tt>newtype</tt>
Newtype :: DatatypeVariant

-- | Type declared with <tt>data instance</tt>
DataInstance :: DatatypeVariant

-- | Type declared with <tt>newtype instance</tt>
NewtypeInstance :: DatatypeVariant

-- | Possible variants of data constructors.
data ConstructorVariant

-- | Constructor without field names
NormalConstructor :: ConstructorVariant

-- | Constructor without field names that is declared infix
InfixConstructor :: ConstructorVariant

-- | Constructor with field names
RecordConstructor :: [Name] -> ConstructorVariant

-- | Normalized information about a constructor field's <tt>UNPACK</tt> and
--   strictness annotations.
--   
--   Note that the interface for reifying strictness in Template Haskell
--   changed considerably in GHC 8.0. The presentation in this library
--   mirrors that which can be found in GHC 8.0 or later, whereas
--   previously, unpackedness and strictness were represented with a single
--   data type:
--   
--   <pre>
--   data Strict
--     = IsStrict
--     | NotStrict
--     | Unpacked -- On GHC 7.4 or later
--   </pre>
--   
--   For backwards compatibility, we retrofit these constructors onto the
--   following three values, respectively:
--   
--   <pre>
--   <a>isStrictAnnot</a>  = <a>FieldStrictness</a> <a>UnspecifiedUnpackedness</a> <a>Strict</a>
--   <a>notStrictAnnot</a> = <a>FieldStrictness</a> <a>UnspecifiedUnpackedness</a> <a>UnspecifiedStrictness</a>
--   <a>unpackedAnnot</a>  = <a>FieldStrictness</a> <a>Unpack</a> <a>Strict</a>
--   </pre>
data FieldStrictness
FieldStrictness :: Unpackedness -> Strictness -> FieldStrictness
[fieldUnpackedness] :: FieldStrictness -> Unpackedness
[fieldStrictness] :: FieldStrictness -> Strictness

-- | Compute a normalized view of the metadata about a data type or newtype
--   given a constructor.
--   
--   This function will accept any constructor (value or type) for a type
--   declared with newtype or data. Value constructors must be used to
--   lookup datatype information about <i>data instances</i> and <i>newtype
--   instances</i>, as giving the type constructor of a data family is
--   often not enough to determine a particular data family instance.
--   
--   In addition, this function will also accept a record selector for a
--   data type with a constructor which uses that record.
--   
--   GADT constructors are normalized into datatypes with explicit equality
--   constraints. Note that no effort is made to distinguish between
--   equalities of the same (homogeneous) kind and equalities between
--   different (heterogeneous) kinds. For instance, the following GADT's
--   constructors:
--   
--   <pre>
--   data T (a :: k -&gt; *) where
--     MkT1 :: T Proxy
--     MkT2 :: T Maybe
--   </pre>
--   
--   will be normalized to the following equality constraints:
--   
--   <pre>
--   AppT (AppT EqualityT (VarT a)) (ConT Proxy) -- MkT1
--   AppT (AppT EqualityT (VarT a)) (ConT Maybe) -- MkT2
--   </pre>
--   
--   But only the first equality constraint is well kinded, since in the
--   second constraint, the kinds of <tt>(a :: k -&gt; *)</tt> and
--   <tt>(Maybe :: * -&gt; *)</tt> are different. Trying to categorize
--   which constraints need homogeneous or heterogeneous equality is
--   tricky, so we leave that task to users of this library.
--   
--   This function will apply various bug-fixes to the output of the
--   underlying <tt>template-haskell</tt> library in order to provide a
--   view of datatypes in as uniform a way as possible.
reifyDatatype :: Name -> Q DatatypeInfo

-- | Compute a normalized view of the metadata about a constructor given
--   its <a>Name</a>. This is useful for scenarios when you don't care
--   about the info for the enclosing data type.
reifyConstructor :: Name -> Q ConstructorInfo

-- | Compute a normalized view of the metadata about a constructor given
--   the <a>Name</a> of one of its record selectors. This is useful for
--   scenarios when you don't care about the info for the enclosing data
--   type.
reifyRecord :: Name -> Q ConstructorInfo

-- | Normalize <a>Info</a> for a newtype or datatype into a
--   <a>DatatypeInfo</a>. Fail in <a>Q</a> otherwise.
normalizeInfo :: Info -> Q DatatypeInfo

-- | Normalize <a>Dec</a> for a newtype or datatype into a
--   <a>DatatypeInfo</a>. Fail in <a>Q</a> otherwise.
--   
--   Beware: <a>normalizeDec</a> can have surprising behavior when it comes
--   to fixity. For instance, if you have this quasiquoted data
--   declaration:
--   
--   <pre>
--   [d| infix 5 :^^:
--       data Foo where
--         (:^^:) :: Int -&gt; Int -&gt; Foo |]
--   </pre>
--   
--   Then if you pass the <a>Dec</a> for <tt>Foo</tt> to
--   <a>normalizeDec</a> without splicing it in a previous Template Haskell
--   splice, then <tt>(:^^:)</tt> will be labeled a
--   <a>NormalConstructor</a> instead of an <a>InfixConstructor</a>. This
--   is because Template Haskell has no way to reify the fixity declaration
--   for <tt>(:^^:)</tt>, so it must assume there isn't one. To work around
--   this behavior, use <a>reifyDatatype</a> instead.
normalizeDec :: Dec -> Q DatatypeInfo

-- | Normalize a <a>Con</a> into a <a>ConstructorInfo</a>. This requires
--   knowledge of the type and parameters of the constructor, as well as
--   whether the constructor is for a data family instance, as extracted
--   from the outer <a>Dec</a>.
normalizeCon :: Name -> [Type] -> DatatypeVariant -> Con -> Q [ConstructorInfo]

-- | Given a <a>DatatypeInfo</a>, find the <a>ConstructorInfo</a>
--   corresponding to the <a>Name</a> of one of its constructors.
lookupByConstructorName :: Name -> DatatypeInfo -> ConstructorInfo

-- | Given a <a>DatatypeInfo</a>, find the <a>ConstructorInfo</a>
--   corresponding to the <a>Name</a> of one of its constructors.
lookupByRecordName :: Name -> DatatypeInfo -> ConstructorInfo

-- | Class for types that support type variable substitution.
class TypeSubstitution a

-- | Apply a type variable substitution
applySubstitution :: TypeSubstitution a => Map Name Type -> a -> a

-- | Compute the free type variables
freeVariables :: TypeSubstitution a => a -> [Name]

-- | Add universal quantifier for all free variables in the type. This is
--   useful when constructing a type signature for a declaration. This code
--   is careful to ensure that the order of the variables quantified is
--   determined by their order of appearance in the type signature. (In
--   contrast with being dependent upon the Ord instance for <a>Name</a>)
quantifyType :: Type -> Type

-- | Substitute all of the free variables in a type with fresh ones
freshenFreeVariables :: Type -> Q Type

-- | Construct an equality constraint. The implementation of <a>Pred</a>
--   varies across versions of Template Haskell.
equalPred :: Type -> Type -> Pred

-- | Construct a typeclass constraint. The implementation of <a>Pred</a>
--   varies across versions of Template Haskell.
classPred :: Name -> [Type] -> Pred

-- | Match a <a>Pred</a> representing an equality constraint. Returns
--   arguments to the equality constraint if successful.
asEqualPred :: Pred -> Maybe (Type, Type)

-- | Match a <a>Pred</a> representing a class constraint. Returns the
--   classname and parameters if successful.
asClassPred :: Pred -> Maybe (Name, [Type])

-- | Backward compatible version of <a>dataD</a>
dataDCompat :: CxtQ -> Name -> [TyVarBndr] -> [ConQ] -> [Name] -> DecQ
arrowKCompat :: Kind -> Kind -> Kind
isStrictAnnot :: FieldStrictness
notStrictAnnot :: FieldStrictness
unpackedAnnot :: FieldStrictness

-- | Expand all of the type synonyms in a type.
resolveTypeSynonyms :: Type -> Q Type

-- | Expand all of the type synonyms in a <a>Pred</a>.
resolvePredSynonyms :: Pred -> Q Pred

-- | Resolve any infix type application in a type using the fixities that
--   are currently available. Starting in `template-haskell-2.11` types
--   could contain unresolved infix applications.
resolveInfixT :: Type -> Q Type

-- | Backwards compatibility wrapper for <a>Fixity</a> lookup.
--   
--   In <tt>template-haskell-2.11.0.0</tt> and later, the answer will
--   always be <a>Just</a> of a fixity.
--   
--   Before <tt>template-haskell-2.11.0.0</tt> it was only possible to
--   determine fixity information for variables, class methods, and data
--   constructors. In this case for type operators the answer could be
--   <a>Nothing</a>, which indicates that the answer is unavailable.
reifyFixityCompat :: Name -> Q (Maybe Fixity)

-- | Render a <a>Fixity</a> as it would appear in Haskell source.
--   
--   Example: <tt>infixl 5</tt>
showFixity :: Fixity -> String

-- | Render a <a>FixityDirection</a> like it would appear in Haskell
--   source.
--   
--   Examples: <tt>infixl</tt> <tt>infixr</tt> <tt>infix</tt>
showFixityDirection :: FixityDirection -> String

-- | Compute the type variable substitution that unifies a list of types,
--   or fail in <a>Q</a>.
unifyTypes :: [Type] -> Q (Map Name Type)

-- | Extract the type variable name from a <a>TyVarBndr</a> ignoring the
--   kind signature if one exists.
tvName :: TyVarBndr -> Name

-- | Construct a Type using the datatype's type constructor and type
--   parameters. Kind signatures are removed.
datatypeType :: DatatypeInfo -> Type
instance GHC.Generics.Generic Language.Haskell.TH.Datatype.DatatypeInfo
instance Data.Data.Data Language.Haskell.TH.Datatype.DatatypeInfo
instance GHC.Classes.Eq Language.Haskell.TH.Datatype.DatatypeInfo
instance GHC.Show.Show Language.Haskell.TH.Datatype.DatatypeInfo
instance GHC.Generics.Generic Language.Haskell.TH.Datatype.ConstructorInfo
instance Data.Data.Data Language.Haskell.TH.Datatype.ConstructorInfo
instance GHC.Classes.Eq Language.Haskell.TH.Datatype.ConstructorInfo
instance GHC.Show.Show Language.Haskell.TH.Datatype.ConstructorInfo
instance GHC.Generics.Generic Language.Haskell.TH.Datatype.FieldStrictness
instance Data.Data.Data Language.Haskell.TH.Datatype.FieldStrictness
instance GHC.Classes.Ord Language.Haskell.TH.Datatype.FieldStrictness
instance GHC.Classes.Eq Language.Haskell.TH.Datatype.FieldStrictness
instance GHC.Show.Show Language.Haskell.TH.Datatype.FieldStrictness
instance GHC.Generics.Generic Language.Haskell.TH.Datatype.Strictness
instance Data.Data.Data Language.Haskell.TH.Datatype.Strictness
instance GHC.Classes.Ord Language.Haskell.TH.Datatype.Strictness
instance GHC.Classes.Eq Language.Haskell.TH.Datatype.Strictness
instance GHC.Show.Show Language.Haskell.TH.Datatype.Strictness
instance GHC.Generics.Generic Language.Haskell.TH.Datatype.Unpackedness
instance Data.Data.Data Language.Haskell.TH.Datatype.Unpackedness
instance GHC.Classes.Ord Language.Haskell.TH.Datatype.Unpackedness
instance GHC.Classes.Eq Language.Haskell.TH.Datatype.Unpackedness
instance GHC.Show.Show Language.Haskell.TH.Datatype.Unpackedness
instance GHC.Generics.Generic Language.Haskell.TH.Datatype.ConstructorVariant
instance Data.Data.Data Language.Haskell.TH.Datatype.ConstructorVariant
instance GHC.Classes.Ord Language.Haskell.TH.Datatype.ConstructorVariant
instance GHC.Classes.Eq Language.Haskell.TH.Datatype.ConstructorVariant
instance GHC.Show.Show Language.Haskell.TH.Datatype.ConstructorVariant
instance GHC.Generics.Generic Language.Haskell.TH.Datatype.DatatypeVariant
instance Data.Data.Data Language.Haskell.TH.Datatype.DatatypeVariant
instance GHC.Classes.Ord Language.Haskell.TH.Datatype.DatatypeVariant
instance GHC.Classes.Eq Language.Haskell.TH.Datatype.DatatypeVariant
instance GHC.Read.Read Language.Haskell.TH.Datatype.DatatypeVariant
instance GHC.Show.Show Language.Haskell.TH.Datatype.DatatypeVariant
instance Language.Haskell.TH.Datatype.TypeSubstitution a => Language.Haskell.TH.Datatype.TypeSubstitution [a]
instance Language.Haskell.TH.Datatype.TypeSubstitution Language.Haskell.TH.Syntax.Type
instance Language.Haskell.TH.Datatype.TypeSubstitution Language.Haskell.TH.Datatype.ConstructorInfo
