As with all known Haskell systems, GHC implements some extensions to the standard Haskell language. They can all be enabled or disabled by command line flags or language pragmas. By default GHC understands the most recent Haskell version it supports, plus a handful of extensions.
Some of the Glasgow extensions serve to give you access to the underlying facilities with which we implement Haskell. Thus, you can get at the Raw Iron, if you are willing to write some nonportable code at a more primitive level. You need not be “stuck” on performance because of the implementation costs of Haskell’s “highlevel” features—you can always code “under” them. In an extreme case, you can write all your timecritical code in C, and then just glue it together with Haskell!
Before you get too carried away working at the lowest level (e.g., sloshing MutableByteArray#s around your program), you may wish to check if there are libraries that provide a “Haskellised veneer” over the features you want. The separate libraries documentation describes all the libraries that come with GHC.
The language option flags control what variation of the language are permitted.
Language options can be controlled in two ways:
Although not recommended, the deprecated fglasgowexts flag enables a large swath of the extensions supported by GHC at once.
The flag fglasgowexts is equivalent to enabling the following extensions:


Enabling these options is the only effect of fglasgowexts. We are trying to move away from this portmanteau flag, and towards enabling features individually.
GHC is built on a raft of primitive data types and operations; “primitive” in the sense that they cannot be defined in Haskell itself. While you really can use this stuff to write fast code, we generally find it a lot less painful, and more satisfying in the long run, to use higherlevel language features and libraries. With any luck, the code you write will be optimised to the efficient unboxed version in any case. And if it isn’t, we’d like to know about it.
All these primitive data types and operations are exported by the library GHC.Prim, for which there is detailed online documentation. (This documentation is generated from the file compiler/prelude/primops.txt.pp.)
If you want to mention any of the primitive data types or operations in your program, you must first import GHC.Prim to bring them into scope. Many of them have names ending in #, and to mention such names you need the XMagicHash extension (The magic hash).
The primops make extensive use of unboxed types and unboxed tuples, which we briefly summarise here.
Most types in GHC are boxed, which means that values of that type are represented by a pointer to a heap object. The representation of a Haskell Int, for example, is a twoword heap object. An unboxed type, however, is represented by the value itself, no pointers or heap allocation are involved.
Unboxed types correspond to the “raw machine” types you would use in C: Int# (long int), Double# (double), Addr# (void *), etc. The primitive operations (PrimOps) on these types are what you might expect; e.g., (+#) is addition on Int#s, and is the machineaddition that we all know and love—usually one instruction.
Primitive (unboxed) types cannot be defined in Haskell, and are therefore built into the language and compiler. Primitive types are always unlifted; that is, a value of a primitive type cannot be bottom. (Note: a “boxed” type means that a value is represented by a pointer to a heap object; a “lifted” type means that terms of that type may be bottom. See the next paragraph for an example.) We use the convention (but it is only a convention) that primitive types, values, and operations have a # suffix (see The magic hash). For some primitive types we have special syntax for literals, also described in the same section.
Primitive values are often represented by a simple bitpattern, such as Int#, Float#, Double#. But this is not necessarily the case: a primitive value might be represented by a pointer to a heapallocated object. Examples include Array#, the type of primitive arrays. Thus, Array# is an unlifted, boxed type. A primitive array is heapallocated because it is too big a value to fit in a register, and would be too expensive to copy around; in a sense, it is accidental that it is represented by a pointer. If a pointer represents a primitive value, then it really does point to that value: no unevaluated thunks, no indirections. Nothing can be at the other end of the pointer than the primitive value. A numericallyintensive program using unboxed types can go a lot faster than its “standard” counterpart—we saw a threefold speedup on one example.
Because unboxed types are represented without the use of pointers, we cannot store them in use a polymorphic datatype at an unboxed type. For example, the Just node of Just 42# would have to be different from the Just node of Just 42; the former stores an integer directly, while the latter stores a pointer. GHC currently does not support this variety of Just nodes (nor for any other datatype). Accordingly, the kind of an unboxed type is different from the kind of a boxed type.
The Haskell Report describes that * is the kind of ordinary datatypes, such as Int. Furthermore, type constructors can have kinds with arrows; for example, Maybe has kind * > *. Unboxed types have a kind that specifies their runtime representation. For example, the type Int# has kind TYPE 'IntRep and Double# has kind TYPE 'DoubleRep. These kinds say that the runtime representation of an Int# is a machine integer, and the runtime representation of a Double# is a machine doubleprecision floating point. In constrast, the kind * is actually just a synonym for TYPE 'PtrRepLifted. More details of the TYPE mechanisms appear in the section on runtime representation polymorphism.
Given that Int#‘s kind is not *, it then it follows that Maybe Int# is disallowed. Similarly, because type variables tend to be of kind * (for example, in (.) :: (b > c) > (a > b) > a > c, all the type variables have kind *), polymorphism tends not to work over primitive types. Stepping back, this makes some sense, because a polymorphic function needs to manipulate the pointers to its data, and most primitive types are unboxed.
There are some restrictions on the use of primitive types:
You cannot define a newtype whose representation type (the argument type of the data constructor) is an unboxed type. Thus, this is illegal:
newtype A = MkA Int#
You cannot bind a variable with an unboxed type in a toplevel binding.
You cannot bind a variable with an unboxed type in a recursive binding.
You may bind unboxed variables in a (nonrecursive, nontoplevel) pattern binding, but you must make any such patternmatch strict. For example, rather than:
data Foo = Foo Int Int#
f x = let (Foo a b, w) = ..rhs.. in ..body..
you must write:
data Foo = Foo Int Int#
f x = let !(Foo a b, w) = ..rhs.. in ..body..
since b has type Int#.
Enable the use of unboxed tuple syntax.
Unboxed tuples aren’t really exported by GHC.Exts; they are a syntactic extension enabled by the language flag XUnboxedTuples. An unboxed tuple looks like this:
(# e_1, ..., e_n #)
where e_1..e_n are expressions of any type (primitive or nonprimitive). The type of an unboxed tuple looks the same.
Note that when unboxed tuples are enabled, (# is a single lexeme, so for example when using operators like # and # you need to write ( # ) and ( # ) rather than (#) and (#).
Unboxed tuples are used for functions that need to return multiple values, but they avoid the heap allocation normally associated with using fullyfledged tuples. When an unboxed tuple is returned, the components are put directly into registers or on the stack; the unboxed tuple itself does not have a composite representation. Many of the primitive operations listed in primops.txt.pp return unboxed tuples. In particular, the IO and ST monads use unboxed tuples to avoid unnecessary allocation during sequences of operations.
There are some restrictions on the use of unboxed tuples:
Values of unboxed tuple types are subject to the same restrictions as other unboxed types; i.e. they may not be stored in polymorphic data structures or passed to polymorphic functions.
The typical use of unboxed tuples is simply to return multiple values, binding those multiple results with a case expression, thus:
f x y = (# x+1, y1 #)
g x = case f x x of { (# a, b #) > a + b }
You can have an unboxed tuple in a pattern binding, thus
f x = let (# p,q #) = h x in ..body..
If the types of p and q are not unboxed, the resulting binding is lazy like any other Haskell pattern binding. The above example desugars like this:
f x = let t = case h x of { (# p,q #) > (p,q) }
p = fst t
q = snd t
in ..body..
Indeed, the bindings can even be recursive.
Enable the use of Unicode characters in place of their equivalent ASCII sequences.
The language extension XUnicodeSyntax enables Unicode characters to be used to stand for certain ASCII character sequences. The following alternatives are provided:
ASCII  Unicode alternative  Code point  Name 

::  ∷  0x2237  PROPORTION 
=>  ⇒  0x21D2  RIGHTWARDS DOUBLE ARROW 
>  →  0x2192  RIGHTWARDS ARROW 
<  ←  0x2190  LEFTWARDS ARROW 
>  ⤚  0x291a  RIGHTWARDS ARROWTAIL 
<  ⤙  0x2919  LEFTWARDS ARROWTAIL 
>>  ⤜  0x291C  RIGHTWARDS DOUBLE ARROWTAIL 
<<  ⤛  0x291B  LEFTWARDS DOUBLE ARROWTAIL 
*  ★  0x2605  BLACK STAR 
forall  ∀  0x2200  FOR ALL 
Enable the use of the hash character (#) as an identifier suffix.
The language extension XMagicHash allows # as a postfix modifier to identifiers. Thus, x# is a valid variable, and T# is a valid type constructor or data constructor.
The hash sign does not change semantics at all. We tend to use variable names ending in “#” for unboxed values or types (e.g. Int#), but there is no requirement to do so; they are just plain ordinary variables. Nor does the XMagicHash extension bring anything into scope. For example, to bring Int# into scope you must import GHC.Prim (see Unboxed types and primitive operations); the XMagicHash extension then allows you to refer to the Int# that is now in scope. Note that with this option, the meaning of x#y = 0 is changed: it defines a function x# taking a single argument y; to define the operator #, put a space: x # y = 0.
The XMagicHash also enables some new forms of literals (see Unboxed types):
Since:  7.8.1 

Enable the use of unparenthesized negative numeric literals.
The literal 123 is, according to Haskell98 and Haskell 2010, desugared as negate (fromInteger 123). The language extension XNegativeLiterals means that it is instead desugared as fromInteger (123).
This can make a difference when the positive and negative range of a numeric data type don’t match up. For example, in 8bit arithmetic 128 is representable, but +128 is not. So negate (fromInteger 128) will elicit an unexpected integerliteraloverflow message.
Since:  7.8.1 

Allow the use of floatingpoint literal syntax for integral types.
Haskell 2010 and Haskell 98 define floating literals with the syntax 1.2e6. These literals have the type Fractional a => a.
The language extension XNumDecimals allows you to also use the floating literal syntax for instances of Integral, and have values like (1.2e6 :: Num a => a)
Since:  7.10.1 

Allow the use of binary notation in integer literals.
Haskell 2010 and Haskell 98 allows for integer literals to be given in decimal, octal (prefixed by 0o or 0O), or hexadecimal notation (prefixed by 0x or 0X).
The language extension XBinaryLiterals adds support for expressing integer literals in binary notation with the prefix 0b or 0B. For instance, the binary integer literal 0b11001001 will be desugared into fromInteger 201 when XBinaryLiterals is enabled.
Enable pattern matches in guards.
The discussion that follows is an abbreviated version of Simon Peyton Jones’s original proposal. (Note that the proposal was written before pattern guards were implemented, so refers to them as unimplemented.)
Suppose we have an abstract data type of finite maps, with a lookup operation:
lookup :: FiniteMap > Int > Maybe Int
The lookup returns Nothing if the supplied key is not in the domain of the mapping, and (Just v) otherwise, where v is the value that the key maps to. Now consider the following definition:
clunky env var1 var2
 ok1 && ok2 = val1 + val2
 otherwise = var1 + var2
where
m1 = lookup env var1
m2 = lookup env var2
ok1 = maybeToBool m1
ok2 = maybeToBool m2
val1 = expectJust m1
val2 = expectJust m2
The auxiliary functions are
maybeToBool :: Maybe a > Bool
maybeToBool (Just x) = True
maybeToBool Nothing = False
expectJust :: Maybe a > a
expectJust (Just x) = x
expectJust Nothing = error "Unexpected Nothing"
What is clunky doing? The guard ok1 && ok2 checks that both lookups succeed, using maybeToBool to convert the Maybe types to booleans. The (lazily evaluated) expectJust calls extract the values from the results of the lookups, and binds the returned values to val1 and val2 respectively. If either lookup fails, then clunky takes the otherwise case and returns the sum of its arguments.
This is certainly legal Haskell, but it is a tremendously verbose and unobvious way to achieve the desired effect. Arguably, a more direct way to write clunky would be to use case expressions:
clunky env var1 var2 = case lookup env var1 of
Nothing > fail
Just val1 > case lookup env var2 of
Nothing > fail
Just val2 > val1 + val2
where
fail = var1 + var2
This is a bit shorter, but hardly better. Of course, we can rewrite any set of patternmatching, guarded equations as case expressions; that is precisely what the compiler does when compiling equations! The reason that Haskell provides guarded equations is because they allow us to write down the cases we want to consider, one at a time, independently of each other. This structure is hidden in the case version. Two of the righthand sides are really the same (fail), and the whole expression tends to become more and more indented.
Here is how I would write clunky:
clunky env var1 var2
 Just val1 < lookup env var1
, Just val2 < lookup env var2
= val1 + val2
...other equations for clunky...
The semantics should be clear enough. The qualifiers are matched in order. For a < qualifier, which I call a pattern guard, the right hand side is evaluated and matched against the pattern on the left. If the match fails then the whole guard fails and the next equation is tried. If it succeeds, then the appropriate binding takes place, and the next qualifier is matched, in the augmented environment. Unlike list comprehensions, however, the type of the expression to the right of the < is the same as the type of the pattern to its left. The bindings introduced by pattern guards scope over all the remaining guard qualifiers, and over the right hand side of the equation.
Just as with list comprehensions, boolean expressions can be freely mixed with among the pattern guards. For example:
f x  [y] < x
, y > 3
, Just z < h y
= ...
Haskell’s current guards therefore emerge as a special case, in which the qualifier list has just one element, a boolean expression.
Allow use of view pattern syntax.
View patterns are enabled by the flag XViewPatterns. More information and examples of view patterns can be found on the Wiki page.
View patterns are somewhat like pattern guards that can be nested inside of other patterns. They are a convenient way of patternmatching against values of abstract types. For example, in a programming language implementation, we might represent the syntax of the types of the language as follows:
type Typ
data TypView = Unit
 Arrow Typ Typ
view :: Typ > TypView
 additional operations for constructing Typ's ...
The representation of Typ is held abstract, permitting implementations to use a fancy representation (e.g., hashconsing to manage sharing). Without view patterns, using this signature is a little inconvenient:
size :: Typ > Integer
size t = case view t of
Unit > 1
Arrow t1 t2 > size t1 + size t2
It is necessary to iterate the case, rather than using an equational function definition. And the situation is even worse when the matching against t is buried deep inside another pattern.
View patterns permit calling the view function inside the pattern and matching against the result:
size (view > Unit) = 1
size (view > Arrow t1 t2) = size t1 + size t2
That is, we add a new form of pattern, written ⟨expression⟩ > ⟨pattern⟩ that means “apply the expression to whatever we’re trying to match against, and then match the result of that application against the pattern”. The expression can be any Haskell expression of function type, and view patterns can be used wherever patterns are used.
The semantics of a pattern ( ⟨exp⟩ > ⟨pat⟩ ) are as follows:
Scoping: The variables bound by the view pattern are the variables bound by ⟨pat⟩.
Any variables in ⟨exp⟩ are bound occurrences, but variables bound “to the left” in a pattern are in scope. This feature permits, for example, one argument to a function to be used in the view of another argument. For example, the function clunky from Pattern guards can be written using view patterns as follows:
clunky env (lookup env > Just val1) (lookup env > Just val2) = val1 + val2
...other equations for clunky...
More precisely, the scoping rules are:
In a single pattern, variables bound by patterns to the left of a view pattern expression are in scope. For example:
example :: Maybe ((String > Integer,Integer), String) > Bool
example Just ((f,_), f > 4) = True
Additionally, in function definitions, variables bound by matching earlier curried arguments may be used in view pattern expressions in later arguments:
example :: (String > Integer) > String > Bool
example f (f > 4) = True
That is, the scoping is the same as it would be if the curried arguments were collected into a tuple.
In mutually recursive bindings, such as let, where, or the top level, view patterns in one declaration may not mention variables bound by other declarations. That is, each declaration must be selfcontained. For example, the following program is not allowed:
let {(x > y) = e1 ;
(y > x) = e2 } in x
(For some amplification on this design choice see Trac #4061.
Typing: If ⟨exp⟩ has type ⟨T1⟩ > ⟨T2⟩ and ⟨pat⟩ matches a ⟨T2⟩, then the whole view pattern matches a ⟨T1⟩.
Matching: To the equations in Section 3.17.3 of the Haskell 98 Report, add the following:
case v of { (e > p) > e1 ; _ > e2 }
=
case (e v) of { p > e1 ; _ > e2 }
That is, to match a variable ⟨v⟩ against a pattern ( ⟨exp⟩ > ⟨pat⟩ ), evaluate ( ⟨exp⟩ ⟨v⟩ ) and match the result against ⟨pat⟩.
Efficiency: When the same view function is applied in multiple branches of a function definition or a case expression (e.g., in size above), GHC makes an attempt to collect these applications into a single nested case expression, so that the view function is only applied once. Pattern compilation in GHC follows the matrix algorithm described in Chapter 4 of The Implementation of Functional Programming Languages. When the top rows of the first column of a matrix are all view patterns with the “same” expression, these patterns are transformed into a single nested case. This includes, for example, adjacent view patterns that line up in a tuple, as in
f ((view > A, p1), p2) = e1
f ((view > B, p3), p4) = e2
The current notion of when two view pattern expressions are “the same” is very restricted: it is not even full syntactic equality. However, it does include variables, literals, applications, and tuples; e.g., two instances of view ("hi", "there") will be collected. However, the current implementation does not compare up to alphaequivalence, so two instances of (x, view x > y) will not be coalesced.
Allow the use of recursive do notation.
The donotation of Haskell 98 does not allow recursive bindings, that is, the variables bound in a doexpression are visible only in the textually following code block. Compare this to a letexpression, where bound variables are visible in the entire binding group.
It turns out that such recursive bindings do indeed make sense for a variety of monads, but not all. In particular, recursion in this sense requires a fixedpoint operator for the underlying monad, captured by the mfix method of the MonadFix class, defined in Control.Monad.Fix as follows:
class Monad m => MonadFix m where
mfix :: (a > m a) > m a
Haskell’s Maybe, [] (list), ST (both strict and lazy versions), IO, and many other monads have MonadFix instances. On the negative side, the continuation monad, with the signature (a > r) > r, does not.
For monads that do belong to the MonadFix class, GHC provides an extended version of the donotation that allows recursive bindings. The XRecursiveDo (language pragma: RecursiveDo) provides the necessary syntactic support, introducing the keywords mdo and rec for higher and lower levels of the notation respectively. Unlike bindings in a do expression, those introduced by mdo and rec are recursively defined, much like in an ordinary letexpression. Due to the new keyword mdo, we also call this notation the mdonotation.
Here is a simple (albeit contrived) example:
{# LANGUAGE RecursiveDo #}
justOnes = mdo { xs < Just (1:xs)
; return (map negate xs) }
or equivalently
{# LANGUAGE RecursiveDo #}
justOnes = do { rec { xs < Just (1:xs) }
; return (map negate xs) }
As you can guess justOnes will evaluate to Just [1,1,1,....
GHC’s implementation the mdonotation closely follows the original translation as described in the paper A recursive do for Haskell, which in turn is based on the work Value Recursion in Monadic Computations. Furthermore, GHC extends the syntax described in the former paper with a lower level syntax flagged by the rec keyword, as we describe next.
The flag XRecursiveDo also introduces a new keyword rec, which wraps a mutuallyrecursive group of monadic statements inside a do expression, producing a single statement. Similar to a let statement inside a do, variables bound in the rec are visible throughout the rec group, and below it. For example, compare
do { a < getChar do { a < getChar
; let { r1 = f a r2 ; rec { r1 < f a r2
; ; r2 = g r1 } ; ; r2 < g r1 }
; return (r1 ++ r2) } ; return (r1 ++ r2) }
In both cases, r1 and r2 are available both throughout the let or rec block, and in the statements that follow it. The difference is that let is nonmonadic, while rec is monadic. (In Haskell let is really letrec, of course.)
The semantics of rec is fairly straightforward. Whenever GHC finds a rec group, it will compute its set of bound variables, and will introduce an appropriate call to the underlying monadic valuerecursion operator mfix, belonging to the MonadFix class. Here is an example:
rec { b < f a c ===> (b,c) < mfix (\ ~(b,c) > do { b < f a c
; c < f b a } ; c < f b a
; return (b,c) })
As usual, the metavariables b, c etc., can be arbitrary patterns. In general, the statement rec ss is desugared to the statement
vs < mfix (\ ~vs > do { ss; return vs })
where vs is a tuple of the variables bound by ss.
Note in particular that the translation for a rec block only involves wrapping a call to mfix: it performs no other analysis on the bindings. The latter is the task for the mdo notation, which is described next.
A recblock tells the compiler where precisely the recursive knot should be tied. It turns out that the placement of the recursive knots can be rather delicate: in particular, we would like the knots to be wrapped around as minimal groups as possible. This process is known as segmentation, and is described in detail in Section 3.2 of A recursive do for Haskell. Segmentation improves polymorphism and reduces the size of the recursive knot. Most importantly, it avoids unnecessary interference caused by a fundamental issue with the socalled rightshrinking axiom for monadic recursion. In brief, most monads of interest (IO, strict state, etc.) do not have recursion operators that satisfy this axiom, and thus not performing segmentation can cause unnecessary interference, changing the termination behavior of the resulting translation. (Details can be found in Sections 3.1 and 7.2.2 of Value Recursion in Monadic Computations.)
The mdo notation removes the burden of placing explicit rec blocks in the code. Unlike an ordinary do expression, in which variables bound by statements are only in scope for later statements, variables bound in an mdo expression are in scope for all statements of the expression. The compiler then automatically identifies minimal mutually recursively dependent segments of statements, treating them as if the user had wrapped a rec qualifier around them.
The definition is syntactic:
Segments in this sense are related to stronglyconnected components analysis, with the exception that bindings in a segment cannot be reordered and must be contiguous.
Here is an example mdoexpression, and its translation to rec blocks:
mdo { a < getChar ===> do { a < getChar
; b < f a c ; rec { b < f a c
; c < f b a ; ; c < f b a }
; z < h a b ; z < h a b
; d < g d e ; rec { d < g d e
; e < g a z ; ; e < g a z }
; putChar c } ; putChar c }
Note that a given mdo expression can cause the creation of multiple rec blocks. If there are no recursive dependencies, mdo will introduce no rec blocks. In this latter case an mdo expression is precisely the same as a do expression, as one would expect.
In summary, given an mdo expression, GHC first performs segmentation, introducing rec blocks to wrap over minimal recursive groups. Then, each resulting rec is desugared, using a call to Control.Monad.Fix.mfix as described in the previous section. The original mdoexpression typechecks exactly when the desugared version would do so.
Here are some other important points in using the recursivedo notation:
Since:  8.0.1 

Allow use of Applicative do notation.
The language option XApplicativeDo enables an alternative translation for the donotation, which uses the operators <$>, <*>, along with join as far as possible. There are two main reasons for wanting to do this:
Applicative donotation desugaring preserves the original semantics, provided that the Applicative instance satisfies <*> = ap and pure = return (these are true of all the common monadic types). Thus, you can normally turn on XApplicativeDo without fear of breaking your program. There is one pitfall to watch out for; see Things to watch out for.
There are no syntactic changes with XApplicativeDo. The only way it shows up at the source level is that you can have a do expression that doesn’t require a Monad constraint. For example, in GHCi:
Prelude> :set XApplicativeDo
Prelude> :t \m > do { x < m; return (not x) }
\m > do { x < m; return (not x) }
:: Functor f => f Bool > f Bool
This example only requires Functor, because it is translated into (\x > not x) <$> m. A more complex example requires Applicative,
Prelude> :t \m > do { x < m 'a'; y < m 'b'; return (x  y) }
\m > do { x < m 'a'; y < m 'b'; return (x  y) }
:: Applicative f => (Char > f Bool) > f Bool
Here GHC has translated the expression into
(\x y > x  y) <$> m 'a' <*> m 'b'
It is possible to see the actual translation by using ddumpds, but be warned, the output is quite verbose.
Note that if the expression can’t be translated into uses of <$>, <*> only, then it will incur a Monad constraint as usual. This happens when there is a dependency on a value produced by an earlier statement in the doblock:
Prelude> :t \m > do { x < m True; y < m x; return (x  y) }
\m > do { x < m True; y < m x; return (x  y) }
:: Monad m => (Bool > m Bool) > m Bool
Here, m x depends on the value of x produced by the first statement, so the expression cannot be translated using <*>.
In general, the rule for when a do statement incurs a Monad constraint is as follows. If the doexpression has the following form:
do p1 < E1; ...; pn < En; return E
where none of the variables defined by p1...pn are mentioned in E1...En, then the expression will only require Applicative. Otherwise, the expression will require Monad. The block may return a pure expression E depending upon the results p1...pn with either return or pure.
Note: the final statement must match one of these patterns exactly:
otherwise GHC cannot recognise it as a return statement, and the transformation to use <$> that we saw above does not apply. In particular, slight variations such as return . Just $ x or let x = e in return x would not be recognised.
If the final statement is not of one of these forms, GHC falls back to standard do desugaring, and the expression will require a Monad constraint.
When the statements of a do expression have dependencies between them, and ApplicativeDo cannot infer an Applicative type, it uses a heuristic algorithm to try to use <*> as much as possible. This algorithm usually finds the best solution, but in rare complex cases it might miss an opportunity. There is an algorithm that finds the optimal solution, provided as an option:
Since:  8.0.1 

Enables an alternative algorithm for choosing where to use <*> in conjunction with the ApplicativeDo language extension. This algorithm always finds the optimal solution, but it is expensive: O(n^3), so this option can lead to long compile times when there are very large do expressions (over 100 statements). The default ApplicativeDo algorithm is O(n^2).
Your code should just work as before when XApplicativeDo is enabled, provided you use conventional Applicative instances. However, if you define a Functor or Applicative instance using donotation, then it will likely get turned into an infinite loop by GHC. For example, if you do this:
instance Functor MyType where
fmap f m = do x < m; return (f x)
Then applicative desugaring will turn it into
instance Functor MyType where
fmap f m = fmap (\x > f x) m
And the program will loop at runtime. Similarly, an Applicative instance like this
instance Applicative MyType where
pure = return
x <*> y = do f < x; a < y; return (f a)
will result in an infinte loop when <*> is called.
Just as you wouldn’t define a Monad instance using the donotation, you shouldn’t define Functor or Applicative instance using donotation (when using ApplicativeDo) either. The correct way to define these instances in terms of Monad is to use the Monad operations directly, e.g.
instance Functor MyType where
fmap f m = m >>= return . f
instance Applicative MyType where
pure = return
(<*>) = ap
Allow parallel list comprehension syntax.
Parallel list comprehensions are a natural extension to list comprehensions. List comprehensions can be thought of as a nice syntax for writing maps and filters. Parallel comprehensions extend this to include the zipWith family.
A parallel list comprehension has multiple independent branches of qualifier lists, each separated by a  symbol. For example, the following zips together two lists:
[ (x, y)  x < xs  y < ys ]
The behaviour of parallel list comprehensions follows that of zip, in that the resulting list will have the same length as the shortest branch.
We can define parallel list comprehensions by translation to regular comprehensions. Here’s the basic idea:
Given a parallel comprehension of the form:
[ e  p1 < e11, p2 < e12, ...
 q1 < e21, q2 < e22, ...
...
]
This will be translated to:
[ e  ((p1,p2), (q1,q2), ...) < zipN [(p1,p2)  p1 < e11, p2 < e12, ...]
[(q1,q2)  q1 < e21, q2 < e22, ...]
...
]
where zipN is the appropriate zip for the given number of branches.
Allow use of generalised list (SQLlike) comprehension syntax. This introduces the group, by, and using keywords.
Generalised list comprehensions are a further enhancement to the list comprehension syntactic sugar to allow operations such as sorting and grouping which are familiar from SQL. They are fully described in the paper Comprehensive comprehensions: comprehensions with “order by” and “group by”, except that the syntax we use differs slightly from the paper.
The extension is enabled with the flag XTransformListComp.
Here is an example:
employees = [ ("Simon", "MS", 80)
, ("Erik", "MS", 100)
, ("Phil", "Ed", 40)
, ("Gordon", "Ed", 45)
, ("Paul", "Yale", 60) ]
output = [ (the dept, sum salary)
 (name, dept, salary) < employees
, then group by dept using groupWith
, then sortWith by (sum salary)
, then take 5 ]
In this example, the list output would take on the value:
[("Yale", 60), ("Ed", 85), ("MS", 180)]
There are three new keywords: group, by, and using. (The functions sortWith and groupWith are not keywords; they are ordinary functions that are exported by GHC.Exts.)
There are five new forms of comprehension qualifier, all introduced by the (existing) keyword then:
then f
This statement requires that f have the type forall a. [a] > [a] . You can see an example of its use in the motivating example, as this form is used to apply take 5 .
then f by e
This form is similar to the previous one, but allows you to create a function which will be passed as the first argument to f. As a consequence f must have the type forall a. (a > t) > [a] > [a]. As you can see from the type, this function lets f “project out” some information from the elements of the list it is transforming.
An example is shown in the opening example, where sortWith is supplied with a function that lets it find out the sum salary for any item in the list comprehension it transforms.
then group by e using f
This is the most general of the groupingtype statements. In this form, f is required to have type forall a. (a > t) > [a] > [[a]]. As with the then f by e case above, the first argument is a function supplied to f by the compiler which lets it compute e on every element of the list being transformed. However, unlike the nongrouping case, f additionally partitions the list into a number of sublists: this means that at every point after this statement, binders occurring before it in the comprehension refer to lists of possible values, not single values. To help understand this, let’s look at an example:
 This works similarly to groupWith in GHC.Exts, but doesn't sort its input first
groupRuns :: Eq b => (a > b) > [a] > [[a]]
groupRuns f = groupBy (\x y > f x == f y)
output = [ (the x, y)
 x < ([1..3] ++ [1..2])
, y < [4..6]
, then group by x using groupRuns ]
This results in the variable output taking on the value below:
[(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])]
Note that we have used the the function to change the type of x from a list to its original numeric type. The variable y, in contrast, is left unchanged from the list form introduced by the grouping.
then group using f
With this form of the group statement, f is required to simply have the type forall a. [a] > [[a]], which will be used to group up the comprehension so far directly. An example of this form is as follows:
output = [ x
 y < [1..5]
, x < "hello"
, then group using inits]
This will yield a list containing every prefix of the word “hello” written out 5 times:
["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...]
Since:  7.2 

Enable list comprehension syntax for arbitrary monads.
Monad comprehensions generalise the list comprehension notation, including parallel comprehensions (Parallel List Comprehensions) and transform comprehensions (Generalised (SQLlike) List Comprehensions) to work for any monad.
Monad comprehensions support:
Bindings:
[ x + y  x < Just 1, y < Just 2 ]
Bindings are translated with the (>>=) and return functions to the usual donotation:
do x < Just 1
y < Just 2
return (x+y)
Guards:
[ x  x < [1..10], x <= 5 ]
Guards are translated with the guard function, which requires a MonadPlus instance:
do x < [1..10]
guard (x <= 5)
return x
Transform statements (as with XTransformListComp):
[ x+y  x < [1..10], y < [1..x], then take 2 ]
This translates to:
do (x,y) < take 2 (do x < [1..10]
y < [1..x]
return (x,y))
return (x+y)
Group statements (as with XTransformListComp):
[ x  x < [1,1,2,2,3], then group by x using GHC.Exts.groupWith ]
[ x  x < [1,1,2,2,3], then group using myGroup ]
Parallel statements (as with XParallelListComp):
[ (x+y)  x < [1..10]
 y < [11..20]
]
Parallel statements are translated using the mzip function, which requires a MonadZip instance defined in Control.Monad.Zip:
do (x,y) < mzip (do x < [1..10]
return x)
(do y < [11..20]
return y)
return (x+y)
All these features are enabled by default if the XMonadComprehensions extension is enabled. The types and more detailed examples on how to use comprehensions are explained in the previous chapters Generalised (SQLlike) List Comprehensions and Parallel List Comprehensions. In general you just have to replace the type [a] with the type Monad m => m a for monad comprehensions.
Note
Even though most of these examples are using the list monad, monad comprehensions work for any monad. The base package offers all necessary instances for lists, which make XMonadComprehensions backward compatible to builtin, transform and parallel list comprehensions.
More formally, the desugaring is as follows. We write D[ e  Q] to mean the desugaring of the monad comprehension [ e  Q]:
Expressions: e
Declarations: d
Lists of qualifiers: Q,R,S
 Basic forms
D[ e  ] = return e
D[ e  p < e, Q ] = e >>= \p > D[ e  Q ]
D[ e  e, Q ] = guard e >> \p > D[ e  Q ]
D[ e  let d, Q ] = let d in D[ e  Q ]
 Parallel comprehensions (iterate for multiple parallel branches)
D[ e  (Q  R), S ] = mzip D[ Qv  Q ] D[ Rv  R ] >>= \(Qv,Rv) > D[ e  S ]
 Transform comprehensions
D[ e  Q then f, R ] = f D[ Qv  Q ] >>= \Qv > D[ e  R ]
D[ e  Q then f by b, R ] = f (\Qv > b) D[ Qv  Q ] >>= \Qv > D[ e  R ]
D[ e  Q then group using f, R ] = f D[ Qv  Q ] >>= \ys >
case (fmap selQv1 ys, ..., fmap selQvn ys) of
Qv > D[ e  R ]
D[ e  Q then group by b using f, R ] = f (\Qv > b) D[ Qv  Q ] >>= \ys >
case (fmap selQv1 ys, ..., fmap selQvn ys) of
Qv > D[ e  R ]
where Qv is the tuple of variables bound by Q (and used subsequently)
selQvi is a selector mapping Qv to the ith component of Qv
Operator Standard binding Expected type

return GHC.Base t1 > m t2
(>>=) GHC.Base m1 t1 > (t2 > m2 t3) > m3 t3
(>>) GHC.Base m1 t1 > m2 t2 > m3 t3
guard Control.Monad t1 > m t2
fmap GHC.Base forall a b. (a>b) > n a > n b
mzip Control.Monad.Zip forall a b. m a > m b > m (a,b)
The comprehension should typecheck when its desugaring would typecheck, except that (as discussed in Generalised (SQLlike) List Comprehensions) in the “then f” and “then group using f” clauses, when the “by b” qualifier is omitted, argument f should have a polymorphic type. In particular, “then Data.List.sort” and “then group using Data.List.group” are insufficiently polymorphic.
Monad comprehensions support rebindable syntax (Rebindable syntax and the implicit Prelude import). Without rebindable syntax, the operators from the “standard binding” module are used; with rebindable syntax, the operators are looked up in the current lexical scope. For example, parallel comprehensions will be typechecked and desugared using whatever “mzip” is in scope.
The rebindable operators must have the “Expected type” given in the table above. These types are surprisingly general. For example, you can use a bind operator with the type
(>>=) :: T x y a > (a > T y z b) > T x z b
In the case of transform comprehensions, notice that the groups are parameterised over some arbitrary type n (provided it has an fmap, as well as the comprehension being over an arbitrary monad.
Since:  8.0.1 

Use the MonadFail.fail instead of the legacy Monad.fail function when desugaring refutable patterns in do blocks.
The XMonadFailDesugaring extension switches the desugaring of doblocks to use MonadFail.fail instead of Monad.fail. This will eventually be the default behaviour in a future GHC release, under the MonadFail Proposal (MFP).
This extension is temporary, and will be deprecated in a future release. It is included so that library authors have a hard check for whether their code will work with future GHC versions.
Don’t import Prelude by default.
GHC normally imports Prelude.hi files for you. If you’d rather it didn’t, then give it a XNoImplicitPrelude option. The idea is that you can then import a Prelude of your own. (But don’t call it Prelude; the Haskell module namespace is flat, and you must not conflict with any Prelude module.)
Implies:  XNoImplicitPrelude 

Since:  7.0.1 
Enable rebinding of a variety of usuallybuiltin operations.
Suppose you are importing a Prelude of your own in order to define your own numeric class hierarchy. It completely defeats that purpose if the literal “1” means “Prelude.fromInteger 1”, which is what the Haskell Report specifies. So the XRebindableSyntax flag causes the following pieces of builtin syntax to refer to whatever is in scope, not the Prelude versions:
XRebindableSyntax implies XNoImplicitPrelude.
In all cases (apart from arrow notation), the static semantics should be that of the desugared form, even if that is a little unexpected. For example, the static semantics of the literal 368 is exactly that of fromInteger (368::Integer); it’s fine for fromInteger to have any of the types:
fromInteger :: Integer > Integer
fromInteger :: forall a. Foo a => Integer > a
fromInteger :: Num a => a > Integer
fromInteger :: Integer > Bool > Bool
Be warned: this is an experimental facility, with fewer checks than usual. Use dcorelint to typecheck the desugared program. If Core Lint is happy you should be all right.
XRebindableSyntax does not apply to any code generated from a deriving clause or declaration. To see why, consider the following code:
{# LANGUAGE RebindableSyntax, OverloadedStrings #}
newtype Text = Text String
fromString :: String > Text
fromString = Text
data Foo = Foo deriving Show
This will generate code to the effect of:
instance Show Foo where
showsPrec _ Foo = showString "Foo"
But because XRebindableSyntax and XOverloadedStrings are enabled, the "Foo" string literal would now be of type Text, not String, which showString doesn’t accept! This causes the generated Show instance to fail to typecheck. It’s hard to imagine any scenario where it would be desirable have XRebindableSyntax behavior within derived code, so GHC simply ignores XRebindableSyntax entirely when checking derived code.
Allow the use of postfix operators
The XPostfixOperators flag enables a small extension to the syntax of left operator sections, which allows you to define postfix operators. The extension is this: the left section
(e !)
is equivalent (from the point of view of both type checking and execution) to the expression
((!) e)
(for any expression e and operator (!). The strict Haskell 98 interpretation is that the section is equivalent to
(\y > (!) e y)
That is, the operator must be a function of two arguments. GHC allows it to take only one argument, and that in turn allows you to write the function postfix.
The extension does not extend to the lefthand side of function definitions; you must define such a function in prefix form.
Since:  6.12 

Allow the use of tuple section syntax
The XTupleSections flag enables Pythonstyle partially applied tuple constructors. For example, the following program
(, True)
is considered to be an alternative notation for the more unwieldy alternative
\x > (x, True)
You can omit any combination of arguments to the tuple, as in the following
(, "I", , , "Love", , 1337)
which translates to
\a b c d > (a, "I", b, c, "Love", d, 1337)
If you have unboxed tuples enabled, tuple sections will also be available for them, like so
(# , True #)
Because there is no unboxed unit tuple, the following expression
(# #)
continues to stand for the unboxed singleton tuple data constructor.
Since:  7.6.1 

Allow the use of lambdacase syntax.
The XLambdaCase flag enables expressions of the form
\case { p1 > e1; ...; pN > eN }
which is equivalent to
\freshName > case freshName of { p1 > e1; ...; pN > eN }
Note that \case starts a layout, so you can write
\case
p1 > e1
...
pN > eN
Since:  7.8.1 

Allow empty case expressions.
The XEmptyCase flag enables case expressions, or lambdacase expressions, that have no alternatives, thus:
case e of { }  No alternatives
or
\case { }  XLambdaCase is also required
This can be useful when you know that the expression being scrutinised has no nonbottom values. For example:
data Void
f :: Void > Int
f x = case x of { }
With dependentlytyped features it is more useful (see Trac #2431`). For example, consider these two candidate definitions of absurd:
data a :==: b where
Refl :: a :==: a
absurd :: True :~: False > a
absurd x = error "absurd"  (A)
absurd x = case x of {}  (B)
We much prefer (B). Why? Because GHC can figure out that (True :~: False) is an empty type. So (B) has no partiality and GHC should be able to compile with Wincompletepatterns. (Though the pattern match checking is not yet clever enough to do that.) On the other hand (A) looks dangerous, and GHC doesn’t check to make sure that, in fact, the function can never get called.
Since:  7.6.1 

Allow the use of multiwayif syntax.
With XMultiWayIf flag GHC accepts conditional expressions with multiple branches:
if  guard1 > expr1
 ...
 guardN > exprN
which is roughly equivalent to
case () of
_  guard1 > expr1
...
_  guardN > exprN
Multiway if expressions introduce a new layout context. So the example above is equivalent to:
if {  guard1 > expr1
;  ...
;  guardN > exprN
}
The following behaves as expected:
if  guard1 > if  guard2 > expr2
 guard3 > expr3
 guard4 > expr4
because layout translates it as
if {  guard1 > if {  guard2 > expr2
;  guard3 > expr3
}
;  guard4 > expr4
}
Layout with multiway if works in the same way as other layout contexts, except that the semicolons between guards in a multiway if are optional. So it is not necessary to line up all the guards at the same column; this is consistent with the way guards work in function definitions and case expressions.
A careful reading of the Haskell 98 Report reveals that fixity declarations (infix, infixl, and infixr) are permitted to appear inside local bindings such those introduced by let and where. However, the Haskell Report does not specify the semantics of such bindings very precisely.
In GHC, a fixity declaration may accompany a local binding:
let f = ...
infixr 3 `f`
in
...
and the fixity declaration applies wherever the binding is in scope. For example, in a let, it applies in the righthand sides of other letbindings and the body of the letC. Or, in recursive do expressions (The recursive donotation), the local fixity declarations of a let statement scope over other statements in the group, just as the bound name does.
Moreover, a local fixity declaration must accompany a local binding of that name: it is not possible to revise the fixity of name bound elsewhere, as in
let infixr 9 $ in ...
Because local fixity declarations are technically Haskell 98, no flag is necessary to enable them.
Technically in Haskell 2010 this is illegal:
module A( f ) where
f = True
module B where
import A hiding( g )  A does not export g
g = f
The import A hiding( g ) in module B is technically an error (Haskell Report, 5.3.1) because A does not export g. However GHC allows it, in the interests of supporting backward compatibility; for example, a newer version of A might export g, and you want B to work in either case.
The warning Wdodgyimports, which is off by default but included with W, warns if you hide something that the imported module does not export.
Allow the use of packagequalified import syntax.
With the XPackageImports flag, GHC allows import declarations to be qualified by the package name that the module is intended to be imported from. For example:
import "network" Network.Socket
would import the module Network.Socket from the package network (any version). This may be used to disambiguate an import when the same module is available from multiple packages, or is present in both the current package being built and an external package.
The special package name this can be used to refer to the current package being built.
Note
You probably don’t need to use this feature, it was added mainly so that we can build backwardscompatible versions of packages when APIs change. It can lead to fragile dependencies in the common case: modules occasionally move from one package to another, rendering any packagequalified imports broken. See also Thinning and renaming modules for an alternative way of disambiguating between module names.
Since:  7.2 

Declare the Safe Haskell state of the current module.
With the XSafe, XTrustworthy and XUnsafe language flags, GHC extends the import declaration syntax to take an optional safe keyword after the import keyword. This feature is part of the Safe Haskell GHC extension. For example:
import safe qualified Network.Socket as NS
would import the module Network.Socket with compilation only succeeding if Network.Socket can be safely imported. For a description of when a import is considered safe see Safe Haskell.
Since:  7.6.1 

Enable use of explicit namespaces in module export lists.
In an import or export list, such as
module M( f, (++) ) where ...
import N( f, (++) )
...
the entities f and (++) are values. However, with type operators (Type operators) it becomes possible to declare (++) as a type constructor. In that case, how would you export or import it?
The XExplicitNamespaces extension allows you to prefix the name of a type constructor in an import or export list with “type” to disambiguate this case, thus:
module M( f, type (++) ) where ...
import N( f, type (++) )
...
module N( f, type (++) ) where
data family a ++ b = L a  R b
The extension XExplicitNamespaces is implied by XTypeOperators and (for some reason) by XTypeFamilies.
In addition, with XPatternSynonyms you can prefix the name of a data constructor in an import or export list with the keyword pattern, to allow the import or export of a data constructor without its parent type constructor (see Import and export of pattern synonyms).
Turning on an option that enables special syntax might cause working Haskell 98 code to fail to compile, perhaps because it uses a variable name which has become a reserved word. This section lists the syntax that is “stolen” by language extensions. We use notation and nonterminal names from the Haskell 98 lexical syntax (see the Haskell 98 Report). We only list syntax changes here that might affect existing working programs (i.e. “stolen” syntax). Many of these extensions will also enable new contextfree syntax, but in all cases programs written to use the new syntax would not be compilable without the option enabled.
There are two classes of special syntax:
The following syntax is stolen:
Stolen (in types) by: XExplicitForAll, and hence by XScopedTypeVariables, XLiberalTypeSynonyms, XRankNTypes, XExistentialQuantification
Stolen by: XRecursiveDo
Stolen by: XForeignFunctionInterface
Stolen by: XArrows
Stolen by: XImplicitParams
Stolen by: XQuasiQuotes. Moreover, this introduces an ambiguity with list comprehension syntax. See the discussion on quasiquoting for details.
Stolen by: XTemplateHaskell
Stolen by: XQuasiQuotes
Allow definition of empty data types.
With the XEmptyDataDecls flag (or equivalent LANGUAGE pragma), GHC lets you declare a data type with no constructors. For example:
data S  S :: *
data T a  T :: * > *
Syntactically, the declaration lacks the “= constrs” part. The type can be parameterised over types of any kind, but if the kind is not * then an explicit kind annotation must be used (see Explicitlykinded quantification).
Such data types have only one value, namely bottom. Nevertheless, they can be useful when defining “phantom types”.
Since:  7.0.1 

Allow contexts on data types.
Haskell allows datatypes to be given contexts, e.g.
data Eq a => Set a = NilSet  ConsSet a (Set a)
give constructors with types:
NilSet :: Set a
ConsSet :: Eq a => a > Set a > Set a
This is widely considered a misfeature, and is going to be removed from the language. In GHC, it is controlled by the deprecated extension DatatypeContexts.
GHC allows type constructors, classes, and type variables to be operators, and to be written infix, very much like expressions. More specifically:
A type constructor or class can be any nonreserved operator. Symbols used in types are always like capitalized identifiers; they are never variables. Note that this is different from the lexical syntax of data constructors, which are required to begin with a :.
Data type and typesynonym declarations can be written infix, parenthesised if you want further arguments. E.g.
data a :*: b = Foo a b
type a :+: b = Either a b
class a :=: b where ...
data (a :**: b) x = Baz a b x
type (a :++: b) y = Either (a,b) y
Types, and class constraints, can be written infix. For example
x :: Int :*: Bool
f :: (a :=: b) => a > b
Backquotes work as for expressions, both for type constructors and type variables; e.g. Int `Either` Bool, or Int `a` Bool. Similarly, parentheses work the same; e.g. (:*:) Int Bool.
Fixities may be declared for type constructors, or classes, just as for data constructors. However, one cannot distinguish between the two in a fixity declaration; a fixity declaration sets the fixity for a data constructor and the corresponding type constructor. For example:
infixl 7 T, :*:
sets the fixity for both type constructor T and data constructor T, and similarly for :*:. Int `a` Bool.
Function arrow is infixr with fixity 0 (this might change; it’s not clear what it should be).
Implies:  XExplicitNamespaces 

Allow the use and definition of types with operator names.
In types, an operator symbol like (+) is normally treated as a type variable, just like a. Thus in Haskell 98 you can say
type T (+) = ((+), (+))
 Just like: type T a = (a,a)
f :: T Int > Int
f (x,y)= x
As you can see, using operators in this way is not very useful, and Haskell 98 does not even allow you to write them infix.
The language XTypeOperators changes this behaviour:
Operator symbols become type constructors rather than type variables.
Operator symbols in types can be written infix, both in definitions and uses. For example:
data a + b = Plus a b
type Foo = Int + Bool
There is now some potential ambiguity in import and export lists; for example if you write import M( (+) ) do you mean the function (+) or the type constructor (+)? The default is the former, but with XExplicitNamespaces (which is implied by XTypeOperators) GHC allows you to specify the latter by preceding it with the keyword type, thus:
import M( type (+) )
The fixity of a type operator may be set using the usual fixity declarations but, as in Infix type constructors, classes, and type variables, the function and type constructor share a single fixity.
Implies:  XExplicitForAll 

Relax many of the Haskell 98 rules on type synonym definitions.
Type synonyms are like macros at the type level, but Haskell 98 imposes many rules on individual synonym declarations. With the XLiberalTypeSynonyms extension, GHC does validity checking on types only after expanding type synonyms. That means that GHC can be very much more liberal about type synonyms than Haskell 98.
You can write a forall (including overloading) in a type synonym, thus:
type Discard a = forall b. Show b => a > b > (a, String)
f :: Discard a
f x y = (x, show y)
g :: Discard Int > (Int,String)  A rank2 type
g f = f 3 True
If you also use XUnboxedTuples, you can write an unboxed tuple in a type synonym:
type Pr = (# Int, Int #)
h :: Int > Pr
h x = (# x, x #)
You can apply a type synonym to a forall type:
type Foo a = a > a > Bool
f :: Foo (forall b. b>b)
After expanding the synonym, f has the legal (in GHC) type:
f :: (forall b. b>b) > (forall b. b>b) > Bool
You can apply a type synonym to a partially applied type synonym:
type Generic i o = forall x. i x > o x
type Id x = x
foo :: Generic Id []
After expanding the synonym, foo has the legal (in GHC) type:
foo :: forall x. x > [x]
GHC currently does kind checking before expanding synonyms (though even that could be changed)..
After expanding type synonyms, GHC does validity checking on types, looking for the following malformedness which isn’t detected simply by kind checking:
So, for example, this will be rejected:
type Pr = forall a. a
h :: [Pr]
h = ...
because GHC does not allow type constructors applied to forall types.
Implies:  XExplicitForAll 

Allow existentially quantified type variables in types.
The idea of using existential quantification in data type declarations was suggested by Perry, and implemented in Hope+ (Nigel Perry, The Implementation of Practical Functional Programming Languages, PhD Thesis, University of London, 1991). It was later formalised by Laufer and Odersky (Polymorphic type inference and abstract data types, TOPLAS, 16(5), pp. 14111430, 1994). It’s been in Lennart Augustsson’s hbc Haskell compiler for several years, and proved very useful. Here’s the idea. Consider the declaration:
data Foo = forall a. MkFoo a (a > Bool)
 Nil
The data type Foo has two constructors with types:
MkFoo :: forall a. a > (a > Bool) > Foo
Nil :: Foo
Notice that the type variable a in the type of MkFoo does not appear in the data type itself, which is plain Foo. For example, the following expression is fine:
[MkFoo 3 even, MkFoo 'c' isUpper] :: [Foo]
Here, (MkFoo 3 even) packages an integer with a function even that maps an integer to Bool; and MkFoo 'c' isUpper packages a character with a compatible function. These two things are each of type Foo and can be put in a list.
What can we do with a value of type Foo? In particular, what happens when we patternmatch on MkFoo?
f (MkFoo val fn) = ???
Since all we know about val and fn is that they are compatible, the only (useful) thing we can do with them is to apply fn to val to get a boolean. For example:
f :: Foo > Bool
f (MkFoo val fn) = fn val
What this allows us to do is to package heterogeneous values together with a bunch of functions that manipulate them, and then treat that collection of packages in a uniform manner. You can express quite a bit of objectorientedlike programming this way.
What has this to do with existential quantification? Simply that MkFoo has the (nearly) isomorphic type
MkFoo :: (exists a . (a, a > Bool)) > Foo
But Haskell programmers can safely think of the ordinary universally quantified type given above, thereby avoiding adding a new existential quantification construct.
An easy extension is to allow arbitrary contexts before the constructor. For example:
data Baz = forall a. Eq a => Baz1 a a
 forall b. Show b => Baz2 b (b > b)
The two constructors have the types you’d expect:
Baz1 :: forall a. Eq a => a > a > Baz
Baz2 :: forall b. Show b => b > (b > b) > Baz
But when pattern matching on Baz1 the matched values can be compared for equality, and when pattern matching on Baz2 the first matched value can be converted to a string (as well as applying the function to it). So this program is legal:
f :: Baz > String
f (Baz1 p q)  p == q = "Yes"
 otherwise = "No"
f (Baz2 v fn) = show (fn v)
Operationally, in a dictionarypassing implementation, the constructors Baz1 and Baz2 must store the dictionaries for Eq and Show respectively, and extract it on pattern matching.
GHC allows existentials to be used with records syntax as well. For example:
data Counter a = forall self. NewCounter
{ _this :: self
, _inc :: self > self
, _display :: self > IO ()
, tag :: a
}
Here tag is a public field, with a welltyped selector function tag :: Counter a > a. The self type is hidden from the outside; any attempt to apply _this, _inc or _display as functions will raise a compiletime error. In other words, GHC defines a record selector function only for fields whose type does not mention the existentiallyquantified variables. (This example used an underscore in the fields for which record selectors will not be defined, but that is only programming style; GHC ignores them.)
To make use of these hidden fields, we need to create some helper functions:
inc :: Counter a > Counter a
inc (NewCounter x i d t) = NewCounter
{ _this = i x, _inc = i, _display = d, tag = t }
display :: Counter a > IO ()
display NewCounter{ _this = x, _display = d } = d x
Now we can define counters with different underlying implementations:
counterA :: Counter String
counterA = NewCounter
{ _this = 0, _inc = (1+), _display = print, tag = "A" }
counterB :: Counter String
counterB = NewCounter
{ _this = "", _inc = ('#':), _display = putStrLn, tag = "B" }
main = do
display (inc counterA)  prints "1"
display (inc (inc counterB))  prints "##"
Record update syntax is supported for existentials (and GADTs):
setTag :: Counter a > a > Counter a
setTag obj t = obj{ tag = t }
The rule for record update is this:
the types of the updated fields may mention only the universallyquantified type variables of the data constructor. For GADTs, the field may mention only types that appear as a simple typevariable argument in the constructor’s result type.
For example:
data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b }  c is existential
upd1 t x = t { f1=x }  OK: upd1 :: T a b > a' > T a' b
upd2 t x = t { f3=x }  BAD (f3's type mentions c, which is
 existentially quantified)
data G a b where { G1 { g1::a, g2::c } :: G a [c] }
upd3 g x = g { g1=x }  OK: upd3 :: G a b > c > G c b
upd4 g x = g { g2=x }  BAD (f2's type mentions c, which is not a simple
 typevariable argument in G1's result type)
There are several restrictions on the ways in which existentiallyquantified constructors can be used.
When pattern matching, each pattern match introduces a new, distinct, type for each existential type variable. These types cannot be unified with any other type, nor can they escape from the scope of the pattern match. For example, these fragments are incorrect:
f1 (MkFoo a f) = a
Here, the type bound by MkFoo “escapes”, because a is the result of f1. One way to see why this is wrong is to ask what type f1 has:
f1 :: Foo > a  Weird!
What is this “a” in the result type? Clearly we don’t mean this:
f1 :: forall a. Foo > a  Wrong!
The original program is just plain wrong. Here’s another sort of error
f2 (Baz1 a b) (Baz1 p q) = a==q
It’s ok to say a==b or p==q, but a==q is wrong because it equates the two distinct types arising from the two Baz1 constructors.
You can’t patternmatch on an existentially quantified constructor in a let or where group of bindings. So this is illegal:
f3 x = a==b where { Baz1 a b = x }
Instead, use a case expression:
f3 x = case x of Baz1 a b > a==b
In general, you can only patternmatch on an existentiallyquantified constructor in a case expression or in the patterns of a function definition. The reason for this restriction is really an implementation one. Typechecking binding groups is already a nightmare without existentials complicating the picture. Also an existential pattern binding at the top level of a module doesn’t make sense, because it’s not clear how to prevent the existentiallyquantified type “escaping”. So for now, there’s a simpletostate restriction. We’ll see how annoying it is.
You can’t use existential quantification for newtype declarations. So this is illegal:
newtype T = forall a. Ord a => MkT a
Reason: a value of type T must be represented as a pair of a dictionary for Ord t and a value of type t. That contradicts the idea that newtype should have no concrete representation. You can get just the same efficiency and effect by using data instead of newtype. If there is no overloading involved, then there is more of a case for allowing an existentiallyquantified newtype, because the data version does carry an implementation cost, but singlefield existentially quantified constructors aren’t much use. So the simple restriction (no existential stuff on newtype) stands, unless there are convincing reasons to change it.
You can’t use deriving to define instances of a data type with existentially quantified data constructors. Reason: in most cases it would not make sense. For example:;
data T = forall a. MkT [a] deriving( Eq )
To derive Eq in the standard way we would need to have equality between the single component of two MkT constructors:
instance Eq T where
(MkT a) == (MkT b) = ???
But a and b have distinct types, and so can’t be compared. It’s just about possible to imagine examples in which the derived instance would make sense, but it seems altogether simpler simply to prohibit such declarations. Define your own instances!
Since:  7.2 

Allow the use of GADT syntax in data type definitions (but not GADTs themselves; for this see XGADTs)
When the GADTSyntax extension is enabled, GHC allows you to declare an algebraic data type by giving the type signatures of constructors explicitly. For example:
data Maybe a where
Nothing :: Maybe a
Just :: a > Maybe a
The form is called a “GADTstyle declaration” because Generalised Algebraic Data Types, described in Generalised Algebraic Data Types (GADTs), can only be declared using this form.
Notice that GADTstyle syntax generalises existential types (Existentially quantified data constructors). For example, these two declarations are equivalent:
data Foo = forall a. MkFoo a (a > Bool)
data Foo' where { MKFoo :: a > (a>Bool) > Foo' }
Any data type that can be declared in standard Haskell 98 syntax can also be declared using GADTstyle syntax. The choice is largely stylistic, but GADTstyle declarations differ in one important respect: they treat class constraints on the data constructors differently. Specifically, if the constructor is given a typeclass context, that context is made available by pattern matching. For example:
data Set a where
MkSet :: Eq a => [a] > Set a
makeSet :: Eq a => [a] > Set a
makeSet xs = MkSet (nub xs)
insert :: a > Set a > Set a
insert a (MkSet as)  a `elem` as = MkSet as
 otherwise = MkSet (a:as)
A use of MkSet as a constructor (e.g. in the definition of makeSet) gives rise to a (Eq a) constraint, as you would expect. The new feature is that patternmatching on MkSet (as in the definition of insert) makes available an (Eq a) context. In implementation terms, the MkSet constructor has a hidden field that stores the (Eq a) dictionary that is passed to MkSet; so when patternmatching that dictionary becomes available for the righthand side of the match. In the example, the equality dictionary is used to satisfy the equality constraint generated by the call to elem, so that the type of insert itself has no Eq constraint.
For example, one possible application is to reify dictionaries:
data NumInst a where
MkNumInst :: Num a => NumInst a
intInst :: NumInst Int
intInst = MkNumInst
plus :: NumInst a > a > a > a
plus MkNumInst p q = p + q
Here, a value of type NumInst a is equivalent to an explicit (Num a) dictionary.
All this applies to constructors declared using the syntax of Existentials and type classes. For example, the NumInst data type above could equivalently be declared like this:
data NumInst a
= Num a => MkNumInst (NumInst a)
Notice that, unlike the situation when declaring an existential, there is no forall, because the Num constrains the data type’s universally quantified type variable a. A constructor may have both universal and existential type variables: for example, the following two declarations are equivalent:
data T1 a
= forall b. (Num a, Eq b) => MkT1 a b
data T2 a where
MkT2 :: (Num a, Eq b) => a > b > T2 a
All this behaviour contrasts with Haskell 98’s peculiar treatment of contexts on a data type declaration (Section 4.2.1 of the Haskell 98 Report). In Haskell 98 the definition
data Eq a => Set' a = MkSet' [a]
gives MkSet' the same type as MkSet above. But instead of making available an (Eq a) constraint, patternmatching on MkSet' requires an (Eq a) constraint! GHC faithfully implements this behaviour, odd though it is. But for GADTstyle declarations, GHC’s behaviour is much more useful, as well as much more intuitive.
The rest of this section gives further details about GADTstyle data type declarations.
The result type of each data constructor must begin with the type constructor being defined. If the result type of all constructors has the form T a1 ... an, where a1 ... an are distinct type variables, then the data type is ordinary; otherwise is a generalised data type (Generalised Algebraic Data Types (GADTs)).
As with other type signatures, you can give a single signature for several data constructors. In this example we give a single signature for T1 and T2:
data T a where
T1,T2 :: a > T a
T3 :: T a
The type signature of each constructor is independent, and is implicitly universally quantified as usual. In particular, the type variable(s) in the “data T a where” header have no scope, and different constructors may have different universallyquantified type variables:
data T a where  The 'a' has no scope
T1,T2 :: b > T b  Means forall b. b > T b
T3 :: T a  Means forall a. T a
A constructor signature may mention type class constraints, which can differ for different constructors. For example, this is fine:
data T a where
T1 :: Eq b => b > b > T b
T2 :: (Show c, Ix c) => c > [c] > T c
When pattern matching, these constraints are made available to discharge constraints in the body of the match. For example:
f :: T a > String
f (T1 x y)  x==y = "yes"
 otherwise = "no"
f (T2 a b) = show a
Note that f is not overloaded; the Eq constraint arising from the use of == is discharged by the pattern match on T1 and similarly the Show constraint arising from the use of show.
Unlike a Haskell98style data type declaration, the type variable(s) in the “data Set a where” header have no scope. Indeed, one can write a kind signature instead:
data Set :: * > * where ...
or even a mixture of the two:
data Bar a :: (* > *) > * where ...
The type variables (if given) may be explicitly kinded, so we could also write the header for Foo like this:
data Bar a (b :: * > *) where ...
You can use strictness annotations, in the obvious places in the constructor type:
data Term a where
Lit :: !Int > Term Int
If :: Term Bool > !(Term a) > !(Term a) > Term a
Pair :: Term a > Term b > Term (a,b)
You can use a deriving clause on a GADTstyle data type declaration. For example, these two declarations are equivalent
data Maybe1 a where {
Nothing1 :: Maybe1 a ;
Just1 :: a > Maybe1 a
} deriving( Eq, Ord )
data Maybe2 a = Nothing2  Just2 a
deriving( Eq, Ord )
The type signature may have quantified type variables that do not appear in the result type:
data Foo where
MkFoo :: a > (a>Bool) > Foo
Nil :: Foo
Here the type variable a does not appear in the result type of either constructor. Although it is universally quantified in the type of the constructor, such a type variable is often called “existential”. Indeed, the above declaration declares precisely the same type as the data Foo in Existentially quantified data constructors.
The type may contain a class context too, of course:
data Showable where
MkShowable :: Show a => a > Showable
You can use record syntax on a GADTstyle data type declaration:
data Person where
Adult :: { name :: String, children :: [Person] } > Person
Child :: Show a => { name :: !String, funny :: a } > Person
As usual, for every constructor that has a field f, the type of field f must be the same (modulo alpha conversion). The Child constructor above shows that the signature may have a context, existentiallyquantified variables, and strictness annotations, just as in the nonrecord case. (NB: the “type” that follows the doublecolon is not really a type, because of the record syntax and strictness annotations. A “type” of this form can appear only in a constructor signature.)
Record updates are allowed with GADTstyle declarations, only fields that have the following property: the type of the field mentions no existential type variables.
As in the case of existentials declared using the Haskell98like record syntax (Record Constructors), recordselector functions are generated only for those fields that have welltyped selectors. Here is the example of that section, in GADTstyle syntax:
data Counter a where
NewCounter :: { _this :: self
, _inc :: self > self
, _display :: self > IO ()
, tag :: a
} > Counter a
As before, only one selector function is generated here, that for tag. Nevertheless, you can still use all the field names in pattern matching and record construction.
In a GADTstyle data type declaration there is no obvious way to specify that a data constructor should be infix, which makes a difference if you derive Show for the type. (Data constructors declared infix are displayed infix by the derived show.) So GHC implements the following design: a data constructor declared in a GADTstyle data type declaration is displayed infix by Show iff (a) it is an operator symbol, (b) it has two arguments, (c) it has a programmersupplied fixity declaration. For example
infix 6 (::)
data T a where
(::) :: Int > Bool > T Int
Implies:  XMonoLocalBinds, XGADTSyntax 

Allow use of Generalised Algebraic Data Types (GADTs).
Generalised Algebraic Data Types generalise ordinary algebraic data types by allowing constructors to have richer return types. Here is an example:
data Term a where
Lit :: Int > Term Int
Succ :: Term Int > Term Int
IsZero :: Term Int > Term Bool
If :: Term Bool > Term a > Term a > Term a
Pair :: Term a > Term b > Term (a,b)
Notice that the return type of the constructors is not always Term a, as is the case with ordinary data types. This generality allows us to write a welltyped eval function for these Terms:
eval :: Term a > a
eval (Lit i) = i
eval (Succ t) = 1 + eval t
eval (IsZero t) = eval t == 0
eval (If b e1 e2) = if eval b then eval e1 else eval e2
eval (Pair e1 e2) = (eval e1, eval e2)
The key point about GADTs is that pattern matching causes type refinement. For example, in the right hand side of the equation
eval :: Term a > a
eval (Lit i) = ...
the type a is refined to Int. That’s the whole point! A precise specification of the type rules is beyond what this user manual aspires to, but the design closely follows that described in the paper Simple unificationbased type inference for GADTs, (ICFP 2006). The general principle is this: type refinement is only carried out based on usersupplied type annotations. So if no type signature is supplied for eval, no type refinement happens, and lots of obscure error messages will occur. However, the refinement is quite general. For example, if we had:
eval :: Term a > a > a
eval (Lit i) j = i+j
the pattern match causes the type a to be refined to Int (because of the type of the constructor Lit), and that refinement also applies to the type of j, and the result type of the case expression. Hence the addition i+j is legal.
These and many other examples are given in papers by Hongwei Xi, and Tim Sheard. There is a longer introduction on the wiki, and Ralf Hinze’s Fun with phantom types also has a number of examples. Note that papers may use different notation to that implemented in GHC.
The rest of this section outlines the extensions to GHC that support GADTs. The extension is enabled with XGADTs. The XGADTs flag also sets XGADTSyntax and XMonoLocalBinds.
A GADT can only be declared using GADTstyle syntax (Declaring data types with explicit constructor signatures); the old Haskell 98 syntax for data declarations always declares an ordinary data type. The result type of each constructor must begin with the type constructor being defined, but for a GADT the arguments to the type constructor can be arbitrary monotypes. For example, in the Term data type above, the type of each constructor must end with Term ty, but the ty need not be a type variable (e.g. the Lit constructor).
It is permitted to declare an ordinary algebraic data type using GADTstyle syntax. What makes a GADT into a GADT is not the syntax, but rather the presence of data constructors whose result type is not just T a b.
You cannot use a deriving clause for a GADT; only for an ordinary data type.
As mentioned in Declaring data types with explicit constructor signatures, record syntax is supported. For example:
data Term a where
Lit :: { val :: Int } > Term Int
Succ :: { num :: Term Int } > Term Int
Pred :: { num :: Term Int } > Term Int
IsZero :: { arg :: Term Int } > Term Bool
Pair :: { arg1 :: Term a
, arg2 :: Term b
} > Term (a,b)
If :: { cnd :: Term Bool
, tru :: Term a
, fls :: Term a
} > Term a
However, for GADTs there is the following additional constraint: every constructor that has a field f must have the same result type (modulo alpha conversion) Hence, in the above example, we cannot merge the num and arg fields above into a single name. Although their field types are both Term Int, their selector functions actually have different types:
num :: Term Int > Term Int
arg :: Term Bool > Term Int
When patternmatching against data constructors drawn from a GADT, for example in a case expression, the following rules apply:
A type is “rigid” if it is completely known to the compiler at its binding site. The easiest way to ensure that a variable a rigid type is to give it a type signature. For more precise details see Simple unificationbased type inference for GADTs. The criteria implemented by GHC are given in the Appendix.
Since:  7.4.1 

Disallow use of record syntax.
Traditional record syntax, such as C {f = x}, is enabled by default. To disable it, you can use the XNoTraditionalRecordSyntax flag.
Allow the compiler to automatically choose between identicallynamed record selectors based on type (if the choice is unambiguous).
In record construction and record pattern matching it is entirely unambiguous which field is referred to, even if there are two different data types in scope with a common field name. For example:
module M where
data S = MkS { x :: Int, y :: Bool }
module Foo where
import M
data T = MkT { x :: Int }
ok1 (MkS { x = n }) = n+1  Unambiguous
ok2 n = MkT { x = n+1 }  Unambiguous
bad1 k = k { x = 3 }  Ambiguous
bad2 k = x k  Ambiguous
Even though there are two x‘s in scope, it is clear that the x in the pattern in the definition of ok1 can only mean the field x from type S. Similarly for the function ok2. However, in the record update in bad1 and the record selection in bad2 it is not clear which of the two types is intended.
Haskell 98 regards all four as ambiguous, but with the XDisambiguateRecordFields flag, GHC will accept the former two. The rules are precisely the same as those for instance declarations in Haskell 98, where the method names on the lefthand side of the method bindings in an instance declaration refer unambiguously to the method of that class (provided they are in scope at all), even if there are other variables in scope with the same name. This reduces the clutter of qualified names when you import two records from different modules that use the same field name.
Some details:
Field disambiguation can be combined with punning (see Record puns). For example:
module Foo where
import M
x=True
ok3 (MkS { x }) = x+1  Uses both disambiguation and punning
With XDisambiguateRecordFields you can use unqualified field names even if the corresponding selector is only in scope qualified For example, assuming the same module M as in our earlier example, this is legal:
module Foo where
import qualified M  Note qualified
ok4 (M.MkS { x = n }) = n+1  Unambiguous
Since the constructor MkS is only in scope qualified, you must name it M.MkS, but the field x does not need to be qualified even though M.x is in scope but x is not (In effect, it is qualified by the constructor).
Implies:  XDisambiguateRecordFields 

Since:  8.0.1 
Allow definition of record types with identicallynamed fields.
Going beyond XDisambiguateRecordFields (see Record field disambiguation), the XDuplicateRecordFields extension allows multiple datatypes to be declared using the same field names in a single module. For example, it allows this:
module M where
data S = MkS { x :: Int }
data T = MkT { x :: Bool }
Uses of fields that are always unambiguous because they mention the constructor, including construction and patternmatching, may freely use duplicated field names. For example, the following are permitted (just as with XDisambiguateRecordFields):
s = MkS { x = 3 }
f (MkT { x = b }) = b
Field names used as selector functions or in record updates must be unambiguous, either because there is only one such field in scope, or because a type signature is supplied, as described in the following sections.
Fields may be used as selector functions only if they are unambiguous, so this is still not allowed if both S(x) and T(x) are in scope:
bad r = x r
An ambiguous selector may be disambiguated by the type being “pushed down” to the occurrence of the selector (see Type inference for more details on what “pushed down” means). For example, the following are permitted:
ok1 = x :: S > Int
ok2 :: S > Int
ok2 = x
ok3 = k x  assuming we already have k :: (S > Int) > _
In addition, the datatype that is meant may be given as a type signature on the argument to the selector:
ok4 s = x (s :: S)
However, we do not infer the type of the argument to determine the datatype, or have any way of deferring the choice to the constraint solver. Thus the following is ambiguous:
bad :: S > Int
bad s = x s
Even though a field label is duplicated in its defining module, it may be possible to use the selector unambiguously elsewhere. For example, another module could import S(x) but not T(x), and then use x unambiguously.
In a record update such as e { x = 1 }, if there are multiple x fields in scope, then the type of the context must fix which record datatype is intended, or a type annotation must be supplied. Consider the following definitions:
data S = MkS { foo :: Int }
data T = MkT { foo :: Int, bar :: Int }
data U = MkU { bar :: Int, baz :: Int }
Without XDuplicateRecordFields, an update mentioning foo will always be ambiguous if all these definitions were in scope. When the extension is enabled, there are several options for disambiguating updates:
Check for types that have all the fields being updated. For example:
f x = x { foo = 3, bar = 2 }
Here f must be updating T because neither S nor U have both fields.
Use the type being pushed in to the record update, as in the following:
g1 :: T > T
g1 x = x { foo = 3 }
g2 x = x { foo = 3 } :: T
g3 = k (x { foo = 3 })  assuming we already have k :: T > _
Use an explicit type signature on the record expression, as in:
h x = (x :: T) { foo = 3 }
The type of the expression being updated will not be inferred, and no constraintsolving will be performed, so the following will be rejected as ambiguous:
let x :: T
x = blah
in x { foo = 3 }
\x > [x { foo = 3 }, blah :: T ]
\ (x :: T) > x { foo = 3 }
When XDuplicateRecordFields is enabled, an ambiguous field must be exported as part of its datatype, rather than at the top level. For example, the following is legal:
module M (S(x), T(..)) where
data S = MkS { x :: Int }
data T = MkT { x :: Bool }
However, this would not be permitted, because x is ambiguous:
module M (x) where ...
Similar restrictions apply on import.
Allow use of record puns.
Record puns are enabled by the flag XNamedFieldPuns.
When using records, it is common to write a pattern that binds a variable with the same name as a record field, such as:
data C = C {a :: Int}
f (C {a = a}) = a
Record punning permits the variable name to be elided, so one can simply write
f (C {a}) = a
to mean the same pattern as above. That is, in a record pattern, the pattern a expands into the pattern a = a for the same name a.
Note that:
Record punning can also be used in an expression, writing, for example,
let a = 1 in C {a}
instead of
let a = 1 in C {a = a}
The expansion is purely syntactic, so the expanded righthand side expression refers to the nearest enclosing variable that is spelled the same as the field name.
Puns and other patterns can be mixed in the same record:
data C = C {a :: Int, b :: Int}
f (C {a, b = 4}) = a
Puns can be used wherever record patterns occur (e.g. in let bindings or at the toplevel).
A pun on a qualified field name is expanded by stripping off the module qualifier. For example:
f (C {M.a}) = a
means
f (M.C {M.a = a}) = a
(This is useful if the field selector a for constructor M.C is only in scope in qualified form.)
Implies:  XDisambiguateRecordFields. 

Allow the use of wildcards in record construction and pattern matching.
Record wildcards are enabled by the flag XRecordWildCards. This flag implies XDisambiguateRecordFields.
For records with many fields, it can be tiresome to write out each field individually in a record pattern, as in
data C = C {a :: Int, b :: Int, c :: Int, d :: Int}
f (C {a = 1, b = b, c = c, d = d}) = b + c + d
Record wildcard syntax permits a “..” in a record pattern, where each elided field f is replaced by the pattern f = f. For example, the above pattern can be written as
f (C {a = 1, ..}) = b + c + d
More details:
Record wildcards in patterns can be mixed with other patterns, including puns (Record puns); for example, in a pattern (C {a = 1, b, ..}). Additionally, record wildcards can be used wherever record patterns occur, including in let bindings and at the toplevel. For example, the toplevel binding
C {a = 1, ..} = e
defines b, c, and d.
Record wildcards can also be used in an expression, when constructing a record. For example,
let {a = 1; b = 2; c = 3; d = 4} in C {..}
in place of
let {a = 1; b = 2; c = 3; d = 4} in C {a=a, b=b, c=c, d=d}
The expansion is purely syntactic, so the record wildcard expression refers to the nearest enclosing variables that are spelled the same as the omitted field names.
Record wildcards may not be used in record updates. For example this is illegal:
f r = r { x = 3, .. }
For both pattern and expression wildcards, the “..” expands to the missing inscope record fields. Specifically the expansion of “C {..}” includes f if and only if:
These rules restrict record wildcards to the situations in which the user could have written the expanded version. For example
module M where
data R = R { a,b,c :: Int }
module X where
import M( R(a,c) )
f b = R { .. }
The R{..} expands to R{M.a=a}, omitting b since the record field is not in scope, and omitting c since the variable c is not in scope (apart from the binding of the record selector c, of course).
Record wildcards cannot be used (a) in a record update construct, and (b) for data constructors that are not declared with record fields. For example:
f x = x { v=True, .. }  Illegal (a)
data T = MkT Int Bool
g = MkT { .. }  Illegal (b)
h (MkT { .. }) = True  Illegal (b)
The Haskell Report is vague about exactly when a deriving clause is legal. For example:
data T0 f a = MkT0 a deriving( Eq )
data T1 f a = MkT1 (f a) deriving( Eq )
data T2 f a = MkT2 (f (f a)) deriving( Eq )
The natural generated Eq code would result in these instance declarations:
instance Eq a => Eq (T0 f a) where ...
instance Eq (f a) => Eq (T1 f a) where ...
instance Eq (f (f a)) => Eq (T2 f a) where ...
The first of these is obviously fine. The second is still fine, although less obviously. The third is not Haskell 98, and risks losing termination of instances.
GHC takes a conservative position: it accepts the first two, but not the third. The rule is this: each constraint in the inferred instance context must consist only of type variables, with no repetitions.
This rule is applied regardless of flags. If you want a more exotic context, you can write it yourself, using the standalone deriving mechanism.
Allow the use of standalone deriving declarations.
GHC allows standalone deriving declarations, enabled by XStandaloneDeriving:
data Foo a = Bar a  Baz String
deriving instance Eq a => Eq (Foo a)
The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword deriving, and (b) the absence of the where part.
However, standalone deriving differs from a deriving clause in a number of important ways:
The standalone deriving declaration does not need to be in the same module as the data type declaration. (But be aware of the dangers of orphan instances (Orphan modules and instance declarations).
You must supply an explicit context (in the example the context is (Eq a)), exactly as you would in an ordinary instance declaration. (In contrast, in a deriving clause attached to a data type declaration, the context is inferred.)
Unlike a deriving declaration attached to a data declaration, the instance can be more specific than the data type (assuming you also use XFlexibleInstances, Relaxed rules for instance contexts). Consider for example
data Foo a = Bar a  Baz String
deriving instance Eq a => Eq (Foo [a])
deriving instance Eq a => Eq (Foo (Maybe a))
This will generate a derived instance for (Foo [a]) and (Foo (Maybe a)), but other types such as (Foo (Int,Bool)) will not be an instance of Eq.
Unlike a deriving declaration attached to a data declaration, GHC does not restrict the form of the data type. Instead, GHC simply generates the appropriate boilerplate code for the specified class, and typechecks it. If there is a type error, it is your problem. (GHC will show you the offending code if it has a type error.)
The merit of this is that you can derive instances for GADTs and other exotic data types, providing only that the boilerplate code does indeed typecheck. For example:
data T a where
T1 :: T Int
T2 :: T Bool
deriving instance Show (T a)
In this example, you cannot say ... deriving( Show ) on the data type declaration for T, because T is a GADT, but you can generate the instance declaration using standalone deriving.
The downside is that, if the boilerplate code fails to typecheck, you will get an error message about that code, which you did not write. Whereas, with a deriving clause the sideconditions are necessarily more conservative, but any error message may be more comprehensible.
In other ways, however, a standalone deriving obeys the same rules as ordinary deriving:
A deriving instance declaration must obey the same rules concerning form and termination as ordinary instance declarations, controlled by the same flags; see Instance declarations.
The standalone syntax is generalised for newtypes in exactly the same way that ordinary deriving clauses are generalised (Generalised derived instances for newtypes). For example:
newtype Foo a = MkFoo (State Int a)
deriving instance MonadState Int Foo
GHC always treats the last parameter of the instance (Foo in this example) as the type whose instance is being derived.
Since:  7.2 

Allow automatic deriving of instances for the Generic typeclass.
Since:  6.12 

Allow automatic deriving of instances for the Functor typeclass.
Since:  6.12 

Allow automatic deriving of instances for the Foldable typeclass.
Since:  6.12 

Implies:  XDeriveFoldable, XDeriveFunctor 
Allow automatic deriving of instances for the Traversable typeclass.
Haskell 98 allows the programmer to add “deriving( Eq, Ord )” to a data type declaration, to generate a standard instance declaration for classes specified in the deriving clause. In Haskell 98, the only classes that may appear in the deriving clause are the standard classes Eq, Ord, Enum, Ix, Bounded, Read, and Show.
GHC extends this list with several more classes that may be automatically derived:
You can also use a standalone deriving declaration instead (see Standalone deriving declarations).
In each case the appropriate class must be in scope before it can be mentioned in the deriving clause.
With XDeriveFunctor, one can derive Functor instances for data types of kind * > *. For example, this declaration:
data Example a = Ex a Char (Example a) (Example Char)
deriving Functor
would generate the following instance:
instance Functor Example where
fmap f (Ex a1 a2 a3 a4) = Ex (f a1) a2 (fmap f a3) a4
The basic algorithm for XDeriveFunctor walks the arguments of each constructor of a data type, applying a mapping function depending on the type of each argument. If a plain type variable is found that is syntactically equivalent to the last type parameter of the data type (a in the above example), then we apply the function f directly to it. If a type is encountered that is not syntactically equivalent to the last type parameter but does mention the last type parameter somewhere in it, then a recursive call to fmap is made. If a type is found which doesn’t mention the last type paramter at all, then it is left alone.
The second of those cases, in which a type is unequal to the type parameter but does contain the type parameter, can be surprisingly tricky. For example, the following example compiles:
newtype Right a = Right (Either Int a) deriving Functor
Modifying the code slightly, however, produces code which will not compile:
newtype Wrong a = Wrong (Either a Int) deriving Functor
The difference involves the placement of the last type parameter, a. In the Right case, a occurs within the type Either Int a, and moreover, it appears as the last type argument of Either. In the Wrong case, however, a is not the last type argument to Either; rather, Int is.
This distinction is important because of the way XDeriveFunctor works. The derived Functor Right instance would be:
instance Functor Right where
fmap f (Right a) = Right (fmap f a)
Given a value of type Right a, GHC must produce a value of type Right b. Since the argument to the Right constructor has type Either Int a, the code recursively calls fmap on it to produce a value of type Either Int b, which is used in turn to construct a final value of type Right b.
The generated code for the Functor Wrong instance would look exactly the same, except with Wrong replacing every occurrence of Right. The problem is now that fmap is being applied recursively to a value of type Either a Int. This cannot possibly produce a value of type Either b Int, as fmap can only change the last type parameter! This causes the generated code to be illtyped.
As a general rule, if a data type has a derived Functor instance and its last type parameter occurs on the righthand side of the data declaration, then either it must (1) occur bare (e.g., newtype Id a = a), or (2) occur as the last argument of a type constructor (as in Right above).
There are two exceptions to this rule:
Tuple types. When a nonunit tuple is used on the righthand side of a data declaration, XDeriveFunctor treats it as a product of distinct types. In other words, the following code:
newtype Triple a = Triple (a, Int, [a]) deriving Functor
Would result in a generated Functor instance like so:
instance Functor Triple where
fmap f (Triple a) =
Triple (case a of
(a1, a2, a3) > (f a1, a2, fmap f a3))
That is, XDeriveFunctor patternmatches its way into tuples and maps over each type that constitutes the tuple. The generated code is reminiscient of what would be generated from data Triple a = Triple a Int [a], except with extra machinery to handle the tuple.
Function types. The last type parameter can appear anywhere in a function type as long as it occurs in a covariant position. To illustrate what this means, consider the following three examples:
newtype CovFun1 a = CovFun1 (Int > a) deriving Functor
newtype CovFun2 a = CovFun2 ((a > Int) > a) deriving Functor
newtype CovFun3 a = CovFun3 (((Int > a) > Int) > a) deriving Functor
All three of these examples would compile without issue. On the other hand:
newtype ContraFun1 a = ContraFun1 (a > Int) deriving Functor
newtype ContraFun2 a = ContraFun2 ((Int > a) > Int) deriving Functor
newtype ContraFun3 a = ContraFun3 (((a > Int) > a) > Int) deriving Functor
While these examples look similar, none of them would successfully compile. This is because all occurrences of the last type parameter a occur in contravariant positions, not covariant ones.
Intuitively, a covariant type is produced, and a contravariant type is consumed. Most types in Haskell are covariant, but the function type is special in that the lefthand side of a function arrow reverses variance. If a function type a > b appears in a covariant position (e.g., CovFun1 above), then a is in a contravariant position and b is in a covariant position. Similarly, if a > b appears in a contravariant position (e.g., CovFun2 above), then a is in a covariant position and b is in a contravariant position.
To see why a data type with a contravariant occurrence of its last type parameter cannot have a derived Functor instance, let’s suppose that a Functor ContraFun1 instance exists. The implementation would look something like this:
instance Functor ContraFun1 where
fmap f (ContraFun g) = ContraFun (\x > _)
We have f :: a > b, g :: a > Int, and x :: b. Using these, we must somehow fill in the hole (denoted with an underscore) with a value of type Int. What are our options?
We could try applying g to x. This won’t work though, as g expects an argument of type a, and x :: b. Even worse, we can’t turn x into something of type a, since f also needs an argument of type a! In short, there’s no good way to make this work.
On the other hand, a derived Functor instances for the CovFuns are within the realm of possibility:
instance Functor CovFun1 where
fmap f (CovFun1 g) = CovFun1 (\x > f (g x))
instance Functor CovFun2 where
fmap f (CovFun2 g) = CovFun2 (\h > f (g (\x > h (f x))))
instance Functor CovFun3 where
fmap f (CovFun3 g) = CovFun3 (\h > f (g (\k > h (\x > f (k x)))))
There are some other scenarios in which a derived Functor instance will fail to compile:
A data type has no type parameters (e.g., data Nothing = Nothing).
A data type’s last type variable is used in a XDatatypeContexts constraint (e.g., data Ord a => O a = O a).
A data type’s last type variable is used in an XExistentialQuantification constraint, or is refined in a GADT. For example,
data T a b where
T4 :: Ord b => b > T a b
T5 :: b > T b b
T6 :: T a (b,b)
deriving instance Functor (T a)
would not compile successfully due to the way in which b is constrained.
With XDeriveFoldable, one can derive Foldable instances for data types of kind * > *. For example, this declaration:
data Example a = Ex a Char (Example a) (Example Char)
deriving Foldable
would generate the following instance:
instance Foldable Example where
foldr f z (Ex a1 a2 a3 a4) = f a1 (foldr f z a3)
foldMap f (Ex a1 a2 a3 a4) = mappend (f a1) (foldMap f a3)
The algorithm for XDeriveFoldable is adapted from the XDeriveFunctor algorithm, but it generates definitions for foldMap and foldr instead of fmap. In addition, XDeriveFoldable filters out all constructor arguments on the RHS expression whose types do not mention the last type parameter, since those arguments do not need to be folded over.
Here are the differences between the generated code in each extension:
There are some other differences regarding what data types can have derived Foldable instances:
Data types containing function types on the righthand side cannot have derived Foldable instances.
Foldable instances can be derived for data types in which the last type parameter is existentially constrained or refined in a GADT. For example, this data type:
data E a where
E1 :: (a ~ Int) => a > E a
E2 :: Int > E Int
E3 :: (a ~ Int) => a > E Int
E4 :: (a ~ Int) => Int > E a
deriving instance Foldable E
would have the following generated Foldable instance:
instance Foldable E where
foldr f z (E1 e) = f e z
foldr f z (E2 e) = z
foldr f z (E3 e) = z
foldr f z (E4 e) = z
foldMap f (E1 e) = f e
foldMap f (E2 e) = mempty
foldMap f (E3 e) = mempty
foldMap f (E4 e) = mempty
Notice how every constructor of E utilizes some sort of existential quantification, but only the argument of E1 is actually “folded over”. This is because we make a deliberate choice to only fold over universally polymorphic types that are syntactically equivalent to the last type parameter. In particular:
 We don’t fold over the arguments of E1 or E4 beacause even though (a ~ Int), Int is not syntactically equivalent to a.
 We don’t fold over the argument of E3 because a is not universally polymorphic. The a in E3 is (implicitly) existentially quantified, so it is not the same as the last type parameter of E.
With XDeriveTraversable, one can derive Traversable instances for data types of kind * > *. For example, this declaration:
data Example a = Ex a Char (Example a) (Example Char)
deriving (Functor, Foldable, Traversable)
would generate the following Traversable instance:
instance Traversable Example where
traverse f (Ex a1 a2 a3 a4)
= fmap (\b1 b3 > Ex b1 a2 b3 a4) (f a1) <*> traverse f a3
The algorithm for XDeriveTraversable is adapted from the XDeriveFunctor algorithm, but it generates a definition for traverse instead of fmap. In addition, XDeriveTraversable filters out all constructor arguments on the RHS expression whose types do not mention the last type parameter, since those arguments do not produce any effects in a traversal. Here are the differences between the generated code in each extension:
Unlike XDeriveFunctor, XDeriveTraversable cannot be used on data types containing a function type on the righthand side.
For a full specification of the algorithms used in XDeriveFunctor, XDeriveFoldable, and XDeriveTraversable, see this wiki page.
Enable automatic deriving of instances for the Typeable typeclass
The class Typeable is very special:
Typeable is kindpolymorphic (see Kind polymorphism and TypeinType).
GHC has a custom solver for discharging constraints that involve class Typeable, and handwritten instances are forbidden. This ensures that the programmer cannot subvert the type system by writing bogus instances.
Derived instances of Typeable are ignored, and may be reported as an error in a later version of the compiler.
The rules for solving `Typeable` constraints are as follows:
A concrete type constructor applied to some types.
instance (Typeable t1, .., Typeable t_n) =>
Typeable (T t1 .. t_n)
This rule works for any concrete type constructor, including type constructors with polymorphic kinds. The only restriction is that if the type constructor has a polymorphic kind, then it has to be applied to all of its kinds parameters, and these kinds need to be concrete (i.e., they cannot mention kind variables).
A type variable applied to some types.
instance (Typeable f, Typeable t1, .., Typeable t_n) =>
Typeable (f t1 .. t_n)
A concrete type literal.
instance Typeable 0  Type natural literals
instance Typeable "Hello"  Typelevel symbols
Since:  8.0.1 

Enable automatic deriving of instances for the Lift typeclass for Template Haskell.
The class Lift, unlike other derivable classes, lives in templatehaskell instead of base. Having a data type be an instance of Lift permits its values to be promoted to Template Haskell expressions (of type ExpQ), which can then be spliced into Haskell source code.
Here is an example of how one can derive Lift:
{# LANGUAGE DeriveLift #}
module Bar where
import Language.Haskell.TH.Syntax
data Foo a = Foo a  a :^: a deriving Lift
{
instance (Lift a) => Lift (Foo a) where
lift (Foo a)
= appE
(conE
(mkNameG_d "packagename" "Bar" "Foo"))
(lift a)
lift (u :^: v)
= infixApp
(lift u)
(conE
(mkNameG_d "packagename" "Bar" ":^:"))
(lift v)
}

{# LANGUAGE TemplateHaskell #}
module Baz where
import Bar
import Language.Haskell.TH.Lift
foo :: Foo String
foo = $(lift $ Foo "foo")
fooExp :: Lift a => Foo a > Q Exp
fooExp f = [ f ]
XDeriveLift also works for certain unboxed types (Addr#, Char#, Double#, Float#, Int#, and Word#):
{# LANGUAGE DeriveLift, MagicHash #}
module Unboxed where
import GHC.Exts
import Language.Haskell.TH.Syntax
data IntHash = IntHash Int# deriving Lift
{
instance Lift IntHash where
lift (IntHash i)
= appE
(conE
(mkNameG_d "packagename" "Unboxed" "IntHash"))
(litE
(intPrimL (toInteger (I# i))))
}
Enable GHC’s cunning generalised deriving mechanism for newtypes
When you define an abstract type using newtype, you may want the new type to inherit some instances from its representation. In Haskell 98, you can inherit instances of Eq, Ord, Enum and Bounded by deriving them, but for any other classes you have to write an explicit instance declaration. For example, if you define
newtype Dollars = Dollars Int
and you want to use arithmetic on Dollars, you have to explicitly define an instance of Num:
instance Num Dollars where
Dollars a + Dollars b = Dollars (a+b)
...
All the instance does is apply and remove the newtype constructor. It is particularly galling that, since the constructor doesn’t appear at runtime, this instance declaration defines a dictionary which is wholly equivalent to the Int dictionary, only slower!
GHC now permits such instances to be derived instead, using the flag XGeneralizedNewtypeDeriving, so one can write
newtype Dollars = Dollars Int deriving (Eq,Show,Num)
and the implementation uses the same Num dictionary for Dollars as for Int. Notionally, the compiler derives an instance declaration of the form
instance Num Int => Num Dollars
which just adds or removes the newtype constructor according to the type.
We can also derive instances of constructor classes in a similar way. For example, suppose we have implemented state and failure monad transformers, such that
instance Monad m => Monad (State s m)
instance Monad m => Monad (Failure m)
In Haskell 98, we can define a parsing monad by
type Parser tok m a = State [tok] (Failure m) a
which is automatically a monad thanks to the instance declarations above. With the extension, we can make the parser type abstract, without needing to write an instance of class Monad, via
newtype Parser tok m a = Parser (State [tok] (Failure m) a)
deriving Monad
In this case the derived instance declaration is of the form
instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)
Notice that, since Monad is a constructor class, the instance is a partial application of the new type, not the entire left hand side. We can imagine that the type declaration is “etaconverted” to generate the context of the instance declaration.
We can even derive instances of multiparameter classes, provided the newtype is the last class parameter. In this case, a “partial application” of the class appears in the deriving clause. For example, given the class
class StateMonad s m  m > s where ...
instance Monad m => StateMonad s (State s m) where ...
then we can derive an instance of StateMonad for Parser by
newtype Parser tok m a = Parser (State [tok] (Failure m) a)
deriving (Monad, StateMonad [tok])
The derived instance is obtained by completing the application of the class to the new type:
instance StateMonad [tok] (State [tok] (Failure m)) =>
StateMonad [tok] (Parser tok m)
As a result of this extension, all derived instances in newtype declarations are treated uniformly (and implemented just by reusing the dictionary for the representation type), except Show and Read, which really behave differently for the newtype and its representation.
A derived instance is derived only for declarations of these forms (after expansion of any type synonyms)
newtype T v1..vn = MkT (t vk+1..vn) deriving (C t1..tj)
newtype instance T s1..sk vk+1..vn = MkT (t vk+1..vn) deriving (C t1..tj)
where
Then the derived instance declaration is of the form
instance C t1..tj t => C t1..tj (T v1...vk)
As an example which does not work, consider
newtype NonMonad m s = NonMonad (State s m s) deriving Monad
Here we cannot derive the instance
instance Monad (State s m) => Monad (NonMonad m)
because the type variable s occurs in State s m, and so cannot be “etaconverted” away. It is a good thing that this deriving clause is rejected, because NonMonad m is not, in fact, a monad — for the same reason. Try defining >>= with the correct type: you won’t be able to.
Notice also that the order of class parameters becomes important, since we can only derive instances for the last one. If the StateMonad class above were instead defined as
class StateMonad m s  m > s where ...
then we would not have been able to derive an instance for the Parser type above. We hypothesise that multiparameter classes usually have one “main” parameter for which deriving new instances is most interesting.
Lastly, all of this applies only for classes other than Read, Show, Typeable, and Data, for which the builtin derivation applies (section 4.3.3. of the Haskell Report). (For the standard classes Eq, Ord, Ix, and Bounded it is immaterial whether the standard method is used or the one described here.)
Since:  7.10.1 

Allow use of any typeclass in deriving clauses.
With XDeriveAnyClass you can derive any other class. The compiler will simply generate an instance declaration with no explicitlydefined methods. This is mostly useful in classes whose minimal set is empty, and especially when writing generic functions.
As an example, consider a simple prettyprinter class SPretty, which outputs pretty strings:
{# LANGUAGE DefaultSignatures, DeriveAnyClass #}
class SPretty a where
sPpr :: a > String
default sPpr :: Show a => a > String
sPpr = show
If a user does not provide a manual implementation for sPpr, then it will default to show. Now we can leverage the XDeriveAnyClass extension to easily implement a SPretty instance for a new data type:
data Foo = Foo deriving (Show, SPretty)
The above code is equivalent to:
data Foo = Foo deriving Show
instance SPretty Foo
That is, an SPretty Foo instance will be created with empty implementations for all methods. Since we are using XDefaultSignatures in this example, a default implementation of sPpr is filled in automatically.
Note the following details
In case you try to derive some class on a newtype, and XGeneralizedNewtypeDeriving is also on, XDeriveAnyClass takes precedence.
XDeriveAnyClass is allowed only when the last argument of the class has kind * or (* > *). So this is not allowed:
data T a b = MkT a b deriving( Bifunctor )
because the last argument of Bifunctor :: (* > * > *) > Constraint has the wrong kind.
The instance context will be generated according to the same rules used when deriving Eq (if the kind of the type is *), or the rules for Functor (if the kind of the type is (* > *)). For example
instance C a => C (a,b) where ...
data T a b = MkT a (a,b) deriving( C )
The deriving clause will generate
instance C a => C (T a b) where {}
The constraints C a and C (a,b) are generated from the data constructor arguments, but the latter simplifies to C a.
XDeriveAnyClass can be used with partially applied classes, such as
data T a = MKT a deriving( D Int )
which generates
instance D Int a => D Int (T a) where {}
XDeriveAnyClass can be used to fill in default instances for associated type families:
{# LANGUAGE DeriveAnyClass, TypeFamilies #}
class Sizable a where
type Size a
type Size a = Int
data Bar = Bar deriving Sizable
doubleBarSize :: Size Bar > Size Bar
doubleBarSize s = 2*s
The deriving( Sizable ) is equivalent to saying
instance Sizeable Bar where {}
and then the normal rules for filling in associated types from the default will apply, making Size Bar equal to Int.
Since:  7.8.1 

Allow the definition of pattern synonyms.
Pattern synonyms are enabled by the flag XPatternSynonyms, which is required for defining them, but not for using them. More information and examples of view patterns can be found on the Wiki page <PatternSynonyms>.
Pattern synonyms enable giving names to parametrized pattern schemes. They can also be thought of as abstract constructors that don’t have a bearing on data representation. For example, in a programming language implementation, we might represent types of the language as follows:
data Type = App String [Type]
Here are some examples of using said representation. Consider a few types of the Type universe encoded like this:
App ">" [t1, t2]  t1 > t2
App "Int" []  Int
App "Maybe" [App "Int" []]  Maybe Int
This representation is very generic in that no types are given special treatment. However, some functions might need to handle some known types specially, for example the following two functions collect all argument types of (nested) arrow types, and recognize the Int type, respectively:
collectArgs :: Type > [Type]
collectArgs (App ">" [t1, t2]) = t1 : collectArgs t2
collectArgs _ = []
isInt :: Type > Bool
isInt (App "Int" []) = True
isInt _ = False
Matching on App directly is both hard to read and error prone to write. And the situation is even worse when the matching is nested:
isIntEndo :: Type > Bool
isIntEndo (App ">" [App "Int" [], App "Int" []]) = True
isIntEndo _ = False
Pattern synonyms permit abstracting from the representation to expose matchers that behave in a constructorlike manner with respect to pattern matching. We can create pattern synonyms for the known types we care about, without committing the representation to them (note that these don’t have to be defined in the same module as the Type type):
pattern Arrow t1 t2 = App ">" [t1, t2]
pattern Int = App "Int" []
pattern Maybe t = App "Maybe" [t]
Which enables us to rewrite our functions in a much cleaner style:
collectArgs :: Type > [Type]
collectArgs (Arrow t1 t2) = t1 : collectArgs t2
collectArgs _ = []
isInt :: Type > Bool
isInt Int = True
isInt _ = False
isIntEndo :: Type > Bool
isIntEndo (Arrow Int Int) = True
isIntEndo _ = False
In general there are three kinds of pattern synonyms. Unidirectional, bidirectional and explicitly bidirectional. The examples given so far are examples of bidirectional pattern synonyms. A bidirectional synonym behaves the same as an ordinary data constructor. We can use it in a pattern context to deconstruct values and in an expression context to construct values. For example, we can construct the value intEndo using the pattern synonyms Arrow and Int as defined previously.
intEndo :: Type
intEndo = Arrow Int Int
This example is equivalent to the much more complicated construction if we had directly used the Type constructors.
intEndo :: Type
intEndo = App ">" [App "Int" [], App "Int" []]
Unidirectional synonyms can only be used in a pattern context and are defined as follows:
pattern Head x < x:xs
In this case, Head ⟨x⟩ cannot be used in expressions, only patterns, since it wouldn’t specify a value for the ⟨xs⟩ on the righthand side. However, we can define an explicitly bidirectional pattern synonym by separately specifying how to construct and deconstruct a type. The syntax for doing this is as follows:
pattern HeadC x < x:xs where
HeadC x = [x]
We can then use HeadC in both expression and pattern contexts. In a pattern context it will match the head of any list with length at least one. In an expression context it will construct a singleton list.
The table below summarises where each kind of pattern synonym can be used.
Context  Unidirectional  Bidirectional  Explicitly Bidirectional 

Pattern  Yes  Yes  Yes 
Expression  No  Yes (Inferred)  Yes (Explicit) 
It is also possible to define pattern synonyms which behave just like record constructors. The syntax for doing this is as follows:
pattern Point :: (Int, Int)
pattern Point{x, y} = (x, y)
The idea is that we can then use Point just as if we had defined a new datatype MyPoint with two fields x and y.
data MyPoint = Point { x :: Int, y :: Int }
Whilst a normal pattern synonym can be used in two ways, there are then seven ways in which to use Point. Precisely the ways in which a normal record constructor can be used.
Usage  Example 

As a constructor  zero = Point 0 0 
As a constructor with record syntax  zero = Point { x = 0, y = 0} 
In a pattern context  isZero (Point 0 0) = True 
In a pattern context with record syntax  isZero (Point { x = 0, y = 0 } 
In a pattern context with field puns  getX (Point {x}) = x 
In a record update  (0, 0) { x = 1 } == (1,0) 
Using record selectors  x (0,0) == 0 
For a unidirectional record pattern synonym we define record selectors but do not allow record updates or construction.
The syntax and semantics of pattern synonyms are elaborated in the following subsections. See the Wiki page for more details.
A pattern synonym declaration can be either unidirectional, bidirectional or explicitly bidirectional. The syntax for unidirectional pattern synonyms is:
pattern pat_lhs < pat
the syntax for bidirectional pattern synonyms is:
pattern pat_lhs = pat
and the syntax for explicitly bidirectional pattern synonyms is:
pattern pat_lhs < pat where
pat_lhs = expr
We can define either prefix, infix or record pattern synonyms by modifying the form of pat_lhs. The syntax for these is as follows:
Prefix  Name args 
Infix  arg1 `Name` arg2 or arg1 op arg2 
Record  Name{arg1,arg2,...,argn} 
Pattern synonym declarations can only occur in the top level of a module. In particular, they are not allowed as local definitions.
The variables in the lefthand side of the definition are bound by the pattern on the righthand side. For bidirectional pattern synonyms, all the variables of the righthand side must also occur on the lefthand side; also, wildcard patterns and view patterns are not allowed. For unidirectional and explicitly bidirectional pattern synonyms, there is no restriction on the righthand side pattern.
Pattern synonyms cannot be defined recursively.
The name of the pattern synonym is in the same namespace as proper data constructors. Like normal data constructors, pattern synonyms can be imported and exported through association with a type constructor or independently.
To export them on their own, in an export or import specification, you must prefix pattern names with the pattern keyword, e.g.:
module Example (pattern Zero) where
data MyNum = MkNum Int
pattern Zero :: MyNum
pattern Zero = MkNum 0
Without the pattern prefix, Zero would be interpreted as a type constructor in the export list.
You may also use the pattern keyword in an import/export specification to import or export an ordinary data constructor. For example:
import Data.Maybe( pattern Just )
would bring into scope the data constructor Just from the Maybe type, without also bringing the type constructor Maybe into scope.
To bundle a pattern synonym with a type constructor, we list the pattern synonym in the export list of a module which exports the type constructor. For example, to bundle Zero with MyNum we could write the following:
module Example ( MyNum(Zero) ) where
If a module was then to import MyNum from Example, it would also import the pattern synonym Zero.
It is also possible to use the special token .. in an export list to mean all currently bundled constructors. For example, we could write:
module Example ( MyNum(.., Zero) ) where
in which case, Example would export the type constructor MyNum with the data constructor MkNum and also the pattern synonym Zero.
Bundled patterns synoyms are type checked to ensure that they are of the same type as the type constructor which they are bundled with. A pattern synonym P can not be bundled with a type constructor T if P‘s type is visibly incompatible with T.
A module which imports MyNum(..) from Example and then reexports MyNum(..) will also export any pattern synonyms bundled with MyNum in Example. A more complete specification can be found on the wiki.
Given a pattern synonym definition of the form
pattern P var1 var2 ... varN < pat
it is assigned a pattern type of the form
pattern P :: CReq => CProv => t1 > t2 > ... > tN > t
where ⟨CReq⟩ and ⟨CProv⟩ are type contexts, and ⟨t1⟩, ⟨t2⟩, ..., ⟨tN⟩ and ⟨t⟩ are types. Notice the unusual form of the type, with two contexts ⟨CReq⟩ and ⟨CProv⟩:
For example, consider
data T a where
MkT :: (Show b) => a > b > T a
f1 :: (Num a, Eq a) => T a > String
f1 (MkT 42 x) = show x
pattern ExNumPat :: (Num a, Eq a) => (Show b) => b > T a
pattern ExNumPat x = MkT 42 x
f2 :: (Eq a, Num a) => T a > String
f2 (ExNumPat x) = show x
Here f1 does not use pattern synonyms. To match against the numeric pattern 42 requires the caller to satisfy the constraints (Num a, Eq a), so they appear in f1‘s type. The call to show generates a (Show b) constraint, where b is an existentially type variable bound by the pattern match on MkT. But the same pattern match also provides the constraint (Show b) (see MkT‘s type), and so all is well.
Exactly the same reasoning applies to ExNumPat: matching against ExNumPat requires the constraints (Num a, Eq a), and provides the constraint (Show b).
Note also the following points
In the common case where CProv is empty, (i.e., ()), it can be omitted altogether in the above pattern type signature for P.
However, if CProv is nonempty, while CReq is, the above pattern type signature for P must be specified as
P :: () => CProv => t1 > t2 > .. > tN > t
You may specify an explicit pattern signature, as we did for ExNumPat above, to specify the type of a pattern, just as you can for a function. As usual, the type signature can be less polymorphic than the inferred type. For example
 Inferred type would be 'a > [a]'
pattern SinglePair :: (a, a) > [(a, a)]
pattern SinglePair x = [x]
The GHCi :info command shows pattern types in this format.
For a bidirectional pattern synonym, a use of the pattern synonym as an expression has the type
(CReq, CProv) => t1 > t2 > ... > tN > t
So in the previous example, when used in an expression, ExNumPat has type
ExNumPat :: (Num a, Eq a, Show b) => b > T t
Notice that this is a tiny bit more restrictive than the expression MkT 42 x which would not require (Eq a).
Consider these two pattern synonyms:
data S a where
S1 :: Bool > S Bool
pattern P1 :: Bool > Maybe Bool
pattern P1 b = Just b
pattern P2 :: () => (b ~ Bool) => Bool > S b
pattern P2 b = S1 b
f :: Maybe a > String
f (P1 x) = "no no no"  Typeincorrect
g :: S a > String
g (P2 b) = "yes yes yes"  Fine
Pattern P1 can only match against a value of type Maybe Bool, so function f is rejected because the type signature is Maybe a. (To see this, imagine expanding the pattern synonym.)
On the other hand, function g works fine, because matching against P2 (which wraps the GADT S) provides the local equality (a~Bool). If you were to give an explicit pattern signature P2 :: Bool > S Bool, then P2 would become less polymorphic, and would behave exactly like P1 so that g would then be rejected.
In short, if you want GADTlike behaviour for pattern synonyms, then (unlike concrete data constructors like S1) you must write its type with explicit provided equalities. For a concrete data constructor like S1 you can write its type signature as either S1 :: Bool > S Bool or S1 :: (b~Bool) => Bool > S b; the two are equivalent. Not so for pattern synonyms: the two forms are different, in order to distinguish the two cases above. (See Trac #9953 for discussion of this choice.)
A pattern synonym occurrence in a pattern is evaluated by first matching against the pattern synonym itself, and then on the argument patterns. For example, in the following program, f and f' are equivalent:
pattern Pair x y < [x, y]
f (Pair True True) = True
f _ = False
f' [x, y]  True < x, True < y = True
f' _ = False
Note that the strictness of f differs from that of g defined below:
g [True, True] = True
g _ = False
*Main> f (False:undefined)
*** Exception: Prelude.undefined
*Main> g (False:undefined)
False
This section, and the next one, documents GHC’s typeclass extensions. There’s lots of background in the paper Type classes: exploring the design space (Simon Peyton Jones, Mark Jones, Erik Meijer).
Implies:  XConstrainedClassMethods 

Allow the definition of typeclasses with more than one parameter.
Multiparameter type classes are permitted, with flag XMultiParamTypeClasses. For example:
class Collection c a where
union :: c a > c a > c a
...etc.
Allow the use of complex constraints in class declaration contexts.
In Haskell 98 the context of a class declaration (which introduces superclasses) must be simple; that is, each predicate must consist of a class applied to type variables. The flag XFlexibleContexts (The context of a type signature) lifts this restriction, so that the only restriction on the context in a class declaration is that the class hierarchy must be acyclic. So these class declarations are OK:
class Functor (m k) => FiniteMap m k where
...
class (Monad m, Monad (t m)) => Transform t m where
lift :: m a > (t m) a
As in Haskell 98, the class hierarchy must be acyclic. However, the definition of “acyclic” involves only the superclass relationships. For example, this is okay:
class C a where
op :: D b => a > b > b
class C a => D a where ...
Here, C is a superclass of D, but it’s OK for a class operation op of C to mention D. (It would not be OK for D to be a superclass of C.)
With the extension that adds a kind of constraints, you can write more exotic superclass definitions. The superclass cycle check is even more liberal in these case. For example, this is OK:
class A cls c where
meth :: cls c => c > c
class A B c => B c where
A superclass context for a class C is allowed if, after expanding type synonyms to their righthandsides, and uses of classes (other than C) to their superclasses, C does not occur syntactically in the context.
Allows the definition of further constraints on individual class methods.
Haskell 98 prohibits class method types to mention constraints on the class type variable, thus:
class Seq s a where
fromList :: [a] > s a
elem :: Eq a => a > s a > Bool
The type of elem is illegal in Haskell 98, because it contains the constraint Eq a, which constrains only the class type variable (in this case a).
GHC lifts this restriction with language extension XConstrainedClassMethods. The restriction is a pretty stupid one in the first place, so XConstrainedClassMethods is implied by XMultiParamTypeClasses.
Since:  7.2 

Allows the definition of default method signatures in class definitions.
Haskell 98 allows you to define a default implementation when declaring a class:
class Enum a where
enum :: [a]
enum = []
The type of the enum method is [a], and this is also the type of the default method. You can lift this restriction and give another type to the default method using the flag XDefaultSignatures. For instance, if you have written a generic implementation of enumeration in a class GEnum with method genum in terms of GHC.Generics, you can specify a default method that uses that generic implementation:
class Enum a where
enum :: [a]
default enum :: (Generic a, GEnum (Rep a)) => [a]
enum = map to genum
We reuse the keyword default to signal that a signature applies to the default method only; when defining instances of the Enum class, the original type [a] of enum still applies. When giving an empty instance, however, the default implementation map to genum is filledin, and typechecked with the type (Generic a, GEnum (Rep a)) => [a].
We use default signatures to simplify generic programming in GHC (Generic programming).
Since:  7.8.1 

Allows the use definition of type classes with no parameters. This flag has been replaced by XMultiParamTypeClasses.
Nullary (no parameter) type classes are enabled with XMultiParamTypeClasses; historically, they were enabled with the (now deprecated) XNullaryTypeClasses. Since there are no available parameters, there can be at most one instance of a nullary class. A nullary type class might be used to document some assumption in a type signature (such as reliance on the Riemann hypothesis) or add some globally configurable settings in a program. For example,
class RiemannHypothesis where
assumeRH :: a > a
 Deterministic version of the Miller test
 correctness depends on the generalised Riemann hypothesis
isPrime :: RiemannHypothesis => Integer > Bool
isPrime n = assumeRH (...)
The type signature of isPrime informs users that its correctness depends on an unproven conjecture. If the function is used, the user has to acknowledge the dependence with:
instance RiemannHypothesis where
assumeRH = id
Implies:  XMultiParamTypeClasses 

Allow use of functional dependencies in class declarations.
Functional dependencies are implemented as described by [Jones2000].Mark Jones in
Functional dependencies are introduced by a vertical bar in the syntax of a class declaration; e.g.
class (Monad m) => MonadState s m  m > s where ...
class Foo a b c  a b > c where ...
There should be more documentation, but there isn’t (yet). Yell if you need it.
[Jones2000]  “Type Classes with Functional Dependencies”, Mark P. Jones, In Proceedings of the 9th European Symposium on Programming, ESOP 2000, Berlin, Germany, March 2000, SpringerVerlag LNCS 1782, . 
In a class declaration, all of the class type variables must be reachable (in the sense mentioned in The context of a type signature) from the free variables of each method type. For example:
class Coll s a where
empty :: s
insert :: s > a > s
is not OK, because the type of empty doesn’t mention a. Functional dependencies can make the type variable reachable:
class Coll s a  s > a where
empty :: s
insert :: s > a > s
Alternatively Coll might be rewritten
class Coll s a where
empty :: s a
insert :: s a > a > s a
which makes the connection between the type of a collection of a‘s (namely (s a)) and the element type a. Occasionally this really doesn’t work, in which case you can split the class like this:
class CollE s where
empty :: s
class CollE s => Coll s a where
insert :: s > a > s
The following description of the motivation and use of functional dependencies is taken from the Hugs user manual, reproduced here (with minor changes) by kind permission of Mark Jones.
Consider the following class, intended as part of a library for collection types:
class Collects e ce where
empty :: ce
insert :: e > ce > ce
member :: e > ce > Bool
The type variable e used here represents the element type, while ce is the type of the container itself. Within this framework, we might want to define instances of this class for lists or characteristic functions (both of which can be used to represent collections of any equality type), bit sets (which can be used to represent collections of characters), or hash tables (which can be used to represent any collection whose elements have a hash function). Omitting standard implementation details, this would lead to the following declarations:
instance Eq e => Collects e [e] where ...
instance Eq e => Collects e (e > Bool) where ...
instance Collects Char BitSet where ...
instance (Hashable e, Collects a ce)
=> Collects e (Array Int ce) where ...
All this looks quite promising; we have a class and a range of interesting implementations. Unfortunately, there are some serious problems with the class declaration. First, the empty function has an ambiguous type:
empty :: Collects e ce => ce
By “ambiguous” we mean that there is a type variable e that appears on the left of the => symbol, but not on the right. The problem with this is that, according to the theoretical foundations of Haskell overloading, we cannot guarantee a welldefined semantics for any term with an ambiguous type.
We can sidestep this specific problem by removing the empty member from the class declaration. However, although the remaining members, insert and member, do not have ambiguous types, we still run into problems when we try to use them. For example, consider the following two functions:
f x y = insert x . insert y
g = f True 'a'
for which GHC infers the following types:
f :: (Collects a c, Collects b c) => a > b > c > c
g :: (Collects Bool c, Collects Char c) => c > c
Notice that the type for f allows the two parameters x and y to be assigned different types, even though it attempts to insert each of the two values, one after the other, into the same collection. If we’re trying to model collections that contain only one type of value, then this is clearly an inaccurate type. Worse still, the definition for g is accepted, without causing a type error. As a result, the error in this code will not be flagged at the point where it appears. Instead, it will show up only when we try to use g, which might even be in a different module.
Faced with the problems described above, some Haskell programmers might be tempted to use something like the following version of the class declaration:
class Collects e c where
empty :: c e
insert :: e > c e > c e
member :: e > c e > Bool
The key difference here is that we abstract over the type constructor c that is used to form the collection type c e, and not over that collection type itself, represented by ce in the original class declaration. This avoids the immediate problems that we mentioned above: empty has type Collects e c => c e, which is not ambiguous.
The function f from the previous section has a more accurate type:
f :: (Collects e c) => e > e > c e > c e
The function g from the previous section is now rejected with a type error as we would hope because the type of f does not allow the two arguments to have different types. This, then, is an example of a multiple parameter class that does actually work quite well in practice, without ambiguity problems. There is, however, a catch. This version of the Collects class is nowhere near as general as the original class seemed to be: only one of the four instances for Collects given above can be used with this version of Collects because only one of them—the instance for lists—has a collection type that can be written in the form c e, for some type constructor c, and element type e.
To get a more useful version of the Collects class, GHC provides a mechanism that allows programmers to specify dependencies between the parameters of a multiple parameter class (For readers with an interest in theoretical foundations and previous work: The use of dependency information can be seen both as a generalisation of the proposal for “parametric type classes” that was put forward by Chen, Hudak, and Odersky, or as a special case of Mark Jones’s later framework for “improvement” of qualified types. The underlying ideas are also discussed in a more theoretical and abstract setting in a manuscript [implparam], where they are identified as one point in a general design space for systems of implicit parameterisation). To start with an abstract example, consider a declaration such as:
class C a b where ...
which tells us simply that C can be thought of as a binary relation on types (or type constructors, depending on the kinds of a and b). Extra clauses can be included in the definition of classes to add information about dependencies between parameters, as in the following examples:
class D a b  a > b where ...
class E a b  a > b, b > a where ...
The notation a > b used here between the  and where symbols — not to be confused with a function type — indicates that the a parameter uniquely determines the b parameter, and might be read as “a determines b.” Thus D is not just a relation, but actually a (partial) function. Similarly, from the two dependencies that are included in the definition of E, we can see that E represents a (partial) onetoone mapping between types.
More generally, dependencies take the form x1 ... xn > y1 ... ym, where x1, ..., xn, and y1, ..., yn are type variables with n>0 and m>=0, meaning that the y parameters are uniquely determined by the x parameters. Spaces can be used as separators if more than one variable appears on any single side of a dependency, as in t > a b. Note that a class may be annotated with multiple dependencies using commas as separators, as in the definition of E above. Some dependencies that we can write in this notation are redundant, and will be rejected because they don’t serve any useful purpose, and may instead indicate an error in the program. Examples of dependencies like this include a > a, a > a a, a >, etc. There can also be some redundancy if multiple dependencies are given, as in a>b, b>c, a>c, and in which some subset implies the remaining dependencies. Examples like this are not treated as errors. Note that dependencies appear only in class declarations, and not in any other part of the language. In particular, the syntax for instance declarations, class constraints, and types is completely unchanged.
By including dependencies in a class declaration, we provide a mechanism for the programmer to specify each multiple parameter class more precisely. The compiler, on the other hand, is responsible for ensuring that the set of instances that are in scope at any given point in the program is consistent with any declared dependencies. For example, the following pair of instance declarations cannot appear together in the same scope because they violate the dependency for D, even though either one on its own would be acceptable:
instance D Bool Int where ...
instance D Bool Char where ...
Note also that the following declaration is not allowed, even by itself:
instance D [a] b where ...
The problem here is that this instance would allow one particular choice of [a] to be associated with more than one choice for b, which contradicts the dependency specified in the definition of D. More generally, this means that, in any instance of the form:
instance D t s where ...
for some particular types t and s, the only variables that can appear in s are the ones that appear in t, and hence, if the type t is known, then s will be uniquely determined.
The benefit of including dependency information is that it allows us to define more general multiple parameter classes, without ambiguity problems, and with the benefit of more accurate types. To illustrate this, we return to the collection class example, and annotate the original definition of Collects with a simple dependency:
class Collects e ce  ce > e where
empty :: ce
insert :: e > ce > ce
member :: e > ce > Bool
The dependency ce > e here specifies that the type e of elements is uniquely determined by the type of the collection ce. Note that both parameters of Collects are of kind *; there are no constructor classes here. Note too that all of the instances of Collects that we gave earlier can be used together with this new definition.
What about the ambiguity problems that we encountered with the original definition? The empty function still has type Collects e ce => ce, but it is no longer necessary to regard that as an ambiguous type: Although the variable e does not appear on the right of the => symbol, the dependency for class Collects tells us that it is uniquely determined by ce, which does appear on the right of the => symbol. Hence the context in which empty is used can still give enough information to determine types for both ce and e, without ambiguity. More generally, we need only regard a type as ambiguous if it contains a variable on the left of the => that is not uniquely determined (either directly or indirectly) by the variables on the right.
Dependencies also help to produce more accurate types for user defined functions, and hence to provide earlier detection of errors, and less cluttered types for programmers to work with. Recall the previous definition for a function f:
f x y = insert x y = insert x . insert y
for which we originally obtained a type:
f :: (Collects a c, Collects b c) => a > b > c > c
Given the dependency information that we have for Collects, however, we can deduce that a and b must be equal because they both appear as the second parameter in a Collects constraint with the same first parameter c. Hence we can infer a shorter and more accurate type for f:
f :: (Collects a c) => a > a > c > c
In a similar way, the earlier definition of g will now be flagged as a type error.
Although we have given only a few examples here, it should be clear that the addition of dependency information can help to make multiple parameter classes more useful in practice, avoiding ambiguity problems, and allowing more general sets of instance declarations.
An instance declaration has the form
instance ( assertion1, ..., assertionn) => class type1 ... typem where ...
The part before the “=>” is the context, while the part after the “=>” is the head of the instance declaration.
When GHC tries to resolve, say, the constraint C Int Bool, it tries to match every instance declaration against the constraint, by instantiating the head of the instance declaration. Consider these declarations:
instance context1 => C Int a where ...  (A)
instance context2 => C a Bool where ...  (B)
GHC’s default behaviour is that exactly one instance must match the constraint it is trying to resolve. For example, the constraint C Int Bool matches instances (A) and (B), and hence would be rejected; while C Int Char matches only (A) and hence (A) is chosen.
Notice that
See also Overlapping instances for flags that loosen the instance resolution rules.
Allow definition of type class instances for type synonyms.
Implies:  XTypeSynonymInstances 

Allow definition of type class instances with arbitrary nested types in the instance head.
In Haskell 98 the head of an instance declaration must be of the form C (T a1 ... an), where C is the class, T is a data type constructor, and the a1 ... an are distinct type variables. In the case of multiparameter type classes, this rule applies to each parameter of the instance head (Arguably it should be okay if just one has this form and the others are type variables, but that’s the rules at the moment).
GHC relaxes this rule in two ways:
With the XTypeSynonymInstances flag, instance heads may use type synonyms. As always, using a type synonym is just shorthand for writing the RHS of the type synonym definition. For example:
type Point a = (a,a)
instance C (Point a) where ...
is legal. The instance declaration is equivalent to
instance C (a,a) where ...
As always, type synonyms must be fully applied. You cannot, for example, write:
instance Monad Point where ...
The XFlexibleInstances flag allows the head of the instance declaration to mention arbitrary nested types. For example, this becomes a legal instance declaration
instance C (Maybe Int) where ...
See also the rules on overlap.
The XFlexibleInstances flag implies XTypeSynonymInstances.
However, the instance declaration must still conform to the rules for instance termination: see Instance termination rules.
In Haskell 98, the class constraints in the context of the instance declaration must be of the form C a where a is a type variable that occurs in the head.
The XFlexibleContexts flag relaxes this rule, as well as relaxing the corresponding rule for type signatures (see The context of a type signature). Specifically, XFlexibleContexts, allows (wellkinded) class constraints of form (C t1 ... tn) in the context of an instance declaration.
Notice that the flag does not affect equality constraints in an instance context; they are permitted by XTypeFamilies or XGADTs.
However, the instance declaration must still conform to the rules for instance termination: see Instance termination rules.
Permit definition of instances which may lead to typechecker nontermination.
Regardless of XFlexibleInstances and XFlexibleContexts, instance declarations must conform to some rules that ensure that instance resolution will terminate. The restrictions can be lifted with XUndecidableInstances (see Undecidable instances).
The rules are these:
These restrictions ensure that instance resolution terminates: each reduction step makes the problem smaller by at least one constructor. You can find lots of background material about the reason for these restrictions in the paper Understanding functional dependencies via Constraint Handling Rules.
For example, these are okay:
instance C Int [a]  Multiple parameters
instance Eq (S [a])  Structured type in head
 Repeated type variable in head
instance C4 a a => C4 [a] [a]
instance Stateful (ST s) (MutVar s)
 Head can consist of type variables only
instance C a
instance (Eq a, Show b) => C2 a b
 Nontype variables in context
instance Show (s a) => Show (Sized s a)
instance C2 Int a => C3 Bool [a]
instance C2 Int a => C3 [a] b
But these are not:
 Context assertion no smaller than head
instance C a => C a where ...
 (C b b) has more occurrences of b than the head
instance C b b => Foo [b] where ...
The same restrictions apply to instances generated by deriving clauses. Thus the following is accepted:
data MinHeap h a = H a (h a)
deriving (Show)
because the derived instance
instance (Show a, Show (h a)) => Show (MinHeap h a)
conforms to the above rules.
A useful idiom permitted by the above rules is as follows. If one allows overlapping instance declarations then it’s quite convenient to have a “default instance” declaration that applies if something more specific does not:
instance C a where
op = ...  Default
Sometimes even the termination rules of Instance termination rules are too onerous. So GHC allows you to experiment with more liberal rules: if you use the experimental flag XUndecidableInstances, both the Paterson Conditions and the Coverage Condition (described in Instance termination rules) are lifted. Termination is still ensured by having a fixeddepth recursion stack. If you exceed the stack depth you get a sort of backtrace, and the opportunity to increase the stack depth with freductiondepth=N. However, if you should exceed the default reduction depth limit, it is probably best just to disable depth checking, with freductiondepth=0. The exact depth your program requires depends on minutiae of your code, and it may change between minor GHC releases. The safest bet for released code – if you’re sure that it should compile in finite time – is just to disable the check.
For example, sometimes you might want to use the following to get the effect of a “class synonym”:
class (C1 a, C2 a, C3 a) => C a where { }
instance (C1 a, C2 a, C3 a) => C a where { }
This allows you to write shorter signatures:
f :: C a => ...
instead of
f :: (C1 a, C2 a, C3 a) => ...
The restrictions on functional dependencies (Functional dependencies) are particularly troublesome. It is tempting to introduce type variables in the context that do not appear in the head, something that is excluded by the normal rules. For example:
class HasConverter a b  a > b where
convert :: a > b
data Foo a = MkFoo a
instance (HasConverter a b,Show b) => Show (Foo a) where
show (MkFoo value) = show (convert value)
This is dangerous territory, however. Here, for example, is a program that would make the typechecker loop:
class D a
class F a b  a>b
instance F [a] [[a]]
instance (D c, F a c) => D [a]  'c' is not mentioned in the head
Similarly, it can be tempting to lift the coverage condition:
class Mul a b c  a b > c where
(.*.) :: a > b > c
instance Mul Int Int Int where (.*.) = (*)
instance Mul Int Float Float where x .*. y = fromIntegral x * y
instance Mul a b c => Mul a [b] [c] where x .*. v = map (x.*.) v
The third instance declaration does not obey the coverage condition; and indeed the (somewhat strange) definition:
f = \ b x y > if b then x .*. [y] else y
makes instance inference go into a loop, because it requires the constraint (Mul a [b] b).
The XUndecidableInstances flag is also used to lift some of the restrictions imposed on type family instances. See Decidability of type synonym instances.
Deprecated flags to weaken checks intended to ensure instance resolution termination.
In general, as discussed in Instance resolution, GHC requires that it be unambiguous which instance declaration should be used to resolve a typeclass constraint. GHC also provides a way to to loosen the instance resolution, by allowing more than one instance to match, provided there is a most specific one. Moreover, it can be loosened further, by allowing more than one instance to match irrespective of whether there is a most specific one. This section gives the details.
To control the choice of instance, it is possible to specify the overlap behavior for individual instances with a pragma, written immediately after the instance keyword. The pragma may be one of: {# OVERLAPPING #}, {# OVERLAPPABLE #}, {# OVERLAPS #}, or {# INCOHERENT #}.
The matching behaviour is also influenced by two modulelevel language extension flags: XOverlappingInstances and XIncoherentInstances. These flags are now deprecated (since GHC 7.10) in favour of the finegrained perinstance pragmas.
A more precise specification is as follows. The willingness to be overlapped or incoherent is a property of the instance declaration itself, controlled as follows:
Now suppose that, in some client module, we are searching for an instance of the target constraint (C ty1 .. tyn). The search works like this:
Notice that these rules are not influenced by flag settings in the client module, where the instances are used. These rules make it possible for a library author to design a library that relies on overlapping instances without the client having to know.
Errors are reported lazily (when attempting to solve a constraint), rather than eagerly (when the instances themselves are defined). Consider, for example
instance C Int b where ..
instance C a Bool where ..
These potentially overlap, but GHC will not complain about the instance declarations themselves, regardless of flag settings. If we later try to solve the constraint (C Int Char) then only the first instance matches, and all is well. Similarly with (C Bool Bool). But if we try to solve (C Int Bool), both instances match and an error is reported.
As a more substantial example of the rules in action, consider
instance {# OVERLAPPABLE #} context1 => C Int b where ...  (A)
instance {# OVERLAPPABLE #} context2 => C a Bool where ...  (B)
instance {# OVERLAPPABLE #} context3 => C a [b] where ...  (C)
instance {# OVERLAPPING #} context4 => C Int [Int] where ...  (D)
Now suppose that the type inference engine needs to solve the constraint C Int [Int]. This constraint matches instances (A), (C) and (D), but the last is more specific, and hence is chosen.
If (D) did not exist then (A) and (C) would still be matched, but neither is most specific. In that case, the program would be rejected, unless XIncoherentInstances is enabled, in which case it would be accepted and (A) or (C) would be chosen arbitrarily.
An instance declaration is more specific than another iff the head of former is a substitution instance of the latter. For example (D) is “more specific” than (C) because you can get from (C) to (D) by substituting a := Int.
GHC is conservative about committing to an overlapping instance. For example:
f :: [b] > [b]
f x = ...
Suppose that from the RHS of f we get the constraint C b [b]. But GHC does not commit to instance (C), because in a particular call of f, b might be instantiate to Int, in which case instance (D) would be more specific still. So GHC rejects the program.
If, however, you add the flag XIncoherentInstances when compiling the module that contains (D), GHC will instead pick (C), without complaining about the problem of subsequent instantiations.
Notice that we gave a type signature to f, so GHC had to check that f has the specified type. Suppose instead we do not give a type signature, asking GHC to infer it instead. In this case, GHC will refrain from simplifying the constraint C Int [b] (for the same reason as before) but, rather than rejecting the program, it will infer the type
f :: C b [b] => [b] > [b]
That postpones the question of which instance to pick to the call site for f by which time more is known about the type b. You can write this type signature yourself if you use the XFlexibleContexts flag.
Exactly the same situation can arise in instance declarations themselves. Suppose we have
class Foo a where
f :: a > a
instance Foo [b] where
f x = ...
and, as before, the constraint C Int [b] arises from f‘s right hand side. GHC will reject the instance, complaining as before that it does not know how to resolve the constraint C Int [b], because it matches more than one instance declaration. The solution is to postpone the choice by adding the constraint to the context of the instance declaration, thus:
instance C Int [b] => Foo [b] where
f x = ...
(You need XFlexibleInstances to do this.)
Warning
Overlapping instances must be used with care. They can give rise to incoherence (i.e. different instance choices are made in different parts of the program) even without XIncoherentInstances. Consider:
{# LANGUAGE OverlappingInstances #}
module Help where
class MyShow a where
myshow :: a > String
instance MyShow a => MyShow [a] where
myshow xs = concatMap myshow xs
showHelp :: MyShow a => [a] > String
showHelp xs = myshow xs
{# LANGUAGE FlexibleInstances, OverlappingInstances #}
module Main where
import Help
data T = MkT
instance MyShow T where
myshow x = "Used generic instance"
instance MyShow [T] where
myshow xs = "Used more specific instance"
main = do { print (myshow [MkT]); print (showHelp [MkT]) }
In function showHelp GHC sees no overlapping instances, and so uses the MyShow [a] instance without complaint. In the call to myshow in main, GHC resolves the MyShow [T] constraint using the overlapping instance declaration in module Main. As a result, the program prints
"Used more specific instance"
"Used generic instance"
(An alternative possible behaviour, not currently implemented, would be to reject module Help on the grounds that a later instance declaration might overlap the local one.)
Since:  7.6.1 

Allow type signatures for members in instance definitions.
In Haskell, you can’t write a type signature in an instance declaration, but it is sometimes convenient to do so, and the language extension XInstanceSigs allows you to do so. For example:
data T a = MkT a a
instance Eq a => Eq (T a) where
(==) :: T a > T a > Bool  The signature
(==) (MkT x1 x2) (MkTy y1 y2) = x1==y1 && x2==y2
Some details
The type signature in the instance declaration must be more polymorphic than (or the same as) the one in the class declaration, instantiated with the instance type. For example, this is fine:
instance Eq a => Eq (T a) where
(==) :: forall b. b > b > Bool
(==) x y = True
Here the signature in the instance declaration is more polymorphic than that required by the instantiated class method.
The code for the method in the instance declaration is typechecked against the type signature supplied in the instance declaration, as you would expect. So if the instance signature is more polymorphic than required, the code must be too.
One stylistic reason for wanting to write a type signature is simple documentation. Another is that you may want to bring scoped type variables into scope. For example:
class C a where
foo :: b > a > (a, [b])
instance C a => C (T a) where
foo :: forall b. b > T a > (T a, [b])
foo x (T y) = (T y, xs)
where
xs :: [b]
xs = [x,x,x]
Provided that you also specify XScopedTypeVariables (Lexically scoped type variables), the forall b scopes over the definition of foo, and in particular over the type signature for xs.
Enable overloaded string literals (e.g. string literals desugared via the IsString class).
GHC supports overloaded string literals. Normally a string literal has type String, but with overloaded string literals enabled (with XOverloadedStrings) a string literal has type (IsString a) => a.
This means that the usual string syntax can be used, e.g., for ByteString, Text, and other variations of string like types. String literals behave very much like integer literals, i.e., they can be used in both expressions and patterns. If used in a pattern the literal will be replaced by an equality test, in the same way as an integer literal is.
The class IsString is defined as:
class IsString a where
fromString :: String > a
The only predefined instance is the obvious one to make strings work as usual:
instance IsString [Char] where
fromString cs = cs
The class IsString is not in scope by default. If you want to mention it explicitly (for example, to give an instance declaration for it), you can import it from module GHC.Exts.
Haskell’s defaulting mechanism (Haskell Report, Section 4.3.4) is extended to cover string literals, when XOverloadedStrings is specified. Specifically:
So, for example, the expression length "foo" will give rise to an ambiguous use of IsString a0 which, because of the above rules, will default to String.
A small example:
module Main where
import GHC.Exts( IsString(..) )
newtype MyString = MyString String deriving (Eq, Show)
instance IsString MyString where
fromString = MyString
greet :: MyString > MyString
greet "hello" = "world"
greet other = other
main = do
print $ greet "hello"
print $ greet "fool"
Note that deriving Eq is necessary for the pattern matching to work since it gets translated into an equality comparison.
Since:  8.0.1 

Enable use of the #foo overloaded label syntax.
GHC supports overloaded labels, a form of identifier whose interpretation may depend both on its type and on its literal text. When the XOverloadedLabels extension is enabled, an overloaded label can written with a prefix hash, for example #foo. The type of this expression is IsLabel "foo" a => a.
The class IsLabel is defined as:
class IsLabel (x :: Symbol) a where
fromLabel :: Proxy# x > a
This is rather similar to the class IsString (see Overloaded string literals), but with an additional type parameter that makes the text of the label available as a typelevel string (see TypeLevel Literals).
There are no predefined instances of this class. It is not in scope by default, but can be brought into scope by importing GHC.OverloadedLabels:. Unlike IsString, there are no special defaulting rules for IsLabel.
During typechecking, GHC will replace an occurrence of an overloaded label like #foo with
fromLabel (proxy# :: Proxy# "foo")
This will have some type alpha and require the solution of a class constraint IsLabel "foo" alpha.
The intention is for IsLabel to be used to support overloaded record fields and perhaps anonymous records. Thus, it may be given instances for base datatypes (in particular (>)) in the future.
When writing an overloaded label, there must be no space between the hash sign and the following identifier. The magic hash makes use of postfix hash signs; if OverloadedLabels and MagicHash are both enabled then x#y means x# y, but if only OverloadedLabels is enabled then it means x #y. To avoid confusion, you are strongly encouraged to put a space before the hash when using OverloadedLabels.
When using OverloadedLabels (or MagicHash) in a .hsc file (see Writing Haskell interfaces to C code: hsc2hs), the hash signs must be doubled (write ##foo instead of #foo) to avoid them being treated as hsc2hs directives.
Here is an extension of the record access example in TypeLevel Literals showing how an overloaded label can be used as a record selector:
{# LANGUAGE DataKinds, KindSignatures, MultiParamTypeClasses,
FunctionalDependencies, FlexibleInstances,
OverloadedLabels, ScopedTypeVariables #}
import GHC.OverloadedLabels (IsLabel(..))
import GHC.TypeLits (Symbol)
data Label (l :: Symbol) = Get
class Has a l b  a l > b where
from :: a > Label l > b
data Point = Point Int Int deriving Show
instance Has Point "x" Int where from (Point x _) _ = x
instance Has Point "y" Int where from (Point _ y) _ = y
instance Has a l b => IsLabel l (a > b) where
fromLabel _ x = from x (Get :: Label l)
example = #x (Point 1 2)
Since:  7.8.1 

Enable overloaded list syntax (e.g. desugaring of lists via the IsList class).
GHC supports overloading of the list notation. Let us recap the notation for constructing lists. In Haskell, the list notation can be be used in the following seven ways:
[]  Empty list
[x]  x : []
[x,y,z]  x : y : z : []
[x .. ]  enumFrom x
[x,y ..]  enumFromThen x y
[x .. y]  enumFromTo x y
[x,y .. z]  enumFromThenTo x y z
When the OverloadedLists extension is turned on, the aforementioned seven notations are desugared as follows:
[]  fromListN 0 []
[x]  fromListN 1 (x : [])
[x,y,z]  fromListN 3 (x : y : z : [])
[x .. ]  fromList (enumFrom x)
[x,y ..]  fromList (enumFromThen x y)
[x .. y]  fromList (enumFromTo x y)
[x,y .. z]  fromList (enumFromThenTo x y z)
This extension allows programmers to use the list notation for construction of structures like: Set, Map, IntMap, Vector, Text and Array. The following code listing gives a few examples:
['0' .. '9'] :: Set Char
[1 .. 10] :: Vector Int
[("default",0), (k1,v1)] :: Map String Int
['a' .. 'z'] :: Text
List patterns are also overloaded. When the OverloadedLists extension is turned on, these definitions are desugared as follows
f [] = ...  f (toList > []) = ...
g [x,y,z] = ...  g (toList > [x,y,z]) = ...
(Here we are using viewpattern syntax for the translation, see View patterns.)
In the above desugarings, the functions toList, fromList and fromListN are all methods of the IsList class, which is itself exported from the GHC.Exts module. The type class is defined as follows:
class IsList l where
type Item l
fromList :: [Item l] > l
toList :: l > [Item l]
fromListN :: Int > [Item l] > l
fromListN _ = fromList
The IsList class and its methods are intended to be used in conjunction with the OverloadedLists extension.
It is perfectly fine to declare new instances of IsList, so that list notation becomes useful for completely new data types. Here are several example instances:
instance IsList [a] where
type Item [a] = a
fromList = id
toList = id
instance (Ord a) => IsList (Set a) where
type Item (Set a) = a
fromList = Set.fromList
toList = Set.toList
instance (Ord k) => IsList (Map k v) where
type Item (Map k v) = (k,v)
fromList = Map.fromList
toList = Map.toList
instance IsList (IntMap v) where
type Item (IntMap v) = (Int,v)
fromList = IntMap.fromList
toList = IntMap.toList
instance IsList Text where
type Item Text = Char
fromList = Text.pack
toList = Text.unpack
instance IsList (Vector a) where
type Item (Vector a) = a
fromList = Vector.fromList
fromListN = Vector.fromListN
toList = Vector.toList
When desugaring list notation with XOverloadedLists GHC uses the fromList (etc) methods from module GHC.Exts. You do not need to import GHC.Exts for this to happen.
However if you use XRebindableSyntax, then GHC instead uses whatever is in scope with the names of toList, fromList and fromListN. That is, these functions are rebindable; c.f. Rebindable syntax and the implicit Prelude import.
Currently, the IsList class is not accompanied with defaulting rules. Although feasible, not much thought has gone into how to specify the meaning of the default declarations like:
default ([a])
The current implementation of the OverloadedLists extension can be improved by handling the lists that are only populated with literals in a special way. More specifically, the compiler could allocate such lists statically using a compact representation and allow IsList instances to take advantage of the compact representation. Equipped with this capability the OverloadedLists extension will be in a good position to subsume the OverloadedStrings extension (currently, as a special case, string literals benefit from statically allocated compact representation).
Since:  8.0.1 

Allow all superclass constraints, including those that may result in nontermination of the typechecker.
The language extension XUndecidableSuperClasses allows much more flexible constraints in superclasses.
A class cannot generally have itself as a superclass. So this is illegal
class C a => D a where ...
class D a => C a where ...
GHC implements this test conservatively when type functions, or type variables, are involved. For example
type family F a :: Constraint
class F a => C a where ...
GHC will complain about this, because you might later add
type instance F Int = C Int
and now we’d be in a superclass loop. Here’s an example involving a type variable
class f (C f) => C f
class c => Id c
If we expanded the superclasses of C Id we’d get first Id (C Id) and thence C Id again.
But superclass constraints like these are sometimes useful, and the conservative check is annoying where no actual recursion is involved.
Moreover genuninelyrecursive superclasses are sometimes useful. Here’s a reallife example (Trac #10318)
class (Frac (Frac a) ~ Frac a,
Fractional (Frac a),
IntegralDomain (Frac a))
=> IntegralDomain a where
type Frac a :: *
Here the superclass cycle does terminate but it’s not entirely straightforward to see that it does.
With the language extension XUndecidableSuperClasses GHC lifts all restrictions on superclass constraints. If there really is a loop, GHC will only expand it to finite depth.
Implies:  XMonoLocalBinds, XKindSignatures, XExplicitNamespaces 

Allow use and definition of indexed type and data families.
Indexed type families form an extension to facilitate typelevel programming. Type families are a generalisation of associated data types [AssocDataTypes2005] and associated type synonyms [AssocTypeSyn2005] Type families themselves are described in Schrijvers 2008 [TypeFamilies2008]. Type families essentially provide typeindexed data types and named functions on types, which are useful for generic programming and highly parameterised library interfaces as well as interfaces with enhanced static information, much like dependent types. They might also be regarded as an alternative to functional dependencies, but provide a more functional style of typelevel programming than the relational style of functional dependencies.
Indexed type families, or type families for short, are type constructors that represent sets of types. Set members are denoted by supplying the type family constructor with type parameters, which are called type indices. The difference between vanilla parametrised type constructors and family constructors is much like between parametrically polymorphic functions and (adhoc polymorphic) methods of type classes. Parametric polymorphic functions behave the same at all type instances, whereas class methods can change their behaviour in dependence on the class type parameters. Similarly, vanilla type constructors imply the same data representation for all type instances, but family constructors can have varying representation types for varying type indices.
Indexed type families come in three flavours: data families, open type synonym families, and closed type synonym families. They are the indexed family variants of algebraic data types and type synonyms, respectively. The instances of data families can be data types and newtypes.
Type families are enabled by the flag XTypeFamilies. Additional information on the use of type families in GHC is available on the Haskell wiki page on type families.
[AssocDataTypes2005]  “Associated Types with Class”, M. Chakravarty, G. Keller, S. Peyton Jones, and S. Marlow. In Proceedings of “The 32nd Annual ACM SIGPLANSIGACT Symposium on Principles of Programming Languages (POPL‘05)”, pages 113, ACM Press, 2005) 
[AssocTypeSyn2005]  “Type Associated Type Synonyms”. M. Chakravarty, G. Keller, and S. Peyton Jones. In Proceedings of “The Tenth ACM SIGPLAN International Conference on Functional Programming”, ACM Press, pages 241253, 2005). 
[TypeFamilies2008]  “Type Checking with Open Type Functions”, T. Schrijvers, S. PeytonJones, M. Chakravarty, and M. Sulzmann, in Proceedings of “ICFP 2008: The 13th ACM SIGPLAN International Conference on Functional Programming”, ACM Press, pages 5162, 2008. 
Data families appear in two flavours: (1) they can be defined on the toplevel or (2) they can appear inside type classes (in which case they are known as associated types). The former is the more general variant, as it lacks the requirement for the typeindexes to coincide with the class parameters. However, the latter can lead to more clearly structured code and compiler warnings if some type instances were  possibly accidentally  omitted. In the following, we always discuss the general toplevel form first and then cover the additional constraints placed on associated types.
Indexed data families are introduced by a signature, such as
data family GMap k :: * > *
The special family distinguishes family from standard data declarations. The result kind annotation is optional and, as usual, defaults to * if omitted. An example is
data family Array e
Named arguments can also be given explicit kind signatures if needed. Just as with GADT declarations named arguments are entirely optional, so that we can declare Array alternatively with
data family Array :: * > *
Instance declarations of data and newtype families are very similar to standard data and newtype declarations. The only two differences are that the keyword data or newtype is followed by instance and that some or all of the type arguments can be nonvariable types, but may not contain forall types or type synonym families. However, data families are generally allowed in type parameters, and type synonyms are allowed as long as they are fully applied and expand to a type that is itself admissible  exactly as this is required for occurrences of type synonyms in class instance parameters. For example, the Either instance for GMap is
data instance GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
In this example, the declaration has only one variant. In general, it can be any number.
When the flag Wunusedtypepatterns is enabled, type variables that are mentioned in the patterns on the left hand side, but not used on the right hand side are reported. Variables that occur multiple times on the left hand side are also considered used. To suppress the warnings, unused variables should be either replaced or prefixed with underscores. Type variables starting with an underscore (_x) are otherwise treated as ordinary type variables.
This resembles the wildcards that can be used in Partial Type Signatures. However, there are some differences. No error messages reporting the inferred types are generated, nor does the flag XPartialTypeSignatures have any effect.
Data and newtype instance declarations are only permitted when an appropriate family declaration is in scope  just as a class instance declaration requires the class declaration to be visible. Moreover, each instance declaration has to conform to the kind determined by its family declaration. This implies that the number of parameters of an instance declaration matches the arity determined by the kind of the family.
A data family instance declaration can use the full expressiveness of ordinary data or newtype declarations:
Although, a data family is introduced with the keyword “data”, a data family instance can use either data or newtype. For example:
data family T a
data instance T Int = T1 Int  T2 Bool
newtype instance T Char = TC Bool
A data instance can use GADT syntax for the data constructors, and indeed can define a GADT. For example:
data family G a b
data instance G [a] b where
G1 :: c > G [Int] b
G2 :: G [a] Bool
You can use a deriving clause on a data instance or newtype instance declaration.
Even if data families are defined as toplevel declarations, functions that perform different computations for different family instances may still need to be defined as methods of type classes. In particular, the following is not possible:
data family T a
data instance T Int = A
data instance T Char = B
foo :: T a > Int
foo A = 1
foo B = 2
Instead, you would have to write foo as a class operation, thus:
class Foo a where
foo :: T a > Int
instance Foo Int where
foo A = 1
instance Foo Char where
foo B = 2
Given the functionality provided by GADTs (Generalised Algebraic Data Types), it might seem as if a definition, such as the above, should be feasible. However, type families  in contrast to GADTs  are open; i.e., new instances can always be added, possibly in other modules. Supporting pattern matching across different data instances would require a form of extensible case construct.
The instance declarations of a data family used in a single program may not overlap at all, independent of whether they are associated or not. In contrast to type class instances, this is not only a matter of consistency, but one of type safety.
Type families appear in three flavours: (1) they can be defined as open families on the toplevel, (2) they can be defined as closed families on the toplevel, or (3) they can appear inside type classes (in which case they are known as associated type synonyms). Toplevel families are more general, as they lack the requirement for the typeindexes to coincide with the class parameters. However, associated type synonyms can lead to more clearly structured code and compiler warnings if some type instances were  possibly accidentally  omitted. In the following, we always discuss the general toplevel forms first and then cover the additional constraints placed on associated types. Note that closed associated type synonyms do not exist.
Open indexed type families are introduced by a signature, such as
type family Elem c :: *
The special family distinguishes family from standard type declarations. The result kind annotation is optional and, as usual, defaults to * if omitted. An example is
type family Elem c
Parameters can also be given explicit kind signatures if needed. We call the number of parameters in a type family declaration, the family’s arity, and all applications of a type family must be fully saturated with respect to to that arity. This requirement is unlike ordinary type synonyms and it implies that the kind of a type family is not sufficient to determine a family’s arity, and hence in general, also insufficient to determine whether a type family application is well formed. As an example, consider the following declaration:
type family F a b :: * > *  F's arity is 2,
 although its overall kind is * > * > * > *
Given this declaration the following are examples of wellformed and malformed types:
F Char [Int]  OK! Kind: * > *
F Char [Int] Bool  OK! Kind: *
F IO Bool  WRONG: kind mismatch in the first argument
F Bool  WRONG: unsaturated application
The result kind annotation is optional and defaults to * (like argument kinds) if omitted. Polykinded type families can be declared using a parameter in the kind annotation:
type family F a :: k
In this case the kind parameter k is actually an implicit parameter of the type family.
Instance declarations of type families are very similar to standard type synonym declarations. The only two differences are that the keyword type is followed by instance and that some or all of the type arguments can be nonvariable types, but may not contain forall types or type synonym families. However, data families are generally allowed, and type synonyms are allowed as long as they are fully applied and expand to a type that is admissible  these are the exact same requirements as for data instances. For example, the [e] instance for Elem is
type instance Elem [e] = e
Type arguments can be replaced with underscores (_) if the names of the arguments don’t matter. This is the same as writing type variables with unique names. Unused type arguments can be replaced or prefixed with underscores to avoid warnings when the Wunusedtypepatterns flag is enabled. The same rules apply as for Data instance declarations.
Type family instance declarations are only legitimate when an appropriate family declaration is in scope  just like class instances require the class declaration to be visible. Moreover, each instance declaration has to conform to the kind determined by its family declaration, and the number of type parameters in an instance declaration must match the number of type parameters in the family declaration. Finally, the righthand side of a type instance must be a monotype (i.e., it may not include foralls) and after the expansion of all saturated vanilla type synonyms, no synonyms, except family synonyms may remain.
A type family can also be declared with a where clause, defining the full set of equations for that family. For example:
type family F a where
F Int = Double
F Bool = Char
F a = String
A closed type family’s equations are tried in order, from top to bottom, when simplifying a type family application. In this example, we declare an instance for F such that F Int simplifies to Double, F Bool simplifies to Char, and for any other type a that is known not to be Int or Bool, F a simplifies to String. Note that GHC must be sure that a cannot unify with Int or Bool in that last case; if a programmer specifies just F a in their code, GHC will not be able to simplify the type. After all, a might later be instantiated with Int.
A closed type family’s equations have the same restrictions as the equations for open type family instances.
A closed type family may be declared with no equations. Such closed type families are opaque typelevel definitions that will never reduce, are not necessarily injective (unlike empty data types), and cannot be given any instances. This is different from omitting the equations of a closed type family in a hsboot file, which uses the syntax where .., as in that case there may or may not be equations given in the hs file.
Here are some examples of admissible and illegal type instances:
type family F a :: *
type instance F [Int] = Int  OK!
type instance F String = Char  OK!
type instance F (F a) = a  WRONG: type parameter mentions a type family
type instance
F (forall a. (a, b)) = b  WRONG: a forall type appears in a type parameter
type instance
F Float = forall a.a  WRONG: righthand side may not be a forall type
type family H a where  OK!
H Int = Int
H Bool = Bool
H a = String
type instance H Char = Char  WRONG: cannot have instances of closed family
type family K a where  OK!
type family G a b :: * > *
type instance G Int = (,)  WRONG: must be two type parameters
type instance G Int Char Float = Double  WRONG: must be two type parameters
There must be some restrictions on the equations of type families, lest we define an ambiguous rewrite system. So, equations of open type families are restricted to be compatible. Two type patterns are compatible if
Two types are considered apart if, for all possible substitutions, the types cannot reduce to a common reduct.
The first clause of “compatible” is the more straightforward one. It says that the patterns of two distinct type family instances cannot overlap. For example, the following is disallowed:
type instance F Int = Bool
type instance F Int = Char
The second clause is a little more interesting. It says that two overlapping type family instances are allowed if the righthand sides coincide in the region of overlap. Some examples help here:
type instance F (a, Int) = [a]
type instance F (Int, b) = [b]  overlap permitted
type instance G (a, Int) = [a]
type instance G (Char, a) = [a]  ILLEGAL overlap, as [Char] /= [Int]
Note that this compatibility condition is independent of whether the type family is associated or not, and it is not only a matter of consistency, but one of type safety.
For a polykinded type family, the kinds are checked for apartness just like types. For example, the following is accepted:
type family J a :: k
type instance J Int = Bool
type instance J Int = Maybe
These instances are compatible because they differ in their implicit kind parameter; the first uses * while the second uses * > *.
The definition for “compatible” uses a notion of “apart”, whose definition in turn relies on type family reduction. This condition of “apartness”, as stated, is impossible to check, so we use this conservative approximation: two types are considered to be apart when the two types cannot be unified, even by a potentially infinite unifier. Allowing the unifier to be infinite disallows the following pair of instances:
type instance H x x = Int
type instance H [x] x = Bool
The type patterns in this pair equal if x is replaced by an infinite nesting of lists. Rejecting instances such as these is necessary for type soundness.
Compatibility also affects closed type families. When simplifying an application of a closed type family, GHC will select an equation only when it is sure that no incompatible previous equation will ever apply. Here are some examples:
type family F a where
F Int = Bool
F a = Char
type family G a where
G Int = Int
G a = a
In the definition for F, the two equations are incompatible – their patterns are not apart, and yet their righthand sides do not coincide. Thus, before GHC selects the second equation, it must be sure that the first can never apply. So, the type F a does not simplify; only a type such as F Double will simplify to Char. In G, on the other hand, the two equations are compatible. Thus, GHC can ignore the first equation when looking at the second. So, G a will simplify to a.
However see Type, class and other declarations for the overlap rules in GHCi.
Relax restrictions on the decidability of type synonym family instances.
In order to guarantee that type inference in the presence of type families decidable, we need to place a number of additional restrictions on the formation of type instance declarations (c.f., Definition 5 (Relaxed Conditions) of “Type Checking with Open Type Functions”). Instance declarations have the general form
type instance F t1 .. tn = t
where we require that for every type family application (G s1 .. sm) in t,
These restrictions are easily verified and ensure termination of type inference. However, they are not sufficient to guarantee completeness of type inference in the presence of, so called, ‘’loopy equalities’‘, such as a ~ [F a], where a recursive occurrence of a type variable is underneath a family application and data constructor application  see the above mentioned paper for details.
If the option XUndecidableInstances is passed to the compiler, the above restrictions are not enforced and it is on the programmer to ensure termination of the normalisation of type families during type inference.
When the name of a type argument of a data or type instance declaration doesn’t matter, it can be replaced with an underscore (_). This is the same as writing a type variable with a unique name.
data family F a b :: *
data instance F Int _ = Int
 Equivalent to data instance F Int b = Int
type family T a :: *
type instance T (a,_) = a
 Equivalent to type instance T (a,b) = a
This use of underscore for wildcard in a type pattern is exactly like pattern matching in the term language, but is rather different to the use of a underscore in a partial type signature (see Type Wildcards).
A type variable beginning with an underscore is not treated specially in a type or data instance declaration. For example:
data instance F Bool _a = _a > Int
 Equivalent to data instance F Bool a = a > Int
Contrast this with the special treatment of named wildcards in type signatures (Named Wildcards).
A data or type synonym family can be declared as part of a type class, thus:
class GMapKey k where
data GMap k :: * > *
...
class Collects ce where
type Elem ce :: *
...
When doing so, we (optionally) may drop the “family” keyword.
The type parameters must all be type variables, of course, and some (but not necessarily all) of then can be the class parameters. Each class parameter may only be used at most once per associated type, but some may be omitted and they may be in an order other than in the class head. Hence, the following contrived example is admissible:
class C a b c where
type T c a x :: *
Here c and a are class parameters, but the type is also indexed on a third parameter x.
When an associated data or type synonym family instance is declared within a type class instance, we (optionally) may drop the instance keyword in the family instance:
instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where
data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
...
instance Eq (Elem [e]) => Collects [e] where
type Elem [e] = e
...
Note the following points:
The type indexes corresponding to class parameters must have precisely the same shape the type given in the instance head. To have the same “shape” means that the two types are identical modulo renaming of type variables. For example:
instance Eq (Elem [e]) => Collects [e] where
 Choose one of the following alternatives:
type Elem [e] = e  OK
type Elem [x] = x  OK
type Elem x = x  BAD; shape of 'x' is different to '[e]'
type Elem [Maybe x] = x  BAD: shape of '[Maybe x]' is different to '[e]'
An instances for an associated family can only appear as part of an instance declarations of the class in which the family was declared, just as with the equations of the methods of a class.
The instance for an associated type can be omitted in class instances. In that case, unless there is a default instance (see Associated type synonym defaults), the corresponding instance type is not inhabited; i.e., only diverging expressions, such as undefined, can assume the type.
Although it is unusual, there (currently) can be multiple instances for an associated family in a single instance declaration. For example, this is legitimate:
instance GMapKey Flob where
data GMap Flob [v] = G1 v
data GMap Flob Int = G2 Int
...
Here we give two data instance declarations, one in which the last parameter is [v], and one for which it is Int. Since you cannot give any subsequent instances for (GMap Flob ...), this facility is most useful when the free indexed parameter is of a kind with a finite number of alternatives (unlike *). WARNING: this facility may be withdrawn in the future.
It is possible for the class defining the associated type to specify a default for associated type instances. So for example, this is OK:
class IsBoolMap v where
type Key v
type instance Key v = Int
lookupKey :: Key v > v > Maybe Bool
instance IsBoolMap [(Int, Bool)] where
lookupKey = lookup
In an instance declaration for the class, if no explicit type instance declaration is given for the associated type, the default declaration is used instead, just as with default class methods.
Note the following points:
Here are some examples:
class C a where
type F1 a :: *
type instance F1 a = [a]  OK
type instance F1 a = a>a  BAD; only one default instance is allowed
type F2 b a  OK; note the family has more type
 variables than the class
type instance F2 c d = c>d  OK; you don't have to use 'a' in the type instance
type F3 a
type F3 [b] = b  BAD; only type variables allowed on the LHS
type F4 a
type F4 b = a  BAD; 'a' is not in scope in the RHS
The visibility of class parameters in the righthand side of associated family instances depends solely on the parameters of the family. As an example, consider the simple class declaration
class C a b where
data T a
Only one of the two class parameters is a parameter to the data family. Hence, the following instance declaration is invalid:
instance C [c] d where
data T [c] = MkT (c, d)  WRONG!! 'd' is not in scope
Here, the righthand side of the data instance mentions the type variable d that does not occur in its lefthand side. We cannot admit such data instances as they would compromise type safety.
Associated type and data instance declarations do not inherit any context specified on the enclosing instance. For type instance declarations, it is unclear what the context would mean. For data instance declarations, it is unlikely a user would want the context repeated for every data constructor. The only place where the context might likely be useful is in a deriving clause of an associated data instance. However, even here, the role of the outer instance context is murky. So, for clarity, we just stick to the rule above: the enclosing instance context is ignored. If you need to use a nontrivial context on a derived instance, use a standalone deriving clause (at the top level).
The rules for export lists (Haskell Report Section 5.2) needs adjustment for type families:
Recall our running GMapKey class example:
class GMapKey k where
data GMap k :: * > *
insert :: GMap k v > k > v > GMap k v
lookup :: GMap k v > k > Maybe v
empty :: GMap k v
instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where
data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
...method declarations...
Here are some export lists and their meaning:
module GMap( GMapKey )
Exports just the class name.
module GMap( GMapKey(..) )
Exports the class, the associated type GMap and the member functions empty, lookup, and insert. The data constructors of GMap (in this case GMapEither) are not exported.
module GMap( GMapKey( type GMap, empty, lookup, insert ) )
Same as the previous item. Note the “type” keyword.
module GMap( GMapKey(..), GMap(..) )
Same as previous item, but also exports all the data constructors for GMap, namely GMapEither.
module GMap ( GMapKey( empty, lookup, insert), GMap(..) )
Same as previous item.
module GMap ( GMapKey, empty, lookup, insert, GMap(..) )
Same as previous item.
Two things to watch out for:
You cannot write GMapKey(type GMap(..)) — i.e., subcomponent specifications cannot be nested. To specify GMap‘s data constructors, you have to list it separately.
Consider this example:
module X where
data family D
module Y where
import X
data instance D Int = D1  D2
Module Y exports all the entities defined in Y, namely the data constructors D1 and D2, and implicitly the data family D, even though it’s defined in X. This means you can write import Y( D(D1,D2) ) without giving an explicit export list like this:
module Y( D(..) ) where ...
or module Y( module Y, D ) where ...
Family instances are implicitly exported, just like class instances. However, this applies only to the heads of instances, not to the data constructors an instance defines.
Type families require us to extend the rules for the form of instance heads, which are given in Relaxed rules for the instance head. Specifically:
The reason for the latter restriction is that there is no way to check for instance matching. Consider
type family F a
type instance F Bool = Int
class C a
instance C Int
instance C (F a)
Now a constraint (C (F Bool)) would match both instances. The situation is especially bad because the type instance for F Bool might be in another module, or even in a module that is not yet written.
However, type class instances of instances of data families can be defined much like any other data type. For example, we can say
data instance T Int = T1 Int  T2 Bool
instance Eq (T Int) where
(T1 i) == (T1 j) = i==j
(T2 i) == (T2 j) = i==j
_ == _ = False
Note that class instances are always for particular instances of a data family and never for an entire family as a whole. This is for essentially the same reasons that we cannot define a toplevel function that performs pattern matching on the data constructors of different instances of a single type family. It would require a form of extensible case construct.
Data instance declarations can also have deriving clauses. For example, we can write
data GMap () v = GMapUnit (Maybe v)
deriving Show
which implicitly defines an instance of the form
instance Show v => Show (GMap () v) where ...
Implies:  XTypeFamilies 

Since:  8.0.1 
Allow functional dependency annotations on type families. This allows one to define injective type families.
Starting with GHC 8.0 type families can be annotated with injectivity information. This information is then used by GHC during type checking to resolve type ambiguities in situations where a type variable appears only under type family applications. Consider this contrived example:
type family Id a
type instance Id Int = Int
type instance Id Bool = Bool
id :: Id t > Id t
id x = x
Here the definition of id will be rejected because type variable t appears only under type family applications and is thus ambiguous. But this code will be accepted if we tell GHC that Id is injective, which means it will be possible to infer t at call sites from the type of the argument:
type family Id a = r  r > a
Injective type families are enabled with XTypeFamilyDependencies language extension. This extension implies XTypeFamilies.
For full details on injective type families refer to Haskell Symposium 2015 paper Injective type families for Haskell.
Injectivity annotation is added after type family head and consists of two parts:
Examples:
type family Id a = result  result > a where
type family F a b c = d  d > a c b
type family G (a :: k) b c = foo  foo > k b where
For open and closed type families it is OK to name the result but skip the injectivity annotation. This is not the case for associated type synonyms, where the named result without injectivity annotation will be interpreted as associated type synonym default.
Once the user declares type family to be injective GHC must verify that this declaration is correct, ie. type family equations don’t violate the injectivity annotation. A general idea is that if at least one equation (bullets (1), (2) and (3) below) or a pair of equations (bullets (4) and (5) below) violates the injectivity annotation then a type family is not injective in a way user claims and an error is reported. In the bullets below RHS refers to the righthand side of the type family equation being checked for injectivity. LHS refers to the arguments of that type family equation. Below are the rules followed when checking injectivity of a type family:
If a RHS of a type family equation is a type family application GHC reports that the type family is not injective.
If a RHS of a type family equation is a bare type variable we require that all LHS variables (including implicit kind variables) are also bare. In other words, this has to be a sole equation of that type family and it has to cover all possible patterns. If the patterns are not covering GHC reports that the type family is not injective.
If a LHS type variable that is declared as injective is not mentioned on injective position in the RHS GHC reports that the type family is not injective. Injective position means either argument to a type constructor or injective argument to a type family.
Open type families Open type families are typechecked incrementally. This means that when a module is imported type family instances contained in that module are checked against instances present in already imported modules.
A pair of an open type family equations is checked by attempting to unify their RHSs. If the RHSs don’t unify this pair does not violate injectivity annotation. If unification succeeds with a substitution then LHSs of unified equations must be identical under that substitution. If they are not identical then GHC reports that the type family is not injective.
In a closed type family all equations are ordered and in one place. Equations are also checked pairwise but this time an equation has to be paired with all the preceeding equations. Of course a singleequation closed type family is trivially injective (unless (1), (2) or (3) above holds).
When checking a pair of closed type family equations GHC tried to unify their RHSs. If they don’t unify this pair of equations does not violate injectivity annotation. If the RHSs can be unified under some substitution (possibly empty) then either the LHSs unify under the same substitution or the LHS of the latter equation is subsumed by earlier equations. If neither condition is met GHC reports that a type family is not injective.
Note that for the purpose of injectivity check in bullets (4) and (5) GHC uses a special variant of unification algorithm that treats type family applications as possibly unifying with anything.
Since:  7.4.1 

Allow promotion of data types to kind level.
This section describes data type promotion, an extension to the kind system that complements kind polymorphism. It is enabled by XDataKinds, and described in more detail in the paper Giving Haskell a Promotion, which appeared at TLDI 2012.
Standard Haskell has a rich type language. Types classify terms and serve to avoid many common programming mistakes. The kind language, however, is relatively simple, distinguishing only regular types (kind *) and type constructors (e.g. kind * > * > *). In particular when using advanced type system features, such as type families (Type families) or GADTs (Generalised Algebraic Data Types (GADTs)), this simple kind system is insufficient, and fails to prevent simple errors. Consider the example of typelevel natural numbers, and lengthindexed vectors:
data Ze
data Su n
data Vec :: * > * > * where
Nil :: Vec a Ze
Cons :: a > Vec a n > Vec a (Su n)
The kind of Vec is * > * > *. This means that, e.g., Vec Int Char is a wellkinded type, even though this is not what we intend when defining lengthindexed vectors.
With XDataKinds, the example above can then be rewritten to:
data Nat = Ze  Su Nat
data Vec :: * > Nat > * where
Nil :: Vec a 'Ze
Cons :: a > Vec a n > Vec a ('Su n)
With the improved kind of Vec, things like Vec Int Char are now illkinded, and GHC will report an error.
With XDataKinds, GHC automatically promotes every datatype to be a kind and its (value) constructors to be type constructors. The following types
data Nat = Zero  Succ Nat
data List a = Nil  Cons a (List a)
data Pair a b = Pair a b
data Sum a b = L a  R b
give rise to the following kinds and type constructors (where promoted constructors are prefixed by a tick '):
Nat :: *
'Zero :: Nat
'Succ :: Nat > Nat
List :: * > *
'Nil :: forall k. List k
'Cons :: forall k. k > List k > List k
Pair :: * > * > *
'Pair :: forall k1 k2. k1 > k2 > Pair k1 k2
Sum :: * > * > *
'L :: k1 > Sum k1 k2
'R :: k2 > Sum k1 k2
The following restrictions apply to promotion:
The flag XTypeInType (which implies XDataKinds) relaxes some of these restrictions, allowing:
Promotion of type synonyms and type families, but not data families. GHC’s type theory just isn’t up to the task of promoting data families, which requires full dependent types.
All datatypes, even those with rich kinds, get promoted. For example:
data Proxy a = Proxy
data App f a = MkApp (f a)  App :: forall k. (k > *) > k > *
x = Proxy :: Proxy ('MkApp ('Just 'True))
In the examples above, all promoted constructors are prefixed with a single quote mark '. This mark tells GHC to look in the data constructor namespace for a name, not the type (constructor) namespace. Consider
data P = MkP  1
data Prom = P  2
We can thus distinguish the type P (which has a constructor MkP) from the promoted data constructor 'P (of kind Prom).
As a convenience, GHC allows you to omit the quote mark when the name is unambiguous. However, our experience has shown that the quote mark helps to make code more readable and less errorprone. GHC thus supports Wuntickedpromotedconstructors that will warn you if you use a promoted data constructor without a preceding quote mark.
Just as in the case of Template Haskell (Syntax), GHC gets confused if you put a quote mark before a data constructor whose second character is a quote mark. In this case, just put a space between the promotion quote and the data constructor:
data T = A'
type S = 'A'  ERROR: looks like a character
type R = ' A'  OK: promoted `A'`
With XDataKinds, Haskell’s list and tuple types are natively promoted to kinds, and enjoy the same convenient syntax at the type level, albeit prefixed with a quote:
data HList :: [*] > * where
HNil :: HList '[]
HCons :: a > HList t > HList (a ': t)
data Tuple :: (*,*) > * where
Tuple :: a > b > Tuple '(a,b)
foo0 :: HList '[]
foo0 = HNil
foo1 :: HList '[Int]
foo1 = HCons (3::Int) HNil
foo2 :: HList [Int, Bool]
foo2 = ...
For typelevel lists of two or more elements, such as the signature of foo2 above, the quote may be omitted because the meaning is unambiguous. But for lists of one or zero elements (as in foo0 and foo1), the quote is required, because the types [] and [Int] have existing meanings in Haskell.
Note
The declaration for HCons also requires XTypeOperators because of infix type operator (:')
Note that we do promote existential data constructors that are otherwise suitable. For example, consider the following:
data Ex :: * where
MkEx :: forall a. a > Ex
Both the type Ex and the data constructor MkEx get promoted, with the polymorphic kind 'MkEx :: forall k. k > Ex. Somewhat surprisingly, you can write a type family to extract the member of a typelevel existential:
type family UnEx (ex :: Ex) :: k
type instance UnEx (MkEx x) = x
At first blush, UnEx seems poorlykinded. The return kind k is not mentioned in the arguments, and thus it would seem that an instance would have to return a member of k for any k. However, this is not the case. The type family UnEx is a kindindexed type family. The return kind k is an implicit parameter to UnEx. The elaborated definitions are as follows (where implicit parameters are denoted by braces):
type family UnEx {k :: *} (ex :: Ex) :: k
type instance UnEx {k} (MkEx @k x) = x
Thus, the instance triggers only when the implicit parameter to UnEx matches the implicit parameter to MkEx. Because k is actually a parameter to UnEx, the kind is not escaping the existential, and the above code is valid.
See also Trac #7347.
Implies:  XPolyKinds, XDataKinds, XKindSignatures 

Since:  8.0.1 
Allow kinds to be as intricate as types, allowing explicit quantification over kind variables, higherrank kinds, and the use of type synonyms and families in kinds, among other features.
Implies:  XKindSignatures 

Since:  7.4.1 
Allow kind polymorphic types.
This section describes GHC’s kind system, as it appears in version 8.0 and beyond. The kind system as described here is always in effect, with or without extensions, although it is a conservative extension beyond standard Haskell. The extensions above simply enable syntax and tweak the inference algorithm to allow users to take advantage of the extra expressiveness of GHC’s kind system.
It is natural to consider XTypeInType as an extension of XPolyKinds. The latter simply enables fewer features of GHC’s rich kind system than does the former. The need for two separate extensions stems from their history: XPolyKinds was introduced for GHC 7.4, when it was experimental and temperamental. The wrinkles were smoothed out for GHC 7.6. XTypeInType was introduced for GHC 8.0, and is currently experimental and temperamental, with the wrinkles to be smoothed out in due course. The intent of having the two extensions is that users can rely on XPolyKinds to work properly while being duly sceptical of XTypeInType. In particular, we recommend enabling dcorelint whenever using XTypeInType; that flag turns on a set of internal checks within GHC that will discover bugs in the implementation of XTypeInType. Please report bugs at our bug tracker.
Although we have tried to allow the new behavior only when XTypeInType is enabled, some particularly thorny cases may have slipped through. It is thus possible that some construct is available in GHC 8.0 with XPolyKinds that was not possible in GHC 7.x. If you spot such a case, you are welcome to submit that as a bug as well. We flag newlyavailable capabilities below.
Consider inferring the kind for
data App f a = MkApp (f a)
In Haskell 98, the inferred kind for App is (* > *) > * > *. But this is overly specific, because another suitable Haskell 98 kind for App is ((* > *) > *) > (* > *) > *, where the kind assigned to a is * > *. Indeed, without kind signatures (XKindSignatures), it is necessary to use a dummy constructor to get a Haskell compiler to infer the second kind. With kind polymorphism (XPolyKinds), GHC infers the kind forall k. (k > *) > k > * for App, which is its most general kind.
Thus, the chief benefit of kind polymorphism is that we can now infer these most general kinds and use App at a variety of kinds:
App Maybe Int  `k` is instantiated to *
data T a = MkT (a Int)  `a` is inferred to have kind (* > *)
App T Maybe  `k` is instantiated to (* > *)
GHC 8 extends the idea of kind polymorphism by declaring that types and kinds are indeed one and the same. Nothing within GHC distinguishes between types and kinds. Another way of thinking about this is that the type Bool and the “promoted kind” Bool are actually identical. (Note that term True and the type 'True are still distinct, because the former can be used in expressions and the latter in types.) This lack of distinction between types and kinds is a hallmark of dependently typed languages. Full dependently typed languages also remove the difference between expressions and types, but doing that in GHC is a story for another day.
One simplification allowed by combining types and kinds is that the type of * is just *. It is true that the * :: * axiom can lead to nontermination, but this is not a problem in GHC, as we already have other means of nonterminating programs in both types and expressions. This decision (among many, many others) does mean that despite the expressiveness of GHC’s type system, a “proof” you write in Haskell is not an irrefutable mathematical proof. GHC promises only partial correctness, that if your programs compile and run to completion, their results indeed have the types assigned. It makes no claim about programs that do not finish in a finite amount of time.
To learn more about this decision and the design of GHC under the hood please see the paper introducing this kind system to GHC/Haskell.
Generally speaking, when XPolyKinds is on, GHC tries to infer the most general kind for a declaration. In this case the definition has a righthand side to inform kind inference. But that is not always the case. Consider
type family F a
Type family declarations have no righthand side, but GHC must still infer a kind for F. Since there are no constraints, it could infer F :: forall k1 k2. k1 > k2, but that seems too polymorphic. So GHC defaults those entirelyunconstrained kind variables to * and we get F :: * > *. You can still declare F to be kindpolymorphic using kind signatures:
type family F1 a  F1 :: * > *
type family F2 (a :: k)  F2 :: forall k. k > *
type family F3 a :: k  F3 :: forall k. * > k
type family F4 (a :: k1) :: k2  F4 :: forall k1 k2. k1 > k2
The general principle is this:
This rule has occasionallysurprising consequences (see Trac #10132.
class C a where  Class declarations are generalised
 so C :: forall k. k > Constraint
data D1 a  No right hand side for these two family
type F1 a  declarations, but the class forces (a :: k)
 so D1, F1 :: forall k. k > *
data D2 a  No righthand side so D2 :: * > *
type F2 a  No righthand side so F2 :: * > *
The kindpolymorphism from the class declaration makes D1 kindpolymorphic, but not so D2; and similarly F1, F1.
Just as in type inference, kind inference for recursive types can only use monomorphic recursion. Consider this (contrived) example:
data T m a = MkT (m a) (T Maybe (m a))
 GHC infers kind T :: (* > *) > * > *
The recursive use of T forced the second argument to have kind *. However, just as in type inference, you can achieve polymorphic recursion by giving a complete usersupplied kind signature (or CUSK) for T. A CUSK is present when all argument kinds and the result kind are known, without any need for inference. For example:
data T (m :: k > *) :: k > * where
MkT :: m a > T Maybe (m a) > T m a
The complete usersupplied kind signature specifies the polymorphic kind for T, and this signature is used for all the calls to T including the recursive ones. In particular, the recursive use of T is at kind *.
What exactly is considered to be a “complete usersupplied kind signature” for a type constructor? These are the forms:
For a datatype, every type variable must be annotated with a kind. In a GADTstyle declaration, there may also be a kind signature (with a toplevel :: in the header), but the presence or absence of this annotation does not affect whether or not the declaration has a complete signature.
data T1 :: (k > *) > k > * where ...
 Yes; T1 :: forall k. (k>*) > k > *
data T2 (a :: k > *) :: k > * where ...
 Yes; T2 :: forall k. (k>*) > k > *
data T3 (a :: k > *) (b :: k) :: * where ...
 Yes; T3 :: forall k. (k>*) > k > *
data T4 (a :: k > *) (b :: k) where ...
 Yes; T4 :: forall k. (k>*) > k > *
data T5 a (b :: k) :: * where ...
 No; kind is inferred
data T6 a b where ...
 No; kind is inferred
For a datatype with a toplevel :: when XTypeInType is in effect: all kind variables introduced after the :: must be explicitly quantified.
 XTypeInType is on
data T1 :: k > *  No CUSK: `k` is not explicitly quantified
data T2 :: forall k. k > *  CUSK: `k` is bound explicitly
data T3 :: forall (k :: *). k > *  still a CUSK
Note that the first example would indeed have a CUSK without XTypeInType.
For a class, every type variable must be annotated with a kind.
For a type synonym, every type variable and the result type must all be annotated with kinds:
type S1 (a :: k) = (a :: k)  Yes S1 :: forall k. k > k
type S2 (a :: k) = a  No kind is inferred
type S3 (a :: k) = Proxy a  No kind is inferred
Note that in S2 and S3, the kind of the righthand side is rather apparent, but it is still not considered to have a complete signature – no inference can be done before detecting the signature.
An unassociated open type or data family declaration always has a CUSK; unannotated type variables default to kind *:
data family D1 a  D1 :: * > *
data family D2 (a :: k)  D2 :: forall k. k > *
data family D3 (a :: k) :: *  D3 :: forall k. k > *
type family S1 a :: k > *  S1 :: forall k. * > k > *
An associated type or data family declaration has a CUSK precisely if its enclosing class has a CUSK.
class C a where  no CUSK
type AT a b  no CUSK, b is defaulted
class D (a :: k) where  yes CUSK
type AT2 a b  yes CUSK, b is defaulted
A closed type family has a complete signature when all of its type variables are annotated and a return kind (with a toplevel ::) is supplied.
With XTypeInType enabled, it is possible to write a datatype that syntactically has a CUSK (according to the rules above) but actually requires some inference. As a very contrived example, consider
data Proxy a  Proxy :: forall k. k > *
data X (a :: Proxy k)
According to the rules above X has a CUSK. Yet, what is the kind of k? It is impossible to know. This code is thus rejected as masquerading as having a CUSK, but not really. If you wish k to be polykinded, it is straightforward to specify this:
data X (a :: Proxy (k1 :: k2))
The above definition is indeed fully fixed, with no masquerade.
Although all open type families are considered to have a complete usersupplied kind signature, we can relax this condition for closed type families, where we have equations on which to perform kind inference. GHC will infer kinds for the arguments and result types of a closed type family.
GHC supports kindindexed type families, where the family matches both on the kind and type. GHC will not infer this behaviour without a complete usersupplied kind signature, as doing so would sometimes infer nonprincipal types. Indeed, we can see kindindexing as a form of polymorphic recursion, where a type is used at a kind other than its most general in its own definition.
For example:
type family F1 a where
F1 True = False
F1 False = True
F1 x = x
 F1 fails to compile: kindindexing is not inferred
type family F2 (a :: k) where
F2 True = False
F2 False = True
F2 x = x
 F2 fails to compile: no complete signature
type family F3 (a :: k) :: k where
F3 True = False
F3 False = True
F3 x = x
 OK
Consider the following example of a polykinded class and an instance for it:
class C a where
type F a
instance C b where
type F b = b > b
In the class declaration, nothing constrains the kind of the type a, so it becomes a polykinded type variable (a :: k). Yet, in the instance declaration, the righthand side of the associated type instance b > b says that b must be of kind *. GHC could theoretically propagate this information back into the instance head, and make that instance declaration apply only to type of kind *, as opposed to types of any kind. However, GHC does not do this.
In short: GHC does not propagate kind information from the members of a class instance declaration into the instance declaration head.
This lack of kind inference is simply an engineering problem within GHC, but getting it to work would make a substantial change to the inference infrastructure, and it’s not clear the payoff is worth it. If you want to restrict b‘s kind in the instance above, just use a kind signature in the instance head.
When kindchecking a type, GHC considers only what is written in that type when figuring out how to generalise the type’s kind.
For example, consider these definitions (with XScopedTypeVariables):
data Proxy a  Proxy :: forall k. k > *
p :: forall a. Proxy a
p = Proxy :: Proxy (a :: *)
GHC reports an error, saying that the kind of a should be a kind variable k, not *. This is because, by looking at the type signature forall a. Proxy a, GHC assumes a‘s kind should be generalised, not restricted to be *. The function definition is then rejected for being more specific than its type signature.
Enabled by XTypeInType, GHC now supports explicit kind quantification, as in these examples:
data Proxy :: forall k. k > *
f :: (forall k (a :: k). Proxy a > ()) > Int
Note that the second example has a forall that binds both a kind k and a type variable a of kind k. In general, there is no limit to how deeply nested this sort of dependency can work. However, the dependency must be wellscoped: forall (a :: k) k. ... is an error.
For backward compatibility, kind variables do not need to be bound explicitly, even if the type starts with forall.
Accordingly, the rule for kind quantification in higherrank contexts has changed slightly. In GHC 7, if a kind variable was mentioned for the first time in the kind of a variable bound in a nontoplevel forall, the kind variable was bound there, too. That is, in f :: (forall (a :: k). ...) > ..., the k was bound by the same forall as the a. In GHC 8, however, all kind variables mentioned in a type are bound at the outermost level. If you want one bound in a higherrank forall, include it explicitly.
Consider the type
data G (a :: k) where
GInt :: G Int
GMaybe :: G Maybe
This datatype G is GADTlike in both its kind and its type. Suppose you have g :: G a, where a :: k. Then pattern matching to discover that g is in fact `GMaybe tells you both that k ~ (* > *) and a ~ Maybe. The definition for G requires that XTypeInType be in effect, but patternmatching on G requires no extension beyond XGADTs. That this works is actually a straightforward extension of regular GADTs and a consequence of the fact that kinds and types are the same.
Note that the datatype G is used at different kinds in its body, and therefore that kindindexed GADTs use a form of polymorphic recursion. It is thus only possible to use this feature if you have provided a complete usersupplied kind signature for the datatype (Complete usersupplied kind signatures and polymorphic recursion).
As kinds and types are the same, kinds can now (with XTypeInType) contain type constraints. Only equality constraints are currently supported, however. We expect this to extend to other constraints in the future.
Here is an example of a constrained kind:
type family IsTypeLit a where
IsTypeLit Nat = 'True
IsTypeLit Symbol = 'True
IsTypeLit a = 'False
data T :: forall a. (IsTypeLit a ~ 'True) => a > * where
MkNat :: T 42
MkSymbol :: T "Don't panic!"
The declarations above are accepted. However, if we add MkOther :: T Int, we get an error that the equality constraint is not satisfied; Int is not a type literal. Note that explicitly quantifying with forall a is not necessary here.
The kind * classifies ordinary types. Without XTypeInType, this identifier is always in scope when writing a kind. However, with XTypeInType, a user may wish to use * in a type or a type operator * in a kind. To make this all more manageable, * becomes an (almost) ordinary name with XTypeInType enabled. So as not to cause naming collisions, it is not imported by default; you must import Data.Kind to get * (but only with XTypeInType enabled).
The only way * is unordinary is in its parsing. In order to be backward compatible, * is parsed as if it were an alphanumeric idenfifier; note that we do not write Int :: (*) but just plain Int :: *. Due to the bizarreness with which * is parsedand the fact that it is the only such operator in GHCthere are some corner cases that are not handled. We are aware of two:
In a Haskell98style data constructor, you must put parentheses around *, like this:
data Universe = Ty (*)  Num Int  ...
In an import/export list, you must put parentheses around *, like this:
import Data.Kind ( type (*) )
Note that the keyword type there is just to disambiguate the import from a termlevel (*). (Explicit namespaces in import/export)
The Data.Kind module also exports Type as a synonym for *. Now that type synonyms work in kinds, it is conceivable that we will deprecate * when there is a good migration story for everyone to use Type. If you like neither of these names, feel free to write your own synonym:
type Set = *  silly Agda programmers...
All the affordances for * also apply to ★, the Unicode variant of *.
If a type variable a in a datatype, class, or type family declaration depends on another such variable k in the same declaration, two properties must hold:
The first bullet simply means that the dependency must be wellscoped. The second bullet concerns GHC’s ability to infer dependency. Inferring this dependency is difficult, and GHC currently requires the dependency to be made explicit, meaning that k must appear in the kind of a type variable, making it obvious to GHC that dependency is intended. For example:
data Proxy k (a :: k)  OK: dependency is "obvious"
data Proxy2 k a = P (Proxy k a)  ERROR: dependency is unclear
In the second declaration, GHC cannot immediately tell that k should be a dependent variable, and so the declaration is rejected.
It is conceivable that this restriction will be relaxed in the future, but it is (at the time of writing) unclear if the difficulties around this scenario are theoretical (inferring this dependency would mean our type system does not have principal types) or merely practical (inferring this dependency is hard, given GHC’s implementation). So, GHC takes the easy way out and requires a little help from the user.
Without XPolyKinds or XTypeInType enabled, GHC refuses to generalise over kind variables. It thus defaults kind variables to * when possible; when this is not possible, an error is issued.
Here is an example of this in action:
{# LANGUAGE TypeInType #}
data Proxy a = P  inferred kind: Proxy :: k > *
data Compose f g x = MkCompose (f (g x))
 inferred kind: Compose :: (b > *) > (a > b) > a > *
 separate module having imported the first
{# LANGUAGE NoPolyKinds, DataKinds #}
z = Proxy :: Proxy 'MkCompose
In the last line, we use the promoted constructor 'MkCompose, which has kind
forall (a :: *) (b :: *) (f :: b > *) (g :: a > b) (x :: a).
f (g x) > Compose f g x
Now we must infer a type for z. To do so without generalising over kind variables, we must default the kind variables of 'MkCompose. We can easily default a and b to *, but f and g would be illkinded if defaulted. The definition for z is thus an error.
With kind polymorphism, there is quite a bit going on behind the scenes that may be invisible to a Haskell programmer. GHC supports several flags that control how types are printed in error messages and at the GHCi prompt. See the discussion of type prettyprinting options for further details. If you are using kind polymorphism and are confused as to why GHC is rejecting (or accepting) your program, we encourage you to turn on these flags, especially fprintexplicitkinds.
In order to allow full flexibility in how kinds are used, it is necessary to use the kind system to differentiate between boxed, lifted types (normal, everyday types like Int and [Bool]) and unboxed, primitive types (Unboxed types and primitive operations) like Int#. We thus have socalled representation polymorphism.
Note
For quite some time, this idea was known as levity polymorphism, when it differentiated between only lifted and unlifted types. Now that it differentiates between any runtime representations, the name has been changed. But anything you’ve read or heard about levity polymorphism likely applies to the story told here – this is just a small generalisation.
Here are the key definitions, all available from GHC.Exts:
TYPE :: RuntimeRep > *  highly magical, built into GHC
data RuntimeRep = PtrRepLifted  for things like `Int`
 PtrRepUnlifted  for things like `Array#`
 IntRep  for things like `Int#`
 ...
type * = TYPE PtrRepLifted  * is just an ordinary type synonym
The idea is that we have a new fundamental type constant TYPE, which is parameterised by a RuntimeRep. We thus get Int# :: TYPE 'IntRep and Bool :: TYPE 'PtrRepLifted. Anything with a type of the form TYPE x can appear to either side of a function arrow >. We can thus say that > has type TYPE r1 > TYPE r2 > TYPE 'PtrRepLifted. The result is always lifted because all functions are lifted in GHC.
If GHC didn’t have to compile programs that run in the real world, that would be the end of the story. But representation polymorphism can cause quite a bit of trouble for GHC’s code generator. Consider
bad :: forall (r1 :: RuntimeRep) (r2 :: RuntimeRep)
(a :: TYPE r1) (b :: TYPE r2).
(a > b) > a > b
bad f x = f x
This seems like a generalisation of the standard $ operator. If we think about compiling this to runnable code, though, problems appear. In particular, when we call bad, we must somehow pass x into bad. How wide (that is, how many bits) is x? Is it a pointer? What kind of register (floatingpoint or integral) should x go in? It’s all impossible to say, because x‘s type, TYPE r2 is representation polymorphic. We thus forbid such constructions, via the following straightforward rule:
No variable may have a representationpolymorphic type.
This eliminates bad because the variable x would have a representationpolymorphic type.
However, not all is lost. We can still do this:
($) :: forall r (a :: *) (b :: TYPE r).
(a > b) > a > b
f $ x = f x
Here, only b is representation polymorphic. There are no variables with a representation polymorphic type. And the code generator has no trouble with this. Indeed, this is the true type of GHC’s $ operator, slightly more general than the Haskell 98 version.
We can use representation polymorphism to good effect with error and undefined, whose types are given here:
undefined :: forall (r :: RuntimeRep) (a :: TYPE r).
HasCallStack => a
error :: forall (r :: RuntimeRep) (a :: TYPE r).
HasCallStack => String > a
These functions do not bind a representationpolymorphic variable, and so are accepted. Their polymorphism allows users to use these to conveniently stub out functions that return unboxed types.
Print RuntimeRep parameters as they appear; otherwise, they are defaulted to 'PtrRepLifted.
Most GHC users will not need to worry about representation polymorphism or unboxed types. For these users, see the representation polymorphism in the type of $ is unhelpful. And thus, by default, it is suppressed, by supposing all type variables of type RuntimeType to be 'PtrRepLifted when printing, and printing TYPE 'PtrRepLifted as *.
Should you wish to see representation polymorphism in your types, enable the flag fprintexplicitruntimereps.
GHC supports numeric and string literals at the type level, giving convenient access to a large number of predefined typelevel constants. Numeric literals are of kind Nat, while string literals are of kind Symbol. This feature is enabled by the XDataKinds language extension.
The kinds of the literals and all other lowlevel operations for this feature are defined in module GHC.TypeLits. Note that the module defines some typelevel operators that clash with their valuelevel counterparts (e.g. (+)). Import and export declarations referring to these operators require an explicit namespace annotation (see Explicit namespaces in import/export).
Here is an example of using typelevel numeric literals to provide a safe interface to a lowlevel function:
import GHC.TypeLits
import Data.Word
import Foreign
newtype ArrPtr (n :: Nat) a = ArrPtr (Ptr a)
clearPage :: ArrPtr 4096 Word8 > IO ()
clearPage (ArrPtr p) = ...
Here is an example of using typelevel string literals to simulate simple record operations:
data Label (l :: Symbol) = Get
class Has a l b  a l > b where
from :: a > Label l > b
data Point = Point Int Int deriving Show
instance Has Point "x" Int where from (Point x _) _ = x
instance Has Point "y" Int where from (Point _ y) _ = y
example = from (Point 1 2) (Get :: Label "x")
Sometimes it is useful to access the valuelevel literal associated with a typelevel literal. This is done with the functions natVal and symbolVal. For example:
GHC.TypeLits> natVal (Proxy :: Proxy 2)
2
These functions are overloaded because they need to return a different result, depending on the type at which they are instantiated.
natVal :: KnownNat n => proxy n > Integer
 instance KnownNat 0
 instance KnownNat 1
 instance KnownNat 2
 ...
GHC discharges the constraint as soon as it knows what concrete typelevel literal is being used in the program. Note that this works only for literals and not arbitrary type expressions. For example, a constraint of the form KnownNat (a + b) will not be simplified to (KnownNat a, KnownNat b); instead, GHC will keep the constraint as is, until it can simplify a + b to a constant value.
It is also possible to convert a runtime integer or string value to the corresponding typelevel literal. Of course, the resulting type literal will be unknown at compiletime, so it is hidden in an existential type. The conversion may be performed using someNatVal for integers and someSymbolVal for strings:
someNatVal :: Integer > Maybe SomeNat
SomeNat :: KnownNat n => Proxy n > SomeNat
The operations on strings are similar.
GHC 7.8 can evaluate arithmetic expressions involving typelevel natural numbers. Such expressions may be constructed using the typefamilies (+), (*), (^) for addition, multiplication, and exponentiation. Numbers may be compared using (<=?), which returns a promoted boolean value, or (<=), which compares numbers as a constraint. For example:
GHC.TypeLits> natVal (Proxy :: Proxy (2 + 3))
5
At present, GHC is quite limited in its reasoning about arithmetic: it will only evaluate the arithmetic type functions and compare the results— in the same way that it does for any other type function. In particular, it does not know more general facts about arithmetic, such as the commutativity and associativity of (+), for example.
However, it is possible to perform a bit of “backwards” evaluation. For example, here is how we could get GHC to compute arbitrary logarithms at the type level:
lg :: Proxy base > Proxy (base ^ pow) > Proxy pow
lg _ _ = Proxy
GHC.TypeLits> natVal (lg (Proxy :: Proxy 2) (Proxy :: Proxy 8))
3
A type context can include equality constraints of the form t1 ~ t2, which denote that the types t1 and t2 need to be the same. In the presence of type families, whether two types are equal cannot generally be decided locally. Hence, the contexts of function signatures may include equality constraints, as in the following example:
sumCollects :: (Collects c1, Collects c2, Elem c1 ~ Elem c2) => c1 > c2 > c2
where we require that the element type of c1 and c2 are the same. In general, the types t1 and t2 of an equality constraint may be arbitrary monotypes; i.e., they may not contain any quantifiers, independent of whether higherrank types are otherwise enabled.
Equality constraints can also appear in class and instance contexts. The former enable a simple translation of programs using functional dependencies into programs using family synonyms instead. The general idea is to rewrite a class declaration of the form
class C a b  a > b
to
class (F a ~ b) => C a b where
type F a
That is, we represent every functional dependency (FD) a1 .. an > b by an FD type family F a1 .. an and a superclass context equality F a1 .. an ~ b, essentially giving a name to the functional dependency. In class instances, we define the type instances of FD families in accordance with the class head. Method signatures are not affected by that process.
GHC also supports kindheterogeneous equality, which relates two types of potentially different kinds. Heterogeneous equality is spelled ~~. Here are the kinds of ~ and ~~ to better understand their difference:
(~) :: forall k. k > k > Constraint
(~~) :: forall k1 k2. k1 > k2 > Constraint
Users will most likely want ~, but ~~ is available if GHC cannot know, a priori, that the two types of interest have the same kind. Evidence that (a :: k1) ~~ (b :: k2) tells GHC both that k1 and k2 are the same and that a and b are the same.
Because ~ is the more common equality relation, GHC prints out ~~ like ~ unless fprintequalityrelations is set.
Internal to GHC is yet a third equality relation (~#). It is heterogeneous (like ~~) and is used only internally. It may appear in error messages and other output only when fprintequalityrelations is enabled.
The constraint Coercible t1 t2 is similar to t1 ~ t2, but denotes representational equality between t1 and t2 in the sense of Roles (Roles). It is exported by Data.Coerce, which also contains the documentation. More details and discussion can be found in the paper “Safe Coercions”.
Since:  7.4.1 

Allow types of kind Constraint to be used in contexts.
Normally, constraints (which appear in types to the left of the => arrow) have a very restricted syntax. They can only be:
With the XConstraintKinds flag, GHC becomes more liberal in what it accepts as constraints in your program. To be precise, with this flag any type of the new kind Constraint can be used as a constraint. The following things have kind Constraint:
Anything which is already valid as a constraint without the flag: saturated applications to type classes, implicit parameter and equality constraints.
Tuples, all of whose component types have kind Constraint. So for example the type (Show a, Ord a) is of kind Constraint.
Anything whose form is not yet known, but the user has declared to have kind Constraint (for which they need to import it from GHC.Exts). So for example type Foo (f :: \* > Constraint) = forall b. f b => b > b is allowed, as well as examples involving type families:
type family Typ a b :: Constraint
type instance Typ Int b = Show b
type instance Typ Bool b = Num b
func :: Typ a b => a > b > b
func = ...
Note that because constraints are just handled as types of a particular kind, this extension allows type constraint synonyms:
type Stringy a = (Read a, Show a)
foo :: Stringy a => a > (String, String > a)
foo x = (show x, read)
Presently, only standard constraints, tuples and type synonyms for those two sorts of constraint are permitted in instance contexts and superclasses (without extra flags). The reason is that permitting more general constraints can cause type checking to loop, as it would with these two programs:
type family Clsish u a
type instance Clsish () a = Cls a
class Clsish () a => Cls a where
class OkCls a where
type family OkClsish u a
type instance OkClsish () a = OkCls a
instance OkClsish () a => OkCls a where
You may write programs that use exotic sorts of constraints in instance contexts and superclasses, but to do so you must use XUndecidableInstances to signal that you don’t mind if the type checker fails to terminate.
Since:  6.12 

Allow use of the forall keyword in places where universal quantification is implicit.
Haskell type signatures are implicitly quantified. When the language option XExplicitForAll is used, the keyword forall allows us to say exactly what this means. For example:
g :: b > b
means this:
g :: forall b. (b > b)
The two are treated identically, except that the latter may bring type variables into scope (see Lexically scoped type variables).
Notes:
With XExplicitForAll, forall becomes a keyword; you can’t use forall as a type variable any more!
As well in type signatures, you can also use an explicit forall in an instance declaration:
instance forall a. Eq a => Eq [a] where ...
If the Wunusedforalls flag is enabled, a warning will be emitted when you write a type variable in an explicit forall statement that is otherwise unused. For instance:
g :: forall a b. (b > b)
would warn about the unused type variable a.
The XFlexibleContexts flag lifts the Haskell 98 restriction that the typeclass constraints in a type signature must have the form (class typevariable) or (class (typevariable type1 type2 ... typen)). With XFlexibleContexts these type signatures are perfectly okay
g :: Eq [a] => ...
g :: Ord (T a ()) => ...
The flag XFlexibleContexts also lifts the corresponding restriction on class declarations (The superclasses of a class declaration) and instance declarations (Relaxed rules for instance contexts).
Since:  7.8.1 

Allow type signatures which appear that they would result in an unusable binding.
Each userwritten type signature is subjected to an ambiguity check. The ambiguity check rejects functions that can never be called; for example:
f :: C a => Int
The idea is there can be no legal calls to f because every call will give rise to an ambiguous constraint. Indeed, the only purpose of the ambiguity check is to report functions that cannot possibly be called. We could soundly omit the ambiguity check on type signatures entirely, at the expense of delaying ambiguity errors to call sites. Indeed, the language extension XAllowAmbiguousTypes switches off the ambiguity check.
Ambiguity can be subtle. Consider this example which uses functional dependencies:
class D a b  a > b where ..
h :: D Int b => Int
The Int may well fix b at the call site, so that signature should not be rejected. Moreover, the dependencies might be hidden. Consider
class X a b where ...
class D a b  a > b where ...
instance D a b => X [a] b where...
h :: X a b => a > a
Here h‘s type looks ambiguous in b, but here’s a legal call:
...(h [True])...
That gives rise to a (X [Bool] beta) constraint, and using the instance means we need (D Bool beta) and that fixes beta via D‘s fundep!
Behind all these special cases there is a simple guiding principle. Consider
f :: type
f = ...blah...
g :: type
g = f
You would think that the definition of g would surely typecheck! After all f has exactly the same type, and g=f. But in fact f‘s type is instantiated and the instantiated constraints are solved against the constraints bound by g‘s signature. So, in the case an ambiguous type, solving will fail. For example, consider the earlier definition f :: C a => Int:
f :: C a => Int
f = ...blah...
g :: C a => Int
g = f
In g‘s definition, we’ll instantiate to (C alpha) and try to deduce (C alpha) from (C a), and fail.
So in fact we use this as our definition of ambiguity: a type ty is ambiguous if and only if ((undefined :: ty) :: ty) would fail to typecheck. We use a very similar test for inferred types, to ensure that they too are unambiguous.
Switching off the ambiguity check. Even if a function is has an ambiguous type according the “guiding principle”, it is possible that the function is callable. For example:
class D a b where ...
instance D Bool b where ...
strange :: D a b => a > a
strange = ...blah...
foo = strange True
Here strange‘s type is ambiguous, but the call in foo is OK because it gives rise to a constraint (D Bool beta), which is soluble by the (D Bool b) instance. So the language extension XAllowAmbiguousTypes allows you to switch off the ambiguity check. But even with ambiguity checking switched off, GHC will complain about a function that can never be called, such as this one:
f :: (Int ~ Bool) => a > a
Note
A historical note. GHC used to impose some more restrictive and less principled conditions on type signatures. For type forall tv1..tvn (c1, ...,cn) => type GHC used to require
 that each universally quantified type variable tvi must be “reachable” from type, and
 that every constraint ci mentions at least one of the universally quantified type variables tvi. These adhoc restrictions are completely subsumed by the new ambiguity check.
Allow explicit kind signatures on type variables.
Haskell infers the kind of each type variable. Sometimes it is nice to be able to give the kind explicitly as (machinechecked) documentation, just as it is nice to give a type signature for a function. On some occasions, it is essential to do so. For example, in his paper “Restricted Data Types in Haskell” (Haskell Workshop 1999) John Hughes had to define the data type:
data Set cxt a = Set [a]
 Unused (cxt a > ())
The only use for the Unused constructor was to force the correct kind for the type variable cxt.
GHC now instead allows you to specify the kind of a type variable directly, wherever a type variable is explicitly bound, with the flag XKindSignatures.
This flag enables kind signatures in the following places:
data declarations:
data Set (cxt :: * > *) a = Set [a]
type declarations:
type T (f :: * > *) = f Int
class declarations:
class (Eq a) => C (f :: * > *) a where ...
forall‘s in type signatures:
f :: forall (cxt :: * > *). Set cxt Int
The parentheses are required. Some of the spaces are required too, to separate the lexemes. If you write (f::*>*) you will get a parse error, because ::*>* is a single lexeme in Haskell.
As part of the same extension, you can put kind annotations in types as well. Thus:
f :: (Int :: *) > Int
g :: forall a. a > (a :: *)
The syntax is
atype ::= '(' ctype '::' kind ')
The parentheses are required.
Implies:  XExplicitForAll 

Enable lexical scoping of type variables explicitly introduced with forall.
GHC supports lexically scoped type variables, without which some type signatures are simply impossible to write. For example:
f :: forall a. [a] > [a]
f xs = ys ++ ys
where
ys :: [a]
ys = reverse xs
The type signature for f brings the type variable a into scope, because of the explicit forall (Declaration type signatures). The type variables bound by a forall scope over the entire definition of the accompanying value declaration. In this example, the type variable a scopes over the whole definition of f, including over the type signature for ys. In Haskell 98 it is not possible to declare a type for ys; a major benefit of scoped type variables is that it becomes possible to do so.
The design follows the following principles
A lexically scoped type variable can be bound by:
In Haskell, a programmerwritten type signature is implicitly quantified over its free type variables (Section 4.1.2 of the Haskell Report). Lexically scoped type variables affect this implicit quantification rules as follows: any type variable that is in scope is not universally quantified. For example, if type variable a is in scope, then
(e :: a > a) means (e :: a > a)
(e :: b > b) means (e :: forall b. b>b)
(e :: a > b) means (e :: forall b. a>b)
A declaration type signature that has explicit quantification (using forall) brings into scope the explicitlyquantified type variables, in the definition of the named function. For example:
f :: forall a. [a] > [a]
f (x:xs) = xs ++ [ x :: a ]
The “forall a” brings “a” into scope in the definition of “f”.
This only happens if:
The quantification in f‘s type signature is explicit. For example:
g :: [a] > [a]
g (x:xs) = xs ++ [ x :: a ]
This program will be rejected, because “a” does not scope over the definition of “g”, so “x::a” means “x::forall a. a” by Haskell’s usual implicit quantification rules.
The signature gives a type for a function binding or a bare variable binding, not a pattern binding. For example:
f1 :: forall a. [a] > [a]
f1 (x:xs) = xs ++ [ x :: a ]  OK
f2 :: forall a. [a] > [a]
f2 = \(x:xs) > xs ++ [ x :: a ]  OK
f3 :: forall a. [a] > [a]
Just f3 = Just (\(x:xs) > xs ++ [ x :: a ])  Not OK!
The binding for f3 is a pattern binding, and so its type signature does not bring a into scope. However f1 is a function binding, and f2 binds a bare variable; in both cases the type signature brings a into scope.
An expression type signature that has explicit quantification (using forall) brings into scope the explicitlyquantified type variables, in the annotated expression. For example:
f = runST ( (op >>= \(x :: STRef s Int) > g x) :: forall s. ST s Bool )
Here, the type signature forall s. ST s Bool brings the type variable s into scope, in the annotated expression (op >>= \(x :: STRef s Int) > g x).
A type signature may occur in any pattern; this is a pattern type signature. For example:
 f and g assume that 'a' is already in scope
f = \(x::Int, y::a) > x
g (x::a) = x
h ((x,y) :: (Int,Bool)) = (y,x)
In the case where all the type variables in the pattern type signature are already in scope (i.e. bound by the enclosing context), matters are simple: the signature simply constrains the type of the pattern in the obvious way.
Unlike expression and declaration type signatures, pattern type signatures are not implicitly generalised. The pattern in a pattern binding may only mention type variables that are already in scope. For example:
f :: forall a. [a] > (Int, [a])
f xs = (n, zs)
where
(ys::[a], n) = (reverse xs, length xs)  OK
zs::[a] = xs ++ ys  OK
Just (v::b) = ...  Not OK; b is not in scope
Here, the pattern signatures for ys and zs are fine, but the one for v is not because b is not in scope.
However, in all patterns other than pattern bindings, a pattern type signature may mention a type variable that is not in scope; in this case, the signature brings that type variable into scope. This is particularly important for existential data constructors. For example:
data T = forall a. MkT [a]
k :: T > T
k (MkT [t::a]) =
MkT t3
where
t3::[a] = [t,t,t]
Here, the pattern type signature (t::a) mentions a lexical type variable that is not already in scope. Indeed, it cannot already be in scope, because it is bound by the pattern match. GHC’s rule is that in this situation (and only then), a pattern type signature can mention a type variable that is not already in scope; the effect is to bring it into scope, standing for the existentiallybound type variable.
When a pattern type signature binds a type variable in this way, GHC insists that the type variable is bound to a rigid, or fullyknown, type variable. This means that any userwritten type signature always stands for a completely known type.
If all this seems a little odd, we think so too. But we must have some way to bring such type variables into scope, else we could not name existentiallybound type variables in subsequent type signatures.
This is (now) the only situation in which a pattern type signature is allowed to mention a lexical variable that is not already in scope. For example, both f and g would be illegal if a was not already in scope.
The type variables in the head of a class or instance declaration scope over the methods defined in the where part. You do not even need an explicit forall (although you are allowed an explicit forall in an instance declaration; see Explicit universal quantification (forall)). For example:
class C a where
op :: [a] > a
op xs = let ys::[a]
ys = reverse xs
in
head ys
instance C b => C [b] where
op xs = reverse (head (xs :: [[b]]))
Default:  on 

Prevents the compiler from applying the monomorphism restriction to bindings lacking explicit type signatures.
Haskell’s monomorphism restriction (see Section 4.5.5 of the Haskell Report) can be completely switched off by XNoMonomorphismRestriction. Since GHC 7.8.1, the monomorphism restriction is switched off by default in GHCi’s interactive options (see Setting options for interactive evaluation only).
Since:  6.12 

Infer less polymorphic types for local bindings by default.
An MLstyle language usually generalises the type of any letbound or wherebound variable, so that it is as polymorphic as possible. With the flag XMonoLocalBinds GHC implements a slightly more conservative policy, using the following rules:
For example, consider
f x = x + 1
g x = let h y = f y * 2
k z = z+x
in h x + k x
Here f is generalised because it has no free variables; and its binding group is unaffected by the monomorphism restriction; and hence f is closed. The same reasoning applies to g, except that it has one closed free variable, namely f. Similarly h is closed, even though it is not bound at top level, because its only free variable f is closed. But k is not closed, because it mentions x which is not closed (because it is not letbound).
Notice that a toplevel binding that is affected by the monomorphism restriction is not closed, and hence may in turn prevent generalisation of bindings that mention it.
The rationale for this more conservative strategy is given in the papers “Let should not be generalised” and “Modular type inference with local assumptions”, and a related blog post.
The flag XMonoLocalBinds is implied by XTypeFamilies and XGADTs. You can switch it off again with XNoMonoLocalBinds but type inference becomes less predicatable if you do so. (Read the papers!)
Since:  8.0.1 

Allow the use of type application syntax.
The XTypeApplications extension allows you to use visible type application in expressions. Here is an example: show (read @Int "5"). The @Int is the visible type application; it specifies the value of the type variable in read‘s type.
A visible type application is preceded with an @ sign. (To disambiguate the syntax, the @ must be preceded with a nonidentifier letter, usually a space. For example, read@Int 5 would not parse.) It can be used whenever the full polymorphic type of the function is known. If the function is an identifier (the common case), its type is considered known only when the identifier has been given a type signature. If the identifier does not have a type signature, visible type application cannot be used.
Here are the details:
If an identifier’s type signature does not include an explicit forall, the type variable arguments appear in the lefttoright order in which the variables appear in the type. So, foo :: Monad m => a b > m (a c) will have its type variables ordered as m, a, b, c.
If any of the variables depend on other variables (that is, if some of the variables are kind variables), the variables are reordered so that kind variables come before type variables, preserving the lefttoright order as much as possible. That is, GHC performs a stable topological sort on the variables.
For example: if we have bar :: Proxy (a :: (j, k)) > b, then the variables are ordered j, k, a, b.
Visible type application is available to instantiate only userspecified type variables. This means that in data Proxy a = Proxy, the unmentioned kind variable used in a‘s kind is not available for visible type application.
Class methods’ type arguments include the class type variables, followed by any variables an individual method is polymorphic in. So, class Monad m where return :: a > m a means that return‘s type arguments are m, a.
With the XRankNTypes extension (Lexically scoped type variables), it is possible to declare type arguments somewhere other than the beginning of a type. For example, we can have pair :: forall a. a > forall b. b > (a, b) and then say pair @Bool True @Char which would have type Char > (Bool, Char).
Partial type signatures (Partial Type Signatures) work nicely with visible type application. If you want to specify only the second type argument to wurble, then you can say wurble @_ @Int. The first argument is a wildcard, just like in a partial type signature. However, if used in a visible type application, it is not necessary to specify XPartialTypeSignatures and your code will not generate a warning informing you of the omitted type.
When printing types with fprintexplicitforalls enabled, type variables not available for visible type application are printed in braces. Thus, if you write myLength = length without a type signature, myLength‘s inferred type will be forall {f} {a}. Foldable f => f a > Int.
Data constructors declared with GADT syntax follow different rules for the time being; it is expected that these will be brought in line with other declarations in the future. The rules for GADT data constructors are as follows:
 All kind and type variables are considered specified and available for visible type application.
 Universal variables always come first, in precisely the order they appear in the type delcaration. Universal variables that are constrained by a GADT return type are not included in the data constructor.
 Existential variables come next. Their order is determined by a user written forall; or, if there is none, by taking the lefttoright order in the data constructor’s type and doing a stable topological sort.
Allow definition of functions expecting implicit parameters.
Implicit parameters are implemented as described in [Lewis2000] and enabled with the option XImplicitParams. (Most of the following, still rather incomplete, documentation is due to Jeff Lewis.)
[Lewis2000]  “Implicit parameters: dynamic scoping with static types”, J Lewis, MB Shields, E Meijer, J Launchbury, 27th ACM Symposium on Principles of Programming Languages (POPL‘00), Boston, Jan 2000. 
A variable is called dynamically bound when it is bound by the calling context of a function and statically bound when bound by the callee’s context. In Haskell, all variables are statically bound. Dynamic binding of variables is a notion that goes back to Lisp, but was later discarded in more modern incarnations, such as Scheme. Dynamic binding can be very confusing in an untyped language, and unfortunately, typed languages, in particular HindleyMilner typed languages like Haskell, only support static scoping of variables.
However, by a simple extension to the type class system of Haskell, we can support dynamic binding. Basically, we express the use of a dynamically bound variable as a constraint on the type. These constraints lead to types of the form (?x::t') => t, which says “this function uses a dynamicallybound variable ?x of type t'”. For example, the following expresses the type of a sort function, implicitly parameterised by a comparison function named cmp.
sort :: (?cmp :: a > a > Bool) => [a] > [a]
The dynamic binding constraints are just a new form of predicate in the type class system.
An implicit parameter occurs in an expression using the special form ?x, where x is any valid identifier (e.g. ord ?x is a valid expression). Use of this construct also introduces a new dynamicbinding constraint in the type of the expression. For example, the following definition shows how we can define an implicitly parameterised sort function in terms of an explicitly parameterised sortBy function:
sortBy :: (a > a > Bool) > [a] > [a]
sort :: (?cmp :: a > a > Bool) => [a] > [a]
sort = sortBy ?cmp
Dynamic binding constraints behave just like other type class constraints in that they are automatically propagated. Thus, when a function is used, its implicit parameters are inherited by the function that called it. For example, our sort function might be used to pick out the least value in a list:
least :: (?cmp :: a > a > Bool) => [a] > a
least xs = head (sort xs)
Without lifting a finger, the ?cmp parameter is propagated to become a parameter of least as well. With explicit parameters, the default is that parameters must always be explicit propagated. With implicit parameters, the default is to always propagate them.
An implicitparameter type constraint differs from other type class constraints in the following way: All uses of a particular implicit parameter must have the same type. This means that the type of (?x, ?x) is (?x::a) => (a,a), and not (?x::a, ?x::b) => (a, b), as would be the case for type class constraints.
You can’t have an implicit parameter in the context of a class or instance declaration. For example, both these declarations are illegal:
class (?x::Int) => C a where ...
instance (?x::a) => Foo [a] where ...
Reason: exactly which implicit parameter you pick up depends on exactly where you invoke a function. But the “invocation” of instance declarations is done behind the scenes by the compiler, so it’s hard to figure out exactly where it is done. Easiest thing is to outlaw the offending types.
Implicitparameter constraints do not cause ambiguity. For example, consider:
f :: (?x :: [a]) => Int > Int
f n = n + length ?x
g :: (Read a, Show a) => String > String
g s = show (read s)
Here, g has an ambiguous type, and is rejected, but f is fine. The binding for ?x at f‘s call site is quite unambiguous, and fixes the type a.
An implicit parameter is bound using the standard let or where binding forms. For example, we define the min function by binding cmp.
min :: Ord a => [a] > a
min = let ?cmp = (<=) in least
A group of implicitparameter bindings may occur anywhere a normal group of Haskell bindings can occur, except at top level. That is, they can occur in a let (including in a list comprehension, or donotation, or pattern guards), or a where clause. Note the following points:
An implicitparameter binding group must be a collection of simple bindings to implicitstyle variables (no functionstyle bindings, and no type signatures); these bindings are neither polymorphic or recursive.
You may not mix implicitparameter bindings with ordinary bindings in a single let expression; use two nested lets instead. (In the case of where you are stuck, since you can’t nest where clauses.)
You may put multiple implicitparameter bindings in a single binding group; but they are not treated as a mutually recursive group (as ordinary let bindings are). Instead they are treated as a nonrecursive group, simultaneously binding all the implicit parameter. The bindings are not nested, and may be reordered without changing the meaning of the program. For example, consider:
f t = let { ?x = t; ?y = ?x+(1::Int) } in ?x + ?y
The use of ?x in the binding for ?y does not “see” the binding for ?x, so the type of f is
f :: (?x::Int) => Int > Int
Consider these two definitions:
len1 :: [a] > Int
len1 xs = let ?acc = 0 in len_acc1 xs
len_acc1 [] = ?acc
len_acc1 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc1 xs

len2 :: [a] > Int
len2 xs = let ?acc = 0 in len_acc2 xs
len_acc2 :: (?acc :: Int) => [a] > Int
len_acc2 [] = ?acc
len_acc2 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc2 xs
The only difference between the two groups is that in the second group len_acc is given a type signature. In the former case, len_acc1 is monomorphic in its own righthand side, so the implicit parameter ?acc is not passed to the recursive call. In the latter case, because len_acc2 has a type signature, the recursive call is made to the polymorphic version, which takes ?acc as an implicit parameter. So we get the following results in GHCi:
Prog> len1 "hello"
0
Prog> len2 "hello"
5
Adding a type signature dramatically changes the result! This is a rather counterintuitive phenomenon, worth watching out for.
GHC applies the dreaded Monomorphism Restriction (section 4.5.5 of the Haskell Report) to implicit parameters. For example, consider:
f :: Int > Int
f v = let ?x = 0 in
let y = ?x + v in
let ?x = 5 in
y
Since the binding for y falls under the Monomorphism Restriction it is not generalised, so the type of y is simply Int, not (?x::Int) => Int. Hence, (f 9) returns result 9. If you add a type signature for y, then y will get type (?x::Int) => Int, so the occurrence of y in the body of the let will see the inner binding of ?x, so (f 9) will return 14.
Implies:  XExplicitForAll 

Allow types of arbitrary rank.
A deprecated alias of XRankNTypes.
GHC’s type system supports arbitraryrank explicit universal quantification in types. For example, all the following types are legal:
f1 :: forall a b. a > b > a
g1 :: forall a b. (Ord a, Eq b) => a > b > a
f2 :: (forall a. a>a) > Int > Int
g2 :: (forall a. Eq a => [a] > a > Bool) > Int > Int
f3 :: ((forall a. a>a) > Int) > Bool > Bool
f4 :: Int > (forall a. a > a)
Here, f1 and g1 are rank1 types, and can be written in standard Haskell (e.g. f1 :: a>b>a). The forall makes explicit the universal quantification that is implicitly added by Haskell.
The functions f2 and g2 have rank2 types; the forall is on the left of a function arrow. As g2 shows, the polymorphic type on the left of the function arrow can be overloaded.
The function f3 has a rank3 type; it has rank2 types on the left of a function arrow.
The language option XRankNTypes (which implies XExplicitForAll) enables higherrank types. That is, you can nest foralls arbitrarily deep in function arrows. For example, a foralltype (also called a “type scheme”), including a typeclass context, is legal:
The XRankNTypes option is also required for any type with a forall or context to the right of an arrow (e.g. f :: Int > forall a. a>a, or g :: Int > Ord a => a > a). Such types are technically rank 1, but are clearly not Haskell98, and an extra flag did not seem worth the bother.
In particular, in data and newtype declarations the constructor arguments may be polymorphic types of any rank; see examples in Examples. Note that the declared types are nevertheless always monomorphic. This is important because by default GHC will not instantiate type variables to a polymorphic type (Impredicative polymorphism).
The obsolete language options XPolymorphicComponents and XRank2Types are synonyms for XRankNTypes. They used to specify finer distinctions that GHC no longer makes. (They should really elicit a deprecation warning, but they don’t, purely to avoid the need to library authors to change their old flags specifications.)
These are examples of data and newtype declarations whose data constructors have polymorphic argument types:
data T a = T1 (forall b. b > b > b) a
data MonadT m = MkMonad { return :: forall a. a > m a,
bind :: forall a b. m a > (a > m b) > m b
}
newtype Swizzle = MkSwizzle (forall a. Ord a => [a] > [a])
The constructors have rank2 types:
T1 :: forall a. (forall b. b > b > b) > a > T a
MkMonad :: forall m. (forall a. a > m a)
> (forall a b. m a > (a > m b) > m b)
> MonadT m
MkSwizzle :: (forall a. Ord a => [a] > [a]) > Swizzle
In earlier versions of GHC, it was possible to omit the forall in the type of the constructor if there was an explicit context. For example:
newtype Swizzle' = MkSwizzle' (Ord a => [a] > [a])
As of GHC 7.10, this is deprecated. The Wcontextquantification flag detects this situation and issues a warning. In GHC 8.0 this flag was deprecated and declarations such as MkSwizzle' will cause an outofscope error.
As for type signatures, implicit quantification happens for nonoverloaded types too. So if you write this:
f :: (a > a) > a
it’s just as if you had written this:
f :: forall a. (a > a) > a
That is, since the type variable a isn’t in scope, it’s implicitly universally quantified.
You construct values of types T1, MonadT, Swizzle by applying the constructor to suitable values, just as usual. For example,
a1 :: T Int
a1 = T1 (\xy>x) 3
a2, a3 :: Swizzle
a2 = MkSwizzle sort
a3 = MkSwizzle reverse
a4 :: MonadT Maybe
a4 = let r x = Just x
b m k = case m of
Just y > k y
Nothing > Nothing
in
MkMonad r b
mkTs :: (forall b. b > b > b) > a > [T a]
mkTs f x y = [T1 f x, T1 f y]
The type of the argument can, as usual, be more general than the type required, as (MkSwizzle reverse) shows. (reverse does not need the Ord constraint.)
When you use pattern matching, the bound variables may now have polymorphic types. For example:
f :: T a > a > (a, Char)
f (T1 w k) x = (w k x, w 'c' 'd')
g :: (Ord a, Ord b) => Swizzle > [a] > (a > b) > [b]
g (MkSwizzle s) xs f = s (map f (s xs))
h :: MonadT m > [m a] > m [a]
h m [] = return m []
h m (x:xs) = bind m x $ \y >
bind m (h m xs) $ \ys >
return m (y:ys)
In the function h we use the record selectors return and bind to extract the polymorphic bind and return functions from the MonadT data structure, rather than using pattern matching.
In general, type inference for arbitraryrank types is undecidable. GHC uses an algorithm proposed by Odersky and Laufer (“Putting type annotations to work”, POPL‘96) to get a decidable algorithm by requiring some help from the programmer. We do not yet have a formal specification of “some help” but the rule is this:
For a lambdabound or casebound variable, x, either the programmer provides an explicit polymorphic type for x, or GHC’s type inference will assume that x’s type has no foralls in it.
What does it mean to “provide” an explicit type for x? You can do that by giving a type signature for x directly, using a pattern type signature (Lexically scoped type variables), thus:
\ f :: (forall a. a>a) > (f True, f 'c')
Alternatively, you can give a type signature to the enclosing context, which GHC can “push down” to find the type for the variable:
(\ f > (f True, f 'c')) :: (forall a. a>a) > (Bool,Char)
Here the type signature on the expression can be pushed inwards to give a type signature for f. Similarly, and more commonly, one can give a type signature for the function itself:
h :: (forall a. a>a) > (Bool,Char)
h f = (f True, f 'c')
You don’t need to give a type signature if the lambda bound variable is a constructor argument. Here is an example we saw earlier:
f :: T a > a > (a, Char)
f (T1 w k) x = (w k x, w 'c' 'd')
Here we do not need to give a type signature to w, because it is an argument of constructor T1 and that tells GHC all it needs to know.
GHC performs implicit quantification as follows. At the outermost level (only) of userwritten types, if and only if there is no explicit forall, GHC finds all the type variables mentioned in the type that are not already in scope, and universally quantifies them. For example, the following pairs are equivalent:
f :: a > a
f :: forall a. a > a
g (x::a) = let
h :: a > b > b
h x y = y
in ...
g (x::a) = let
h :: forall b. a > b > b
h x y = y
in ...
Notice that GHC always adds implicit quantfiers at the outermost level of a userwritten type; it does not find the innermost possible quantification point. For example:
f :: (a > a) > Int
 MEANS
f :: forall a. (a > a) > Int
 NOT
f :: (forall a. a > a) > Int
g :: (Ord a => a > a) > Int
 MEANS
g :: forall a. (Ord a => a > a) > Int
 NOT
g :: (forall a. Ord a => a > a) > Int
If you want the latter type, you can write your foralls explicitly. Indeed, doing so is strongly advised for rank2 types.
Sometimes there is no “outermost level”, in which case no implicit quanification happens:
data PackMap a b s t = PackMap (Monad f => (a > f b) > s > f t)
This is rejected because there is no “outermost level” for the types on the RHS (it would obviously be terrible to add extra parameters to PackMap), so no implicit quantificaiton happens, and the declaration is rejected (with “f is out of scope”). Solution: use an explicit forall:
data PackMap a b s t = PackMap (forall f. Monad f => (a > f b) > s > f t)
Implies:  RankNTypes 

Allow impredicative polymorphic types.
In general, GHC will only instantiate a polymorphic function at a monomorphic type (one with no foralls). For example,
runST :: (forall s. ST s a) > a
id :: forall b. b > b
foo = id runST  Rejected
The definition of foo is rejected because one would have to instantiate id‘s type with b := (forall s. ST s a) > a, and that is not allowed. Instantiating polymorphic type variables with polymorphic types is called impredicative polymorphism.
GHC has extremely flaky support for impredicative polymorphism, enabled with XImpredicativeTypes. If it worked, this would mean that you could call a polymorphic function at a polymorphic type, and parameterise data structures over polymorphic types. For example:
f :: Maybe (forall a. [a] > [a]) > Maybe ([Int], [Char])
f (Just g) = Just (g [3], g "hello")
f Nothing = Nothing
Notice here that the Maybe type is parameterised by the polymorphic type (forall a. [a] > [a]). However the extension should be considered highly experimental, and certainly unsupported. You are welcome to try it, but please don’t rely on it working consistently, or working the same in subsequent releases. See this wiki page for more details.
If you want impredicative polymorphism, the main workaround is to use a newtype wrapper. The id runST example can be written using theis workaround like this:
runST :: (forall s. ST s a) > a
id :: forall b. b > b
nwetype Wrap a = Wrap { unWrap :: (forall s. ST s a) > a }
foo :: (forall s. ST s a) > a
foo = unWrap (id (Wrap runST))
 Here id is called at monomorphic type (Wrap a)
Typed holes are a feature of GHC that allows special placeholders written with a leading underscore (e.g., “_”, “_foo”, “_bar”), to be used as expressions. During compilation these holes will generate an error message that describes which type is expected at the hole’s location, information about the origin of any free type variables, and a list of local bindings that might help fill the hole with actual code. Typed holes are always enabled in GHC.
The goal of typed holes is to help with writing Haskell code rather than to change the type system. Typed holes can be used to obtain extra information from the type checker, which might otherwise be hard to get. Normally, using GHCi, users can inspect the (inferred) type signatures of all toplevel bindings. However, this method is less convenient with terms that are not defined on toplevel or inside complex expressions. Holes allow the user to check the type of the term they are about to write.
For example, compiling the following module with GHC:
f :: a > a
f x = _
will fail with the following error:
hole.hs:2:7:
Found hole `_' with type: a
Where: `a' is a rigid type variable bound by
the type signature for f :: a > a at hole.hs:1:6
Relevant bindings include
f :: a > a (bound at hole.hs:2:1)
x :: a (bound at hole.hs:2:3)
In the expression: _
In an equation for `f': f x = _
Here are some more details:
A “Found hole” error usually terminates compilation, like any other type error. After all, you have omitted some code from your program. Nevertheless, you can run and test a piece of code containing holes, by using the fdefertypedholes flag. This flag defers errors produced by typed holes until runtime, and converts them into compiletime warnings. These warnings can in turn be suppressed entirely by fnowarntypedholes.
The same behaviour for “Variable out of scope” errors, it terminates compilation by default. You can defer such errors by using the fdeferoutofscopevariables flag. This flag defers errors produced by out of scope variables until runtime, and converts them into compiletime warnings. These warnings can in turn be suppressed entirely by fnowarndeferredoutofscopevariables.
The result is that a hole or a variable will behave like undefined, but with the added benefits that it shows a warning at compile time, and will show the same message if it gets evaluated at runtime. This behaviour follows that of the fdefertypeerrors option, which implies fdefertypedholes and fdeferoutofscopevariables. See Deferring type errors to runtime.
All unbound identifiers are treated as typed holes, whether or not they start with an underscore. The only difference is in the error message:
cons z = z : True : _x : y
yields the errors
Foo.hs:5:15: error:
Found hole: _x :: Bool
Relevant bindings include
p :: Bool (bound at Foo.hs:3:6)
cons :: Bool > [Bool] (bound at Foo.hs:3:1)
Foo.hs:5:20: error:
Variable not in scope: y :: [Bool]
More information is given for explicit holes (i.e. ones that start with an underscore), than for outofscope variables, because the latter are often unintended typos, so the extra information is distracting. If you want the detailed information, use a leading underscore to make explicit your intent to use a hole.
Unbound identifiers with the same name are never unified, even within the same function, but shown individually. For example:
cons = _x : _x
results in the following errors:
unbound.hs:1:8:
Found hole '_x' with type: a
Where: `a' is a rigid type variable bound by
the inferred type of cons :: [a] at unbound.hs:1:1
Relevant bindings include cons :: [a] (bound at unbound.hs:1:1)
In the first argument of `(:)', namely `_x'
In the expression: _x : _x
In an equation for `cons': cons = _x : _x
unbound.hs:1:13:
Found hole '_x' with type: [a]
Arising from: an undeclared identifier `_x' at unbound.hs:1:1314
Where: `a' is a rigid type variable bound by
the inferred type of cons :: [a] at unbound.hs:1:1
Relevant bindings include cons :: [a] (bound at unbound.hs:1:1)
In the second argument of `(:)', namely `_x'
In the expression: _x : _x
In an equation for `cons': cons = _x : _x
Notice the two different types reported for the two different occurrences of _x.
No language extension is required to use typed holes. The lexeme “_” was previously illegal in Haskell, but now has a more informative error message. The lexeme “_x” is a perfectly legal variable, and its behaviour is unchanged when it is in scope. For example
f _x = _x + 1
does not elict any errors. Only a variable that is not in scope (whether or not it starts with an underscore) is treated as an error (which it always was), albeit now with a more informative error message.
Unbound data constructors used in expressions behave exactly as above. However, unbound data constructors used in patterns cannot be deferred, and instead bring compilation to a halt. (In implementation terms, they are reported by the renamer rather than the type checker.)
Since:  7.10.1 

Type checker will allow inferred types for holes.
A partial type signature is a type signature containing special placeholders written with a leading underscore (e.g., “_”, “_foo”, “_bar”) called wildcards. Partial type signatures are to type signatures what Typed Holes are to expressions. During compilation these wildcards or holes will generate an error message that describes which type was inferred at the hole’s location, and information about the origin of any free type variables. GHC reports such error messages by default.
Unlike Typed Holes, which make the program incomplete and will generate errors when they are evaluated, this needn’t be the case for holes in type signatures. The type checker is capable (in most cases) of typechecking a binding with or without a type signature. A partial type signature bridges the gap between the two extremes, the programmer can choose which parts of a type to annotate and which to leave over to the typechecker to infer.
By default, the typechecker will report an error message for each hole in a partial type signature, informing the programmer of the inferred type. When the XPartialTypeSignatures flag is enabled, the typechecker will accept the inferred type for each hole, generating warnings instead of errors. Additionally, these warnings can be silenced with the Wnopartialtypesignatures flag.
A (partial) type signature has the following form: forall a b .. . (C1, C2, ..) => tau. It consists of three parts:
We distinguish three kinds of wildcards.
Wildcards occurring within the monotype (tau) part of the type signature are type wildcards (“type” is often omitted as this is the default kind of wildcard). Type wildcards can be instantiated to any monotype like Bool or Maybe [Bool], including functions and higherkinded types like (Int > Bool) or Maybe.
not' :: Bool > _
not' x = not x
 Inferred: Bool > Bool
maybools :: _
maybools = Just [True]
 Inferred: Maybe [Bool]
just1 :: _ Int
just1 = Just 1
 Inferred: Maybe Int
filterInt :: _ > _ > [Int]
filterInt = filter  has type forall a. (a > Bool) > [a] > [a]
 Inferred: (Int > Bool) > [Int] > [Int]
For instance, the first wildcard in the type signature not' would produce the following error message:
Test.hs:4:17: error:
• Found type wildcard ‘_’ standing for ‘Bool’
To use the inferred type, enable PartialTypeSignatures
• In the type signature:
not' :: Bool > _
• Relevant bindings include
not' :: Bool > Bool (bound at Test.hs:5:1)
When a wildcard is not instantiated to a monotype, it will be generalised over, i.e. replaced by a fresh type variable, e.g.
foo :: _ > _
foo x = x
 Inferred: forall t. t > t
filter' :: _
filter' = filter  has type forall a. (a > Bool) > [a] > [a]
 Inferred: (a > Bool) > [a] > [a]
Since:  7.10.1 

Allow naming of wildcards (e.g. _x) in type signatures.
Type wildcards can also be named by giving the underscore an identifier as suffix, i.e. _a. These are called named wildcards. All occurrences of the same named wildcard within one type signature will unify to the same type. For example:
f :: _x > _x
f ('c', y) = ('d', error "Urk")
 Inferred: forall t. (Char, t) > (Char, t)
The named wildcard forces the argument and result types to be the same. Lacking a signature, GHC would have inferred forall a b. (Char, a) > (Char, b). A named wildcard can be mentioned in constraints, provided it also occurs in the monotype part of the type signature to make sure that it unifies with something:
somethingShowable :: Show _x => _x > _
somethingShowable x = show x
 Inferred type: Show a => a > String
somethingShowable' :: Show _x => _x > _
somethingShowable' x = show (not x)
 Inferred type: Bool > String
Besides an extraconstraints wildcard (see ExtraConstraints Wildcard), only named wildcards can occur in the constraints, e.g. the _x in Show _x.
Named wildcards should not be confused with type variables. Even though syntactically similar, named wildcards can unify with monotypes as well as be generalised over (and behave as type variables).
In the first example above, _x is generalised over (and is effectively replaced by a fresh type variable a). In the second example, _x is unified with the Bool type, and as Bool implements the Show type class, the constraint Show Bool can be simplified away.
By default, GHC (as the Haskell 2010 standard prescribes) parses identifiers starting with an underscore in a type as type variables. To treat them as named wildcards, the XNamedWildCards flag should be enabled. The example below demonstrated the effect.
foo :: _a > _a
foo _ = False
Compiling this program without enabling XNamedWildCards produces the following error message complaining about the type variable _a no matching the actual type Bool.
Test.hs:5:9: error:
• Couldn't match expected type ‘_a’ with actual type ‘Bool’
‘_a’ is a rigid type variable bound by
the type signature for:
foo :: forall _a. _a > _a
at Test.hs:4:8
• In the expression: False
In an equation for ‘foo’: foo _ = False
• Relevant bindings include foo :: _a > _a (bound at Test.hs:5:1)
Compiling this program with XNamedWildCards (as well as XPartialTypeSignatures) enabled produces the following error message reporting the inferred type of the named wildcard _a.
Test.hs:4:8: warning: [Wpartialtypesignatures]
• Found type wildcard ‘_a’ standing for ‘Bool’
• In the type signature:
foo :: _a > _a
• Relevant bindings include
foo :: Bool > Bool (bound at Test.hs:5:1)
The third kind of wildcard is the extraconstraints wildcard. The presence of an extraconstraints wildcard indicates that an arbitrary number of extra constraints may be inferred during type checking and will be added to the type signature. In the example below, the extraconstraints wildcard is used to infer three extra constraints.
arbitCs :: _ => a > String
arbitCs x = show (succ x) ++ show (x == x)
 Inferred:
 forall a. (Enum a, Eq a, Show a) => a > String
 Error:
Test.hs:5:12: error:
Found constraint wildcard ‘_’ standing for ‘(Show a, Eq a, Enum a)’
To use the inferred type, enable PartialTypeSignatures
In the type signature:
arbitCs :: _ => a > String
An extraconstraints wildcard shouldn’t prevent the programmer from already listing the constraints he knows or wants to annotate, e.g.
 Also a correct partial type signature:
arbitCs' :: (Enum a, _) => a > String
arbitCs' x = arbitCs x
 Inferred:
 forall a. (Enum a, Show a, Eq a) => a > String
 Error:
Test.hs:9:22: error:
Found constraint wildcard ‘_’ standing for ‘()’
To use the inferred type, enable PartialTypeSignatures
In the type signature:
arbitCs' :: (Enum a, _) => a > String
An extraconstraints wildcard can also lead to zero extra constraints to be inferred, e.g.
noCs :: _ => String
noCs = "noCs"
 Inferred: String
 Error:
Test.hs:13:9: error:
Found constraint wildcard ‘_’ standing for ‘()’
To use the inferred type, enable PartialTypeSignatures
In the type signature:
noCs :: _ => String
As a single extraconstraints wildcard is enough to infer any number of constraints, only one is allowed in a type signature and it should come last in the list of constraints.
Extraconstraints wildcards cannot be named.
Partial type signatures are allowed for bindings, pattern and expression signatures, except that extraconstraints wildcards are not supported in pattern or expression signatures. In the following example a wildcard is used in each of the three possible contexts.
{# LANGUAGE ScopedTypeVariables #}
foo :: _
foo (x :: _) = (x :: _)
 Inferred: forall w_. w_ > w_
Anonymous and named wildcards can occur on the left hand side of a type or data instance declaration; see Wildcards on the LHS of data and type family instances.
Anonymous wildcards are also allowed in visible type applications (Visible type application). If you want to specify only the second type argument to wurble, then you can say wurble @_ @Int where the first argument is a wildcard.
In all other contexts, type wildcards are disallowed, and a named wildcard is treated as an ordinary type variable. For example:
class C _ where ...  Illegal
instance Eq (T _)  Illegal (currently; would actually make sense)
instance Eq _a => Eq (T _a)  Perfectly fine, same as Eq a => Eq (T a)
Partial type signatures can also be used in Template Haskell splices.
Declaration splices: partial type signature are fully supported.
{# LANGUAGE TemplateHaskell, NamedWildCards #}
$( [d foo :: _ => _a > _a > _
foo x y = x == y] )
Expression splices: anonymous and named wildcards can be used in expression signatures. Extraconstraints wildcards are not supported, just like in regular expression signatures.
{# LANGUAGE TemplateHaskell, NamedWildCards #}
$( [e foo = (Just True :: _m _) ] )
Typed expression splices: the same wildcards as in (untyped) expression splices are supported.
Pattern splices: Template Haskell doesn’t support type signatures in pattern splices. Consequently, partial type signatures are not supported either.
Type splices: only anonymous wildcards are supported in type splices. Named and extraconstraints wildcards are not.
{# LANGUAGE TemplateHaskell #}
foo :: $( [t _ ] ) > a
foo x = x
When designing embedded domain specific languages in Haskell, it is useful to have something like error at the type level. In this way, the EDSL designer may show a type error that is specific to the DSL, rather than the standard GHC type error.
For example, consider a type class that is not intended to be used with functions, but the user accidentally used it at a function type, perhaps because they missed an argument to some function. Then, instead of getting the standard GHC message about a missing instance, it would be nicer to emit a more friendly message specific to the EDSL. Similarly, the reduction of a typelevel function may get stuck due to an error, at which point it would be nice to report an EDSL specific error, rather than a generic error about an ambiguous type.
To solve this, GHC provides a single typelevel function,
type family TypeError (msg :: ErrorMessage) :: k
along with a small typelevel language (via XDataKinds) for constructing prettyprinted error messages,
 ErrorMessage is intended to be used as a kind
data ErrorMessage =
Text Symbol  Show this text as is
 forall t. ShowType t  Pretty print a type
 ErrorMessage :<>: ErrorMessage  Put two chunks of error message next to each other
 ErrorMessage :$$: ErrorMessage  Put two chunks of error message above each other
in the GHC.TypeLits module.
For instance, we might use this interface to provide a more useful error message for applications of show on unsaturated functions like this,
{# LANGUAGE DataKinds #}
{# LANGUAGE TypeOperators #}
{# LANGUAGE UndecidableInstances #}
import GHC.TypeLits
instance TypeError (Text "Cannot 'Show' functions." :$$:
Text "Perhaps there is a missing argument?")
=> Show (a > b) where
showsPrec = error "unreachable"
main = print negate
Which will produce the following compiletime error,
Test.hs:12:8: error:
• Cannot 'Show' functions.
Perhaps there is a missing argument?
• In the expression: print negate
In an equation for ‘main’: main = print negate
While developing, sometimes it is desirable to allow compilation to succeed even if there are type errors in the code. Consider the following case:
module Main where
a :: Int
a = 'a'
main = print "b"
Even though a is illtyped, it is not used in the end, so if all that we’re interested in is main it can be useful to be able to ignore the problems in a.
For more motivation and details please refer to the Wiki page or the original paper.
The flag fdefertypeerrors controls whether type errors are deferred to runtime. Type errors will still be emitted as warnings, but will not prevent compilation. You can use Wnodeferredtypeerrors to suppress these warnings.
This flag implies the fdefertypedholes and fdeferoutofscopevariables flags, which enables this behaviour for typed holes and variables. Should you so wish, it is possible to enable fdefertypeerrors without enabling fdefertypedholes or fdeferoutofscopevariables, by explicitly specifying fnodefertypedholes or fnodeferoutofscopevariables on the commandline after the fdefertypeerrors flag.
At runtime, whenever a term containing a type error would need to be evaluated, the error is converted into a runtime exception of type TypeError. Note that type errors are deferred as much as possible during runtime, but invalid coercions are never performed, even when they would ultimately result in a value of the correct type. For example, given the following code:
x :: Int
x = 0
y :: Char
y = x
z :: Int
z = y
evaluating z will result in a runtime TypeError.
The flag fdefertypeerrors works in GHCi as well, with one exception: for “naked” expressions typed at the prompt, type errors don’t get delayed, so for example:
Prelude> fst (True, 1 == 'a')
<interactive>:2:12:
No instance for (Num Char) arising from the literal `1'
Possible fix: add an instance declaration for (Num Char)
In the first argument of `(==)', namely `1'
In the expression: 1 == 'a'
In the first argument of `fst', namely `(True, 1 == 'a')'
Otherwise, in the common case of a simple type error such as typing reverse True at the prompt, you would get a warning and then an immediatelyfollowing type error when the expression is evaluated.
This exception doesn’t apply to statements, as the following example demonstrates:
Prelude> let x = (True, 1 == 'a')
<interactive>:3:16: Warning:
No instance for (Num Char) arising from the literal `1'
Possible fix: add an instance declaration for (Num Char)
In the first argument of `(==)', namely `1'
In the expression: 1 == 'a'
In the expression: (True, 1 == 'a')
Prelude> fst x
True
Template Haskell allows you to do compiletime metaprogramming in Haskell. The background to the main technical innovations is discussed in “Template Metaprogramming for Haskell” (Proc Haskell Workshop 2002).
There is a Wiki page about Template Haskell at http://www.haskell.org/haskellwiki/Template_Haskell, and that is the best place to look for further details. You may also consult the online Haskell library reference material (look for module Language.Haskell.TH). Many changes to the original design are described in Notes on Template Haskell version 2. Not all of these changes are in GHC, however.
The first example from that paper is set out below (A Template Haskell Worked Example) as a worked example to help get you started.
The documentation here describes the realisation of Template Haskell in GHC. It is not detailed enough to understand Template Haskell; see the Wiki page.
Implies:  XTemplateHaskellQuotes 

Enable Template Haskell’s splice and quotation syntax.
Since:  8.0.1 

Enable only Template Haskell’s quotation syntax.
Template Haskell has the following new syntactic constructions. You need to use the flag XTemplateHaskell to switch these syntactic extensions on. Alternatively, the XTemplateHaskellQuotes flag can be used to enable the quotation subset of Template Haskell (i.e. without splice syntax). The XTemplateHaskellQuotes extension is considered safe under Safe Haskell while XTemplateHaskell is not.
A splice is written $x, where x is an identifier, or $(...), where the ”...” is an arbitrary expression. There must be no space between the “$” and the identifier or parenthesis. This use of “$” overrides its meaning as an infix operator, just as “M.x” overrides the meaning of ”.” as an infix operator. If you want the infix operator, put spaces around it.
A splice can occur in place of
Inside a splice you can only call functions defined in imported modules, not functions defined elsewhere in the same module. Note that declaration splices are not allowed anywhere except at top level (outside any other declarations).
A expression quotation is written in Oxford brackets, thus:
See Where can they occur? for using partial type signatures in quotations.
A typed expression splice is written $$x, where x is an identifier, or $$(...), where the ”...” is an arbitrary expression.
A typed expression splice can occur in place of an expression; the spliced expression must have type Q (TExp a)
A typed expression quotation is written as [ ... ], or [e ... ], where the ”...” is an expression; if the ”...” expression has type a, then the quotation has type Q (TExp a).
Values of type TExp a may be converted to values of type Exp using the function unType :: TExp a > Exp.
A quasiquotation can appear in a pattern, type, expression, or declaration context and is also written in Oxford brackets:
A name can be quoted with either one or two prefix single quotes:
'f has type Name, and names the function f. Similarly 'C has type Name and names the data constructor C. In general '⟨thing⟩ interprets ⟨thing⟩ in an expression context.
A name whose second character is a single quote (sadly) cannot be quoted in this way, because it will be parsed instead as a quoted character. For example, if the function is called f'7 (which is a legal Haskell identifier), an attempt to quote it as 'f'7 would be parsed as the character literal 'f' followed by the numeric literal 7. There is no current escape mechanism in this (unusual) situation.
''T has type Name, and names the type constructor T. That is, ''⟨thing⟩ interprets ⟨thing⟩ in a type context.
These Names can be used to construct Template Haskell expressions, patterns, declarations etc. They may also be given as an argument to the reify function.
It is possible for a splice to expand to an expression that contain names which are not in scope at the site of the splice. As an example, consider the following code:
module Bar where
import Language.Haskell.TH
add1 :: Int > Q Exp
add1 x = [ x + 1 ]
Now consider a splice using <literal>add1</literal> in a separate module:
module Foo where
import Bar
two :: Int
two = $(add1 1)
Template Haskell cannot know what the argument to add1 will be at the function’s definition site, so a lifting mechanism is used to promote x into a value of type Q Exp. This functionality is exposed to the user as the Lift typeclass in the Language.Haskell.TH.Syntax module. If a type has a Lift instance, then any of its values can be lifted to a Template Haskell expression:
class Lift t where
lift :: t > Q Exp
In general, if GHC sees an expression within Oxford brackets (e.g., [ foo bar ], then GHC looks up each name within the brackets. If a name is global (e.g., suppose foo comes from an import or a toplevel declaration), then the fully qualified name is used directly in the quotation. If the name is local (e.g., suppose bar is bound locally in the function definition mkFoo bar = [ foo bar ]), then GHC uses lift on it (so GHC pretends [ foo bar ] actually contains [ foo $(lift bar) ]). Local names, which are not in scope at splice locations, are actually evaluated when the quotation is processed.
The templatehaskell library provides Lift instances for many common data types. Furthermore, it is possible to derive Lift instances automatically by using the XDeriveLift language extension. See Deriving Lift instances for more information.
You may omit the $(...) in a toplevel declaration splice. Simply writing an expression (rather than a declaration) implies a splice. For example, you can write
module Foo where
import Bar
f x = x
$(deriveStuff 'f)  Uses the $(...) notation
g y = y+1
deriveStuff 'g  Omits the $(...)
h z = z1
This abbreviation makes toplevel declaration slices quieter and less intimidating.
Pattern splices introduce variable binders but scoping of variables in expressions inside the pattern’s scope is only checked when a splice is run. Note that pattern splices that occur outside of any quotation brackets are run at compile time. Pattern splices occurring inside a quotation bracket are not run at compile time; they are run when the bracket is spliced in, sometime later. For example,
mkPat :: Q Pat
mkPat = [p (x, y) ]
 in another module:
foo :: (Char, String) > String
foo $(mkPat) = x : z
bar :: Q Exp
bar = [ \ $(mkPat) > x : w ]
will fail with z being out of scope in the definition of foo but it will not fail with w being out of scope in the definition of bar. That will only happen when bar is spliced.
A pattern quasiquoter may generate binders that scope over the righthand side of a definition because these binders are in scope lexically. For example, given a quasiquoter haskell that parses Haskell, in the following code, the y in the righthand side of f refers to the y bound by the haskell pattern quasiquoter, not the toplevel y = 7.
y :: Int
y = 7
f :: Int > Int > Int
f n = \ [haskelly] > y+n
Toplevel declaration splices break up a source file into declaration groups. A declaration group is the group of declarations created by a toplevel declaration splice, plus those following it, down to but not including the next toplevel declaration splice. N.B. only toplevel splices delimit declaration groups, not expression splices. The first declaration group in a module includes all toplevel definitions down to but not including the first toplevel declaration splice.
Each declaration group is mutually recursive only within the group. Declaration groups can refer to definitions within previous groups, but not later ones.
Accordingly, the type environment seen by reify includes all the toplevel declarations up to the end of the immediately preceding declaration group, but no more.
Unlike normal declaration splices, declaration quasiquoters do not cause a break. These quasiquoters are expanded before the rest of the declaration group is processed, and the declarations they generate are merged into the surrounding declaration group. Consequently, the type environment seen by reify from a declaration quasiquoter will not include anything from the quasiquoter’s declaration group.
Concretely, consider the following code
module M where
import ...
f x = x
$(th1 4)
h y = k y y $(blah1)
[qqblah]
k x y z = x + y + z
$(th2 10)
w z = $(blah2)
In this example, a reify inside...
Note that since an expression splice is unable to refer to declarations in the same declaration group, we can introduce a toplevel (empty) splice to break up the declaration group
module M where
data D = C1  C2
f1 = $(th1 ...)
$(return [])
f2 = $(th2 ...)
Here
Expression quotations accept most Haskell language constructs. However, there are some GHCspecific extensions which expression quotations currently do not support, including
(Compared to the original paper, there are many differences of detail. The syntax for a declaration splice uses “$” not “