structuralEquality declares a structural equality predicate.

structuralTypeEquality f returns a function with the type: forall x y . f x -> f y -> Maybe (x :~: y)

structuralTypeOrd f returns a function with the type: forall x y . f x -> f y -> OrderingF x y

This implementation avoids matching on both the first and second parameters in a simple case expression in order to avoid stressing GHC's coverage checker. In the case that the first and second parameters have unique constructors, a simple numeric comparison is done to compute the result.

structuralTraversal tp generates a function that applies a traversal f to the subterms with free variables in tp.

structuralShow tp generates a function with the type tp -> ShowS that shows the constructor.

structuralHash tp generates a function with the type Int -> tp -> Int that hashes type.

All arguments use hashable, and structuralHashWithSalt can be used instead as it allows user-definable patterns to be used at specific types.

structuralHashWithSalt tp generates a function with the type Int -> tp -> Int that hashes type.

The second arguments is for generating user-defined patterns to replace hashWithSalt for specific types.

A polymorphic equality operator that generalizes TestEquality.

Generate a "repr" or singleton type from a data kind. For nullary constructors, this works as follows:

data T1 = A | B | C
$(mkRepr ''T1)
======>
data T1Repr (tp :: T1)
  where
    ARepr :: T1Repr 'A
    BRepr :: T1Repr 'B
    CRepr :: T1Repr 'C

For constructors with fields, we assume each field type T already has a corresponding repr type TRepr :: T -> *.

data T2 = T2_1 T1 | T2_2 T1
$(mkRepr ''T2)
======>
data T2Repr (tp :: T2)
  where
    T2_1Repr :: T1Repr tp -> T2Repr ('T2_1 tp)
    T2_2Repr :: T1Repr tp -> T2Repr ('T2_2 tp)

Constructors with multiple fields work fine as well:

data T3 = T3 T1 T2
$(mkRepr ''T3)
======>
data T3Repr (tp :: T3)
  where
    T3Repr :: T1Repr tp1 -> T2Repr tp2 -> T3Repr ('T3 tp1 tp2)

This is generally compatible with other "repr" types provided by parameterized-utils, such as NatRepr and PeanoRepr:

data T4 = T4_1 Nat | T4_2 Peano
$(mkRepr ''T4)
======>
data T4Repr (tp :: T4)
  where
    T4Repr :: NatRepr tp1 -> PeanoRepr tp2 -> T4Repr ('T4 tp1 tp2)

The data kind must be "simple", i.e. it must be monomorphic and only contain user-defined data constructors (no lists, tuples, etc.). For example, the following will not work:

data T5 a = T5 a
$(mkRepr ''T5)
======>
Foo.hs:1:1: error:
    Exception when trying to run compile-time code:
      mkRepr cannot be used on polymorphic data kinds.

Similarly, this will not work:

data T5 = T5 [Nat]
$(mkRepr ''T5)
======>
Foo.hs:1:1: error:
    Exception when trying to run compile-time code:
      mkRepr cannot be used on this data kind.

Note that at a minimum, you will need the following extensions to use this macro:

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE GADTs #-}
{-# LANGUAGE KindSignatures #-}
{-# LANGUAGE TemplateHaskell #-}

Generate KnownRepr instances for each constructor of a data kind. Given a data kind T, we assume a repr type TRepr (t :: T) is in scope with structure that perfectly matches T (using mkRepr to generate the repr type will guarantee this).

Given data kinds T1, T2, and T3 from the documentation of mkRepr, and the associated repr types T1Repr, T2Repr, and T3Repr, we can use mkKnownReprs to generate these instances like so:

$(mkKnownReprs ''T1)
======>
instance KnownRepr T1Repr 'A where
  knownRepr = ARepr
instance KnownRepr T1Repr 'B where
  knownRepr = BRepr
instance KnownRepr T1Repr 'C where
  knownRepr = CRepr

$(mkKnownReprs ''T2)
======>
instance KnownRepr T1Repr tp =>
         KnownRepr T2Repr ('T2_1 tp) where
  knownRepr = T2_1Repr knownRepr

$(mkKnownReprs ''T3)
======>
instance (KnownRepr T1Repr tp1, KnownRepr T2Repr tp2) =>
         KnownRepr T3Repr ('T3_1 tp1 tp2) where
  knownRepr = T3_1Repr knownRepr knownRepr

The same restrictions that apply to mkRepr also apply to mkKnownReprs. The data kind must be "simple", i.e. it must be monomorphic and only contain user-defined data constructors (no lists, tuples, etc.).

Note that at a minimum, you will need the following extensions to use this macro:

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE GADTs #-}
{-# LANGUAGE KindSignatures #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE TemplateHaskell #-}

Also, mkKnownReprs must be used in the same module as the definition of the repr type (not necessarily for the data kind).

Given a constructor and string, this generates a pattern for matching the expression, and the names of variables bound by pattern in order they appear in constructor.

A type used to describe (and match) types appearing in generated pattern matches inside of the TH generators in this module (structuralEquality, structuralTypeEquality, structuralTypeOrd, and structuralTraversal)

The dataParamTypes function returns the list of Type arguments for the constructor. For example, if passed the DatatypeInfo for a newtype Id a = MkId a then this would return [SigT (VarT a) StarT]. Note that there may be type *variables* not referenced in the returned array; this simply returns the type *arguments*.

Find value associated with first pattern that matches given pat if any.