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 non-portable code at a more primitive level. You need not be “stuck” on performance because of the implementation costs of Haskell’s “high-level” features—you can always code “under” them. In an extreme case, you can write all your time-critical 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.

# 10.1. Language options¶

The language option flags control what variation of the language are permitted.

Language options can be controlled in two ways:

• Every language option can switched on by a command-line flag “-X...” (e.g. -XTemplateHaskell), and switched off by the flag “-XNo...”; (e.g. -XNoTemplateHaskell).
• Language options recognised by Cabal can also be enabled using the LANGUAGE pragma, thus {-# LANGUAGE TemplateHaskell #-} (see LANGUAGE pragma).

Although not recommended, the deprecated -fglasgow-exts flag enables a large swath of the extensions supported by GHC at once.

-fglasgow-exts

The flag -fglasgow-exts is equivalent to enabling the following extensions:

 -XConstrainedClassMethods -XDeriveDataTypeable -XDeriveFoldable -XDeriveFunctor -XDeriveGeneric -XDeriveTraversable -XEmptyDataDecls -XExistentialQuantification -XExplicitNamespaces -XFlexibleContexts -XFlexibleInstances -XForeignFunctionInterface -XFunctionalDependencies -XGeneralizedNewtypeDeriving -XImplicitParams -XKindSignatures -XLiberalTypeSynonyms -XMagicHash -XMultiParamTypeClasses -XParallelListComp -XPatternGuards -XPostfixOperators -XRankNTypes -XRecursiveDo -XScopedTypeVariables -XStandaloneDeriving -XTypeOperators -XTypeSynonymInstances -XUnboxedTuples -XUnicodeSyntax -XUnliftedFFITypes

Enabling these options is the only effect of -fglasgow-exts. We are trying to move away from this portmanteau flag, and towards enabling features individually.

# 10.2. Unboxed types and primitive operations¶

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 higher-level 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.

## 10.2.1. Unboxed types¶

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 two-word 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 machine-addition 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 bit-pattern, such as Int#, Float#, Double#. But this is not necessarily the case: a primitive value might be represented by a pointer to a heap-allocated object. Examples include Array#, the type of primitive arrays. Thus, Array# is an unlifted, boxed type. A primitive array is heap-allocated 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 numerically-intensive program using unboxed types can go a lot faster than its “standard” counterpart—we saw a threefold speedup on one example.

## 10.2.2. Unboxed type kinds¶

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 double-precision floating point. In contrast, 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 top-level binding.

• You cannot bind a variable with an unboxed type in a recursive binding.

• You may bind unboxed variables in a (non-recursive, non-top-level) pattern binding, but you must make any such pattern-match strict. (Failing to do so emits a warning -Wunbanged-strict-patterns.) 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#.

## 10.2.3. Unboxed tuples¶

-XUnboxedTuples

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 non-primitive). 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 fully-fledged 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:

• 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, y-1 #)
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.

## 10.2.4. Unboxed sums¶

-XUnboxedSums

Enable the use of unboxed sum syntax.

-XUnboxedSums enables new syntax for anonymous, unboxed sum types. The syntax for an unboxed sum type with N alternatives is

