Language.Haskell.TH.Datatype

Normalized information about newtypes and data types.

DatatypeInfo contains two fields, datatypeVars and datatypeInstTypes, which encode information about the argument types. The simplest explanation is that datatypeVars contains all the type variables bound by the data type constructor, while datatypeInstTypes contains the type arguments to the data type constructor. To be more precise:

• For ADTs declared with data and newtype, it will likely be the case that datatypeVars and datatypeInstTypes coincide. For instance, given newtype Id a = MkId a, in the DatatypeInfo for Id we would have datatypeVars = [KindedTV a () StarT] and datatypeInstVars = [SigT (VarT a) StarT].

ADTs that leverage PolyKinds may have more datatypeVars than datatypeInstTypes. For instance, given data Proxy (a :: k) = MkProxy, in the DatatypeInfo for Proxy we would have datatypeVars = [KindedTV k () StarT, KindedTV a () (VarT k)] (since there are two variables, k and a), whereas datatypeInstTypes = [SigT (VarT a) (VarT k)], since there is only one explicit type argument to Proxy.

The same outcome would occur if Proxy were declared using TypeAbstractions, i.e., if it were declared as data Proxy @k (a :: k) = MkProxy. The datatypeInstTypes would not include a separate type for @k.

• For data instances and newtype instances of data families, datatypeVars and datatypeInstTypes can be quite different. Here is an example to illustrate the difference:

  data family F a b
  data instance F (Maybe c) (f x) = MkF c (f x)
  

Then in the DatatypeInfo for F's data instance, we would have:

  datatypeVars      = [ KindedTV c () StarT
                        , KindedTV f () StarT
                        , KindedTV x () StarT ]
  datatypeInstTypes = [ AppT (ConT ''Maybe) (VarT c)
                        , AppT (VarT f) (VarT x) ]
  

Normalized information about constructors associated with newtypes and data types.

Possible variants of data type declarations.

Possible variants of data constructors.

Normalized information about a constructor field's UNPACK 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:

data Strict
  = IsStrict
  | NotStrict
  | Unpacked -- On GHC 7.4 or later

For backwards compatibility, we retrofit these constructors onto the following three values, respectively:

isStrictAnnot  = FieldStrictness UnspecifiedUnpackedness Strict
notStrictAnnot = FieldStrictness UnspecifiedUnpackedness UnspecifiedStrictness
unpackedAnnot  = FieldStrictness Unpack Strict

Information about a constructor field's unpackedness annotation.

Information about a constructor field's strictness annotation.

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 data instances and newtype instances, 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:

data T (a :: k -> *) where
  MkT1 :: T Proxy
  MkT2 :: T Maybe

will be normalized to the following equality constraints:

AppT (AppT EqualityT (VarT a)) (ConT Proxy) -- MkT1
AppT (AppT EqualityT (VarT a)) (ConT Maybe) -- MkT2

But only the first equality constraint is well kinded, since in the second constraint, the kinds of (a :: k -> *) and (Maybe :: * -> *) are different. Trying to categorize which constraints need homogeneous or heterogeneous equality is tricky, so we leave that task to users of this library.

Primitive types (other than unboxed sums and tuples) will have no datatypeCons in their normalization.

This function will apply various bug-fixes to the output of the underlying template-haskell library in order to provide a view of datatypes in as uniform a way as possible.

Compute a normalized view of the metadata about a constructor given its Name. This is useful for scenarios when you don't care about the info for the enclosing data type.

Compute a normalized view of the metadata about a constructor given the Name of one of its record selectors. This is useful for scenarios when you don't care about the info for the enclosing data type.

Normalize Info for a newtype or datatype into a DatatypeInfo. Fail in Q otherwise.

Normalize Dec for a newtype or datatype into a DatatypeInfo. Fail in Q otherwise.

Beware: normalizeDec can have surprising behavior when it comes to fixity. For instance, if you have this quasiquoted data declaration:

[d| infix 5 :^^:
    data Foo where
      (:^^:) :: Int -> Int -> Foo |]

Then if you pass the Dec for Foo to normalizeDec without splicing it in a previous Template Haskell splice, then (:^^:) will be labeled a NormalConstructor instead of an InfixConstructor. This is because Template Haskell has no way to reify the fixity declaration for (:^^:), so it must assume there isn't one. To work around this behavior, use reifyDatatype instead.

Normalize a Con into a ConstructorInfo. 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 Dec.

Given a DatatypeInfo, find the ConstructorInfo corresponding to the Name of one of its constructors.

Given a DatatypeInfo, find the ConstructorInfo corresponding to the Name of one of its constructors.

Class for types that support type variable substitution.

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 Name)

Take a list of Types, find their free variables, and sort them according to dependency order.

As an example of how this function works, consider the following type:

Proxy (a :: k)

Calling freeVariables on this type would yield [a, k], since that is the order in which those variables appear in a left-to-right fashion. But this order does not preserve the fact that k is the kind of a. Moreover, if you tried writing the type forall a k. Proxy (a :: k), GHC would reject this, since GHC would demand that k come before a.

freeVariablesWellScoped orders the free variables of a type in a way that preserves this dependency ordering. If one were to call freeVariablesWellScoped on the type above, it would return [k, (a :: k)]. (This is why freeVariablesWellScoped returns a list of TyVarBndrs instead of Names, since it must make it explicit that k is the kind of a.)

freeVariablesWellScoped guarantees the free variables returned will be ordered such that:

1. Whenever an explicit kind signature of the form (A :: K) is encountered, the free variables of K will always appear to the left of the free variables of A in the returned result.

2. The constraint in (1) notwithstanding, free variables will appear in left-to-right order of their original appearance.

On older GHCs, this takes measures to avoid returning explicitly bound kind variables, which was not possible before TypeInType.

Substitute all of the free variables in a type with fresh ones

Construct an equality constraint. The implementation of Pred varies across versions of Template Haskell.

Construct a typeclass constraint. The implementation of Pred varies across versions of Template Haskell.

Match a Pred representing an equality constraint. Returns arguments to the equality constraint if successful.

Match a Pred representing a class constraint. Returns the classname and parameters if successful.

Backward compatible version of dataD

Backward compatible version of newtypeD

Backward compatible version of tySynInstD

Backward compatible version of pragLineD. Returns Nothing if line pragmas are not suported.

Expand all of the type synonyms in a type.

Note that this function will drop parentheses as a side effect.

Expand all of the type synonyms in a Kind.

Expand all of the type synonyms in a 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.

Backwards compatibility wrapper for Fixity lookup.

In template-haskell-2.11.0.0 and later, the answer will always be Just of a fixity.

Before template-haskell-2.11.0.0 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 Nothing, which indicates that the answer is unavailable.

Render a Fixity as it would appear in Haskell source.

Example: infixl 5

Render a FixityDirection like it would appear in Haskell source.

Examples: infixl infixr infix

Compute the type variable substitution that unifies a list of types, or fail in Q.

All infix issue should be resolved before using unifyTypes

Alpha equivalent quantified types are not unified.

Extract the type variable name from a TyVarBndr, ignoring the kind signature if one exists.

Extract the kind from a TyVarBndr. Assumes PlainTV has kind *.

Construct a Type using the datatype's type constructor and type parameters. Kind signatures are removed.