(# t_1 | t_2 | ... | t_N #)


where t_1 ... t_N are types (which can be unlifted, including unboxed tuple and sums).

Unboxed tuples can be used for multi-arity alternatives. For example:

(# (# Int, String #) | Bool #)


Term level syntax is similar. Leading and preceding bars (|) indicate which alternative it is. Here is two terms of the type shown above:

(# (# 1, "foo" #) | #) -- first alternative

(# | True #) -- second alternative


Pattern syntax reflects the term syntax:

case x of
(# (# i, str #) | #) -> ...
(# | bool #) -> ...


Unboxed sums are “unboxed” in the sense that, instead of allocating sums in the heap and representing values as pointers, unboxed sums are represented as their components, just like unboxed tuples. These “components” depend on alternatives of a sum type. Code generator tries to generate as compact layout as possible. In the best case, size of an unboxed sum is size of its biggest alternative + one word (for tag). The algorithm for generating memory layout for a sum type works like this:

• All types are classified as one of these classes: 32bit word, 64bit word, 32bit float, 64bit float, pointer.

• For each alternative of the sum type, a layout that consists of these fields is generated. For example, if an alternative has Int, Float# and String fields, the layout will have an 32bit word, 32bit float and pointer fields.

• Layout fields are then overlapped so that the final layout will be as compact as possible. E.g. say two alternatives have these fields:

Word32, String, Float#
Float#, Float#, Maybe Int


Final layout will be something like

Int32, Float32, Float32, Word32, Pointer


First Int32 is for the tag. It has two Float32 fields because floating point types can’t overlap with other types, because of limitations of the code generator that we’re hoping to overcome in the future, and second alternative needs two Float32 fields. Word32 field is for the Word32 in the first alternative. Pointer field is shared between String and Maybe Int values of the alternatives.

In the case of enumeration types (like Bool), the unboxed sum layout only has an Int32 field (i.e. the whole thing is represented by an integer).

In the example above, a value of this type is thus represented as 5 values. As an another example, this is the layout for unboxed version of Maybe a type:

Int32, Pointer


The Pointer field is not used when tag says that it’s Nothing. Otherwise Pointer points to the value in Just.

# 10.3. Syntactic extensions¶

## 10.3.1. Unicode syntax¶

-XUnicodeSyntax

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 ARROW-TAIL
-< 0x2919 LEFTWARDS ARROW-TAIL
>>- 0x291C RIGHTWARDS DOUBLE ARROW-TAIL
-<< 0x291B LEFTWARDS DOUBLE ARROW-TAIL
* 0x2605 BLACK STAR
forall 0x2200 FOR ALL
(| 0x2987 Z NOTATION LEFT IMAGE BRACKET
|) 0x2988 Z NOTATION RIGHT IMAGE BRACKET
[| 0x27E6 MATHEMATICAL LEFT WHITE SQUARE BRACKET
|] 0x27E7 MATHEMATICAL RIGHT WHITE SQUARE BRACKET

## 10.3.2. The magic hash¶

-XMagicHash

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

• 'x'# has type Char#
• 3# has type Int#. In general, any Haskell integer lexeme followed by a # is an Int# literal, e.g. -0x3A# as well as 32#.
• 3## has type Word#. In general, any non-negative Haskell integer lexeme followed by ## is a Word#.
• 3.2# has type Float#.
• 3.2## has type Double#

## 10.3.3. Negative literals¶

-XNegativeLiterals
Since: 7.8.1

Enable the use of un-parenthesized 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 8-bit arithmetic -128 is representable, but +128 is not. So negate (fromInteger 128) will elicit an unexpected integer-literal-overflow message.

## 10.3.4. Fractional looking integer literals¶

-XNumDecimals
Since: 7.8.1

Allow the use of floating-point 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)

## 10.3.5. Binary integer literals¶

-XBinaryLiterals
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.

## 10.3.6. Pattern guards¶

-XNoPatternGuards

Disable pattern guards.

## 10.3.7. View patterns¶

-XViewPatterns

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 pattern-matching 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., hash-consing 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 self-contained. 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 alpha-equivalence, so two instances of (x, view x -> y) will not be coalesced.

## 10.3.8. n+k patterns¶

-XNPlusKPatterns

Enable use of n+k patterns.

## 10.3.9. The recursive do-notation¶

-XRecursiveDo

Allow the use of recursive do notation.

The do-notation of Haskell 98 does not allow recursive bindings, that is, the variables bound in a do-expression are visible only in the textually following code block. Compare this to a let-expression, 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 fixed-point 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 do-notation 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 let-expression. Due to the new keyword mdo, we also call this notation the mdo-notation.

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 mdo-notation 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.

### 10.3.9.1. Recursive binding groups¶

The flag -XRecursiveDo also introduces a new keyword rec, which wraps a mutually-recursive 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 non-monadic, 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 value-recursion 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 meta-variables 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.

### 10.3.9.2. The mdo notation¶

A rec-block 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 so-called right-shrinking 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:

• A generator ⟨g⟩ depends on a textually following generator ⟨g’⟩, if
• ⟨g’⟩ defines a variable that is used by ⟨g⟩, or
• ⟨g’⟩ textually appears between ⟨g⟩ and ⟨g’‘⟩, where ⟨g⟩ depends on ⟨g’‘⟩.
• A segment of a given mdo-expression is a minimal sequence of generators such that no generator of the sequence depends on an outside generator. As a special case, although it is not a generator, the final expression in an mdo-expression is considered to form a segment by itself.

Segments in this sense are related to strongly-connected components analysis, with the exception that bindings in a segment cannot be reordered and must be contiguous.

Here is an example mdo-expression, 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 mdo-expression typechecks exactly when the desugared version would do so.

Here are some other important points in using the recursive-do notation:

• It is enabled with the flag -XRecursiveDo, or the LANGUAGE RecursiveDo pragma. (The same flag enables both mdo-notation, and the use of rec blocks inside do expressions.)
• rec blocks can also be used inside mdo-expressions, which will be treated as a single statement. However, it is good style to either use mdo or rec blocks in a single expression.
• If recursive bindings are required for a monad, then that monad must be declared an instance of the MonadFix class.
• The following instances of MonadFix are automatically provided: List, Maybe, IO. Furthermore, the Control.Monad.ST and Control.Monad.ST.Lazy modules provide the instances of the MonadFix class for Haskell’s internal state monad (strict and lazy, respectively).
• Like let and where bindings, name shadowing is not allowed within an mdo-expression or a rec-block; that is, all the names bound in a single rec must be distinct. (GHC will complain if this is not the case.)

## 10.3.10. Applicative do-notation¶

-XApplicativeDo
Since: 8.0.1

Allow use of Applicative do notation.

The language option -XApplicativeDo enables an alternative translation for the do-notation, which uses the operators <$>, <*>, along with join as far as possible. There are two main reasons for wanting to do this: • We can use do-notation with types that are an instance of Applicative and Functor, but not Monad • In some monads, using the applicative operators is more efficient than monadic bind. For example, it may enable more parallelism. Applicative do-notation 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 -ddump-ds, 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 do-block:

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 do-expression 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:

• return E
• return $E • pure E • pure$ E

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:

-foptimal-applicative-do
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).

### 10.3.10.1. Existential patterns and GADTs¶

Note that when the pattern in a statement matches a constructor with existential type variables and/or constraints, the transformation that ApplicativeDo performs may mean that the pattern does not scope over the statements that follow it. This is because the rearrangement happens before the expression is typechecked. For example, this program does not typecheck:

{-# LANGUAGE RankNTypes, GADTs, ApplicativeDo #-}

data T where A :: forall a . Eq a => a -> T

test = do
A x <- undefined
_ <- return True
return (x == x)


The reason is that the Eq constraint that would be brought into scope from the pattern match A x is not available when typechecking the expression x == x, because ApplicativeDo has rearranged the expression to look like this:

test =
(\x _ -> x == x)
<$> do A x <- undefined; return x <*> return True  Turning off ApplicativeDo lets the program typecheck. This is something to bear in mind when using ApplicativeDo in combination with Existentially quantified data constructors or Generalised Algebraic Data Types (GADTs). ### 10.3.10.2. Things to watch out for¶ 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 do-notation, 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 do-notation, you shouldn’t define Functor or Applicative instance using do-notation (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  ## 10.3.11. Parallel List Comprehensions¶ -XParallelListComp 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. ## 10.3.12. Generalised (SQL-like) List Comprehensions¶ -XTransformListComp Allow use of generalised list (SQL-like) 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 grouping-type 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 non-grouping 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",...]  ## 10.3.13. Monad comprehensions¶ -XMonadComprehensions  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 (SQL-like) 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 do-notation: 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 (SQL-like) 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 built-in, 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 (SQL-like) 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. ## 10.3.14. New monadic failure desugaring mechanism¶ -XMonadFailDesugaring 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 do-blocks 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. ## 10.3.15. Rebindable syntax and the implicit Prelude import¶ -XNoImplicitPrelude 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.) -XRebindableSyntax Implies: -XNoImplicitPrelude 7.0.1 Enable rebinding of a variety of usually-built-in 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 built-in syntax to refer to whatever is in scope, not the Prelude versions: • An integer literal 368 means “fromInteger (368::Integer)”, rather than “Prelude.fromInteger (368::Integer)”. • Fractional literals are handed in just the same way, except that the translation is fromRational (3.68::Rational). • The equality test in an overloaded numeric pattern uses whatever (==) is in scope. • The subtraction operation, and the greater-than-or-equal test, in n+k patterns use whatever (-) and (>=) are in scope. • Negation (e.g. “- (f x)”) means “negate (f x)”, both in numeric patterns, and expressions. • Conditionals (e.g. “if e1 then e2 else e3”) means “ifThenElse e1 e2 e3”. However case expressions are unaffected. • “Do” notation is translated using whatever functions (>>=), (>>), and fail, are in scope (not the Prelude versions). List comprehensions, mdo (The recursive do-notation), and parallel array comprehensions, are unaffected. • Arrow notation (see Arrow notation) uses whatever arr, (>>>), first, app, (|||) and loop functions are in scope. But unlike the other constructs, the types of these functions must match the Prelude types very closely. Details are in flux; if you want to use this, ask! • List notation, such as [x,y] or [m..n] can also be treated via rebindable syntax if you use -XOverloadedLists; see Overloaded lists. • An overloaded label “#foo” means “fromLabel @"foo"”, rather than “GHC.OverloadedLabels.fromLabel @"foo"” (see Overloaded labels). 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 -dcore-lint to typecheck the desugared program. If Core Lint is happy you should be all right. ### 10.3.15.1. Things unaffected by -XRebindableSyntax¶ -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. ## 10.3.16. Postfix operators¶ -XPostfixOperators Allow the use of post-fix 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 left-hand side of function definitions; you must define such a function in prefix form. ## 10.3.17. Tuple sections¶ -XTupleSections  Since: 6.12 Allow the use of tuple section syntax The -XTupleSections flag enables 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. ## 10.3.18. Lambda-case¶ -XLambdaCase Since: 7.6.1 Allow the use of lambda-case 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  ## 10.3.19. Empty case alternatives¶ -XEmptyCase Since: 7.8.1 Allow empty case expressions. The -XEmptyCase flag enables case expressions, or lambda-case 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 non-bottom values. For example: data Void f :: Void -> Int f x = case x of { }  With dependently-typed 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 -Wincomplete-patterns. (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. ## 10.3.20. Multi-way if-expressions¶ -XMultiWayIf Since: 7.6.1 Allow the use of multi-way-if 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  Multi-way 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 multi-way if works in the same way as other layout contexts, except that the semi-colons between guards in a multi-way 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. ## 10.3.21. Local Fixity Declarations¶ 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 right-hand sides of other let-bindings and the body of the letC. Or, in recursive do expressions (The recursive do-notation), 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.

## 10.3.22. Import and export extensions¶

### 10.3.22.1. Hiding things the imported module doesn’t export¶

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 -Wdodgy-imports, which is off by default but included with -W, warns if you hide something that the imported module does not export.

### 10.3.22.2. Package-qualified imports¶

-XPackageImports

Allow the use of package-qualified 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 backwards-compatible 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 package-qualified imports broken. See also Thinning and renaming modules for an alternative way of disambiguating between module names.

### 10.3.22.3. Safe imports¶

-XSafe
-XTrustworthy
-XUnsafe
 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.

### 10.3.22.4. Explicit namespaces in import/export¶

-XExplicitNamespaces
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).

## 10.3.23. Summary of stolen syntax¶

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 context-free 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:

• New reserved words and symbols: character sequences which are no longer available for use as identifiers in the program.
• Other special syntax: sequences of characters that have a different meaning when this particular option is turned on.

The following syntax is stolen:

forall

Stolen (in types) by: -XExplicitForAll, and hence by -XScopedTypeVariables, -XLiberalTypeSynonyms, -XRankNTypes, -XExistentialQuantification

mdo

Stolen by: -XRecursiveDo

foreign

Stolen by: -XForeignFunctionInterface

rec, proc, -<, >-, -<<, >>-, (|, |)

Stolen by: -XArrows

?varid

Stolen by: -XImplicitParams

[|, [e|, [p|, [d|, [t|, [||, [e||

Stolen by: -XQuasiQuotes. Moreover, this introduces an ambiguity with list comprehension syntax. See the discussion on quasi-quoting for details.

print $greet "fool"  Note that deriving Eq is necessary for the pattern matching to work since it gets translated into an equality comparison. ## 10.8.5. Overloaded labels¶ -XOverloadedLabels 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 :: 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 type-level string (see Type-Level Literals). Note that fromLabel had an extra Proxy# x argument in GHC 8.0, but this was removed in GHC 8.2 as a type application (see Visible type application) can be used instead. 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 @"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. If -XRebindableSyntax is enabled, overloaded labels will be desugared using whatever fromLabel function is in scope, rather than always using GHC.OverloadedLabels.fromLabel. When writing an overloaded label, there must be no space between the hash sign and the following identifier. The -XMagicHash extension makes use of postfix hash signs; if -XOverloadedLabels and -XMagicHash are both enabled then x#y means x# y, but if only -XOverloadedLabels is enabled then it means x #y. The -XUnboxedTuples extension makes (# a single lexeme, so when -XUnboxedTuples is enabled you must write a space between an opening parenthesis and an overloaded label. To avoid confusion, you are strongly encouraged to put a space before the hash when using -XOverloadedLabels. When using -XOverloadedLabels (or other extensions that make use of hash signs) 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 Type-Level 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)  ## 10.8.6. Overloaded lists¶ -XOverloadedLists 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 view-pattern syntax for the translation, see View patterns.) ### 10.8.6.1. The IsList class¶ 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. • The type function Item returns the type of items of the structure l. • The function fromList constructs the structure l from the given list of Item l. • The function fromListN takes the input list’s length as a hint. Its behaviour should be equivalent to fromList. The hint can be used for more efficient construction of the structure l compared to fromList. If the given hint is not equal to the input list’s length the behaviour of fromListN is not specified. • The function toList should be the inverse of fromList. 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  ### 10.8.6.2. Rebindable syntax¶ 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. ### 10.8.6.3. Defaulting¶ 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])  ### 10.8.6.4. Speculation about the future¶ 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). ## 10.8.7. Undecidable (or recursive) superclasses¶ -XUndecidableSuperClasses Since: 8.0.1 Allow all superclass constraints, including those that may result in non-termination 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 genuninely-recursive superclasses are sometimes useful. Here’s a real-life 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. # 10.9. Type families¶ -XTypeFamilies Allow use and definition of indexed type and data families. Indexed type families form an extension to facilitate type-level 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 type-indexed 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 type-level 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 (ad-hoc 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 SIGPLAN-SIGACT Symposium on Principles of Programming Languages (POPL‘05)”, pages 1-13, 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 241-253, 2005).  [TypeFamilies2008] “Type Checking with Open Type Functions”, T. Schrijvers, S. Peyton-Jones, M. Chakravarty, and M. Sulzmann, in Proceedings of “ICFP 2008: The 13th ACM SIGPLAN International Conference on Functional Programming”, ACM Press, pages 51-62, 2008. ## 10.9.1. Data families¶ 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 type-indexes 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. ### 10.9.1.1. Data family declarations¶ 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 :: * -> *  ### 10.9.1.2. Data instance declarations¶ 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 non-variable 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 -Wunused-type-patterns 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. ### 10.9.1.3. Overlap of data instances¶ 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. ## 10.9.2. Synonym families¶ 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 type-indexes 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. ### 10.9.2.1. Type family declarations¶ 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 well-formed 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. ### 10.9.2.2. Type instance declarations¶ 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 non-variable 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 -Wunused-type-patterns 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 right-hand 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. ### 10.9.2.3. Closed type families¶ 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 type-level 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 hs-boot file, which uses the syntax where .., as in that case there may or may not be equations given in the hs file. ### 10.9.2.4. Type family examples¶ 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: right-hand 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  ### 10.9.2.5. Compatibility and apartness of type family equations¶ 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 1. all corresponding types and implicit kinds in the patterns are apart, or 2. the two patterns unify producing a substitution, and the right-hand sides are equal under that substitution. 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 right-hand 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 right-hand 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. ### 10.9.2.6. Decidability of type synonym instances¶ -XUndecidableInstances 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, 1. s1 .. sm do not contain any type family constructors, 2. the total number of symbols (data type constructors and type variables) in s1 .. sm is strictly smaller than in t1 .. tn, and 3. for every type variable a, a occurs in s1 .. sm at most as often as in t1 .. tn. 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. ## 10.9.3. Wildcards on the LHS of data and type family instances¶ 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). ## 10.9.4. Associated data and type families¶ 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. ### 10.9.4.1. Associated instances¶ 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 ...  The data or type family instance for an assocated type must follow the rule that the type indexes corresponding to class parameters must have precisely the same as type given in the instance head. For example: class Collects ce where type Elem ce :: * instance Eq (Elem [e]) => Collects [e] where -- Choose one of the following alternatives: type Elem [e] = e -- OK type Elem [x] = x -- BAD; '[x]' is differnet to '[e]' from head type Elem x = x -- BAD; 'x' is different to '[e]' type Elem [Maybe x] = x -- BAD: '[Maybe x]' is different to '[e]'  Note the following points: • An instance 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 variables on the right hand side of the type family equation must, as usual, be bound on the left hand side. • 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 *). ### 10.9.4.2. Associated type synonym defaults¶ 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: • The instance keyword is optional. • There can be at most one default declaration for an associated type synonym. • A default declaration is not permitted for an associated data type. • The default declaration must mention only type variables on the left hand side, and the right hand side must mention only type variables bound on the left hand side. However, unlike the associated type family declaration itself, the type variables of the default instance are independent of those of the parent class. 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  ### 10.9.4.3. Scoping of class parameters¶ The visibility of class parameters in the right-hand 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 right-hand side of the data instance mentions the type variable d that does not occur in its left-hand side. We cannot admit such data instances as they would compromise type safety. ### 10.9.4.4. Instance contexts and associated type and data instances¶ 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 non-trivial context on a derived instance, use a standalone deriving clause (at the top level). ## 10.9.5. Import and export¶ The rules for export lists (Haskell Report Section 5.2) needs adjustment for type families: • The form T(..), where T is a data family, names the family T and all the in-scope constructors (whether in scope qualified or unqualified) that are data instances of T. • The form T(.., ci, .., fj, ..), where T is a data family, names T and the specified constructors ci and fields fj as usual. The constructors and field names must belong to some data instance of T, but are not required to belong to the same instance. • The form C(..), where C is a class, names the class C and all its methods and associated types. • The form C(.., mi, .., type Tj, ..), where C is a class, names the class C, and the specified methods mi and associated types Tj. The types need a keyword “type” to distinguish them from data constructors. • Whenever there is no export list and a data instance is defined, the corresponding data family type constructor is exported along with the new data constructors, regardless of whether the data family is defined locally or in another module. ### 10.9.5.1. Examples¶ 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., sub-component 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 ...  ### 10.9.5.2. Instances¶ 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. ## 10.9.6. Type families and instance declarations¶ 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: • Data type families may appear in an instance head • Type synonym families may not appear (at all) in an instance head 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 ...  ## 10.9.7. Injective type families¶ -XTypeFamilyDependencies Implies: -XTypeFamilies 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. ### 10.9.7.1. Syntax of injectivity annotation¶ Injectivity annotation is added after type family head and consists of two parts: • a type variable that names the result of a type family. Syntax: = tyvar or = (tyvar :: kind). Type variable must be fresh. • an injectivity annotation of the form | A -> B, where A is the result type variable (see previous bullet) and B is a list of argument type and kind variables in which type family is injective. It is possible to omit some variables if type family is not injective in them. 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. ### 10.9.7.2. Verifying injectivity annotation against type family equations¶ 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 right-hand 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: 1. If a RHS of a type family equation is a type family application GHC reports that the type family is not injective. 2. 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. 3. 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. 4. 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. 5. In a closed type family all equations are ordered and in one place. Equations are also checked pair-wise but this time an equation has to be paired with all the preceeding equations. Of course a single-equation 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. # 10.10. Datatype promotion¶ -XDataKinds 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. ## 10.10.1. Motivation¶ 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 type-level natural numbers, and length-indexed 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 well-kinded type, even though this is not what we intend when defining length-indexed 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 ill-kinded, and GHC will report an error. ## 10.10.2. Overview¶ 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: • We promote data types and newtypes; type synonyms and type/data families are not promoted (Type families). • We only promote types whose kinds are of the form * -> ... -> * -> *. In particular, we do not promote higher-kinded datatypes such as data Fix f = In (f (Fix f)), or datatypes whose kinds involve promoted types such as Vec :: * -> Nat -> *. • We do not promote data constructors that are kind polymorphic, involve constraints, mention type or data families, or involve types that are not promotable. 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))  ## 10.10.3. Distinguishing between types and constructors¶ 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 error-prone. GHC thus supports -Wunticked-promoted-constructors 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'  ## 10.10.5. Promoting existential data constructors¶ 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 type-level existential: type family UnEx (ex :: Ex) :: k type instance UnEx (MkEx x) = x  At first blush, UnEx seems poorly-kinded. 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 kind-indexed 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. # 10.11. Kind polymorphism and Type-in-Type¶ -XTypeInType Implies: -XPolyKinds, -XDataKinds, -XKindSignatures 8.0.1 Allow kinds to be as intricate as types, allowing explicit quantification over kind variables, higher-rank kinds, and the use of type synonyms and families in kinds, among other features. -XPolyKinds Implies: -XKindSignatures 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. ## 10.11.1. The difference between -XTypeInType and -XPolyKinds¶ 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 -dcore-lint 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 newly-available capabilities below. ## 10.11.2. Overview of kind polymorphism¶ 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 (* -> *)  ## 10.11.3. Overview of Type-in-Type¶ 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 non-termination, but this is not a problem in GHC, as we already have other means of non-terminating 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. ## 10.11.4. Principles of kind inference¶ Generally speaking, when -XPolyKinds is on, GHC tries to infer the most general kind for a declaration. In this case the definition has a right-hand side to inform kind inference. But that is not always the case. Consider type family F a  Type family declarations have no right-hand 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 entirely-unconstrained kind variables to * and we get F :: * -> *. You can still declare F to be kind-polymorphic 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: • When there is a right-hand side, GHC infers the most polymorphic kind consistent with the right-hand side. Examples: ordinary data type and GADT declarations, class declarations. In the case of a class declaration the role of “right hand side” is played by the class method signatures. • When there is no right hand side, GHC defaults argument and result kinds to *, except when directed otherwise by a kind signature. Examples: data and open type family declarations. This rule has occasionally-surprising 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 right-hand side so D2 :: * -> * type F2 a -- No right-hand side so F2 :: * -> *  The kind-polymorphism from the class declaration makes D1 kind-polymorphic, but not so D2; and similarly F1, F1. ## 10.11.5. Complete user-supplied kind signatures and polymorphic recursion¶ 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 user-supplied 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 user-supplied 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 user-supplied kind signature” for a type constructor? These are the forms: • For a datatype, every type variable must be annotated with a kind. In a GADT-style declaration, there may also be a kind signature (with a top-level :: 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 top-level :: 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 right-hand 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 un-associated open type or data family declaration always has a CUSK; un-annotated 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 top-level ::) 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. ## 10.11.6. Kind inference in closed type families¶ Although all open type families are considered to have a complete user-supplied 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 kind-indexed type families, where the family matches both on the kind and type. GHC will not infer this behaviour without a complete user-supplied kind signature, as doing so would sometimes infer non-principal types. Indeed, we can see kind-indexing 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: kind-indexing 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  ## 10.11.7. Kind inference in class instance declarations¶ Consider the following example of a poly-kinded 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 poly-kinded type variable (a :: k). Yet, in the instance declaration, the right-hand 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. ## 10.11.8. Kind inference in type signatures¶ When kind-checking 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. ## 10.11.9. Explicit kind quantification¶ 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 well-scoped: 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 higher-rank 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 non-top-level 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 higher-rank forall, include it explicitly. ## 10.11.10. Kind-indexed GADTs¶ Consider the type data G (a :: k) where GInt :: G Int GMaybe :: G Maybe  This datatype G is GADT-like 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 pattern-matching 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 kind-indexed GADTs use a form of polymorphic recursion. It is thus only possible to use this feature if you have provided a complete user-supplied kind signature for the datatype (Complete user-supplied kind signatures and polymorphic recursion). ## 10.11.11. Constraints in kinds¶ 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. ## 10.11.12. The kind *¶ 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 parsed–and the fact that it is the only such operator in GHC–there are some corner cases that are not handled. We are aware of three: • In a Haskell-98-style 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 term-level (*). (Explicit namespaces in import/export) • In an instance declaration head (the part after the word instance), you must parenthesize *. This applies to all manners of instances, including the left-hand sides of individual equations of a closed type family. 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 *. ## 10.11.13. Inferring dependency in datatype declarations¶ 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: • a must appear after k in the declaration, and • k must appear explicitly in the kind of some type variable in that declaration. The first bullet simply means that the dependency must be well-scoped. 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. ## 10.11.14. Kind defaulting without -XPolyKinds¶ 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 ill-kinded if defaulted. The definition for z is thus an error. ## 10.11.15. Pretty-printing in the presence of kind polymorphism¶ 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 pretty-printing 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 -fprint-explicit-kinds. # 10.12. Levity polymorphism¶ 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 so-called levity polymorphism. Here are the key definitions, all available from GHC.Exts: TYPE :: RuntimeRep -> * -- highly magical, built into GHC data RuntimeRep = LiftedRep -- for things like Int | UnliftedRep -- for things like Array# | IntRep -- for Int# | TupleRep [RuntimeRep] -- unboxed tuples, indexed by the representations of the elements | SumRep [RuntimeRep] -- unboxed sums, indexed by the representations of the disjuncts | ... type * = TYPE LiftedRep -- * 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 'LiftedRep. 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 'LiftedRep. The result is always lifted because all functions are lifted in GHC. ## 10.12.1. No levity-polymorphic variables or arguments¶ 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 (floating-point or integral) should x go in? It’s all impossible to say, because x‘s type, a :: TYPE r1 is levity polymorphic. We thus forbid such constructions, via the following straightforward rule:

No variable may have a levity-polymorphic type.

This eliminates bad because the variable x would have a representation-polymorphic 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 levity polymorphic. There are no variables with a levity-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. Because the code generator must store and move arguments as well as variables, the logic above applies equally well to function arguments, which may not be levity-polymorphic. ## 10.12.2. Levity-polymorphic bottoms¶ We can use levity 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 levity-polymorphic variable, and so are accepted. Their polymorphism allows users to use these to conveniently stub out functions that return unboxed types. ## 10.12.3. Printing levity-polymorphic types¶ -Wprint-explicit-runtime-rep Print RuntimeRep parameters as they appear; otherwise, they are defaulted to 'LiftedRep. Most GHC users will not need to worry about levity polymorphism or unboxed types. For these users, seeing the levity polymorphism in the type of$ is unhelpful. And thus, by default, it is suppressed, by supposing all type variables of type RuntimeRep to be 'LiftedRep when printing, and printing TYPE 'LiftedRep as *.

Should you wish to see levity polymorphism in your types, enable the flag -fprint-explicit-runtime-reps.

# 10.13. Type-Level Literals¶

GHC supports numeric and string literals at the type level, giving convenient access to a large number of predefined type-level 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 low-level operations for this feature are defined in module GHC.TypeLits. Note that the module defines some type-level operators that clash with their value-level 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 type-level numeric literals to provide a safe interface to a low-level 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 type-level 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")


## 10.13.1. Runtime Values for Type-Level Literals¶

Sometimes it is useful to access the value-level literal associated with a type-level 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 type-level 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 run-time integer or string value to the corresponding type-level literal. Of course, the resulting type literal will be unknown at compile-time, 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.

## 10.13.2. Computing With Type-Level Naturals¶

GHC 7.8 can evaluate arithmetic expressions involving type-level natural numbers. Such expressions may be constructed using the type-families (+), (*), (^) 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


# 10.14. Constraints in types¶

## 10.14.1. Equality constraints¶

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 higher-rank 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.

## 10.14.2. Heterogeneous equality¶

GHC also supports kind-heterogeneous 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 -fprint-equality-relations is set.

## 10.14.3. Unlifted heterogeneous equality¶

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 -fprint-equality-relations is enabled.

## 10.14.4. The Coercible constraint¶

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”.

## 10.14.5. The Constraint kind¶

-XConstraintKinds
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.

# 10.15. Extensions to type signatures¶

## 10.15.1. Explicit universal quantification (forall)¶

-XExplicitForAll
 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 -Wunused-foralls 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.

## 10.15.2. The context of a type signature¶

The -XFlexibleContexts flag lifts the Haskell 98 restriction that the type-class constraints in a type signature must have the form (class type-variable) or (class (type-variable 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).

## 10.15.3. Ambiguous types and the ambiguity check¶

-XAllowAmbiguousTypes
Since: 7.8.1

Allow type signatures which appear that they would result in an unusable binding.

Each user-written 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 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.

Another way of getting rid of the ambiguity at the call site is to use the -XTypeApplications flag to specify the types. For example:

class D a b where
h :: b
instance D Int Int where ...

main = print (h @Int @Int)


Here a is ambiguous in the definition of D but later specified to be Int using type applications.

-XAllowAmbiguousTypes allows you to switch off the ambiguity check. However, 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

1. that each universally quantified type variable tvi must be “reachable” from type, and
2. that every constraint ci mentions at least one of the universally quantified type variables tvi. These ad-hoc restrictions are completely subsumed by the new ambiguity check.

## 10.15.4. Explicitly-kinded quantification¶

-XKindSignatures

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 (machine-checked) 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.

# 10.16. Lexically scoped type variables¶

-XScopedTypeVariables
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.

## 10.16.1. Overview¶

The design follows the following principles

• A scoped type variable stands for a type variable, and not for a type. (This is a change from GHC’s earlier design.)
• Furthermore, distinct lexical type variables stand for distinct type variables. This means that every programmer-written type signature (including one that contains free scoped type variables) denotes a rigid type; that is, the type is fully known to the type checker, and no inference is involved.
• Lexical type variables may be alpha-renamed freely, without changing the program.

A lexically scoped type variable can be bound by:

In Haskell, a programmer-written 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)


## 10.16.2. Declaration type signatures¶

A declaration type signature that has explicit quantification (using forall) brings into scope the explicitly-quantified 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.

## 10.16.3. Expression type signatures¶

An expression type signature that has explicit quantification (using forall) brings into scope the explicitly-quantified 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).

## 10.16.4. Pattern type signatures¶

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 existentially-bound 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 fully-known, type variable. This means that any user-written 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 existentially-bound 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.

## 10.16.5. Class and instance declarations¶

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

instance C b => C [b] where
op xs = reverse (head (xs :: [[b]]))


# 10.17. Bindings and generalisation¶

## 10.17.1. Switching off the dreaded Monomorphism Restriction¶

-XNoMonomorphismRestriction
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).

## 10.17.2. Let-generalisation¶

-XMonoLocalBinds
 Since: 6.12

Infer less polymorphic types for local bindings by default.

An ML-style language usually generalises the type of any let-bound or where-bound variable, so that it is as polymorphic as possible. With the flag -XMonoLocalBinds GHC implements a slightly more conservative policy, using the following rules:

• A variable is closed if and only if
• the variable is let-bound
• one of the following holds:
• the variable has an explicit type signature that has no free type variables, or
• its binding group is fully generalised (see next bullet)
• A binding group is fully generalised if and only if
• each of its free variables is either imported or closed, and
• the binding is not affected by the monomorphism restriction (Haskell Report, Section 4.5.5)

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 let-bound).

Notice that a top-level 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!)

## 10.17.3. Kind generalisation¶

Just as -XMonoLocalBinds places limitations on when the type of a term is generalised (see Let-generalisation), it also limits when the kind of a type signature is generalised. Here is an example involving type signatures on instance declarations:

data Proxy a = Proxy
newtype Tagged s b = Tagged b

class C b where
c :: forall (s :: k). Tagged s b

instance C (Proxy a) where
c :: forall s. Tagged s (Proxy a)
c = Tagged Proxy


With -XMonoLocalBinds enabled, this C (Proxy a) instance will fail to typecheck. The reason is that the type signature for c captures a, an outer-scoped type variable, which means the type signature is not closed. Therefore, the inferred kind for s will not be generalised, and as a result, it will fail to unify with the kind variable k which is specified in the declaration of c. This can be worked around by specifying an explicit kind variable for s, e.g.,

instance C (Proxy a) where
c :: forall (s :: k). Tagged s (Proxy a)
c = Tagged Proxy


or, alternatively:

instance C (Proxy a) where
c :: forall k (s :: k). Tagged s (Proxy a)
c = Tagged Proxy


This declarations are equivalent using Haskell’s implicit “add implicit foralls” rules (see Implicit quantification). The implicit foralls rules are purely syntactic and are quite separate from the kind generalisation described here.

# 10.18. Visible type application¶

-XTypeApplications
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 non-identifier 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 left-to-right 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 left-to-right 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 user-specified 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 -fprint-explicit-foralls enabled, type variables not available for visible type application are printed in braces. We can observe this behavior in a GHCi session:

> :set -XTypeApplications -fprint-explicit-foralls
> let myLength1 :: Foldable f => f a -> Int; myLength1 = length
> :type +v myLength1
myLength1 :: forall (f :: * -> *) a. Foldable f => f a -> Int
> let myLength2 = length
> :type +v myLength2
myLength2 :: forall {a} {t :: * -> *}. Foldable t => t a -> Int
> :type +v myLength2 @[]

<interactive>:1:1: error:
• Cannot apply expression of type ‘t0 a0 -> Int’
to a visible type argument ‘[]’
• In the expression: myLength2 @[]


Notice that since myLength1 was defined with an explicit type signature, :type +v reports that all of its type variables are available for type application. On the other hand, myLength2 was not given a type signature. As a result, all of its type variables are surrounded with braces, and trying to use visible type application with myLength2 fails.

Also note the use of :type +v in the GHCi session above instead of :type. This is because :type gives you the type that would be inferred for a variable assigned to the expression provided (that is, the type of x in let x = <expr>). As we saw above with myLength2, this type will have no variables available to visible type application. On the other hand, :type +v gives you the actual type of the expression provided. To illustrate this:

> :type myLength1
myLength1 :: forall {a} {f :: * -> *}. Foldable f => f a -> Int
> :type myLength2
myLength2 :: forall {a} {t :: * -> *}. Foldable t => t a -> Int


Using :type might lead one to conclude that none of the type variables in myLength1‘s type signature are available for type application. This isn’t true, however! Be sure to use :type +v if you want the most accurate information with respect to visible type application properties.

• 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 left-to-right order in the data constructor’s type and doing a stable topological sort.

# 10.19. Implicit parameters¶

-XImplicitParams

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 Hindley-Milner 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 dynamically-bound 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 dynamic-binding 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


## 10.19.1. Implicit-parameter type constraints¶

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 implicit-parameter 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.

Implicit-parameter 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.

## 10.19.2. Implicit-parameter bindings¶

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 implicit-parameter 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 do-notation, or pattern guards), or a where clause. Note the following points:

• An implicit-parameter binding group must be a collection of simple bindings to implicit-style variables (no function-style bindings, and no type signatures); these bindings are neither polymorphic or recursive.

• You may not mix implicit-parameter 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 implicit-parameter 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 non-recursive group, simultaneously binding all the implicit parameter. The bindings are not nested, and may be re-ordered 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


## 10.19.3. Implicit parameters and polymorphic recursion¶

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 right-hand 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 counter-intuitive phenomenon, worth watching out for.

## 10.19.4. Implicit parameters and monomorphism¶

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.

# 10.20. Arbitrary-rank polymorphism¶

-XRankNTypes
Implies: -XExplicitForAll

Allow types of arbitrary rank.

-XRank2Types

A deprecated alias of -XRankNTypes.

GHC’s type system supports arbitrary-rank 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 rank-1 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 rank-2 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 rank-3 type; it has rank-2 types on the left of a function arrow.

The language option -XRankNTypes (which implies -XExplicitForAll) enables higher-rank types. That is, you can nest foralls arbitrarily deep in function arrows. For example, a forall-type (also called a “type scheme”), including a type-class context, is legal:

• On the left or right (see f4, for example) of a function arrow
• As the argument of a constructor, or type of a field, in a data type declaration. For example, any of the f1, f2, f3, g1, g2 above would be valid field type signatures.
• As the type of an implicit parameter
• In a pattern type signature (see Lexically scoped type variables)

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 Haskell-98, 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.)

## 10.20.1. Examples¶

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 rank-2 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)

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


Since GHC 8.0 declarations such as MkSwizzle' will cause an out-of-scope error.

As for type signatures, implicit quantification happens for non-overloaded 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 = let r x = Just x
b m k = case m of
Just y -> k y
Nothing -> Nothing
in

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.

## 10.20.2. Type inference¶

In general, type inference for arbitrary-rank 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 lambda-bound or case-bound 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.

## 10.20.3. Implicit quantification¶

GHC performs implicit quantification as follows. At the outermost level (only) of user-written 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 user-written type; it does not find the inner-most 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 rank-2 types.

Sometimes there is no “outermost level”, in which case no implicit quantification 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 quantification 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)


# 10.21. Impredicative polymorphism¶

-XImpredicativeTypes
Implies: -XRankNTypes

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 un-supported. 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))
`