d23da182cdc59426f858f42662e5e9c687fa26cb
[ghc.git] / docs / users_guide / glasgow_exts.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <para>
3 <indexterm><primary>language, GHC</primary></indexterm>
4 <indexterm><primary>extensions, GHC</primary></indexterm>
5 As with all known Haskell systems, GHC implements some extensions to
6 the language. They are all enabled by options; by default GHC
7 understands only plain Haskell 98.
8 </para>
9
10 <para>
11 Some of the Glasgow extensions serve to give you access to the
12 underlying facilities with which we implement Haskell. Thus, you can
13 get at the Raw Iron, if you are willing to write some non-portable
14 code at a more primitive level. You need not be &ldquo;stuck&rdquo;
15 on performance because of the implementation costs of Haskell's
16 &ldquo;high-level&rdquo; features&mdash;you can always code
17 &ldquo;under&rdquo; them. In an extreme case, you can write all your
18 time-critical code in C, and then just glue it together with Haskell!
19 </para>
20
21 <para>
22 Before you get too carried away working at the lowest level (e.g.,
23 sloshing <literal>MutableByteArray&num;</literal>s around your
24 program), you may wish to check if there are libraries that provide a
25 &ldquo;Haskellised veneer&rdquo; over the features you want. The
26 separate <ulink url="../libraries/index.html">libraries
27 documentation</ulink> describes all the libraries that come with GHC.
28 </para>
29
30 <!-- LANGUAGE OPTIONS -->
31 <sect1 id="options-language">
32 <title>Language options</title>
33
34 <indexterm><primary>language</primary><secondary>option</secondary>
35 </indexterm>
36 <indexterm><primary>options</primary><secondary>language</secondary>
37 </indexterm>
38 <indexterm><primary>extensions</primary><secondary>options controlling</secondary>
39 </indexterm>
40
41 <para>The language option flags control what variation of the language are
42 permitted. Leaving out all of them gives you standard Haskell
43 98.</para>
44
45 <para>Language options can be controlled in two ways:
46 <itemizedlist>
47 <listitem><para>Every language option can switched on by a command-line flag "<option>-X...</option>"
48 (e.g. <option>-XTemplateHaskell</option>), and switched off by the flag "<option>-XNo...</option>";
49 (e.g. <option>-XNoTemplateHaskell</option>).</para></listitem>
50 <listitem><para>
51 Language options recognised by Cabal can also be enabled using the <literal>LANGUAGE</literal> pragma,
52 thus <literal>{-# LANGUAGE TemplateHaskell #-}</literal> (see <xref linkend="language-pragma"/>). </para>
53 </listitem>
54 </itemizedlist></para>
55
56 <para>The flag <option>-fglasgow-exts</option>
57 <indexterm><primary><option>-fglasgow-exts</option></primary></indexterm>
58 is equivalent to enabling the following extensions:
59 <option>-XPrintExplicitForalls</option>,
60 <option>-XForeignFunctionInterface</option>,
61 <option>-XUnliftedFFITypes</option>,
62 <option>-XGADTs</option>,
63 <option>-XImplicitParams</option>,
64 <option>-XScopedTypeVariables</option>,
65 <option>-XUnboxedTuples</option>,
66 <option>-XTypeSynonymInstances</option>,
67 <option>-XStandaloneDeriving</option>,
68 <option>-XDeriveDataTypeable</option>,
69 <option>-XFlexibleContexts</option>,
70 <option>-XFlexibleInstances</option>,
71 <option>-XConstrainedClassMethods</option>,
72 <option>-XMultiParamTypeClasses</option>,
73 <option>-XFunctionalDependencies</option>,
74 <option>-XMagicHash</option>,
75 <option>-XPolymorphicComponents</option>,
76 <option>-XExistentialQuantification</option>,
77 <option>-XUnicodeSyntax</option>,
78 <option>-XPostfixOperators</option>,
79 <option>-XPatternGuards</option>,
80 <option>-XLiberalTypeSynonyms</option>,
81 <option>-XRankNTypes</option>,
82 <option>-XImpredicativeTypes</option>,
83 <option>-XTypeOperators</option>,
84 <option>-XRecursiveDo</option>,
85 <option>-XParallelListComp</option>,
86 <option>-XEmptyDataDecls</option>,
87 <option>-XKindSignatures</option>,
88 <option>-XGeneralizedNewtypeDeriving</option>,
89 <option>-XTypeFamilies</option>.
90 Enabling these options is the <emphasis>only</emphasis>
91 effect of <option>-fglasgow-exts</option>.
92 We are trying to move away from this portmanteau flag,
93 and towards enabling features individually.</para>
94
95 </sect1>
96
97 <!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS -->
98 <sect1 id="primitives">
99 <title>Unboxed types and primitive operations</title>
100
101 <para>GHC is built on a raft of primitive data types and operations;
102 "primitive" in the sense that they cannot be defined in Haskell itself.
103 While you really can use this stuff to write fast code,
104 we generally find it a lot less painful, and more satisfying in the
105 long run, to use higher-level language features and libraries. With
106 any luck, the code you write will be optimised to the efficient
107 unboxed version in any case. And if it isn't, we'd like to know
108 about it.</para>
109
110 <para>All these primitive data types and operations are exported by the
111 library <literal>GHC.Prim</literal>, for which there is
112 <ulink url="../libraries/base/GHC.Prim.html">detailed online documentation</ulink>.
113 (This documentation is generated from the file <filename>compiler/prelude/primops.txt.pp</filename>.)
114 </para>
115 <para>
116 If you want to mention any of the primitive data types or operations in your
117 program, you must first import <literal>GHC.Prim</literal> to bring them
118 into scope. Many of them have names ending in "&num;", and to mention such
119 names you need the <option>-XMagicHash</option> extension (<xref linkend="magic-hash"/>).
120 </para>
121
122 <para>The primops make extensive use of <link linkend="glasgow-unboxed">unboxed types</link>
123 and <link linkend="unboxed-tuples">unboxed tuples</link>, which
124 we briefly summarise here. </para>
125
126 <sect2 id="glasgow-unboxed">
127 <title>Unboxed types
128 </title>
129
130 <para>
131 <indexterm><primary>Unboxed types (Glasgow extension)</primary></indexterm>
132 </para>
133
134 <para>Most types in GHC are <firstterm>boxed</firstterm>, which means
135 that values of that type are represented by a pointer to a heap
136 object. The representation of a Haskell <literal>Int</literal>, for
137 example, is a two-word heap object. An <firstterm>unboxed</firstterm>
138 type, however, is represented by the value itself, no pointers or heap
139 allocation are involved.
140 </para>
141
142 <para>
143 Unboxed types correspond to the &ldquo;raw machine&rdquo; types you
144 would use in C: <literal>Int&num;</literal> (long int),
145 <literal>Double&num;</literal> (double), <literal>Addr&num;</literal>
146 (void *), etc. The <emphasis>primitive operations</emphasis>
147 (PrimOps) on these types are what you might expect; e.g.,
148 <literal>(+&num;)</literal> is addition on
149 <literal>Int&num;</literal>s, and is the machine-addition that we all
150 know and love&mdash;usually one instruction.
151 </para>
152
153 <para>
154 Primitive (unboxed) types cannot be defined in Haskell, and are
155 therefore built into the language and compiler. Primitive types are
156 always unlifted; that is, a value of a primitive type cannot be
157 bottom. We use the convention (but it is only a convention)
158 that primitive types, values, and
159 operations have a <literal>&num;</literal> suffix (see <xref linkend="magic-hash"/>).
160 For some primitive types we have special syntax for literals, also
161 described in the <link linkend="magic-hash">same section</link>.
162 </para>
163
164 <para>
165 Primitive values are often represented by a simple bit-pattern, such
166 as <literal>Int&num;</literal>, <literal>Float&num;</literal>,
167 <literal>Double&num;</literal>. But this is not necessarily the case:
168 a primitive value might be represented by a pointer to a
169 heap-allocated object. Examples include
170 <literal>Array&num;</literal>, the type of primitive arrays. A
171 primitive array is heap-allocated because it is too big a value to fit
172 in a register, and would be too expensive to copy around; in a sense,
173 it is accidental that it is represented by a pointer. If a pointer
174 represents a primitive value, then it really does point to that value:
175 no unevaluated thunks, no indirections&hellip;nothing can be at the
176 other end of the pointer than the primitive value.
177 A numerically-intensive program using unboxed types can
178 go a <emphasis>lot</emphasis> faster than its &ldquo;standard&rdquo;
179 counterpart&mdash;we saw a threefold speedup on one example.
180 </para>
181
182 <para>
183 There are some restrictions on the use of primitive types:
184 <itemizedlist>
185 <listitem><para>The main restriction
186 is that you can't pass a primitive value to a polymorphic
187 function or store one in a polymorphic data type. This rules out
188 things like <literal>[Int&num;]</literal> (i.e. lists of primitive
189 integers). The reason for this restriction is that polymorphic
190 arguments and constructor fields are assumed to be pointers: if an
191 unboxed integer is stored in one of these, the garbage collector would
192 attempt to follow it, leading to unpredictable space leaks. Or a
193 <function>seq</function> operation on the polymorphic component may
194 attempt to dereference the pointer, with disastrous results. Even
195 worse, the unboxed value might be larger than a pointer
196 (<literal>Double&num;</literal> for instance).
197 </para>
198 </listitem>
199 <listitem><para> You cannot define a newtype whose representation type
200 (the argument type of the data constructor) is an unboxed type. Thus,
201 this is illegal:
202 <programlisting>
203 newtype A = MkA Int#
204 </programlisting>
205 </para></listitem>
206 <listitem><para> You cannot bind a variable with an unboxed type
207 in a <emphasis>top-level</emphasis> binding.
208 </para></listitem>
209 <listitem><para> You cannot bind a variable with an unboxed type
210 in a <emphasis>recursive</emphasis> binding.
211 </para></listitem>
212 <listitem><para> You may bind unboxed variables in a (non-recursive,
213 non-top-level) pattern binding, but any such variable causes the entire
214 pattern-match
215 to become strict. For example:
216 <programlisting>
217 data Foo = Foo Int Int#
218
219 f x = let (Foo a b, w) = ..rhs.. in ..body..
220 </programlisting>
221 Since <literal>b</literal> has type <literal>Int#</literal>, the entire pattern
222 match
223 is strict, and the program behaves as if you had written
224 <programlisting>
225 data Foo = Foo Int Int#
226
227 f x = case ..rhs.. of { (Foo a b, w) -> ..body.. }
228 </programlisting>
229 </para>
230 </listitem>
231 </itemizedlist>
232 </para>
233
234 </sect2>
235
236 <sect2 id="unboxed-tuples">
237 <title>Unboxed Tuples
238 </title>
239
240 <para>
241 Unboxed tuples aren't really exported by <literal>GHC.Exts</literal>,
242 they're available by default with <option>-fglasgow-exts</option>. An
243 unboxed tuple looks like this:
244 </para>
245
246 <para>
247
248 <programlisting>
249 (# e_1, ..., e_n #)
250 </programlisting>
251
252 </para>
253
254 <para>
255 where <literal>e&lowbar;1..e&lowbar;n</literal> are expressions of any
256 type (primitive or non-primitive). The type of an unboxed tuple looks
257 the same.
258 </para>
259
260 <para>
261 Unboxed tuples are used for functions that need to return multiple
262 values, but they avoid the heap allocation normally associated with
263 using fully-fledged tuples. When an unboxed tuple is returned, the
264 components are put directly into registers or on the stack; the
265 unboxed tuple itself does not have a composite representation. Many
266 of the primitive operations listed in <literal>primops.txt.pp</literal> return unboxed
267 tuples.
268 In particular, the <literal>IO</literal> and <literal>ST</literal> monads use unboxed
269 tuples to avoid unnecessary allocation during sequences of operations.
270 </para>
271
272 <para>
273 There are some pretty stringent restrictions on the use of unboxed tuples:
274 <itemizedlist>
275 <listitem>
276
277 <para>
278 Values of unboxed tuple types are subject to the same restrictions as
279 other unboxed types; i.e. they may not be stored in polymorphic data
280 structures or passed to polymorphic functions.
281
282 </para>
283 </listitem>
284 <listitem>
285
286 <para>
287 No variable can have an unboxed tuple type, nor may a constructor or function
288 argument have an unboxed tuple type. The following are all illegal:
289
290
291 <programlisting>
292 data Foo = Foo (# Int, Int #)
293
294 f :: (# Int, Int #) -&#62; (# Int, Int #)
295 f x = x
296
297 g :: (# Int, Int #) -&#62; Int
298 g (# a,b #) = a
299
300 h x = let y = (# x,x #) in ...
301 </programlisting>
302 </para>
303 </listitem>
304 </itemizedlist>
305 </para>
306 <para>
307 The typical use of unboxed tuples is simply to return multiple values,
308 binding those multiple results with a <literal>case</literal> expression, thus:
309 <programlisting>
310 f x y = (# x+1, y-1 #)
311 g x = case f x x of { (# a, b #) -&#62; a + b }
312 </programlisting>
313 You can have an unboxed tuple in a pattern binding, thus
314 <programlisting>
315 f x = let (# p,q #) = h x in ..body..
316 </programlisting>
317 If the types of <literal>p</literal> and <literal>q</literal> are not unboxed,
318 the resulting binding is lazy like any other Haskell pattern binding. The
319 above example desugars like this:
320 <programlisting>
321 f x = let t = case h x o f{ (# p,q #) -> (p,q)
322 p = fst t
323 q = snd t
324 in ..body..
325 </programlisting>
326 Indeed, the bindings can even be recursive.
327 </para>
328
329 </sect2>
330 </sect1>
331
332
333 <!-- ====================== SYNTACTIC EXTENSIONS ======================= -->
334
335 <sect1 id="syntax-extns">
336 <title>Syntactic extensions</title>
337
338 <sect2 id="unicode-syntax">
339 <title>Unicode syntax</title>
340 <para>The language
341 extension <option>-XUnicodeSyntax</option><indexterm><primary><option>-XUnicodeSyntax</option></primary></indexterm>
342 enables Unicode characters to be used to stand for certain ASCII
343 character sequences. The following alternatives are provided:</para>
344
345 <informaltable>
346 <tgroup cols="2" align="left" colsep="1" rowsep="1">
347 <thead>
348 <row>
349 <entry>ASCII</entry>
350 <entry>Unicode alternative</entry>
351 <entry>Code point</entry>
352 <entry>Name</entry>
353 </row>
354 </thead>
355 <tbody>
356 <row>
357 <entry><literal>::</literal></entry>
358 <entry>::</entry> <!-- no special char, apparently -->
359 <entry>0x2237</entry>
360 <entry>PROPORTION</entry>
361 </row>
362 </tbody>
363 <tbody>
364 <row>
365 <entry><literal>=&gt;</literal></entry>
366 <entry>&rArr;</entry>
367 <entry>0x21D2</entry>
368 <entry>RIGHTWARDS DOUBLE ARROW</entry>
369 </row>
370 </tbody>
371 <tbody>
372 <row>
373 <entry><literal>forall</literal></entry>
374 <entry>&forall;</entry>
375 <entry>0x2200</entry>
376 <entry>FOR ALL</entry>
377 </row>
378 </tbody>
379 <tbody>
380 <row>
381 <entry><literal>-&gt;</literal></entry>
382 <entry>&rarr;</entry>
383 <entry>0x2192</entry>
384 <entry>RIGHTWARDS ARROW</entry>
385 </row>
386 </tbody>
387 <tbody>
388 <row>
389 <entry><literal>&lt;-</literal></entry>
390 <entry>&larr;</entry>
391 <entry>0x2190</entry>
392 <entry>LEFTWARDS ARROW</entry>
393 </row>
394 </tbody>
395 <tbody>
396 <row>
397 <entry>..</entry>
398 <entry>&hellip;</entry>
399 <entry>0x22EF</entry>
400 <entry>MIDLINE HORIZONTAL ELLIPSIS</entry>
401 </row>
402 </tbody>
403 </tgroup>
404 </informaltable>
405 </sect2>
406
407 <sect2 id="magic-hash">
408 <title>The magic hash</title>
409 <para>The language extension <option>-XMagicHash</option> allows "&num;" as a
410 postfix modifier to identifiers. Thus, "x&num;" is a valid variable, and "T&num;" is
411 a valid type constructor or data constructor.</para>
412
413 <para>The hash sign does not change sematics at all. We tend to use variable
414 names ending in "&num;" for unboxed values or types (e.g. <literal>Int&num;</literal>),
415 but there is no requirement to do so; they are just plain ordinary variables.
416 Nor does the <option>-XMagicHash</option> extension bring anything into scope.
417 For example, to bring <literal>Int&num;</literal> into scope you must
418 import <literal>GHC.Prim</literal> (see <xref linkend="primitives"/>);
419 the <option>-XMagicHash</option> extension
420 then allows you to <emphasis>refer</emphasis> to the <literal>Int&num;</literal>
421 that is now in scope.</para>
422 <para> The <option>-XMagicHash</option> also enables some new forms of literals (see <xref linkend="glasgow-unboxed"/>):
423 <itemizedlist>
424 <listitem><para> <literal>'x'&num;</literal> has type <literal>Char&num;</literal></para> </listitem>
425 <listitem><para> <literal>&quot;foo&quot;&num;</literal> has type <literal>Addr&num;</literal></para> </listitem>
426 <listitem><para> <literal>3&num;</literal> has type <literal>Int&num;</literal>. In general,
427 any Haskell 98 integer lexeme followed by a <literal>&num;</literal> is an <literal>Int&num;</literal> literal, e.g.
428 <literal>-0x3A&num;</literal> as well as <literal>32&num;</literal></para>.</listitem>
429 <listitem><para> <literal>3&num;&num;</literal> has type <literal>Word&num;</literal>. In general,
430 any non-negative Haskell 98 integer lexeme followed by <literal>&num;&num;</literal>
431 is a <literal>Word&num;</literal>. </para> </listitem>
432 <listitem><para> <literal>3.2&num;</literal> has type <literal>Float&num;</literal>.</para> </listitem>
433 <listitem><para> <literal>3.2&num;&num;</literal> has type <literal>Double&num;</literal></para> </listitem>
434 </itemizedlist>
435 </para>
436 </sect2>
437
438 <sect2 id="new-qualified-operators">
439 <title>New qualified operator syntax</title>
440
441 <para>A new syntax for referencing qualified operators is
442 planned to be introduced by Haskell', and is enabled in GHC
443 with
444 the <option>-XNewQualifiedOperators</option><indexterm><primary><option>-XNewQualifiedOperators</option></primary></indexterm>
445 option. In the new syntax, the prefix form of a qualified
446 operator is
447 written <literal><replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)</literal>
448 (in Haskell 98 this would
449 be <literal>(<replaceable>module</replaceable>.<replaceable>symbol</replaceable>)</literal>),
450 and the infix form is
451 written <literal>`<replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)`</literal>
452 (in Haskell 98 this would
453 be <literal>`<replaceable>module</replaceable>.<replaceable>symbol</replaceable>`</literal>.
454 For example:
455 <programlisting>
456 add x y = Prelude.(+) x y
457 subtract y = (`Prelude.(-)` y)
458 </programlisting>
459 The new form of qualified operators is intended to regularise
460 the syntax by eliminating odd cases
461 like <literal>Prelude..</literal>. For example,
462 when <literal>NewQualifiedOperators</literal> is on, it is possible to
463 write the enumerated sequence <literal>[Monday..]</literal>
464 without spaces, whereas in Haskell 98 this would be a
465 reference to the operator &lsquo;<literal>.</literal>&lsquo;
466 from module <literal>Monday</literal>.</para>
467
468 <para>When <option>-XNewQualifiedOperators</option> is on, the old Haskell
469 98 syntax for qualified operators is not accepted, so this
470 option may cause existing Haskell 98 code to break.</para>
471
472 </sect2>
473
474
475 <!-- ====================== HIERARCHICAL MODULES ======================= -->
476
477
478 <sect2 id="hierarchical-modules">
479 <title>Hierarchical Modules</title>
480
481 <para>GHC supports a small extension to the syntax of module
482 names: a module name is allowed to contain a dot
483 <literal>&lsquo;.&rsquo;</literal>. This is also known as the
484 &ldquo;hierarchical module namespace&rdquo; extension, because
485 it extends the normally flat Haskell module namespace into a
486 more flexible hierarchy of modules.</para>
487
488 <para>This extension has very little impact on the language
489 itself; modules names are <emphasis>always</emphasis> fully
490 qualified, so you can just think of the fully qualified module
491 name as <quote>the module name</quote>. In particular, this
492 means that the full module name must be given after the
493 <literal>module</literal> keyword at the beginning of the
494 module; for example, the module <literal>A.B.C</literal> must
495 begin</para>
496
497 <programlisting>module A.B.C</programlisting>
498
499
500 <para>It is a common strategy to use the <literal>as</literal>
501 keyword to save some typing when using qualified names with
502 hierarchical modules. For example:</para>
503
504 <programlisting>
505 import qualified Control.Monad.ST.Strict as ST
506 </programlisting>
507
508 <para>For details on how GHC searches for source and interface
509 files in the presence of hierarchical modules, see <xref
510 linkend="search-path"/>.</para>
511
512 <para>GHC comes with a large collection of libraries arranged
513 hierarchically; see the accompanying <ulink
514 url="../libraries/index.html">library
515 documentation</ulink>. More libraries to install are available
516 from <ulink
517 url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para>
518 </sect2>
519
520 <!-- ====================== PATTERN GUARDS ======================= -->
521
522 <sect2 id="pattern-guards">
523 <title>Pattern guards</title>
524
525 <para>
526 <indexterm><primary>Pattern guards (Glasgow extension)</primary></indexterm>
527 The discussion that follows is an abbreviated version of Simon Peyton Jones's original <ulink url="http://research.microsoft.com/~simonpj/Haskell/guards.html">proposal</ulink>. (Note that the proposal was written before pattern guards were implemented, so refers to them as unimplemented.)
528 </para>
529
530 <para>
531 Suppose we have an abstract data type of finite maps, with a
532 lookup operation:
533
534 <programlisting>
535 lookup :: FiniteMap -> Int -> Maybe Int
536 </programlisting>
537
538 The lookup returns <function>Nothing</function> if the supplied key is not in the domain of the mapping, and <function>(Just v)</function> otherwise,
539 where <varname>v</varname> is the value that the key maps to. Now consider the following definition:
540 </para>
541
542 <programlisting>
543 clunky env var1 var2 | ok1 &amp;&amp; ok2 = val1 + val2
544 | otherwise = var1 + var2
545 where
546 m1 = lookup env var1
547 m2 = lookup env var2
548 ok1 = maybeToBool m1
549 ok2 = maybeToBool m2
550 val1 = expectJust m1
551 val2 = expectJust m2
552 </programlisting>
553
554 <para>
555 The auxiliary functions are
556 </para>
557
558 <programlisting>
559 maybeToBool :: Maybe a -&gt; Bool
560 maybeToBool (Just x) = True
561 maybeToBool Nothing = False
562
563 expectJust :: Maybe a -&gt; a
564 expectJust (Just x) = x
565 expectJust Nothing = error "Unexpected Nothing"
566 </programlisting>
567
568 <para>
569 What is <function>clunky</function> doing? The guard <literal>ok1 &amp;&amp;
570 ok2</literal> checks that both lookups succeed, using
571 <function>maybeToBool</function> to convert the <function>Maybe</function>
572 types to booleans. The (lazily evaluated) <function>expectJust</function>
573 calls extract the values from the results of the lookups, and binds the
574 returned values to <varname>val1</varname> and <varname>val2</varname>
575 respectively. If either lookup fails, then clunky takes the
576 <literal>otherwise</literal> case and returns the sum of its arguments.
577 </para>
578
579 <para>
580 This is certainly legal Haskell, but it is a tremendously verbose and
581 un-obvious way to achieve the desired effect. Arguably, a more direct way
582 to write clunky would be to use case expressions:
583 </para>
584
585 <programlisting>
586 clunky env var1 var2 = case lookup env var1 of
587 Nothing -&gt; fail
588 Just val1 -&gt; case lookup env var2 of
589 Nothing -&gt; fail
590 Just val2 -&gt; val1 + val2
591 where
592 fail = var1 + var2
593 </programlisting>
594
595 <para>
596 This is a bit shorter, but hardly better. Of course, we can rewrite any set
597 of pattern-matching, guarded equations as case expressions; that is
598 precisely what the compiler does when compiling equations! The reason that
599 Haskell provides guarded equations is because they allow us to write down
600 the cases we want to consider, one at a time, independently of each other.
601 This structure is hidden in the case version. Two of the right-hand sides
602 are really the same (<function>fail</function>), and the whole expression
603 tends to become more and more indented.
604 </para>
605
606 <para>
607 Here is how I would write clunky:
608 </para>
609
610 <programlisting>
611 clunky env var1 var2
612 | Just val1 &lt;- lookup env var1
613 , Just val2 &lt;- lookup env var2
614 = val1 + val2
615 ...other equations for clunky...
616 </programlisting>
617
618 <para>
619 The semantics should be clear enough. The qualifiers are matched in order.
620 For a <literal>&lt;-</literal> qualifier, which I call a pattern guard, the
621 right hand side is evaluated and matched against the pattern on the left.
622 If the match fails then the whole guard fails and the next equation is
623 tried. If it succeeds, then the appropriate binding takes place, and the
624 next qualifier is matched, in the augmented environment. Unlike list
625 comprehensions, however, the type of the expression to the right of the
626 <literal>&lt;-</literal> is the same as the type of the pattern to its
627 left. The bindings introduced by pattern guards scope over all the
628 remaining guard qualifiers, and over the right hand side of the equation.
629 </para>
630
631 <para>
632 Just as with list comprehensions, boolean expressions can be freely mixed
633 with among the pattern guards. For example:
634 </para>
635
636 <programlisting>
637 f x | [y] &lt;- x
638 , y > 3
639 , Just z &lt;- h y
640 = ...
641 </programlisting>
642
643 <para>
644 Haskell's current guards therefore emerge as a special case, in which the
645 qualifier list has just one element, a boolean expression.
646 </para>
647 </sect2>
648
649 <!-- ===================== View patterns =================== -->
650
651 <sect2 id="view-patterns">
652 <title>View patterns
653 </title>
654
655 <para>
656 View patterns are enabled by the flag <literal>-XViewPatterns</literal>.
657 More information and examples of view patterns can be found on the
658 <ulink url="http://hackage.haskell.org/trac/ghc/wiki/ViewPatterns">Wiki
659 page</ulink>.
660 </para>
661
662 <para>
663 View patterns are somewhat like pattern guards that can be nested inside
664 of other patterns. They are a convenient way of pattern-matching
665 against values of abstract types. For example, in a programming language
666 implementation, we might represent the syntax of the types of the
667 language as follows:
668
669 <programlisting>
670 type Typ
671
672 data TypView = Unit
673 | Arrow Typ Typ
674
675 view :: Type -> TypeView
676
677 -- additional operations for constructing Typ's ...
678 </programlisting>
679
680 The representation of Typ is held abstract, permitting implementations
681 to use a fancy representation (e.g., hash-consing to manage sharing).
682
683 Without view patterns, using this signature a little inconvenient:
684 <programlisting>
685 size :: Typ -> Integer
686 size t = case view t of
687 Unit -> 1
688 Arrow t1 t2 -> size t1 + size t2
689 </programlisting>
690
691 It is necessary to iterate the case, rather than using an equational
692 function definition. And the situation is even worse when the matching
693 against <literal>t</literal> is buried deep inside another pattern.
694 </para>
695
696 <para>
697 View patterns permit calling the view function inside the pattern and
698 matching against the result:
699 <programlisting>
700 size (view -> Unit) = 1
701 size (view -> Arrow t1 t2) = size t1 + size t2
702 </programlisting>
703
704 That is, we add a new form of pattern, written
705 <replaceable>expression</replaceable> <literal>-></literal>
706 <replaceable>pattern</replaceable> that means "apply the expression to
707 whatever we're trying to match against, and then match the result of
708 that application against the pattern". The expression can be any Haskell
709 expression of function type, and view patterns can be used wherever
710 patterns are used.
711 </para>
712
713 <para>
714 The semantics of a pattern <literal>(</literal>
715 <replaceable>exp</replaceable> <literal>-></literal>
716 <replaceable>pat</replaceable> <literal>)</literal> are as follows:
717
718 <itemizedlist>
719
720 <listitem> Scoping:
721
722 <para>The variables bound by the view pattern are the variables bound by
723 <replaceable>pat</replaceable>.
724 </para>
725
726 <para>
727 Any variables in <replaceable>exp</replaceable> are bound occurrences,
728 but variables bound "to the left" in a pattern are in scope. This
729 feature permits, for example, one argument to a function to be used in
730 the view of another argument. For example, the function
731 <literal>clunky</literal> from <xref linkend="pattern-guards" /> can be
732 written using view patterns as follows:
733
734 <programlisting>
735 clunky env (lookup env -> Just val1) (lookup env -> Just val2) = val1 + val2
736 ...other equations for clunky...
737 </programlisting>
738 </para>
739
740 <para>
741 More precisely, the scoping rules are:
742 <itemizedlist>
743 <listitem>
744 <para>
745 In a single pattern, variables bound by patterns to the left of a view
746 pattern expression are in scope. For example:
747 <programlisting>
748 example :: Maybe ((String -> Integer,Integer), String) -> Bool
749 example Just ((f,_), f -> 4) = True
750 </programlisting>
751
752 Additionally, in function definitions, variables bound by matching earlier curried
753 arguments may be used in view pattern expressions in later arguments:
754 <programlisting>
755 example :: (String -> Integer) -> String -> Bool
756 example f (f -> 4) = True
757 </programlisting>
758 That is, the scoping is the same as it would be if the curried arguments
759 were collected into a tuple.
760 </para>
761 </listitem>
762
763 <listitem>
764 <para>
765 In mutually recursive bindings, such as <literal>let</literal>,
766 <literal>where</literal>, or the top level, view patterns in one
767 declaration may not mention variables bound by other declarations. That
768 is, each declaration must be self-contained. For example, the following
769 program is not allowed:
770 <programlisting>
771 let {(x -> y) = e1 ;
772 (y -> x) = e2 } in x
773 </programlisting>
774
775 (We may lift this
776 restriction in the future; the only cost is that type checking patterns
777 would get a little more complicated.)
778
779
780 </para>
781 </listitem>
782 </itemizedlist>
783
784 </para>
785 </listitem>
786
787 <listitem><para> Typing: If <replaceable>exp</replaceable> has type
788 <replaceable>T1</replaceable> <literal>-></literal>
789 <replaceable>T2</replaceable> and <replaceable>pat</replaceable> matches
790 a <replaceable>T2</replaceable>, then the whole view pattern matches a
791 <replaceable>T1</replaceable>.
792 </para></listitem>
793
794 <listitem><para> Matching: To the equations in Section 3.17.3 of the
795 <ulink url="http://www.haskell.org/onlinereport/">Haskell 98
796 Report</ulink>, add the following:
797 <programlisting>
798 case v of { (e -> p) -> e1 ; _ -> e2 }
799 =
800 case (e v) of { p -> e1 ; _ -> e2 }
801 </programlisting>
802 That is, to match a variable <replaceable>v</replaceable> against a pattern
803 <literal>(</literal> <replaceable>exp</replaceable>
804 <literal>-></literal> <replaceable>pat</replaceable>
805 <literal>)</literal>, evaluate <literal>(</literal>
806 <replaceable>exp</replaceable> <replaceable> v</replaceable>
807 <literal>)</literal> and match the result against
808 <replaceable>pat</replaceable>.
809 </para></listitem>
810
811 <listitem><para> Efficiency: When the same view function is applied in
812 multiple branches of a function definition or a case expression (e.g.,
813 in <literal>size</literal> above), GHC makes an attempt to collect these
814 applications into a single nested case expression, so that the view
815 function is only applied once. Pattern compilation in GHC follows the
816 matrix algorithm described in Chapter 4 of <ulink
817 url="http://research.microsoft.com/~simonpj/Papers/slpj-book-1987/">The
818 Implementation of Functional Programming Languages</ulink>. When the
819 top rows of the first column of a matrix are all view patterns with the
820 "same" expression, these patterns are transformed into a single nested
821 case. This includes, for example, adjacent view patterns that line up
822 in a tuple, as in
823 <programlisting>
824 f ((view -> A, p1), p2) = e1
825 f ((view -> B, p3), p4) = e2
826 </programlisting>
827 </para>
828
829 <para> The current notion of when two view pattern expressions are "the
830 same" is very restricted: it is not even full syntactic equality.
831 However, it does include variables, literals, applications, and tuples;
832 e.g., two instances of <literal>view ("hi", "there")</literal> will be
833 collected. However, the current implementation does not compare up to
834 alpha-equivalence, so two instances of <literal>(x, view x ->
835 y)</literal> will not be coalesced.
836 </para>
837
838 </listitem>
839
840 </itemizedlist>
841 </para>
842
843 </sect2>
844
845 <!-- ===================== Recursive do-notation =================== -->
846
847 <sect2 id="mdo-notation">
848 <title>The recursive do-notation
849 </title>
850
851 <para> The recursive do-notation (also known as mdo-notation) is implemented as described in
852 <ulink url="http://citeseer.ist.psu.edu/erk02recursive.html">A recursive do for Haskell</ulink>,
853 by Levent Erkok, John Launchbury,
854 Haskell Workshop 2002, pages: 29-37. Pittsburgh, Pennsylvania.
855 This paper is essential reading for anyone making non-trivial use of mdo-notation,
856 and we do not repeat it here.
857 </para>
858 <para>
859 The do-notation of Haskell does not allow <emphasis>recursive bindings</emphasis>,
860 that is, the variables bound in a do-expression are visible only in the textually following
861 code block. Compare this to a let-expression, where bound variables are visible in the entire binding
862 group. It turns out that several applications can benefit from recursive bindings in
863 the do-notation, and this extension provides the necessary syntactic support.
864 </para>
865 <para>
866 Here is a simple (yet contrived) example:
867 </para>
868 <programlisting>
869 import Control.Monad.Fix
870
871 justOnes = mdo xs &lt;- Just (1:xs)
872 return xs
873 </programlisting>
874 <para>
875 As you can guess <literal>justOnes</literal> will evaluate to <literal>Just [1,1,1,...</literal>.
876 </para>
877
878 <para>
879 The Control.Monad.Fix library introduces the <literal>MonadFix</literal> class. It's definition is:
880 </para>
881 <programlisting>
882 class Monad m => MonadFix m where
883 mfix :: (a -> m a) -> m a
884 </programlisting>
885 <para>
886 The function <literal>mfix</literal>
887 dictates how the required recursion operation should be performed. For example,
888 <literal>justOnes</literal> desugars as follows:
889 <programlisting>
890 justOnes = mfix (\xs' -&gt; do { xs &lt;- Just (1:xs'); return xs }
891 </programlisting>
892 For full details of the way in which mdo is typechecked and desugared, see
893 the paper <ulink url="http://citeseer.ist.psu.edu/erk02recursive.html">A recursive do for Haskell</ulink>.
894 In particular, GHC implements the segmentation technique described in Section 3.2 of the paper.
895 </para>
896 <para>
897 If recursive bindings are required for a monad,
898 then that monad must be declared an instance of the <literal>MonadFix</literal> class.
899 The following instances of <literal>MonadFix</literal> are automatically provided: List, Maybe, IO.
900 Furthermore, the Control.Monad.ST and Control.Monad.ST.Lazy modules provide the instances of the MonadFix class
901 for Haskell's internal state monad (strict and lazy, respectively).
902 </para>
903 <para>
904 Here are some important points in using the recursive-do notation:
905 <itemizedlist>
906 <listitem><para>
907 The recursive version of the do-notation uses the keyword <literal>mdo</literal> (rather
908 than <literal>do</literal>).
909 </para></listitem>
910
911 <listitem><para>
912 It is enabled with the flag <literal>-XRecursiveDo</literal>, which is in turn implied by
913 <literal>-fglasgow-exts</literal>.
914 </para></listitem>
915
916 <listitem><para>
917 Unlike ordinary do-notation, but like <literal>let</literal> and <literal>where</literal> bindings,
918 name shadowing is not allowed; that is, all the names bound in a single <literal>mdo</literal> must
919 be distinct (Section 3.3 of the paper).
920 </para></listitem>
921
922 <listitem><para>
923 Variables bound by a <literal>let</literal> statement in an <literal>mdo</literal>
924 are monomorphic in the <literal>mdo</literal> (Section 3.1 of the paper). However
925 GHC breaks the <literal>mdo</literal> into segments to enhance polymorphism,
926 and improve termination (Section 3.2 of the paper).
927 </para></listitem>
928 </itemizedlist>
929 </para>
930
931 <para>
932 Historical note: The old implementation of the mdo-notation (and most
933 of the existing documents) used the name
934 <literal>MonadRec</literal> for the class and the corresponding library.
935 This name is not supported by GHC.
936 </para>
937
938 </sect2>
939
940
941 <!-- ===================== PARALLEL LIST COMPREHENSIONS =================== -->
942
943 <sect2 id="parallel-list-comprehensions">
944 <title>Parallel List Comprehensions</title>
945 <indexterm><primary>list comprehensions</primary><secondary>parallel</secondary>
946 </indexterm>
947 <indexterm><primary>parallel list comprehensions</primary>
948 </indexterm>
949
950 <para>Parallel list comprehensions are a natural extension to list
951 comprehensions. List comprehensions can be thought of as a nice
952 syntax for writing maps and filters. Parallel comprehensions
953 extend this to include the zipWith family.</para>
954
955 <para>A parallel list comprehension has multiple independent
956 branches of qualifier lists, each separated by a `|' symbol. For
957 example, the following zips together two lists:</para>
958
959 <programlisting>
960 [ (x, y) | x &lt;- xs | y &lt;- ys ]
961 </programlisting>
962
963 <para>The behavior of parallel list comprehensions follows that of
964 zip, in that the resulting list will have the same length as the
965 shortest branch.</para>
966
967 <para>We can define parallel list comprehensions by translation to
968 regular comprehensions. Here's the basic idea:</para>
969
970 <para>Given a parallel comprehension of the form: </para>
971
972 <programlisting>
973 [ e | p1 &lt;- e11, p2 &lt;- e12, ...
974 | q1 &lt;- e21, q2 &lt;- e22, ...
975 ...
976 ]
977 </programlisting>
978
979 <para>This will be translated to: </para>
980
981 <programlisting>
982 [ e | ((p1,p2), (q1,q2), ...) &lt;- zipN [(p1,p2) | p1 &lt;- e11, p2 &lt;- e12, ...]
983 [(q1,q2) | q1 &lt;- e21, q2 &lt;- e22, ...]
984 ...
985 ]
986 </programlisting>
987
988 <para>where `zipN' is the appropriate zip for the given number of
989 branches.</para>
990
991 </sect2>
992
993 <!-- ===================== TRANSFORM LIST COMPREHENSIONS =================== -->
994
995 <sect2 id="generalised-list-comprehensions">
996 <title>Generalised (SQL-Like) List Comprehensions</title>
997 <indexterm><primary>list comprehensions</primary><secondary>generalised</secondary>
998 </indexterm>
999 <indexterm><primary>extended list comprehensions</primary>
1000 </indexterm>
1001 <indexterm><primary>group</primary></indexterm>
1002 <indexterm><primary>sql</primary></indexterm>
1003
1004
1005 <para>Generalised list comprehensions are a further enhancement to the
1006 list comprehension syntatic sugar to allow operations such as sorting
1007 and grouping which are familiar from SQL. They are fully described in the
1008 paper <ulink url="http://research.microsoft.com/~simonpj/papers/list-comp">
1009 Comprehensive comprehensions: comprehensions with "order by" and "group by"</ulink>,
1010 except that the syntax we use differs slightly from the paper.</para>
1011 <para>Here is an example:
1012 <programlisting>
1013 employees = [ ("Simon", "MS", 80)
1014 , ("Erik", "MS", 100)
1015 , ("Phil", "Ed", 40)
1016 , ("Gordon", "Ed", 45)
1017 , ("Paul", "Yale", 60)]
1018
1019 output = [ (the dept, sum salary)
1020 | (name, dept, salary) &lt;- employees
1021 , then group by dept
1022 , then sortWith by (sum salary)
1023 , then take 5 ]
1024 </programlisting>
1025 In this example, the list <literal>output</literal> would take on
1026 the value:
1027
1028 <programlisting>
1029 [("Yale", 60), ("Ed", 85), ("MS", 180)]
1030 </programlisting>
1031 </para>
1032 <para>There are three new keywords: <literal>group</literal>, <literal>by</literal>, and <literal>using</literal>.
1033 (The function <literal>sortWith</literal> is not a keyword; it is an ordinary
1034 function that is exported by <literal>GHC.Exts</literal>.)</para>
1035
1036 <para>There are five new forms of comprehension qualifier,
1037 all introduced by the (existing) keyword <literal>then</literal>:
1038 <itemizedlist>
1039 <listitem>
1040
1041 <programlisting>
1042 then f
1043 </programlisting>
1044
1045 This statement requires that <literal>f</literal> have the type <literal>
1046 forall a. [a] -> [a]</literal>. You can see an example of it's use in the
1047 motivating example, as this form is used to apply <literal>take 5</literal>.
1048
1049 </listitem>
1050
1051
1052 <listitem>
1053 <para>
1054 <programlisting>
1055 then f by e
1056 </programlisting>
1057
1058 This form is similar to the previous one, but allows you to create a function
1059 which will be passed as the first argument to f. As a consequence f must have
1060 the type <literal>forall a. (a -> t) -> [a] -> [a]</literal>. As you can see
1061 from the type, this function lets f &quot;project out&quot; some information
1062 from the elements of the list it is transforming.</para>
1063
1064 <para>An example is shown in the opening example, where <literal>sortWith</literal>
1065 is supplied with a function that lets it find out the <literal>sum salary</literal>
1066 for any item in the list comprehension it transforms.</para>
1067
1068 </listitem>
1069
1070
1071 <listitem>
1072
1073 <programlisting>
1074 then group by e using f
1075 </programlisting>
1076
1077 <para>This is the most general of the grouping-type statements. In this form,
1078 f is required to have type <literal>forall a. (a -> t) -> [a] -> [[a]]</literal>.
1079 As with the <literal>then f by e</literal> case above, the first argument
1080 is a function supplied to f by the compiler which lets it compute e on every
1081 element of the list being transformed. However, unlike the non-grouping case,
1082 f additionally partitions the list into a number of sublists: this means that
1083 at every point after this statement, binders occurring before it in the comprehension
1084 refer to <emphasis>lists</emphasis> of possible values, not single values. To help understand
1085 this, let's look at an example:</para>
1086
1087 <programlisting>
1088 -- This works similarly to groupWith in GHC.Exts, but doesn't sort its input first
1089 groupRuns :: Eq b => (a -> b) -> [a] -> [[a]]
1090 groupRuns f = groupBy (\x y -> f x == f y)
1091
1092 output = [ (the x, y)
1093 | x &lt;- ([1..3] ++ [1..2])
1094 , y &lt;- [4..6]
1095 , then group by x using groupRuns ]
1096 </programlisting>
1097
1098 <para>This results in the variable <literal>output</literal> taking on the value below:</para>
1099
1100 <programlisting>
1101 [(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])]
1102 </programlisting>
1103
1104 <para>Note that we have used the <literal>the</literal> function to change the type
1105 of x from a list to its original numeric type. The variable y, in contrast, is left
1106 unchanged from the list form introduced by the grouping.</para>
1107
1108 </listitem>
1109
1110 <listitem>
1111
1112 <programlisting>
1113 then group by e
1114 </programlisting>
1115
1116 <para>This form of grouping is essentially the same as the one described above. However,
1117 since no function to use for the grouping has been supplied it will fall back on the
1118 <literal>groupWith</literal> function defined in
1119 <ulink url="../libraries/base/GHC-Exts.html"><literal>GHC.Exts</literal></ulink>. This
1120 is the form of the group statement that we made use of in the opening example.</para>
1121
1122 </listitem>
1123
1124
1125 <listitem>
1126
1127 <programlisting>
1128 then group using f
1129 </programlisting>
1130
1131 <para>With this form of the group statement, f is required to simply have the type
1132 <literal>forall a. [a] -> [[a]]</literal>, which will be used to group up the
1133 comprehension so far directly. An example of this form is as follows:</para>
1134
1135 <programlisting>
1136 output = [ x
1137 | y &lt;- [1..5]
1138 , x &lt;- "hello"
1139 , then group using inits]
1140 </programlisting>
1141
1142 <para>This will yield a list containing every prefix of the word "hello" written out 5 times:</para>
1143
1144 <programlisting>
1145 ["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...]
1146 </programlisting>
1147
1148 </listitem>
1149 </itemizedlist>
1150 </para>
1151 </sect2>
1152
1153 <!-- ===================== REBINDABLE SYNTAX =================== -->
1154
1155 <sect2 id="rebindable-syntax">
1156 <title>Rebindable syntax and the implicit Prelude import</title>
1157
1158 <para><indexterm><primary>-XNoImplicitPrelude
1159 option</primary></indexterm> GHC normally imports
1160 <filename>Prelude.hi</filename> files for you. If you'd
1161 rather it didn't, then give it a
1162 <option>-XNoImplicitPrelude</option> option. The idea is
1163 that you can then import a Prelude of your own. (But don't
1164 call it <literal>Prelude</literal>; the Haskell module
1165 namespace is flat, and you must not conflict with any
1166 Prelude module.)</para>
1167
1168 <para>Suppose you are importing a Prelude of your own
1169 in order to define your own numeric class
1170 hierarchy. It completely defeats that purpose if the
1171 literal "1" means "<literal>Prelude.fromInteger
1172 1</literal>", which is what the Haskell Report specifies.
1173 So the <option>-XNoImplicitPrelude</option>
1174 flag <emphasis>also</emphasis> causes
1175 the following pieces of built-in syntax to refer to
1176 <emphasis>whatever is in scope</emphasis>, not the Prelude
1177 versions:
1178 <itemizedlist>
1179 <listitem>
1180 <para>An integer literal <literal>368</literal> means
1181 "<literal>fromInteger (368::Integer)</literal>", rather than
1182 "<literal>Prelude.fromInteger (368::Integer)</literal>".
1183 </para> </listitem>
1184
1185 <listitem><para>Fractional literals are handed in just the same way,
1186 except that the translation is
1187 <literal>fromRational (3.68::Rational)</literal>.
1188 </para> </listitem>
1189
1190 <listitem><para>The equality test in an overloaded numeric pattern
1191 uses whatever <literal>(==)</literal> is in scope.
1192 </para> </listitem>
1193
1194 <listitem><para>The subtraction operation, and the
1195 greater-than-or-equal test, in <literal>n+k</literal> patterns
1196 use whatever <literal>(-)</literal> and <literal>(>=)</literal> are in scope.
1197 </para></listitem>
1198
1199 <listitem>
1200 <para>Negation (e.g. "<literal>- (f x)</literal>")
1201 means "<literal>negate (f x)</literal>", both in numeric
1202 patterns, and expressions.
1203 </para></listitem>
1204
1205 <listitem>
1206 <para>"Do" notation is translated using whatever
1207 functions <literal>(>>=)</literal>,
1208 <literal>(>>)</literal>, and <literal>fail</literal>,
1209 are in scope (not the Prelude
1210 versions). List comprehensions, mdo (<xref linkend="mdo-notation"/>), and parallel array
1211 comprehensions, are unaffected. </para></listitem>
1212
1213 <listitem>
1214 <para>Arrow
1215 notation (see <xref linkend="arrow-notation"/>)
1216 uses whatever <literal>arr</literal>,
1217 <literal>(>>>)</literal>, <literal>first</literal>,
1218 <literal>app</literal>, <literal>(|||)</literal> and
1219 <literal>loop</literal> functions are in scope. But unlike the
1220 other constructs, the types of these functions must match the
1221 Prelude types very closely. Details are in flux; if you want
1222 to use this, ask!
1223 </para></listitem>
1224 </itemizedlist>
1225 In all cases (apart from arrow notation), the static semantics should be that of the desugared form,
1226 even if that is a little unexpected. For example, the
1227 static semantics of the literal <literal>368</literal>
1228 is exactly that of <literal>fromInteger (368::Integer)</literal>; it's fine for
1229 <literal>fromInteger</literal> to have any of the types:
1230 <programlisting>
1231 fromInteger :: Integer -> Integer
1232 fromInteger :: forall a. Foo a => Integer -> a
1233 fromInteger :: Num a => a -> Integer
1234 fromInteger :: Integer -> Bool -> Bool
1235 </programlisting>
1236 </para>
1237
1238 <para>Be warned: this is an experimental facility, with
1239 fewer checks than usual. Use <literal>-dcore-lint</literal>
1240 to typecheck the desugared program. If Core Lint is happy
1241 you should be all right.</para>
1242
1243 </sect2>
1244
1245 <sect2 id="postfix-operators">
1246 <title>Postfix operators</title>
1247
1248 <para>
1249 The <option>-XPostfixOperators</option> flag enables a small
1250 extension to the syntax of left operator sections, which allows you to
1251 define postfix operators. The extension is this: the left section
1252 <programlisting>
1253 (e !)
1254 </programlisting>
1255 is equivalent (from the point of view of both type checking and execution) to the expression
1256 <programlisting>
1257 ((!) e)
1258 </programlisting>
1259 (for any expression <literal>e</literal> and operator <literal>(!)</literal>.
1260 The strict Haskell 98 interpretation is that the section is equivalent to
1261 <programlisting>
1262 (\y -> (!) e y)
1263 </programlisting>
1264 That is, the operator must be a function of two arguments. GHC allows it to
1265 take only one argument, and that in turn allows you to write the function
1266 postfix.
1267 </para>
1268 <para>The extension does not extend to the left-hand side of function
1269 definitions; you must define such a function in prefix form.</para>
1270
1271 </sect2>
1272
1273 <sect2 id="disambiguate-fields">
1274 <title>Record field disambiguation</title>
1275 <para>
1276 In record construction and record pattern matching
1277 it is entirely unambiguous which field is referred to, even if there are two different
1278 data types in scope with a common field name. For example:
1279 <programlisting>
1280 module M where
1281 data S = MkS { x :: Int, y :: Bool }
1282
1283 module Foo where
1284 import M
1285
1286 data T = MkT { x :: Int }
1287
1288 ok1 (MkS { x = n }) = n+1 -- Unambiguous
1289
1290 ok2 n = MkT { x = n+1 } -- Unambiguous
1291
1292 bad1 k = k { x = 3 } -- Ambiguous
1293 bad2 k = x k -- Ambiguous
1294 </programlisting>
1295 Even though there are two <literal>x</literal>'s in scope,
1296 it is clear that the <literal>x</literal> in the pattern in the
1297 definition of <literal>ok1</literal> can only mean the field
1298 <literal>x</literal> from type <literal>S</literal>. Similarly for
1299 the function <literal>ok2</literal>. However, in the record update
1300 in <literal>bad1</literal> and the record selection in <literal>bad2</literal>
1301 it is not clear which of the two types is intended.
1302 </para>
1303 <para>
1304 Haskell 98 regards all four as ambiguous, but with the
1305 <option>-XDisambiguateRecordFields</option> flag, GHC will accept
1306 the former two. The rules are precisely the same as those for instance
1307 declarations in Haskell 98, where the method names on the left-hand side
1308 of the method bindings in an instance declaration refer unambiguously
1309 to the method of that class (provided they are in scope at all), even
1310 if there are other variables in scope with the same name.
1311 This reduces the clutter of qualified names when you import two
1312 records from different modules that use the same field name.
1313 </para>
1314 </sect2>
1315
1316 <!-- ===================== Record puns =================== -->
1317
1318 <sect2 id="record-puns">
1319 <title>Record puns
1320 </title>
1321
1322 <para>
1323 Record puns are enabled by the flag <literal>-XNamedFieldPuns</literal>.
1324 </para>
1325
1326 <para>
1327 When using records, it is common to write a pattern that binds a
1328 variable with the same name as a record field, such as:
1329
1330 <programlisting>
1331 data C = C {a :: Int}
1332 f (C {a = a}) = a
1333 </programlisting>
1334 </para>
1335
1336 <para>
1337 Record punning permits the variable name to be elided, so one can simply
1338 write
1339
1340 <programlisting>
1341 f (C {a}) = a
1342 </programlisting>
1343
1344 to mean the same pattern as above. That is, in a record pattern, the
1345 pattern <literal>a</literal> expands into the pattern <literal>a =
1346 a</literal> for the same name <literal>a</literal>.
1347 </para>
1348
1349 <para>
1350 Note that puns and other patterns can be mixed in the same record:
1351 <programlisting>
1352 data C = C {a :: Int, b :: Int}
1353 f (C {a, b = 4}) = a
1354 </programlisting>
1355 and that puns can be used wherever record patterns occur (e.g. in
1356 <literal>let</literal> bindings or at the top-level).
1357 </para>
1358
1359 <para>
1360 Record punning can also be used in an expression, writing, for example,
1361 <programlisting>
1362 let a = 1 in C {a}
1363 </programlisting>
1364 instead of
1365 <programlisting>
1366 let a = 1 in C {a = a}
1367 </programlisting>
1368
1369 Note that this expansion is purely syntactic, so the record pun
1370 expression refers to the nearest enclosing variable that is spelled the
1371 same as the field name.
1372 </para>
1373
1374 </sect2>
1375
1376 <!-- ===================== Record wildcards =================== -->
1377
1378 <sect2 id="record-wildcards">
1379 <title>Record wildcards
1380 </title>
1381
1382 <para>
1383 Record wildcards are enabled by the flag <literal>-XRecordWildCards</literal>.
1384 </para>
1385
1386 <para>
1387 For records with many fields, it can be tiresome to write out each field
1388 individually in a record pattern, as in
1389 <programlisting>
1390 data C = C {a :: Int, b :: Int, c :: Int, d :: Int}
1391 f (C {a = 1, b = b, c = c, d = d}) = b + c + d
1392 </programlisting>
1393 </para>
1394
1395 <para>
1396 Record wildcard syntax permits a (<literal>..</literal>) in a record
1397 pattern, where each elided field <literal>f</literal> is replaced by the
1398 pattern <literal>f = f</literal>. For example, the above pattern can be
1399 written as
1400 <programlisting>
1401 f (C {a = 1, ..}) = b + c + d
1402 </programlisting>
1403 </para>
1404
1405 <para>
1406 Note that wildcards can be mixed with other patterns, including puns
1407 (<xref linkend="record-puns"/>); for example, in a pattern <literal>C {a
1408 = 1, b, ..})</literal>. Additionally, record wildcards can be used
1409 wherever record patterns occur, including in <literal>let</literal>
1410 bindings and at the top-level. For example, the top-level binding
1411 <programlisting>
1412 C {a = 1, ..} = e
1413 </programlisting>
1414 defines <literal>b</literal>, <literal>c</literal>, and
1415 <literal>d</literal>.
1416 </para>
1417
1418 <para>
1419 Record wildcards can also be used in expressions, writing, for example,
1420
1421 <programlisting>
1422 let {a = 1; b = 2; c = 3; d = 4} in C {..}
1423 </programlisting>
1424
1425 in place of
1426
1427 <programlisting>
1428 let {a = 1; b = 2; c = 3; d = 4} in C {a=a, b=b, c=c, d=d}
1429 </programlisting>
1430
1431 Note that this expansion is purely syntactic, so the record wildcard
1432 expression refers to the nearest enclosing variables that are spelled
1433 the same as the omitted field names.
1434 </para>
1435
1436 </sect2>
1437
1438 <!-- ===================== Local fixity declarations =================== -->
1439
1440 <sect2 id="local-fixity-declarations">
1441 <title>Local Fixity Declarations
1442 </title>
1443
1444 <para>A careful reading of the Haskell 98 Report reveals that fixity
1445 declarations (<literal>infix</literal>, <literal>infixl</literal>, and
1446 <literal>infixr</literal>) are permitted to appear inside local bindings
1447 such those introduced by <literal>let</literal> and
1448 <literal>where</literal>. However, the Haskell Report does not specify
1449 the semantics of such bindings very precisely.
1450 </para>
1451
1452 <para>In GHC, a fixity declaration may accompany a local binding:
1453 <programlisting>
1454 let f = ...
1455 infixr 3 `f`
1456 in
1457 ...
1458 </programlisting>
1459 and the fixity declaration applies wherever the binding is in scope.
1460 For example, in a <literal>let</literal>, it applies in the right-hand
1461 sides of other <literal>let</literal>-bindings and the body of the
1462 <literal>let</literal>C. Or, in recursive <literal>do</literal>
1463 expressions (<xref linkend="mdo-notation"/>), the local fixity
1464 declarations of a <literal>let</literal> statement scope over other
1465 statements in the group, just as the bound name does.
1466 </para>
1467
1468 <para>
1469 Moreover, a local fixity declaration *must* accompany a local binding of
1470 that name: it is not possible to revise the fixity of name bound
1471 elsewhere, as in
1472 <programlisting>
1473 let infixr 9 $ in ...
1474 </programlisting>
1475
1476 Because local fixity declarations are technically Haskell 98, no flag is
1477 necessary to enable them.
1478 </para>
1479 </sect2>
1480
1481 <sect2 id="package-imports">
1482 <title>Package-qualified imports</title>
1483
1484 <para>With the <option>-XPackageImports</option> flag, GHC allows
1485 import declarations to be qualified by the package name that the
1486 module is intended to be imported from. For example:</para>
1487
1488 <programlisting>
1489 import "network" Network.Socket
1490 </programlisting>
1491
1492 <para>would import the module <literal>Network.Socket</literal> from
1493 the package <literal>network</literal> (any version). This may
1494 be used to disambiguate an import when the same module is
1495 available from multiple packages, or is present in both the
1496 current package being built and an external package.</para>
1497
1498 <para>Note: you probably don't need to use this feature, it was
1499 added mainly so that we can build backwards-compatible versions of
1500 packages when APIs change. It can lead to fragile dependencies in
1501 the common case: modules occasionally move from one package to
1502 another, rendering any package-qualified imports broken.</para>
1503 </sect2>
1504
1505 <sect2 id="syntax-stolen">
1506 <title>Summary of stolen syntax</title>
1507
1508 <para>Turning on an option that enables special syntax
1509 <emphasis>might</emphasis> cause working Haskell 98 code to fail
1510 to compile, perhaps because it uses a variable name which has
1511 become a reserved word. This section lists the syntax that is
1512 "stolen" by language extensions.
1513 We use
1514 notation and nonterminal names from the Haskell 98 lexical syntax
1515 (see the Haskell 98 Report).
1516 We only list syntax changes here that might affect
1517 existing working programs (i.e. "stolen" syntax). Many of these
1518 extensions will also enable new context-free syntax, but in all
1519 cases programs written to use the new syntax would not be
1520 compilable without the option enabled.</para>
1521
1522 <para>There are two classes of special
1523 syntax:
1524
1525 <itemizedlist>
1526 <listitem>
1527 <para>New reserved words and symbols: character sequences
1528 which are no longer available for use as identifiers in the
1529 program.</para>
1530 </listitem>
1531 <listitem>
1532 <para>Other special syntax: sequences of characters that have
1533 a different meaning when this particular option is turned
1534 on.</para>
1535 </listitem>
1536 </itemizedlist>
1537
1538 The following syntax is stolen:
1539
1540 <variablelist>
1541 <varlistentry>
1542 <term>
1543 <literal>forall</literal>
1544 <indexterm><primary><literal>forall</literal></primary></indexterm>
1545 </term>
1546 <listitem><para>
1547 Stolen (in types) by: <option>-XScopedTypeVariables</option>,
1548 <option>-XLiberalTypeSynonyms</option>,
1549 <option>-XRank2Types</option>,
1550 <option>-XRankNTypes</option>,
1551 <option>-XPolymorphicComponents</option>,
1552 <option>-XExistentialQuantification</option>
1553 </para></listitem>
1554 </varlistentry>
1555
1556 <varlistentry>
1557 <term>
1558 <literal>mdo</literal>
1559 <indexterm><primary><literal>mdo</literal></primary></indexterm>
1560 </term>
1561 <listitem><para>
1562 Stolen by: <option>-XRecursiveDo</option>,
1563 </para></listitem>
1564 </varlistentry>
1565
1566 <varlistentry>
1567 <term>
1568 <literal>foreign</literal>
1569 <indexterm><primary><literal>foreign</literal></primary></indexterm>
1570 </term>
1571 <listitem><para>
1572 Stolen by: <option>-XForeignFunctionInterface</option>,
1573 </para></listitem>
1574 </varlistentry>
1575
1576 <varlistentry>
1577 <term>
1578 <literal>rec</literal>,
1579 <literal>proc</literal>, <literal>-&lt;</literal>,
1580 <literal>&gt;-</literal>, <literal>-&lt;&lt;</literal>,
1581 <literal>&gt;&gt;-</literal>, and <literal>(|</literal>,
1582 <literal>|)</literal> brackets
1583 <indexterm><primary><literal>proc</literal></primary></indexterm>
1584 </term>
1585 <listitem><para>
1586 Stolen by: <option>-XArrows</option>,
1587 </para></listitem>
1588 </varlistentry>
1589
1590 <varlistentry>
1591 <term>
1592 <literal>?<replaceable>varid</replaceable></literal>,
1593 <literal>%<replaceable>varid</replaceable></literal>
1594 <indexterm><primary>implicit parameters</primary></indexterm>
1595 </term>
1596 <listitem><para>
1597 Stolen by: <option>-XImplicitParams</option>,
1598 </para></listitem>
1599 </varlistentry>
1600
1601 <varlistentry>
1602 <term>
1603 <literal>[|</literal>,
1604 <literal>[e|</literal>, <literal>[p|</literal>,
1605 <literal>[d|</literal>, <literal>[t|</literal>,
1606 <literal>$(</literal>,
1607 <literal>$<replaceable>varid</replaceable></literal>
1608 <indexterm><primary>Template Haskell</primary></indexterm>
1609 </term>
1610 <listitem><para>
1611 Stolen by: <option>-XTemplateHaskell</option>,
1612 </para></listitem>
1613 </varlistentry>
1614
1615 <varlistentry>
1616 <term>
1617 <literal>[:<replaceable>varid</replaceable>|</literal>
1618 <indexterm><primary>quasi-quotation</primary></indexterm>
1619 </term>
1620 <listitem><para>
1621 Stolen by: <option>-XQuasiQuotes</option>,
1622 </para></listitem>
1623 </varlistentry>
1624
1625 <varlistentry>
1626 <term>
1627 <replaceable>varid</replaceable>{<literal>&num;</literal>},
1628 <replaceable>char</replaceable><literal>&num;</literal>,
1629 <replaceable>string</replaceable><literal>&num;</literal>,
1630 <replaceable>integer</replaceable><literal>&num;</literal>,
1631 <replaceable>float</replaceable><literal>&num;</literal>,
1632 <replaceable>float</replaceable><literal>&num;&num;</literal>,
1633 <literal>(&num;</literal>, <literal>&num;)</literal>,
1634 </term>
1635 <listitem><para>
1636 Stolen by: <option>-XMagicHash</option>,
1637 </para></listitem>
1638 </varlistentry>
1639 </variablelist>
1640 </para>
1641 </sect2>
1642 </sect1>
1643
1644
1645 <!-- TYPE SYSTEM EXTENSIONS -->
1646 <sect1 id="data-type-extensions">
1647 <title>Extensions to data types and type synonyms</title>
1648
1649 <sect2 id="nullary-types">
1650 <title>Data types with no constructors</title>
1651
1652 <para>With the <option>-fglasgow-exts</option> flag, GHC lets you declare
1653 a data type with no constructors. For example:</para>
1654
1655 <programlisting>
1656 data S -- S :: *
1657 data T a -- T :: * -> *
1658 </programlisting>
1659
1660 <para>Syntactically, the declaration lacks the "= constrs" part. The
1661 type can be parameterised over types of any kind, but if the kind is
1662 not <literal>*</literal> then an explicit kind annotation must be used
1663 (see <xref linkend="kinding"/>).</para>
1664
1665 <para>Such data types have only one value, namely bottom.
1666 Nevertheless, they can be useful when defining "phantom types".</para>
1667 </sect2>
1668
1669 <sect2 id="infix-tycons">
1670 <title>Infix type constructors, classes, and type variables</title>
1671
1672 <para>
1673 GHC allows type constructors, classes, and type variables to be operators, and
1674 to be written infix, very much like expressions. More specifically:
1675 <itemizedlist>
1676 <listitem><para>
1677 A type constructor or class can be an operator, beginning with a colon; e.g. <literal>:*:</literal>.
1678 The lexical syntax is the same as that for data constructors.
1679 </para></listitem>
1680 <listitem><para>
1681 Data type and type-synonym declarations can be written infix, parenthesised
1682 if you want further arguments. E.g.
1683 <screen>
1684 data a :*: b = Foo a b
1685 type a :+: b = Either a b
1686 class a :=: b where ...
1687
1688 data (a :**: b) x = Baz a b x
1689 type (a :++: b) y = Either (a,b) y
1690 </screen>
1691 </para></listitem>
1692 <listitem><para>
1693 Types, and class constraints, can be written infix. For example
1694 <screen>
1695 x :: Int :*: Bool
1696 f :: (a :=: b) => a -> b
1697 </screen>
1698 </para></listitem>
1699 <listitem><para>
1700 A type variable can be an (unqualified) operator e.g. <literal>+</literal>.
1701 The lexical syntax is the same as that for variable operators, excluding "(.)",
1702 "(!)", and "(*)". In a binding position, the operator must be
1703 parenthesised. For example:
1704 <programlisting>
1705 type T (+) = Int + Int
1706 f :: T Either
1707 f = Left 3
1708
1709 liftA2 :: Arrow (~>)
1710 => (a -> b -> c) -> (e ~> a) -> (e ~> b) -> (e ~> c)
1711 liftA2 = ...
1712 </programlisting>
1713 </para></listitem>
1714 <listitem><para>
1715 Back-quotes work
1716 as for expressions, both for type constructors and type variables; e.g. <literal>Int `Either` Bool</literal>, or
1717 <literal>Int `a` Bool</literal>. Similarly, parentheses work the same; e.g. <literal>(:*:) Int Bool</literal>.
1718 </para></listitem>
1719 <listitem><para>
1720 Fixities may be declared for type constructors, or classes, just as for data constructors. However,
1721 one cannot distinguish between the two in a fixity declaration; a fixity declaration
1722 sets the fixity for a data constructor and the corresponding type constructor. For example:
1723 <screen>
1724 infixl 7 T, :*:
1725 </screen>
1726 sets the fixity for both type constructor <literal>T</literal> and data constructor <literal>T</literal>,
1727 and similarly for <literal>:*:</literal>.
1728 <literal>Int `a` Bool</literal>.
1729 </para></listitem>
1730 <listitem><para>
1731 Function arrow is <literal>infixr</literal> with fixity 0. (This might change; I'm not sure what it should be.)
1732 </para></listitem>
1733
1734 </itemizedlist>
1735 </para>
1736 </sect2>
1737
1738 <sect2 id="type-synonyms">
1739 <title>Liberalised type synonyms</title>
1740
1741 <para>
1742 Type synonyms are like macros at the type level, but Haskell 98 imposes many rules
1743 on individual synonym declarations.
1744 With the <option>-XLiberalTypeSynonyms</option> extension,
1745 GHC does validity checking on types <emphasis>only after expanding type synonyms</emphasis>.
1746 That means that GHC can be very much more liberal about type synonyms than Haskell 98.
1747
1748 <itemizedlist>
1749 <listitem> <para>You can write a <literal>forall</literal> (including overloading)
1750 in a type synonym, thus:
1751 <programlisting>
1752 type Discard a = forall b. Show b => a -> b -> (a, String)
1753
1754 f :: Discard a
1755 f x y = (x, show y)
1756
1757 g :: Discard Int -> (Int,String) -- A rank-2 type
1758 g f = f 3 True
1759 </programlisting>
1760 </para>
1761 </listitem>
1762
1763 <listitem><para>
1764 If you also use <option>-XUnboxedTuples</option>,
1765 you can write an unboxed tuple in a type synonym:
1766 <programlisting>
1767 type Pr = (# Int, Int #)
1768
1769 h :: Int -> Pr
1770 h x = (# x, x #)
1771 </programlisting>
1772 </para></listitem>
1773
1774 <listitem><para>
1775 You can apply a type synonym to a forall type:
1776 <programlisting>
1777 type Foo a = a -> a -> Bool
1778
1779 f :: Foo (forall b. b->b)
1780 </programlisting>
1781 After expanding the synonym, <literal>f</literal> has the legal (in GHC) type:
1782 <programlisting>
1783 f :: (forall b. b->b) -> (forall b. b->b) -> Bool
1784 </programlisting>
1785 </para></listitem>
1786
1787 <listitem><para>
1788 You can apply a type synonym to a partially applied type synonym:
1789 <programlisting>
1790 type Generic i o = forall x. i x -> o x
1791 type Id x = x
1792
1793 foo :: Generic Id []
1794 </programlisting>
1795 After expanding the synonym, <literal>foo</literal> has the legal (in GHC) type:
1796 <programlisting>
1797 foo :: forall x. x -> [x]
1798 </programlisting>
1799 </para></listitem>
1800
1801 </itemizedlist>
1802 </para>
1803
1804 <para>
1805 GHC currently does kind checking before expanding synonyms (though even that
1806 could be changed.)
1807 </para>
1808 <para>
1809 After expanding type synonyms, GHC does validity checking on types, looking for
1810 the following mal-formedness which isn't detected simply by kind checking:
1811 <itemizedlist>
1812 <listitem><para>
1813 Type constructor applied to a type involving for-alls.
1814 </para></listitem>
1815 <listitem><para>
1816 Unboxed tuple on left of an arrow.
1817 </para></listitem>
1818 <listitem><para>
1819 Partially-applied type synonym.
1820 </para></listitem>
1821 </itemizedlist>
1822 So, for example,
1823 this will be rejected:
1824 <programlisting>
1825 type Pr = (# Int, Int #)
1826
1827 h :: Pr -> Int
1828 h x = ...
1829 </programlisting>
1830 because GHC does not allow unboxed tuples on the left of a function arrow.
1831 </para>
1832 </sect2>
1833
1834
1835 <sect2 id="existential-quantification">
1836 <title>Existentially quantified data constructors
1837 </title>
1838
1839 <para>
1840 The idea of using existential quantification in data type declarations
1841 was suggested by Perry, and implemented in Hope+ (Nigel Perry, <emphasis>The Implementation
1842 of Practical Functional Programming Languages</emphasis>, PhD Thesis, University of
1843 London, 1991). It was later formalised by Laufer and Odersky
1844 (<emphasis>Polymorphic type inference and abstract data types</emphasis>,
1845 TOPLAS, 16(5), pp1411-1430, 1994).
1846 It's been in Lennart
1847 Augustsson's <command>hbc</command> Haskell compiler for several years, and
1848 proved very useful. Here's the idea. Consider the declaration:
1849 </para>
1850
1851 <para>
1852
1853 <programlisting>
1854 data Foo = forall a. MkFoo a (a -> Bool)
1855 | Nil
1856 </programlisting>
1857
1858 </para>
1859
1860 <para>
1861 The data type <literal>Foo</literal> has two constructors with types:
1862 </para>
1863
1864 <para>
1865
1866 <programlisting>
1867 MkFoo :: forall a. a -> (a -> Bool) -> Foo
1868 Nil :: Foo
1869 </programlisting>
1870
1871 </para>
1872
1873 <para>
1874 Notice that the type variable <literal>a</literal> in the type of <function>MkFoo</function>
1875 does not appear in the data type itself, which is plain <literal>Foo</literal>.
1876 For example, the following expression is fine:
1877 </para>
1878
1879 <para>
1880
1881 <programlisting>
1882 [MkFoo 3 even, MkFoo 'c' isUpper] :: [Foo]
1883 </programlisting>
1884
1885 </para>
1886
1887 <para>
1888 Here, <literal>(MkFoo 3 even)</literal> packages an integer with a function
1889 <function>even</function> that maps an integer to <literal>Bool</literal>; and <function>MkFoo 'c'
1890 isUpper</function> packages a character with a compatible function. These
1891 two things are each of type <literal>Foo</literal> and can be put in a list.
1892 </para>
1893
1894 <para>
1895 What can we do with a value of type <literal>Foo</literal>?. In particular,
1896 what happens when we pattern-match on <function>MkFoo</function>?
1897 </para>
1898
1899 <para>
1900
1901 <programlisting>
1902 f (MkFoo val fn) = ???
1903 </programlisting>
1904
1905 </para>
1906
1907 <para>
1908 Since all we know about <literal>val</literal> and <function>fn</function> is that they
1909 are compatible, the only (useful) thing we can do with them is to
1910 apply <function>fn</function> to <literal>val</literal> to get a boolean. For example:
1911 </para>
1912
1913 <para>
1914
1915 <programlisting>
1916 f :: Foo -> Bool
1917 f (MkFoo val fn) = fn val
1918 </programlisting>
1919
1920 </para>
1921
1922 <para>
1923 What this allows us to do is to package heterogeneous values
1924 together with a bunch of functions that manipulate them, and then treat
1925 that collection of packages in a uniform manner. You can express
1926 quite a bit of object-oriented-like programming this way.
1927 </para>
1928
1929 <sect3 id="existential">
1930 <title>Why existential?
1931 </title>
1932
1933 <para>
1934 What has this to do with <emphasis>existential</emphasis> quantification?
1935 Simply that <function>MkFoo</function> has the (nearly) isomorphic type
1936 </para>
1937
1938 <para>
1939
1940 <programlisting>
1941 MkFoo :: (exists a . (a, a -> Bool)) -> Foo
1942 </programlisting>
1943
1944 </para>
1945
1946 <para>
1947 But Haskell programmers can safely think of the ordinary
1948 <emphasis>universally</emphasis> quantified type given above, thereby avoiding
1949 adding a new existential quantification construct.
1950 </para>
1951
1952 </sect3>
1953
1954 <sect3 id="existential-with-context">
1955 <title>Existentials and type classes</title>
1956
1957 <para>
1958 An easy extension is to allow
1959 arbitrary contexts before the constructor. For example:
1960 </para>
1961
1962 <para>
1963
1964 <programlisting>
1965 data Baz = forall a. Eq a => Baz1 a a
1966 | forall b. Show b => Baz2 b (b -> b)
1967 </programlisting>
1968
1969 </para>
1970
1971 <para>
1972 The two constructors have the types you'd expect:
1973 </para>
1974
1975 <para>
1976
1977 <programlisting>
1978 Baz1 :: forall a. Eq a => a -> a -> Baz
1979 Baz2 :: forall b. Show b => b -> (b -> b) -> Baz
1980 </programlisting>
1981
1982 </para>
1983
1984 <para>
1985 But when pattern matching on <function>Baz1</function> the matched values can be compared
1986 for equality, and when pattern matching on <function>Baz2</function> the first matched
1987 value can be converted to a string (as well as applying the function to it).
1988 So this program is legal:
1989 </para>
1990
1991 <para>
1992
1993 <programlisting>
1994 f :: Baz -> String
1995 f (Baz1 p q) | p == q = "Yes"
1996 | otherwise = "No"
1997 f (Baz2 v fn) = show (fn v)
1998 </programlisting>
1999
2000 </para>
2001
2002 <para>
2003 Operationally, in a dictionary-passing implementation, the
2004 constructors <function>Baz1</function> and <function>Baz2</function> must store the
2005 dictionaries for <literal>Eq</literal> and <literal>Show</literal> respectively, and
2006 extract it on pattern matching.
2007 </para>
2008
2009 </sect3>
2010
2011 <sect3 id="existential-records">
2012 <title>Record Constructors</title>
2013
2014 <para>
2015 GHC allows existentials to be used with records syntax as well. For example:
2016
2017 <programlisting>
2018 data Counter a = forall self. NewCounter
2019 { _this :: self
2020 , _inc :: self -> self
2021 , _display :: self -> IO ()
2022 , tag :: a
2023 }
2024 </programlisting>
2025 Here <literal>tag</literal> is a public field, with a well-typed selector
2026 function <literal>tag :: Counter a -> a</literal>. The <literal>self</literal>
2027 type is hidden from the outside; any attempt to apply <literal>_this</literal>,
2028 <literal>_inc</literal> or <literal>_display</literal> as functions will raise a
2029 compile-time error. In other words, <emphasis>GHC defines a record selector function
2030 only for fields whose type does not mention the existentially-quantified variables</emphasis>.
2031 (This example used an underscore in the fields for which record selectors
2032 will not be defined, but that is only programming style; GHC ignores them.)
2033 </para>
2034
2035 <para>
2036 To make use of these hidden fields, we need to create some helper functions:
2037
2038 <programlisting>
2039 inc :: Counter a -> Counter a
2040 inc (NewCounter x i d t) = NewCounter
2041 { _this = i x, _inc = i, _display = d, tag = t }
2042
2043 display :: Counter a -> IO ()
2044 display NewCounter{ _this = x, _display = d } = d x
2045 </programlisting>
2046
2047 Now we can define counters with different underlying implementations:
2048
2049 <programlisting>
2050 counterA :: Counter String
2051 counterA = NewCounter
2052 { _this = 0, _inc = (1+), _display = print, tag = "A" }
2053
2054 counterB :: Counter String
2055 counterB = NewCounter
2056 { _this = "", _inc = ('#':), _display = putStrLn, tag = "B" }
2057
2058 main = do
2059 display (inc counterA) -- prints "1"
2060 display (inc (inc counterB)) -- prints "##"
2061 </programlisting>
2062
2063 Record update syntax is supported for existentials (and GADTs):
2064 <programlisting>
2065 setTag :: Counter a -> a -> Counter a
2066 setTag obj t = obj{ tag = t }
2067 </programlisting>
2068 The rule for record update is this: <emphasis>
2069 the types of the updated fields may
2070 mention only the universally-quantified type variables
2071 of the data constructor. For GADTs, the field may mention only types
2072 that appear as a simple type-variable argument in the constructor's result
2073 type</emphasis>. For example:
2074 <programlisting>
2075 data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b } -- c is existential
2076 upd1 t x = t { f1=x } -- OK: upd1 :: T a b -> a' -> T a' b
2077 upd2 t x = t { f3=x } -- BAD (f3's type mentions c, which is
2078 -- existentially quantified)
2079
2080 data G a b where { G1 { g1::a, g2::c } :: G a [c] }
2081 upd3 g x = g { g1=x } -- OK: upd3 :: G a b -> c -> G c b
2082 upd4 g x = g { g2=x } -- BAD (f2's type mentions c, which is not a simple
2083 -- type-variable argument in G1's result type)
2084 </programlisting>
2085 </para>
2086
2087 </sect3>
2088
2089
2090 <sect3>
2091 <title>Restrictions</title>
2092
2093 <para>
2094 There are several restrictions on the ways in which existentially-quantified
2095 constructors can be use.
2096 </para>
2097
2098 <para>
2099
2100 <itemizedlist>
2101 <listitem>
2102
2103 <para>
2104 When pattern matching, each pattern match introduces a new,
2105 distinct, type for each existential type variable. These types cannot
2106 be unified with any other type, nor can they escape from the scope of
2107 the pattern match. For example, these fragments are incorrect:
2108
2109
2110 <programlisting>
2111 f1 (MkFoo a f) = a
2112 </programlisting>
2113
2114
2115 Here, the type bound by <function>MkFoo</function> "escapes", because <literal>a</literal>
2116 is the result of <function>f1</function>. One way to see why this is wrong is to
2117 ask what type <function>f1</function> has:
2118
2119
2120 <programlisting>
2121 f1 :: Foo -> a -- Weird!
2122 </programlisting>
2123
2124
2125 What is this "<literal>a</literal>" in the result type? Clearly we don't mean
2126 this:
2127
2128
2129 <programlisting>
2130 f1 :: forall a. Foo -> a -- Wrong!
2131 </programlisting>
2132
2133
2134 The original program is just plain wrong. Here's another sort of error
2135
2136
2137 <programlisting>
2138 f2 (Baz1 a b) (Baz1 p q) = a==q
2139 </programlisting>
2140
2141
2142 It's ok to say <literal>a==b</literal> or <literal>p==q</literal>, but
2143 <literal>a==q</literal> is wrong because it equates the two distinct types arising
2144 from the two <function>Baz1</function> constructors.
2145
2146
2147 </para>
2148 </listitem>
2149 <listitem>
2150
2151 <para>
2152 You can't pattern-match on an existentially quantified
2153 constructor in a <literal>let</literal> or <literal>where</literal> group of
2154 bindings. So this is illegal:
2155
2156
2157 <programlisting>
2158 f3 x = a==b where { Baz1 a b = x }
2159 </programlisting>
2160
2161 Instead, use a <literal>case</literal> expression:
2162
2163 <programlisting>
2164 f3 x = case x of Baz1 a b -> a==b
2165 </programlisting>
2166
2167 In general, you can only pattern-match
2168 on an existentially-quantified constructor in a <literal>case</literal> expression or
2169 in the patterns of a function definition.
2170
2171 The reason for this restriction is really an implementation one.
2172 Type-checking binding groups is already a nightmare without
2173 existentials complicating the picture. Also an existential pattern
2174 binding at the top level of a module doesn't make sense, because it's
2175 not clear how to prevent the existentially-quantified type "escaping".
2176 So for now, there's a simple-to-state restriction. We'll see how
2177 annoying it is.
2178
2179 </para>
2180 </listitem>
2181 <listitem>
2182
2183 <para>
2184 You can't use existential quantification for <literal>newtype</literal>
2185 declarations. So this is illegal:
2186
2187
2188 <programlisting>
2189 newtype T = forall a. Ord a => MkT a
2190 </programlisting>
2191
2192
2193 Reason: a value of type <literal>T</literal> must be represented as a
2194 pair of a dictionary for <literal>Ord t</literal> and a value of type
2195 <literal>t</literal>. That contradicts the idea that
2196 <literal>newtype</literal> should have no concrete representation.
2197 You can get just the same efficiency and effect by using
2198 <literal>data</literal> instead of <literal>newtype</literal>. If
2199 there is no overloading involved, then there is more of a case for
2200 allowing an existentially-quantified <literal>newtype</literal>,
2201 because the <literal>data</literal> version does carry an
2202 implementation cost, but single-field existentially quantified
2203 constructors aren't much use. So the simple restriction (no
2204 existential stuff on <literal>newtype</literal>) stands, unless there
2205 are convincing reasons to change it.
2206
2207
2208 </para>
2209 </listitem>
2210 <listitem>
2211
2212 <para>
2213 You can't use <literal>deriving</literal> to define instances of a
2214 data type with existentially quantified data constructors.
2215
2216 Reason: in most cases it would not make sense. For example:;
2217
2218 <programlisting>
2219 data T = forall a. MkT [a] deriving( Eq )
2220 </programlisting>
2221
2222 To derive <literal>Eq</literal> in the standard way we would need to have equality
2223 between the single component of two <function>MkT</function> constructors:
2224
2225 <programlisting>
2226 instance Eq T where
2227 (MkT a) == (MkT b) = ???
2228 </programlisting>
2229
2230 But <varname>a</varname> and <varname>b</varname> have distinct types, and so can't be compared.
2231 It's just about possible to imagine examples in which the derived instance
2232 would make sense, but it seems altogether simpler simply to prohibit such
2233 declarations. Define your own instances!
2234 </para>
2235 </listitem>
2236
2237 </itemizedlist>
2238
2239 </para>
2240
2241 </sect3>
2242 </sect2>
2243
2244 <!-- ====================== Generalised algebraic data types ======================= -->
2245
2246 <sect2 id="gadt-style">
2247 <title>Declaring data types with explicit constructor signatures</title>
2248
2249 <para>GHC allows you to declare an algebraic data type by
2250 giving the type signatures of constructors explicitly. For example:
2251 <programlisting>
2252 data Maybe a where
2253 Nothing :: Maybe a
2254 Just :: a -> Maybe a
2255 </programlisting>
2256 The form is called a "GADT-style declaration"
2257 because Generalised Algebraic Data Types, described in <xref linkend="gadt"/>,
2258 can only be declared using this form.</para>
2259 <para>Notice that GADT-style syntax generalises existential types (<xref linkend="existential-quantification"/>).
2260 For example, these two declarations are equivalent:
2261 <programlisting>
2262 data Foo = forall a. MkFoo a (a -> Bool)
2263 data Foo' where { MKFoo :: a -> (a->Bool) -> Foo' }
2264 </programlisting>
2265 </para>
2266 <para>Any data type that can be declared in standard Haskell-98 syntax
2267 can also be declared using GADT-style syntax.
2268 The choice is largely stylistic, but GADT-style declarations differ in one important respect:
2269 they treat class constraints on the data constructors differently.
2270 Specifically, if the constructor is given a type-class context, that
2271 context is made available by pattern matching. For example:
2272 <programlisting>
2273 data Set a where
2274 MkSet :: Eq a => [a] -> Set a
2275
2276 makeSet :: Eq a => [a] -> Set a
2277 makeSet xs = MkSet (nub xs)
2278
2279 insert :: a -> Set a -> Set a
2280 insert a (MkSet as) | a `elem` as = MkSet as
2281 | otherwise = MkSet (a:as)
2282 </programlisting>
2283 A use of <literal>MkSet</literal> as a constructor (e.g. in the definition of <literal>makeSet</literal>)
2284 gives rise to a <literal>(Eq a)</literal>
2285 constraint, as you would expect. The new feature is that pattern-matching on <literal>MkSet</literal>
2286 (as in the definition of <literal>insert</literal>) makes <emphasis>available</emphasis> an <literal>(Eq a)</literal>
2287 context. In implementation terms, the <literal>MkSet</literal> constructor has a hidden field that stores
2288 the <literal>(Eq a)</literal> dictionary that is passed to <literal>MkSet</literal>; so
2289 when pattern-matching that dictionary becomes available for the right-hand side of the match.
2290 In the example, the equality dictionary is used to satisfy the equality constraint
2291 generated by the call to <literal>elem</literal>, so that the type of
2292 <literal>insert</literal> itself has no <literal>Eq</literal> constraint.
2293 </para>
2294 <para>
2295 For example, one possible application is to reify dictionaries:
2296 <programlisting>
2297 data NumInst a where
2298 MkNumInst :: Num a => NumInst a
2299
2300 intInst :: NumInst Int
2301 intInst = MkNumInst
2302
2303 plus :: NumInst a -> a -> a -> a
2304 plus MkNumInst p q = p + q
2305 </programlisting>
2306 Here, a value of type <literal>NumInst a</literal> is equivalent
2307 to an explicit <literal>(Num a)</literal> dictionary.
2308 </para>
2309 <para>
2310 All this applies to constructors declared using the syntax of <xref linkend="existential-with-context"/>.
2311 For example, the <literal>NumInst</literal> data type above could equivalently be declared
2312 like this:
2313 <programlisting>
2314 data NumInst a
2315 = Num a => MkNumInst (NumInst a)
2316 </programlisting>
2317 Notice that, unlike the situation when declaring an existential, there is
2318 no <literal>forall</literal>, because the <literal>Num</literal> constrains the
2319 data type's universally quantified type variable <literal>a</literal>.
2320 A constructor may have both universal and existential type variables: for example,
2321 the following two declarations are equivalent:
2322 <programlisting>
2323 data T1 a
2324 = forall b. (Num a, Eq b) => MkT1 a b
2325 data T2 a where
2326 MkT2 :: (Num a, Eq b) => a -> b -> T2 a
2327 </programlisting>
2328 </para>
2329 <para>All this behaviour contrasts with Haskell 98's peculiar treatment of
2330 contexts on a data type declaration (Section 4.2.1 of the Haskell 98 Report).
2331 In Haskell 98 the definition
2332 <programlisting>
2333 data Eq a => Set' a = MkSet' [a]
2334 </programlisting>
2335 gives <literal>MkSet'</literal> the same type as <literal>MkSet</literal> above. But instead of
2336 <emphasis>making available</emphasis> an <literal>(Eq a)</literal> constraint, pattern-matching
2337 on <literal>MkSet'</literal> <emphasis>requires</emphasis> an <literal>(Eq a)</literal> constraint!
2338 GHC faithfully implements this behaviour, odd though it is. But for GADT-style declarations,
2339 GHC's behaviour is much more useful, as well as much more intuitive.
2340 </para>
2341
2342 <para>
2343 The rest of this section gives further details about GADT-style data
2344 type declarations.
2345
2346 <itemizedlist>
2347 <listitem><para>
2348 The result type of each data constructor must begin with the type constructor being defined.
2349 If the result type of all constructors
2350 has the form <literal>T a1 ... an</literal>, where <literal>a1 ... an</literal>
2351 are distinct type variables, then the data type is <emphasis>ordinary</emphasis>;
2352 otherwise is a <emphasis>generalised</emphasis> data type (<xref linkend="gadt"/>).
2353 </para></listitem>
2354
2355 <listitem><para>
2356 As with other type signatures, you can give a single signature for several data constructors.
2357 In this example we give a single signature for <literal>T1</literal> and <literal>T2</literal>:
2358 <programlisting>
2359 data T a where
2360 T1,T2 :: a -> T a
2361 T3 :: T a
2362 </programlisting>
2363 </para></listitem>
2364
2365 <listitem><para>
2366 The type signature of
2367 each constructor is independent, and is implicitly universally quantified as usual.
2368 Different constructors may have different universally-quantified type variables
2369 and different type-class constraints.
2370 For example, this is fine:
2371 <programlisting>
2372 data T a where
2373 T1 :: Eq b => b -> T b
2374 T2 :: (Show c, Ix c) => c -> [c] -> T c
2375 </programlisting>
2376 </para></listitem>
2377
2378 <listitem><para>
2379 Unlike a Haskell-98-style
2380 data type declaration, the type variable(s) in the "<literal>data Set a where</literal>" header
2381 have no scope. Indeed, one can write a kind signature instead:
2382 <programlisting>
2383 data Set :: * -> * where ...
2384 </programlisting>
2385 or even a mixture of the two:
2386 <programlisting>
2387 data Foo a :: (* -> *) -> * where ...
2388 </programlisting>
2389 The type variables (if given) may be explicitly kinded, so we could also write the header for <literal>Foo</literal>
2390 like this:
2391 <programlisting>
2392 data Foo a (b :: * -> *) where ...
2393 </programlisting>
2394 </para></listitem>
2395
2396
2397 <listitem><para>
2398 You can use strictness annotations, in the obvious places
2399 in the constructor type:
2400 <programlisting>
2401 data Term a where
2402 Lit :: !Int -> Term Int
2403 If :: Term Bool -> !(Term a) -> !(Term a) -> Term a
2404 Pair :: Term a -> Term b -> Term (a,b)
2405 </programlisting>
2406 </para></listitem>
2407
2408 <listitem><para>
2409 You can use a <literal>deriving</literal> clause on a GADT-style data type
2410 declaration. For example, these two declarations are equivalent
2411 <programlisting>
2412 data Maybe1 a where {
2413 Nothing1 :: Maybe1 a ;
2414 Just1 :: a -> Maybe1 a
2415 } deriving( Eq, Ord )
2416
2417 data Maybe2 a = Nothing2 | Just2 a
2418 deriving( Eq, Ord )
2419 </programlisting>
2420 </para></listitem>
2421
2422 <listitem><para>
2423 You can use record syntax on a GADT-style data type declaration:
2424
2425 <programlisting>
2426 data Person where
2427 Adult { name :: String, children :: [Person] } :: Person
2428 Child { name :: String } :: Person
2429 </programlisting>
2430 As usual, for every constructor that has a field <literal>f</literal>, the type of
2431 field <literal>f</literal> must be the same (modulo alpha conversion).
2432 </para>
2433 <para>
2434 At the moment, record updates are not yet possible with GADT-style declarations,
2435 so support is limited to record construction, selection and pattern matching.
2436 For example
2437 <programlisting>
2438 aPerson = Adult { name = "Fred", children = [] }
2439
2440 shortName :: Person -> Bool
2441 hasChildren (Adult { children = kids }) = not (null kids)
2442 hasChildren (Child {}) = False
2443 </programlisting>
2444 </para></listitem>
2445
2446 <listitem><para>
2447 As in the case of existentials declared using the Haskell-98-like record syntax
2448 (<xref linkend="existential-records"/>),
2449 record-selector functions are generated only for those fields that have well-typed
2450 selectors.
2451 Here is the example of that section, in GADT-style syntax:
2452 <programlisting>
2453 data Counter a where
2454 NewCounter { _this :: self
2455 , _inc :: self -> self
2456 , _display :: self -> IO ()
2457 , tag :: a
2458 }
2459 :: Counter a
2460 </programlisting>
2461 As before, only one selector function is generated here, that for <literal>tag</literal>.
2462 Nevertheless, you can still use all the field names in pattern matching and record construction.
2463 </para></listitem>
2464 </itemizedlist></para>
2465 </sect2>
2466
2467 <sect2 id="gadt">
2468 <title>Generalised Algebraic Data Types (GADTs)</title>
2469
2470 <para>Generalised Algebraic Data Types generalise ordinary algebraic data types
2471 by allowing constructors to have richer return types. Here is an example:
2472 <programlisting>
2473 data Term a where
2474 Lit :: Int -> Term Int
2475 Succ :: Term Int -> Term Int
2476 IsZero :: Term Int -> Term Bool
2477 If :: Term Bool -> Term a -> Term a -> Term a
2478 Pair :: Term a -> Term b -> Term (a,b)
2479 </programlisting>
2480 Notice that the return type of the constructors is not always <literal>Term a</literal>, as is the
2481 case with ordinary data types. This generality allows us to
2482 write a well-typed <literal>eval</literal> function
2483 for these <literal>Terms</literal>:
2484 <programlisting>
2485 eval :: Term a -> a
2486 eval (Lit i) = i
2487 eval (Succ t) = 1 + eval t
2488 eval (IsZero t) = eval t == 0
2489 eval (If b e1 e2) = if eval b then eval e1 else eval e2
2490 eval (Pair e1 e2) = (eval e1, eval e2)
2491 </programlisting>
2492 The key point about GADTs is that <emphasis>pattern matching causes type refinement</emphasis>.
2493 For example, in the right hand side of the equation
2494 <programlisting>
2495 eval :: Term a -> a
2496 eval (Lit i) = ...
2497 </programlisting>
2498 the type <literal>a</literal> is refined to <literal>Int</literal>. That's the whole point!
2499 A precise specification of the type rules is beyond what this user manual aspires to,
2500 but the design closely follows that described in
2501 the paper <ulink
2502 url="http://research.microsoft.com/%7Esimonpj/papers/gadt/">Simple
2503 unification-based type inference for GADTs</ulink>,
2504 (ICFP 2006).
2505 The general principle is this: <emphasis>type refinement is only carried out
2506 based on user-supplied type annotations</emphasis>.
2507 So if no type signature is supplied for <literal>eval</literal>, no type refinement happens,
2508 and lots of obscure error messages will
2509 occur. However, the refinement is quite general. For example, if we had:
2510 <programlisting>
2511 eval :: Term a -> a -> a
2512 eval (Lit i) j = i+j
2513 </programlisting>
2514 the pattern match causes the type <literal>a</literal> to be refined to <literal>Int</literal> (because of the type
2515 of the constructor <literal>Lit</literal>), and that refinement also applies to the type of <literal>j</literal>, and
2516 the result type of the <literal>case</literal> expression. Hence the addition <literal>i+j</literal> is legal.
2517 </para>
2518 <para>
2519 These and many other examples are given in papers by Hongwei Xi, and
2520 Tim Sheard. There is a longer introduction
2521 <ulink url="http://www.haskell.org/haskellwiki/GADT">on the wiki</ulink>,
2522 and Ralf Hinze's
2523 <ulink url="http://www.informatik.uni-bonn.de/~ralf/publications/With.pdf">Fun with phantom types</ulink> also has a number of examples. Note that papers
2524 may use different notation to that implemented in GHC.
2525 </para>
2526 <para>
2527 The rest of this section outlines the extensions to GHC that support GADTs. The extension is enabled with
2528 <option>-XGADTs</option>. The <option>-XGADTs</option> flag also sets <option>-XRelaxedPolyRec</option>.
2529 <itemizedlist>
2530 <listitem><para>
2531 A GADT can only be declared using GADT-style syntax (<xref linkend="gadt-style"/>);
2532 the old Haskell-98 syntax for data declarations always declares an ordinary data type.
2533 The result type of each constructor must begin with the type constructor being defined,
2534 but for a GADT the arguments to the type constructor can be arbitrary monotypes.
2535 For example, in the <literal>Term</literal> data
2536 type above, the type of each constructor must end with <literal>Term ty</literal>, but
2537 the <literal>ty</literal> need not be a type variable (e.g. the <literal>Lit</literal>
2538 constructor).
2539 </para></listitem>
2540
2541 <listitem><para>
2542 It's is permitted to declare an ordinary algebraic data type using GADT-style syntax.
2543 What makes a GADT into a GADT is not the syntax, but rather the presence of data constructors
2544 whose result type is not just <literal>T a b</literal>.
2545 </para></listitem>
2546
2547 <listitem><para>
2548 You cannot use a <literal>deriving</literal> clause for a GADT; only for
2549 an ordinary data type.
2550 </para></listitem>
2551
2552 <listitem><para>
2553 As mentioned in <xref linkend="gadt-style"/>, record syntax is supported.
2554 For example:
2555 <programlisting>
2556 data Term a where
2557 Lit { val :: Int } :: Term Int
2558 Succ { num :: Term Int } :: Term Int
2559 Pred { num :: Term Int } :: Term Int
2560 IsZero { arg :: Term Int } :: Term Bool
2561 Pair { arg1 :: Term a
2562 , arg2 :: Term b
2563 } :: Term (a,b)
2564 If { cnd :: Term Bool
2565 , tru :: Term a
2566 , fls :: Term a
2567 } :: Term a
2568 </programlisting>
2569 However, for GADTs there is the following additional constraint:
2570 every constructor that has a field <literal>f</literal> must have
2571 the same result type (modulo alpha conversion)
2572 Hence, in the above example, we cannot merge the <literal>num</literal>
2573 and <literal>arg</literal> fields above into a
2574 single name. Although their field types are both <literal>Term Int</literal>,
2575 their selector functions actually have different types:
2576
2577 <programlisting>
2578 num :: Term Int -> Term Int
2579 arg :: Term Bool -> Term Int
2580 </programlisting>
2581 </para></listitem>
2582
2583 <listitem><para>
2584 When pattern-matching against data constructors drawn from a GADT,
2585 for example in a <literal>case</literal> expression, the following rules apply:
2586 <itemizedlist>
2587 <listitem><para>The type of the scrutinee must be rigid.</para></listitem>
2588 <listitem><para>The type of the entire <literal>case</literal> expression must be rigid.</para></listitem>
2589 <listitem><para>The type of any free variable mentioned in any of
2590 the <literal>case</literal> alternatives must be rigid.</para></listitem>
2591 </itemizedlist>
2592 A type is "rigid" if it is completely known to the compiler at its binding site. The easiest
2593 way to ensure that a variable a rigid type is to give it a type signature.
2594 For more precise details see <ulink url="http://research.microsoft.com/%7Esimonpj/papers/gadt">
2595 Simple unification-based type inference for GADTs
2596 </ulink>. The criteria implemented by GHC are given in the Appendix.
2597
2598 </para></listitem>
2599
2600 </itemizedlist>
2601 </para>
2602
2603 </sect2>
2604 </sect1>
2605
2606 <!-- ====================== End of Generalised algebraic data types ======================= -->
2607
2608 <sect1 id="deriving">
2609 <title>Extensions to the "deriving" mechanism</title>
2610
2611 <sect2 id="deriving-inferred">
2612 <title>Inferred context for deriving clauses</title>
2613
2614 <para>
2615 The Haskell Report is vague about exactly when a <literal>deriving</literal> clause is
2616 legal. For example:
2617 <programlisting>
2618 data T0 f a = MkT0 a deriving( Eq )
2619 data T1 f a = MkT1 (f a) deriving( Eq )
2620 data T2 f a = MkT2 (f (f a)) deriving( Eq )
2621 </programlisting>
2622 The natural generated <literal>Eq</literal> code would result in these instance declarations:
2623 <programlisting>
2624 instance Eq a => Eq (T0 f a) where ...
2625 instance Eq (f a) => Eq (T1 f a) where ...
2626 instance Eq (f (f a)) => Eq (T2 f a) where ...
2627 </programlisting>
2628 The first of these is obviously fine. The second is still fine, although less obviously.
2629 The third is not Haskell 98, and risks losing termination of instances.
2630 </para>
2631 <para>
2632 GHC takes a conservative position: it accepts the first two, but not the third. The rule is this:
2633 each constraint in the inferred instance context must consist only of type variables,
2634 with no repetitions.
2635 </para>
2636 <para>
2637 This rule is applied regardless of flags. If you want a more exotic context, you can write
2638 it yourself, using the <link linkend="stand-alone-deriving">standalone deriving mechanism</link>.
2639 </para>
2640 </sect2>
2641
2642 <sect2 id="stand-alone-deriving">
2643 <title>Stand-alone deriving declarations</title>
2644
2645 <para>
2646 GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by <literal>-XStandaloneDeriving</literal>:
2647 <programlisting>
2648 data Foo a = Bar a | Baz String
2649
2650 deriving instance Eq a => Eq (Foo a)
2651 </programlisting>
2652 The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword
2653 <literal>deriving</literal>, and (b) the absence of the <literal>where</literal> part.
2654 You must supply a context (in the example the context is <literal>(Eq a)</literal>),
2655 exactly as you would in an ordinary instance declaration.
2656 (In contrast the context is inferred in a <literal>deriving</literal> clause
2657 attached to a data type declaration.)
2658
2659 A <literal>deriving instance</literal> declaration
2660 must obey the same rules concerning form and termination as ordinary instance declarations,
2661 controlled by the same flags; see <xref linkend="instance-decls"/>.
2662 </para>
2663 <para>
2664 Unlike a <literal>deriving</literal>
2665 declaration attached to a <literal>data</literal> declaration, the instance can be more specific
2666 than the data type (assuming you also use
2667 <literal>-XFlexibleInstances</literal>, <xref linkend="instance-rules"/>). Consider
2668 for example
2669 <programlisting>
2670 data Foo a = Bar a | Baz String
2671
2672 deriving instance Eq a => Eq (Foo [a])
2673 deriving instance Eq a => Eq (Foo (Maybe a))
2674 </programlisting>
2675 This will generate a derived instance for <literal>(Foo [a])</literal> and <literal>(Foo (Maybe a))</literal>,
2676 but other types such as <literal>(Foo (Int,Bool))</literal> will not be an instance of <literal>Eq</literal>.
2677 </para>
2678
2679 <para>The stand-alone syntax is generalised for newtypes in exactly the same
2680 way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>).
2681 For example:
2682 <programlisting>
2683 newtype Foo a = MkFoo (State Int a)
2684
2685 deriving instance MonadState Int Foo
2686 </programlisting>
2687 GHC always treats the <emphasis>last</emphasis> parameter of the instance
2688 (<literal>Foo</literal> in this example) as the type whose instance is being derived.
2689 </para>
2690
2691 </sect2>
2692
2693
2694 <sect2 id="deriving-typeable">
2695 <title>Deriving clause for extra classes (<literal>Typeable</literal>, <literal>Data</literal>, etc)</title>
2696
2697 <para>
2698 Haskell 98 allows the programmer to add "<literal>deriving( Eq, Ord )</literal>" to a data type
2699 declaration, to generate a standard instance declaration for classes specified in the <literal>deriving</literal> clause.
2700 In Haskell 98, the only classes that may appear in the <literal>deriving</literal> clause are the standard
2701 classes <literal>Eq</literal>, <literal>Ord</literal>,
2702 <literal>Enum</literal>, <literal>Ix</literal>, <literal>Bounded</literal>, <literal>Read</literal>, and <literal>Show</literal>.
2703 </para>
2704 <para>
2705 GHC extends this list with several more classes that may be automatically derived:
2706 <itemizedlist>
2707 <listitem><para> With <option>-XDeriveDataTypeable</option>, you can derive instances of the classes
2708 <literal>Typeable</literal>, and <literal>Data</literal>, defined in the library
2709 modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> respectively.
2710 </para>
2711 <para>An instance of <literal>Typeable</literal> can only be derived if the
2712 data type has seven or fewer type parameters, all of kind <literal>*</literal>.
2713 The reason for this is that the <literal>Typeable</literal> class is derived using the scheme
2714 described in
2715 <ulink url="http://research.microsoft.com/%7Esimonpj/papers/hmap/gmap2.ps">
2716 Scrap More Boilerplate: Reflection, Zips, and Generalised Casts
2717 </ulink>.
2718 (Section 7.4 of the paper describes the multiple <literal>Typeable</literal> classes that
2719 are used, and only <literal>Typeable1</literal> up to
2720 <literal>Typeable7</literal> are provided in the library.)
2721 In other cases, there is nothing to stop the programmer writing a <literal>TypableX</literal>
2722 class, whose kind suits that of the data type constructor, and
2723 then writing the data type instance by hand.
2724 </para>
2725 </listitem>
2726
2727 <listitem><para> With <option>-XDeriveFunctor</option>, you can derive instances of
2728 the class <literal>Functor</literal>,
2729 defined in <literal>GHC.Base</literal>.
2730 </para></listitem>
2731
2732 <listitem><para> With <option>-XDeriveFoldable</option>, you can derive instances of
2733 the class <literal>Foldable</literal>,
2734 defined in <literal>Data.Foldable</literal>.
2735 </para></listitem>
2736
2737 <listitem><para> With <option>-XDeriveTraversable</option>, you can derive instances of
2738 the class <literal>Traversable</literal>,
2739 defined in <literal>Data.Traversable</literal>.
2740 </para></listitem>
2741 </itemizedlist>
2742 In each case the appropriate class must be in scope before it
2743 can be mentioned in the <literal>deriving</literal> clause.
2744 </para>
2745 </sect2>
2746
2747 <sect2 id="newtype-deriving">
2748 <title>Generalised derived instances for newtypes</title>
2749
2750 <para>
2751 When you define an abstract type using <literal>newtype</literal>, you may want
2752 the new type to inherit some instances from its representation. In
2753 Haskell 98, you can inherit instances of <literal>Eq</literal>, <literal>Ord</literal>,
2754 <literal>Enum</literal> and <literal>Bounded</literal> by deriving them, but for any
2755 other classes you have to write an explicit instance declaration. For
2756 example, if you define
2757
2758 <programlisting>
2759 newtype Dollars = Dollars Int
2760 </programlisting>
2761
2762 and you want to use arithmetic on <literal>Dollars</literal>, you have to
2763 explicitly define an instance of <literal>Num</literal>:
2764
2765 <programlisting>
2766 instance Num Dollars where
2767 Dollars a + Dollars b = Dollars (a+b)
2768 ...
2769 </programlisting>
2770 All the instance does is apply and remove the <literal>newtype</literal>
2771 constructor. It is particularly galling that, since the constructor
2772 doesn't appear at run-time, this instance declaration defines a
2773 dictionary which is <emphasis>wholly equivalent</emphasis> to the <literal>Int</literal>
2774 dictionary, only slower!
2775 </para>
2776
2777
2778 <sect3> <title> Generalising the deriving clause </title>
2779 <para>
2780 GHC now permits such instances to be derived instead,
2781 using the flag <option>-XGeneralizedNewtypeDeriving</option>,
2782 so one can write
2783 <programlisting>
2784 newtype Dollars = Dollars Int deriving (Eq,Show,Num)
2785 </programlisting>
2786
2787 and the implementation uses the <emphasis>same</emphasis> <literal>Num</literal> dictionary
2788 for <literal>Dollars</literal> as for <literal>Int</literal>. Notionally, the compiler
2789 derives an instance declaration of the form
2790
2791 <programlisting>
2792 instance Num Int => Num Dollars
2793 </programlisting>
2794
2795 which just adds or removes the <literal>newtype</literal> constructor according to the type.
2796 </para>
2797 <para>
2798
2799 We can also derive instances of constructor classes in a similar
2800 way. For example, suppose we have implemented state and failure monad
2801 transformers, such that
2802
2803 <programlisting>
2804 instance Monad m => Monad (State s m)
2805 instance Monad m => Monad (Failure m)
2806 </programlisting>
2807 In Haskell 98, we can define a parsing monad by
2808 <programlisting>
2809 type Parser tok m a = State [tok] (Failure m) a
2810 </programlisting>
2811
2812 which is automatically a monad thanks to the instance declarations
2813 above. With the extension, we can make the parser type abstract,
2814 without needing to write an instance of class <literal>Monad</literal>, via
2815
2816 <programlisting>
2817 newtype Parser tok m a = Parser (State [tok] (Failure m) a)
2818 deriving Monad
2819 </programlisting>
2820 In this case the derived instance declaration is of the form
2821 <programlisting>
2822 instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)
2823 </programlisting>
2824
2825 Notice that, since <literal>Monad</literal> is a constructor class, the
2826 instance is a <emphasis>partial application</emphasis> of the new type, not the
2827 entire left hand side. We can imagine that the type declaration is
2828 "eta-converted" to generate the context of the instance
2829 declaration.
2830 </para>
2831 <para>
2832
2833 We can even derive instances of multi-parameter classes, provided the
2834 newtype is the last class parameter. In this case, a ``partial
2835 application'' of the class appears in the <literal>deriving</literal>
2836 clause. For example, given the class
2837
2838 <programlisting>
2839 class StateMonad s m | m -> s where ...
2840 instance Monad m => StateMonad s (State s m) where ...
2841 </programlisting>
2842 then we can derive an instance of <literal>StateMonad</literal> for <literal>Parser</literal>s by
2843 <programlisting>
2844 newtype Parser tok m a = Parser (State [tok] (Failure m) a)
2845 deriving (Monad, StateMonad [tok])
2846 </programlisting>
2847
2848 The derived instance is obtained by completing the application of the
2849 class to the new type:
2850
2851 <programlisting>
2852 instance StateMonad [tok] (State [tok] (Failure m)) =>
2853 StateMonad [tok] (Parser tok m)
2854 </programlisting>
2855 </para>
2856 <para>
2857
2858 As a result of this extension, all derived instances in newtype
2859 declarations are treated uniformly (and implemented just by reusing
2860 the dictionary for the representation type), <emphasis>except</emphasis>
2861 <literal>Show</literal> and <literal>Read</literal>, which really behave differently for
2862 the newtype and its representation.
2863 </para>
2864 </sect3>
2865
2866 <sect3> <title> A more precise specification </title>
2867 <para>
2868 Derived instance declarations are constructed as follows. Consider the
2869 declaration (after expansion of any type synonyms)
2870
2871 <programlisting>
2872 newtype T v1...vn = T' (t vk+1...vn) deriving (c1...cm)
2873 </programlisting>
2874
2875 where
2876 <itemizedlist>
2877 <listitem><para>
2878 The <literal>ci</literal> are partial applications of
2879 classes of the form <literal>C t1'...tj'</literal>, where the arity of <literal>C</literal>
2880 is exactly <literal>j+1</literal>. That is, <literal>C</literal> lacks exactly one type argument.
2881 </para></listitem>
2882 <listitem><para>
2883 The <literal>k</literal> is chosen so that <literal>ci (T v1...vk)</literal> is well-kinded.
2884 </para></listitem>
2885 <listitem><para>
2886 The type <literal>t</literal> is an arbitrary type.
2887 </para></listitem>
2888 <listitem><para>
2889 The type variables <literal>vk+1...vn</literal> do not occur in <literal>t</literal>,
2890 nor in the <literal>ci</literal>, and
2891 </para></listitem>
2892 <listitem><para>
2893 None of the <literal>ci</literal> is <literal>Read</literal>, <literal>Show</literal>,
2894 <literal>Typeable</literal>, or <literal>Data</literal>. These classes
2895 should not "look through" the type or its constructor. You can still
2896 derive these classes for a newtype, but it happens in the usual way, not
2897 via this new mechanism.
2898 </para></listitem>
2899 </itemizedlist>
2900 Then, for each <literal>ci</literal>, the derived instance
2901 declaration is:
2902 <programlisting>
2903 instance ci t => ci (T v1...vk)
2904 </programlisting>
2905 As an example which does <emphasis>not</emphasis> work, consider
2906 <programlisting>
2907 newtype NonMonad m s = NonMonad (State s m s) deriving Monad
2908 </programlisting>
2909 Here we cannot derive the instance
2910 <programlisting>
2911 instance Monad (State s m) => Monad (NonMonad m)
2912 </programlisting>
2913
2914 because the type variable <literal>s</literal> occurs in <literal>State s m</literal>,
2915 and so cannot be "eta-converted" away. It is a good thing that this
2916 <literal>deriving</literal> clause is rejected, because <literal>NonMonad m</literal> is
2917 not, in fact, a monad --- for the same reason. Try defining
2918 <literal>>>=</literal> with the correct type: you won't be able to.
2919 </para>
2920 <para>
2921
2922 Notice also that the <emphasis>order</emphasis> of class parameters becomes
2923 important, since we can only derive instances for the last one. If the
2924 <literal>StateMonad</literal> class above were instead defined as
2925
2926 <programlisting>
2927 class StateMonad m s | m -> s where ...
2928 </programlisting>
2929
2930 then we would not have been able to derive an instance for the
2931 <literal>Parser</literal> type above. We hypothesise that multi-parameter
2932 classes usually have one "main" parameter for which deriving new
2933 instances is most interesting.
2934 </para>
2935 <para>Lastly, all of this applies only for classes other than
2936 <literal>Read</literal>, <literal>Show</literal>, <literal>Typeable</literal>,
2937 and <literal>Data</literal>, for which the built-in derivation applies (section
2938 4.3.3. of the Haskell Report).
2939 (For the standard classes <literal>Eq</literal>, <literal>Ord</literal>,
2940 <literal>Ix</literal>, and <literal>Bounded</literal> it is immaterial whether
2941 the standard method is used or the one described here.)
2942 </para>
2943 </sect3>
2944 </sect2>
2945 </sect1>
2946
2947
2948 <!-- TYPE SYSTEM EXTENSIONS -->
2949 <sect1 id="type-class-extensions">
2950 <title>Class and instances declarations</title>
2951
2952 <sect2 id="multi-param-type-classes">
2953 <title>Class declarations</title>
2954
2955 <para>
2956 This section, and the next one, documents GHC's type-class extensions.
2957 There's lots of background in the paper <ulink
2958 url="http://research.microsoft.com/~simonpj/Papers/type-class-design-space/">Type
2959 classes: exploring the design space</ulink> (Simon Peyton Jones, Mark
2960 Jones, Erik Meijer).
2961 </para>
2962 <para>
2963 All the extensions are enabled by the <option>-fglasgow-exts</option> flag.
2964 </para>
2965
2966 <sect3>
2967 <title>Multi-parameter type classes</title>
2968 <para>
2969 Multi-parameter type classes are permitted. For example:
2970
2971
2972 <programlisting>
2973 class Collection c a where
2974 union :: c a -> c a -> c a
2975 ...etc.
2976 </programlisting>
2977
2978 </para>
2979 </sect3>
2980
2981 <sect3>
2982 <title>The superclasses of a class declaration</title>
2983
2984 <para>
2985 There are no restrictions on the context in a class declaration
2986 (which introduces superclasses), except that the class hierarchy must
2987 be acyclic. So these class declarations are OK:
2988
2989
2990 <programlisting>
2991 class Functor (m k) => FiniteMap m k where
2992 ...
2993
2994 class (Monad m, Monad (t m)) => Transform t m where
2995 lift :: m a -> (t m) a
2996 </programlisting>
2997
2998
2999 </para>
3000 <para>
3001 As in Haskell 98, The class hierarchy must be acyclic. However, the definition
3002 of "acyclic" involves only the superclass relationships. For example,
3003 this is OK:
3004
3005
3006 <programlisting>
3007 class C a where {
3008 op :: D b => a -> b -> b
3009 }
3010
3011 class C a => D a where { ... }
3012 </programlisting>
3013
3014
3015 Here, <literal>C</literal> is a superclass of <literal>D</literal>, but it's OK for a
3016 class operation <literal>op</literal> of <literal>C</literal> to mention <literal>D</literal>. (It
3017 would not be OK for <literal>D</literal> to be a superclass of <literal>C</literal>.)
3018 </para>
3019 </sect3>
3020
3021
3022
3023
3024 <sect3 id="class-method-types">
3025 <title>Class method types</title>
3026
3027 <para>
3028 Haskell 98 prohibits class method types to mention constraints on the
3029 class type variable, thus:
3030 <programlisting>
3031 class Seq s a where
3032 fromList :: [a] -> s a
3033 elem :: Eq a => a -> s a -> Bool
3034 </programlisting>
3035 The type of <literal>elem</literal> is illegal in Haskell 98, because it
3036 contains the constraint <literal>Eq a</literal>, constrains only the
3037 class type variable (in this case <literal>a</literal>).
3038 GHC lifts this restriction (flag <option>-XConstrainedClassMethods</option>).
3039 </para>
3040
3041
3042 </sect3>
3043 </sect2>
3044
3045 <sect2 id="functional-dependencies">
3046 <title>Functional dependencies
3047 </title>
3048
3049 <para> Functional dependencies are implemented as described by Mark Jones
3050 in &ldquo;<ulink url="http://citeseer.ist.psu.edu/jones00type.html">Type Classes with Functional Dependencies</ulink>&rdquo;, Mark P. Jones,
3051 In Proceedings of the 9th European Symposium on Programming,
3052 ESOP 2000, Berlin, Germany, March 2000, Springer-Verlag LNCS 1782,
3053 .
3054 </para>
3055 <para>
3056 Functional dependencies are introduced by a vertical bar in the syntax of a
3057 class declaration; e.g.
3058 <programlisting>
3059 class (Monad m) => MonadState s m | m -> s where ...
3060
3061 class Foo a b c | a b -> c where ...
3062 </programlisting>
3063 There should be more documentation, but there isn't (yet). Yell if you need it.
3064 </para>
3065
3066 <sect3><title>Rules for functional dependencies </title>
3067 <para>
3068 In a class declaration, all of the class type variables must be reachable (in the sense
3069 mentioned in <xref linkend="type-restrictions"/>)
3070 from the free variables of each method type.
3071 For example:
3072
3073 <programlisting>
3074 class Coll s a where
3075 empty :: s
3076 insert :: s -> a -> s
3077 </programlisting>
3078
3079 is not OK, because the type of <literal>empty</literal> doesn't mention
3080 <literal>a</literal>. Functional dependencies can make the type variable
3081 reachable:
3082 <programlisting>
3083 class Coll s a | s -> a where
3084 empty :: s
3085 insert :: s -> a -> s
3086 </programlisting>
3087
3088 Alternatively <literal>Coll</literal> might be rewritten
3089
3090 <programlisting>
3091 class Coll s a where
3092 empty :: s a
3093 insert :: s a -> a -> s a
3094 </programlisting>
3095
3096
3097 which makes the connection between the type of a collection of
3098 <literal>a</literal>'s (namely <literal>(s a)</literal>) and the element type <literal>a</literal>.
3099 Occasionally this really doesn't work, in which case you can split the
3100 class like this:
3101
3102
3103 <programlisting>
3104 class CollE s where
3105 empty :: s
3106
3107 class CollE s => Coll s a where
3108 insert :: s -> a -> s
3109 </programlisting>
3110 </para>
3111 </sect3>
3112
3113
3114 <sect3>
3115 <title>Background on functional dependencies</title>
3116
3117 <para>The following description of the motivation and use of functional dependencies is taken
3118 from the Hugs user manual, reproduced here (with minor changes) by kind
3119 permission of Mark Jones.
3120 </para>
3121 <para>
3122 Consider the following class, intended as part of a
3123 library for collection types:
3124 <programlisting>
3125 class Collects e ce where
3126 empty :: ce
3127 insert :: e -> ce -> ce
3128 member :: e -> ce -> Bool
3129 </programlisting>
3130 The type variable e used here represents the element type, while ce is the type
3131 of the container itself. Within this framework, we might want to define
3132 instances of this class for lists or characteristic functions (both of which
3133 can be used to represent collections of any equality type), bit sets (which can
3134 be used to represent collections of characters), or hash tables (which can be
3135 used to represent any collection whose elements have a hash function). Omitting
3136 standard implementation details, this would lead to the following declarations:
3137 <programlisting>
3138 instance Eq e => Collects e [e] where ...
3139 instance Eq e => Collects e (e -> Bool) where ...
3140 instance Collects Char BitSet where ...
3141 instance (Hashable e, Collects a ce)
3142 => Collects e (Array Int ce) where ...
3143 </programlisting>
3144 All this looks quite promising; we have a class and a range of interesting
3145 implementations. Unfortunately, there are some serious problems with the class
3146 declaration. First, the empty function has an ambiguous type:
3147 <programlisting>
3148 empty :: Collects e ce => ce
3149 </programlisting>
3150 By "ambiguous" we mean that there is a type variable e that appears on the left
3151 of the <literal>=&gt;</literal> symbol, but not on the right. The problem with
3152 this is that, according to the theoretical foundations of Haskell overloading,
3153 we cannot guarantee a well-defined semantics for any term with an ambiguous
3154 type.
3155 </para>
3156 <para>
3157 We can sidestep this specific problem by removing the empty member from the
3158 class declaration. However, although the remaining members, insert and member,
3159 do not have ambiguous types, we still run into problems when we try to use
3160 them. For example, consider the following two functions:
3161 <programlisting>
3162 f x y = insert x . insert y
3163 g = f True 'a'
3164 </programlisting>
3165 for which GHC infers the following types:
3166 <programlisting>
3167 f :: (Collects a c, Collects b c) => a -> b -> c -> c
3168 g :: (Collects Bool c, Collects Char c) => c -> c
3169 </programlisting>
3170 Notice that the type for f allows the two parameters x and y to be assigned
3171 different types, even though it attempts to insert each of the two values, one
3172 after the other, into the same collection. If we're trying to model collections
3173 that contain only one type of value, then this is clearly an inaccurate
3174 type. Worse still, the definition for g is accepted, without causing a type
3175 error. As a result, the error in this code will not be flagged at the point
3176 where it appears. Instead, it will show up only when we try to use g, which
3177 might even be in a different module.
3178 </para>
3179
3180 <sect4><title>An attempt to use constructor classes</title>
3181
3182 <para>
3183 Faced with the problems described above, some Haskell programmers might be
3184 tempted to use something like the following version of the class declaration:
3185 <programlisting>
3186 class Collects e c where
3187 empty :: c e
3188 insert :: e -> c e -> c e
3189 member :: e -> c e -> Bool
3190 </programlisting>
3191 The key difference here is that we abstract over the type constructor c that is
3192 used to form the collection type c e, and not over that collection type itself,
3193 represented by ce in the original class declaration. This avoids the immediate
3194 problems that we mentioned above: empty has type <literal>Collects e c => c
3195 e</literal>, which is not ambiguous.
3196 </para>
3197 <para>
3198 The function f from the previous section has a more accurate type:
3199 <programlisting>
3200 f :: (Collects e c) => e -> e -> c e -> c e
3201 </programlisting>
3202 The function g from the previous section is now rejected with a type error as
3203 we would hope because the type of f does not allow the two arguments to have
3204 different types.
3205 This, then, is an example of a multiple parameter class that does actually work
3206 quite well in practice, without ambiguity problems.
3207 There is, however, a catch. This version of the Collects class is nowhere near
3208 as general as the original class seemed to be: only one of the four instances
3209 for <literal>Collects</literal>
3210 given above can be used with this version of Collects because only one of
3211 them---the instance for lists---has a collection type that can be written in
3212 the form c e, for some type constructor c, and element type e.
3213 </para>
3214 </sect4>
3215
3216 <sect4><title>Adding functional dependencies</title>
3217
3218 <para>
3219 To get a more useful version of the Collects class, Hugs provides a mechanism
3220 that allows programmers to specify dependencies between the parameters of a
3221 multiple parameter class (For readers with an interest in theoretical
3222 foundations and previous work: The use of dependency information can be seen
3223 both as a generalization of the proposal for `parametric type classes' that was
3224 put forward by Chen, Hudak, and Odersky, or as a special case of Mark Jones's
3225 later framework for "improvement" of qualified types. The
3226 underlying ideas are also discussed in a more theoretical and abstract setting
3227 in a manuscript [implparam], where they are identified as one point in a
3228 general design space for systems of implicit parameterization.).
3229
3230 To start with an abstract example, consider a declaration such as:
3231 <programlisting>
3232 class C a b where ...
3233 </programlisting>
3234 which tells us simply that C can be thought of as a binary relation on types
3235 (or type constructors, depending on the kinds of a and b). Extra clauses can be
3236 included in the definition of classes to add information about dependencies
3237 between parameters, as in the following examples:
3238 <programlisting>
3239 class D a b | a -> b where ...
3240 class E a b | a -> b, b -> a where ...
3241 </programlisting>
3242 The notation <literal>a -&gt; b</literal> used here between the | and where
3243 symbols --- not to be
3244 confused with a function type --- indicates that the a parameter uniquely
3245 determines the b parameter, and might be read as "a determines b." Thus D is
3246 not just a relation, but actually a (partial) function. Similarly, from the two
3247 dependencies that are included in the definition of E, we can see that E
3248 represents a (partial) one-one mapping between types.
3249 </para>
3250 <para>
3251 More generally, dependencies take the form <literal>x1 ... xn -&gt; y1 ... ym</literal>,
3252 where x1, ..., xn, and y1, ..., yn are type variables with n&gt;0 and
3253 m&gt;=0, meaning that the y parameters are uniquely determined by the x
3254 parameters. Spaces can be used as separators if more than one variable appears
3255 on any single side of a dependency, as in <literal>t -&gt; a b</literal>. Note that a class may be
3256 annotated with multiple dependencies using commas as separators, as in the
3257 definition of E above. Some dependencies that we can write in this notation are
3258 redundant, and will be rejected because they don't serve any useful
3259 purpose, and may instead indicate an error in the program. Examples of
3260 dependencies like this include <literal>a -&gt; a </literal>,
3261 <literal>a -&gt; a a </literal>,
3262 <literal>a -&gt; </literal>, etc. There can also be
3263 some redundancy if multiple dependencies are given, as in
3264 <literal>a-&gt;b</literal>,
3265 <literal>b-&gt;c </literal>, <literal>a-&gt;c </literal>, and
3266 in which some subset implies the remaining dependencies. Examples like this are
3267 not treated as errors. Note that dependencies appear only in class
3268 declarations, and not in any other part of the language. In particular, the
3269 syntax for instance declarations, class constraints, and types is completely
3270 unchanged.
3271 </para>
3272 <para>
3273 By including dependencies in a class declaration, we provide a mechanism for
3274 the programmer to specify each multiple parameter class more precisely. The
3275 compiler, on the other hand, is responsible for ensuring that the set of
3276 instances that are in scope at any given point in the program is consistent
3277 with any declared dependencies. For example, the following pair of instance
3278 declarations cannot appear together in the same scope because they violate the
3279 dependency for D, even though either one on its own would be acceptable:
3280 <programlisting>
3281 instance D Bool Int where ...
3282 instance D Bool Char where ...
3283 </programlisting>
3284 Note also that the following declaration is not allowed, even by itself:
3285 <programlisting>
3286 instance D [a] b where ...
3287 </programlisting>
3288 The problem here is that this instance would allow one particular choice of [a]
3289 to be associated with more than one choice for b, which contradicts the
3290 dependency specified in the definition of D. More generally, this means that,
3291 in any instance of the form:
3292 <programlisting>
3293 instance D t s where ...
3294 </programlisting>
3295 for some particular types t and s, the only variables that can appear in s are
3296 the ones that appear in t, and hence, if the type t is known, then s will be
3297 uniquely determined.
3298 </para>
3299 <para>
3300 The benefit of including dependency information is that it allows us to define
3301 more general multiple parameter classes, without ambiguity problems, and with
3302 the benefit of more accurate types. To illustrate this, we return to the
3303 collection class example, and annotate the original definition of <literal>Collects</literal>
3304 with a simple dependency:
3305 <programlisting>
3306 class Collects e ce | ce -> e where
3307 empty :: ce
3308 insert :: e -> ce -> ce
3309 member :: e -> ce -> Bool
3310 </programlisting>
3311 The dependency <literal>ce -&gt; e</literal> here specifies that the type e of elements is uniquely
3312 determined by the type of the collection ce. Note that both parameters of
3313 Collects are of kind *; there are no constructor classes here. Note too that
3314 all of the instances of Collects that we gave earlier can be used
3315 together with this new definition.
3316 </para>
3317 <para>
3318 What about the ambiguity problems that we encountered with the original
3319 definition? The empty function still has type Collects e ce => ce, but it is no
3320 longer necessary to regard that as an ambiguous type: Although the variable e
3321 does not appear on the right of the => symbol, the dependency for class
3322 Collects tells us that it is uniquely determined by ce, which does appear on
3323 the right of the => symbol. Hence the context in which empty is used can still
3324 give enough information to determine types for both ce and e, without
3325 ambiguity. More generally, we need only regard a type as ambiguous if it
3326 contains a variable on the left of the => that is not uniquely determined
3327 (either directly or indirectly) by the variables on the right.
3328 </para>
3329 <para>
3330 Dependencies also help to produce more accurate types for user defined
3331 functions, and hence to provide earlier detection of errors, and less cluttered
3332 types for programmers to work with. Recall the previous definition for a
3333 function f:
3334 <programlisting>
3335 f x y = insert x y = insert x . insert y
3336 </programlisting>
3337 for which we originally obtained a type:
3338 <programlisting>
3339 f :: (Collects a c, Collects b c) => a -> b -> c -> c
3340 </programlisting>
3341 Given the dependency information that we have for Collects, however, we can
3342 deduce that a and b must be equal because they both appear as the second
3343 parameter in a Collects constraint with the same first parameter c. Hence we
3344 can infer a shorter and more accurate type for f:
3345 <programlisting>
3346 f :: (Collects a c) => a -> a -> c -> c
3347 </programlisting>
3348 In a similar way, the earlier definition of g will now be flagged as a type error.
3349 </para>
3350 <para>
3351 Although we have given only a few examples here, it should be clear that the
3352 addition of dependency information can help to make multiple parameter classes
3353 more useful in practice, avoiding ambiguity problems, and allowing more general
3354 sets of instance declarations.
3355 </para>
3356 </sect4>
3357 </sect3>
3358 </sect2>
3359
3360 <sect2 id="instance-decls">
3361 <title>Instance declarations</title>
3362
3363 <para>An instance declaration has the form
3364 <screen>
3365 instance ( <replaceable>assertion</replaceable><subscript>1</subscript>, ..., <replaceable>assertion</replaceable><subscript>n</subscript>) =&gt; <replaceable>class</replaceable> <replaceable>type</replaceable><subscript>1</subscript> ... <replaceable>type</replaceable><subscript>m</subscript> where ...
3366 </screen>
3367 The part before the "<literal>=&gt;</literal>" is the
3368 <emphasis>context</emphasis>, while the part after the
3369 "<literal>=&gt;</literal>" is the <emphasis>head</emphasis> of the instance declaration.
3370 </para>
3371
3372 <sect3 id="flexible-instance-head">
3373 <title>Relaxed rules for the instance head</title>
3374
3375 <para>
3376 In Haskell 98 the head of an instance declaration
3377 must be of the form <literal>C (T a1 ... an)</literal>, where
3378 <literal>C</literal> is the class, <literal>T</literal> is a data type constructor,
3379 and the <literal>a1 ... an</literal> are distinct type variables.
3380 GHC relaxes these rules in two ways.
3381 <itemizedlist>
3382 <listitem>
3383 <para>
3384 The <option>-XFlexibleInstances</option> flag allows the head of the instance
3385 declaration to mention arbitrary nested types.
3386 For example, this becomes a legal instance declaration
3387 <programlisting>
3388 instance C (Maybe Int) where ...
3389 </programlisting>
3390 See also the <link linkend="instance-overlap">rules on overlap</link>.
3391 </para></listitem>
3392 <listitem><para>
3393 With the <option>-XTypeSynonymInstances</option> flag, instance heads may use type
3394 synonyms. As always, using a type synonym is just shorthand for
3395 writing the RHS of the type synonym definition. For example:
3396
3397
3398 <programlisting>
3399 type Point = (Int,Int)
3400 instance C Point where ...
3401 instance C [Point] where ...
3402 </programlisting>
3403
3404
3405 is legal. However, if you added
3406
3407
3408 <programlisting>
3409 instance C (Int,Int) where ...
3410 </programlisting>
3411
3412
3413 as well, then the compiler will complain about the overlapping
3414 (actually, identical) instance declarations. As always, type synonyms
3415 must be fully applied. You cannot, for example, write:
3416
3417 <programlisting>
3418 type P a = [[a]]
3419 instance Monad P where ...
3420 </programlisting>
3421
3422 </para></listitem>
3423 </itemizedlist>
3424 </para>
3425 </sect3>
3426
3427 <sect3 id="instance-rules">
3428 <title>Relaxed rules for instance contexts</title>
3429
3430 <para>In Haskell 98, the assertions in the context of the instance declaration
3431 must be of the form <literal>C a</literal> where <literal>a</literal>
3432 is a type variable that occurs in the head.
3433 </para>
3434
3435 <para>
3436 The <option>-XFlexibleContexts</option> flag relaxes this rule, as well
3437 as the corresponding rule for type signatures (see <xref linkend="flexible-contexts"/>).
3438 With this flag the context of the instance declaration can each consist of arbitrary
3439 (well-kinded) assertions <literal>(C t1 ... tn)</literal> subject only to the
3440 following rules:
3441 <orderedlist>
3442 <listitem><para>
3443 The Paterson Conditions: for each assertion in the context
3444 <orderedlist>
3445 <listitem><para>No type variable has more occurrences in the assertion than in the head</para></listitem>
3446 <listitem><para>The assertion has fewer constructors and variables (taken together
3447 and counting repetitions) than the head</para></listitem>
3448 </orderedlist>
3449 </para></listitem>
3450
3451 <listitem><para>The Coverage Condition. For each functional dependency,
3452 <replaceable>tvs</replaceable><subscript>left</subscript> <literal>-&gt;</literal>
3453 <replaceable>tvs</replaceable><subscript>right</subscript>, of the class,
3454 every type variable in
3455 S(<replaceable>tvs</replaceable><subscript>right</subscript>) must appear in
3456 S(<replaceable>tvs</replaceable><subscript>left</subscript>), where S is the
3457 substitution mapping each type variable in the class declaration to the
3458 corresponding type in the instance declaration.
3459 </para></listitem>
3460 </orderedlist>
3461 These restrictions ensure that context reduction terminates: each reduction
3462 step makes the problem smaller by at least one
3463 constructor. Both the Paterson Conditions and the Coverage Condition are lifted
3464 if you give the <option>-XUndecidableInstances</option>
3465 flag (<xref linkend="undecidable-instances"/>).
3466 You can find lots of background material about the reason for these
3467 restrictions in the paper <ulink
3468 url="http://research.microsoft.com/%7Esimonpj/papers/fd%2Dchr/">
3469 Understanding functional dependencies via Constraint Handling Rules</ulink>.
3470 </para>
3471 <para>
3472 For example, these are OK:
3473 <programlisting>
3474 instance C Int [a] -- Multiple parameters
3475 instance Eq (S [a]) -- Structured type in head
3476
3477 -- Repeated type variable in head
3478 instance C4 a a => C4 [a] [a]
3479 instance Stateful (ST s) (MutVar s)
3480
3481 -- Head can consist of type variables only
3482 instance C a
3483 instance (Eq a, Show b) => C2 a b
3484
3485 -- Non-type variables in context
3486 instance Show (s a) => Show (Sized s a)
3487 instance C2 Int a => C3 Bool [a]
3488 instance C2 Int a => C3 [a] b
3489 </programlisting>
3490 But these are not:
3491 <programlisting>
3492 -- Context assertion no smaller than head
3493 instance C a => C a where ...
3494 -- (C b b) has more more occurrences of b than the head
3495 instance C b b => Foo [b] where ...
3496 </programlisting>
3497 </para>
3498
3499 <para>
3500 The same restrictions apply to instances generated by
3501 <literal>deriving</literal> clauses. Thus the following is accepted:
3502 <programlisting>
3503 data MinHeap h a = H a (h a)
3504 deriving (Show)
3505 </programlisting>
3506 because the derived instance
3507 <programlisting>
3508 instance (Show a, Show (h a)) => Show (MinHeap h a)
3509 </programlisting>
3510 conforms to the above rules.
3511 </para>
3512
3513 <para>
3514 A useful idiom permitted by the above rules is as follows.
3515 If one allows overlapping instance declarations then it's quite
3516 convenient to have a "default instance" declaration that applies if
3517 something more specific does not:
3518 <programlisting>
3519 instance C a where
3520 op = ... -- Default
3521 </programlisting>
3522 </para>
3523 </sect3>
3524
3525 <sect3 id="undecidable-instances">
3526 <title>Undecidable instances</title>
3527
3528 <para>
3529 Sometimes even the rules of <xref linkend="instance-rules"/> are too onerous.
3530 For example, sometimes you might want to use the following to get the
3531 effect of a "class synonym":
3532 <programlisting>
3533 class (C1 a, C2 a, C3 a) => C a where { }
3534
3535 instance (C1 a, C2 a, C3 a) => C a where { }
3536 </programlisting>
3537 This allows you to write shorter signatures:
3538 <programlisting>
3539 f :: C a => ...
3540 </programlisting>
3541 instead of
3542 <programlisting>
3543 f :: (C1 a, C2 a, C3 a) => ...
3544 </programlisting>
3545 The restrictions on functional dependencies (<xref
3546 linkend="functional-dependencies"/>) are particularly troublesome.
3547 It is tempting to introduce type variables in the context that do not appear in
3548 the head, something that is excluded by the normal rules. For example:
3549 <programlisting>
3550 class HasConverter a b | a -> b where
3551 convert :: a -> b
3552
3553 data Foo a = MkFoo a
3554
3555 instance (HasConverter a b,Show b) => Show (Foo a) where
3556 show (MkFoo value) = show (convert value)
3557 </programlisting>
3558 This is dangerous territory, however. Here, for example, is a program that would make the
3559 typechecker loop:
3560 <programlisting>
3561 class D a
3562 class F a b | a->b
3563 instance F [a] [[a]]
3564 instance (D c, F a c) => D [a] -- 'c' is not mentioned in the head
3565 </programlisting>
3566 Similarly, it can be tempting to lift the coverage condition:
3567 <programlisting>
3568 class Mul a b c | a b -> c where
3569 (.*.) :: a -> b -> c
3570
3571 instance Mul Int Int Int where (.*.) = (*)
3572 instance Mul Int Float Float where x .*. y = fromIntegral x * y
3573 instance Mul a b c => Mul a [b] [c] where x .*. v = map (x.*.) v
3574 </programlisting>
3575 The third instance declaration does not obey the coverage condition;
3576 and indeed the (somewhat strange) definition:
3577 <programlisting>
3578 f = \ b x y -> if b then x .*. [y] else y
3579 </programlisting>
3580 makes instance inference go into a loop, because it requires the constraint
3581 <literal>(Mul a [b] b)</literal>.
3582 </para>
3583 <para>
3584 Nevertheless, GHC allows you to experiment with more liberal rules. If you use
3585 the experimental flag <option>-XUndecidableInstances</option>
3586 <indexterm><primary>-XUndecidableInstances</primary></indexterm>,
3587 both the Paterson Conditions and the Coverage Condition
3588 (described in <xref linkend="instance-rules"/>) are lifted. Termination is ensured by having a
3589 fixed-depth recursion stack. If you exceed the stack depth you get a
3590 sort of backtrace, and the opportunity to increase the stack depth
3591 with <option>-fcontext-stack=</option><emphasis>N</emphasis>.
3592 </para>
3593
3594 </sect3>
3595
3596
3597 <sect3 id="instance-overlap">
3598 <title>Overlapping instances</title>
3599 <para>
3600 In general, <emphasis>GHC requires that that it be unambiguous which instance
3601 declaration
3602 should be used to resolve a type-class constraint</emphasis>. This behaviour
3603 can be modified by two flags: <option>-XOverlappingInstances</option>
3604 <indexterm><primary>-XOverlappingInstances
3605 </primary></indexterm>
3606 and <option>-XIncoherentInstances</option>
3607 <indexterm><primary>-XIncoherentInstances
3608 </primary></indexterm>, as this section discusses. Both these
3609 flags are dynamic flags, and can be set on a per-module basis, using
3610 an <literal>OPTIONS_GHC</literal> pragma if desired (<xref linkend="source-file-options"/>).</para>
3611 <para>
3612 When GHC tries to resolve, say, the constraint <literal>C Int Bool</literal>,
3613 it tries to match every instance declaration against the
3614 constraint,
3615 by instantiating the head of the instance declaration. For example, consider
3616 these declarations:
3617 <programlisting>
3618 instance context1 => C Int a where ... -- (A)
3619 instance context2 => C a Bool where ... -- (B)
3620 instance context3 => C Int [a] where ... -- (C)
3621 instance context4 => C Int [Int] where ... -- (D)
3622 </programlisting>
3623 The instances (A) and (B) match the constraint <literal>C Int Bool</literal>,
3624 but (C) and (D) do not. When matching, GHC takes
3625 no account of the context of the instance declaration
3626 (<literal>context1</literal> etc).
3627 GHC's default behaviour is that <emphasis>exactly one instance must match the
3628 constraint it is trying to resolve</emphasis>.
3629 It is fine for there to be a <emphasis>potential</emphasis> of overlap (by
3630 including both declarations (A) and (B), say); an error is only reported if a
3631 particular constraint matches more than one.
3632 </para>
3633
3634 <para>
3635 The <option>-XOverlappingInstances</option> flag instructs GHC to allow
3636 more than one instance to match, provided there is a most specific one. For
3637 example, the constraint <literal>C Int [Int]</literal> matches instances (A),
3638 (C) and (D), but the last is more specific, and hence is chosen. If there is no
3639 most-specific match, the program is rejected.
3640 </para>
3641 <para>
3642 However, GHC is conservative about committing to an overlapping instance. For example:
3643 <programlisting>
3644 f :: [b] -> [b]
3645 f x = ...
3646 </programlisting>
3647 Suppose that from the RHS of <literal>f</literal> we get the constraint
3648 <literal>C Int [b]</literal>. But
3649 GHC does not commit to instance (C), because in a particular
3650 call of <literal>f</literal>, <literal>b</literal> might be instantiate
3651 to <literal>Int</literal>, in which case instance (D) would be more specific still.
3652 So GHC rejects the program.
3653 (If you add the flag <option>-XIncoherentInstances</option>,
3654 GHC will instead pick (C), without complaining about
3655 the problem of subsequent instantiations.)
3656 </para>
3657 <para>
3658 Notice that we gave a type signature to <literal>f</literal>, so GHC had to
3659 <emphasis>check</emphasis> that <literal>f</literal> has the specified type.
3660 Suppose instead we do not give a type signature, asking GHC to <emphasis>infer</emphasis>
3661 it instead. In this case, GHC will refrain from
3662 simplifying the constraint <literal>C Int [b]</literal> (for the same reason
3663 as before) but, rather than rejecting the program, it will infer the type
3664 <programlisting>
3665 f :: C Int [b] => [b] -> [b]
3666 </programlisting>
3667 That postpones the question of which instance to pick to the
3668 call site for <literal>f</literal>
3669 by which time more is known about the type <literal>b</literal>.
3670 You can write this type signature yourself if you use the
3671 <link linkend="flexible-contexts"><option>-XFlexibleContexts</option></link>
3672 flag.
3673 </para>
3674 <para>
3675 Exactly the same situation can arise in instance declarations themselves. Suppose we have
3676 <programlisting>
3677 class Foo a where
3678 f :: a -> a
3679 instance Foo [b] where
3680 f x = ...
3681 </programlisting>
3682 and, as before, the constraint <literal>C Int [b]</literal> arises from <literal>f</literal>'s
3683 right hand side. GHC will reject the instance, complaining as before that it does not know how to resolve
3684 the constraint <literal>C Int [b]</literal>, because it matches more than one instance
3685 declaration. The solution is to postpone the choice by adding the constraint to the context
3686 of the instance declaration, thus:
3687 <programlisting>
3688 instance C Int [b] => Foo [b] where
3689 f x = ...
3690 </programlisting>
3691 (You need <link linkend="instance-rules"><option>-XFlexibleInstances</option></link> to do this.)
3692 </para>
3693 <para>
3694 The willingness to be overlapped or incoherent is a property of
3695 the <emphasis>instance declaration</emphasis> itself, controlled by the
3696 presence or otherwise of the <option>-XOverlappingInstances</option>
3697 and <option>-XIncoherentInstances</option> flags when that module is
3698 being defined. Neither flag is required in a module that imports and uses the
3699 instance declaration. Specifically, during the lookup process:
3700 <itemizedlist>
3701 <listitem><para>
3702 An instance declaration is ignored during the lookup process if (a) a more specific
3703 match is found, and (b) the instance declaration was compiled with
3704 <option>-XOverlappingInstances</option>. The flag setting for the
3705 more-specific instance does not matter.
3706 </para></listitem>
3707 <listitem><para>
3708 Suppose an instance declaration does not match the constraint being looked up, but
3709 does unify with it, so that it might match when the constraint is further
3710 instantiated. Usually GHC will regard this as a reason for not committing to
3711 some other constraint. But if the instance declaration was compiled with
3712 <option>-XIncoherentInstances</option>, GHC will skip the "does-it-unify?"
3713 check for that declaration.
3714 </para></listitem>
3715 </itemizedlist>
3716 These rules make it possible for a library author to design a library that relies on
3717 overlapping instances without the library client having to know.
3718 </para>
3719 <para>
3720 If an instance declaration is compiled without
3721 <option>-XOverlappingInstances</option>,
3722 then that instance can never be overlapped. This could perhaps be
3723 inconvenient. Perhaps the rule should instead say that the
3724 <emphasis>overlapping</emphasis> instance declaration should be compiled in
3725 this way, rather than the <emphasis>overlapped</emphasis> one. Perhaps overlap
3726 at a usage site should be permitted regardless of how the instance declarations
3727 are compiled, if the <option>-XOverlappingInstances</option> flag is
3728 used at the usage site. (Mind you, the exact usage site can occasionally be
3729 hard to pin down.) We are interested to receive feedback on these points.
3730 </para>
3731 <para>The <option>-XIncoherentInstances</option> flag implies the
3732 <option>-XOverlappingInstances</option> flag, but not vice versa.
3733 </para>
3734 </sect3>
3735
3736
3737
3738 </sect2>
3739
3740 <sect2 id="overloaded-strings">
3741 <title>Overloaded string literals
3742 </title>
3743
3744 <para>
3745 GHC supports <emphasis>overloaded string literals</emphasis>. Normally a
3746 string literal has type <literal>String</literal>, but with overloaded string
3747 literals enabled (with <literal>-XOverloadedStrings</literal>)
3748 a string literal has type <literal>(IsString a) => a</literal>.
3749 </para>
3750 <para>
3751 This means that the usual string syntax can be used, e.g., for packed strings
3752 and other variations of string like types. String literals behave very much
3753 like integer literals, i.e., they can be used in both expressions and patterns.
3754 If used in a pattern the literal with be replaced by an equality test, in the same
3755 way as an integer literal is.
3756 </para>
3757 <para>
3758 The class <literal>IsString</literal> is defined as:
3759 <programlisting>
3760 class IsString a where
3761 fromString :: String -> a
3762 </programlisting>
3763 The only predefined instance is the obvious one to make strings work as usual:
3764 <programlisting>
3765 instance IsString [Char] where
3766 fromString cs = cs
3767 </programlisting>
3768 The class <literal>IsString</literal> is not in scope by default. If you want to mention
3769 it explicitly (for example, to give an instance declaration for it), you can import it
3770 from module <literal>GHC.Exts</literal>.
3771 </para>
3772 <para>
3773 Haskell's defaulting mechanism is extended to cover string literals, when <option>-XOverloadedStrings</option> is specified.
3774 Specifically:
3775 <itemizedlist>
3776 <listitem><para>
3777 Each type in a default declaration must be an
3778 instance of <literal>Num</literal> <emphasis>or</emphasis> of <literal>IsString</literal>.
3779 </para></listitem>
3780
3781 <listitem><para>
3782 The standard defaulting rule (<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.3.4">Haskell Report, Section 4.3.4</ulink>)
3783 is extended thus: defaulting applies when all the unresolved constraints involve standard classes
3784 <emphasis>or</emphasis> <literal>IsString</literal>; and at least one is a numeric class
3785 <emphasis>or</emphasis> <literal>IsString</literal>.
3786 </para></listitem>
3787 </itemizedlist>
3788 </para>
3789 <para>
3790 A small example:
3791 <programlisting>
3792 module Main where
3793
3794 import GHC.Exts( IsString(..) )
3795
3796 newtype MyString = MyString String deriving (Eq, Show)
3797 instance IsString MyString where
3798 fromString = MyString
3799
3800 greet :: MyString -> MyString
3801 greet "hello" = "world"
3802 greet other = other
3803
3804 main = do
3805 print $ greet "hello"
3806 print $ greet "fool"
3807 </programlisting>
3808 </para>
3809 <para>
3810 Note that deriving <literal>Eq</literal> is necessary for the pattern matching
3811 to work since it gets translated into an equality comparison.
3812 </para>
3813 </sect2>
3814
3815 </sect1>
3816
3817 <sect1 id="type-families">
3818 <title>Type families</title>
3819
3820 <para>
3821 <firstterm>Indexed type families</firstterm> are a new GHC extension to
3822 facilitate type-level
3823 programming. Type families are a generalisation of <firstterm>associated
3824 data types</firstterm>
3825 (&ldquo;<ulink url="http://www.cse.unsw.edu.au/~chak/papers/CKPM05.html">Associated
3826 Types with Class</ulink>&rdquo;, M. Chakravarty, G. Keller, S. Peyton Jones,
3827 and S. Marlow. In Proceedings of &ldquo;The 32nd Annual ACM SIGPLAN-SIGACT
3828 Symposium on Principles of Programming Languages (POPL'05)&rdquo;, pages
3829 1-13, ACM Press, 2005) and <firstterm>associated type synonyms</firstterm>
3830 (&ldquo;<ulink url="http://www.cse.unsw.edu.au/~chak/papers/CKP05.html">Type
3831 Associated Type Synonyms</ulink>&rdquo;. M. Chakravarty, G. Keller, and
3832 S. Peyton Jones.
3833 In Proceedings of &ldquo;The Tenth ACM SIGPLAN International Conference on
3834 Functional Programming&rdquo;, ACM Press, pages 241-253, 2005). Type families
3835 themselves are described in the paper &ldquo;<ulink
3836 url="http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html">Type
3837 Checking with Open Type Functions</ulink>&rdquo;, T. Schrijvers,
3838 S. Peyton-Jones,
3839 M. Chakravarty, and M. Sulzmann, in Proceedings of &ldquo;ICFP 2008: The
3840 13th ACM SIGPLAN International Conference on Functional
3841 Programming&rdquo;, ACM Press, pages 51-62, 2008. Type families
3842 essentially provide type-indexed data types and named functions on types,
3843 which are useful for generic programming and highly parameterised library
3844 interfaces as well as interfaces with enhanced static information, much like
3845 dependent types. They might also be regarded as an alternative to functional
3846 dependencies, but provide a more functional style of type-level programming
3847 than the relational style of functional dependencies.
3848 </para>
3849 <para>
3850 Indexed type families, or type families for short, are type constructors that
3851 represent sets of types. Set members are denoted by supplying the type family
3852 constructor with type parameters, which are called <firstterm>type
3853 indices</firstterm>. The
3854 difference between vanilla parametrised type constructors and family
3855 constructors is much like between parametrically polymorphic functions and
3856 (ad-hoc polymorphic) methods of type classes. Parametric polymorphic functions
3857 behave the same at all type instances, whereas class methods can change their
3858 behaviour in dependence on the class type parameters. Similarly, vanilla type
3859 constructors imply the same data representation for all type instances, but
3860 family constructors can have varying representation types for varying type
3861 indices.
3862 </para>
3863 <para>
3864 Indexed type families come in two flavours: <firstterm>data
3865 families</firstterm> and <firstterm>type synonym
3866 families</firstterm>. They are the indexed family variants of algebraic
3867 data types and type synonyms, respectively. The instances of data families
3868 can be data types and newtypes.
3869 </para>
3870 <para>
3871 Type families are enabled by the flag <option>-XTypeFamilies</option>.
3872 Additional information on the use of type families in GHC is available on
3873 <ulink url="http://www.haskell.org/haskellwiki/GHC/Indexed_types">the
3874 Haskell wiki page on type families</ulink>.
3875 </para>
3876
3877 <sect2 id="data-families">
3878 <title>Data families</title>
3879
3880 <para>
3881 Data families appear in two flavours: (1) they can be defined on the
3882 toplevel
3883 or (2) they can appear inside type classes (in which case they are known as
3884 associated types). The former is the more general variant, as it lacks the
3885 requirement for the type-indexes to coincide with the class
3886 parameters. However, the latter can lead to more clearly structured code and
3887 compiler warnings if some type instances were - possibly accidentally -
3888 omitted. In the following, we always discuss the general toplevel form first
3889 and then cover the additional constraints placed on associated types.
3890 </para>
3891
3892 <sect3 id="data-family-declarations">
3893 <title>Data family declarations</title>
3894
3895 <para>
3896 Indexed data families are introduced by a signature, such as
3897 <programlisting>
3898 data family GMap k :: * -> *
3899 </programlisting>
3900 The special <literal>family</literal> distinguishes family from standard
3901 data declarations. The result kind annotation is optional and, as
3902 usual, defaults to <literal>*</literal> if omitted. An example is
3903 <programlisting>
3904 data family Array e
3905 </programlisting>
3906 Named arguments can also be given explicit kind signatures if needed.
3907 Just as with
3908 [http://www.haskell.org/ghc/docs/latest/html/users_guide/gadt.html GADT
3909 declarations] named arguments are entirely optional, so that we can
3910 declare <literal>Array</literal> alternatively with
3911 <programlisting>
3912 data family Array :: * -> *
3913 </programlisting>
3914 </para>
3915
3916 <sect4 id="assoc-data-family-decl">
3917 <title>Associated data family declarations</title>
3918 <para>
3919 When a data family is declared as part of a type class, we drop
3920 the <literal>family</literal> special. The <literal>GMap</literal>
3921 declaration takes the following form
3922 <programlisting>
3923 class GMapKey k where
3924 data GMap k :: * -> *
3925 ...
3926 </programlisting>
3927 In contrast to toplevel declarations, named arguments must be used for
3928 all type parameters that are to be used as type-indexes. Moreover,
3929 the argument names must be class parameters. Each class parameter may
3930 only be used at most once per associated type, but some may be omitted
3931 and they may be in an order other than in the class head. Hence, the
3932 following contrived example is admissible:
3933 <programlisting>
3934 class C a b c where
3935 data T c a :: *
3936 </programlisting>
3937 </para>
3938 </sect4>
3939 </sect3>
3940
3941 <sect3 id="data-instance-declarations">
3942 <title>Data instance declarations</title>
3943
3944 <para>
3945 Instance declarations of data and newtype families are very similar to
3946 standard data and newtype declarations. The only two differences are
3947 that the keyword <literal>data</literal> or <literal>newtype</literal>
3948 is followed by <literal>instance</literal> and that some or all of the
3949 type arguments can be non-variable types, but may not contain forall
3950 types or type synonym families. However, data families are generally
3951 allowed in type parameters, and type synonyms are allowed as long as
3952 they are fully applied and expand to a type that is itself admissible -
3953 exactly as this is required for occurrences of type synonyms in class
3954 instance parameters. For example, the <literal>Either</literal>
3955 instance for <literal>GMap</literal> is
3956 <programlisting>
3957 data instance GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
3958 </programlisting>
3959 In this example, the declaration has only one variant. In general, it
3960 can be any number.
3961 </para>
3962 <para>
3963 Data and newtype instance declarations are only permitted when an
3964 appropriate family declaration is in scope - just as a class instance declaratoin
3965 requires the class declaration to be visible. Moreover, each instance
3966 declaration has to conform to the kind determined by its family
3967 declaration. This implies that the number of parameters of an instance
3968 declaration matches the arity determined by the kind of the family.
3969 </para>
3970 <para>
3971 A data family instance declaration can use the full exprssiveness of
3972 ordinary <literal>data</literal> or <literal>newtype</literal> declarations:
3973 <itemizedlist>
3974 <listitem><para> Although, a data family is <emphasis>introduced</emphasis> with
3975 the keyword "<literal>data</literal>", a data family <emphasis>instance</emphasis> can
3976 use either <literal>data</literal> or <literal>newtype</literal>. For example:
3977 <programlisting>
3978 data family T a
3979 data instance T Int = T1 Int | T2 Bool
3980 newtype instance T Char = TC Bool
3981 </programlisting>
3982 </para></listitem>
3983 <listitem><para> A <literal>data instance</literal> can use GADT syntax for the data constructors,
3984 and indeed can define a GADT. For example:
3985 <programlisting>
3986 data family G a b
3987 data instance G [a] b where
3988 G1 :: c -> G [Int] b
3989 G2 :: G [a] Bool
3990 </programlisting>
3991 </para></listitem>
3992 <listitem><para> You can use a <literal>deriving</literal> clause on a
3993 <literal>data instance</literal> or <literal>newtype instance</literal>
3994 declaration.
3995 </para></listitem>
3996 </itemizedlist>
3997 </para>
3998
3999 <para>
4000 Even if type families are defined as toplevel declarations, functions
4001 that perform different computations for different family instances may still
4002 need to be defined as methods of type classes. In particular, the
4003 following is not possible:
4004 <programlisting>
4005 data family T a
4006 data instance T Int = A
4007 data instance T Char = B
4008 foo :: T a -> Int
4009 foo A = 1 -- WRONG: These two equations together...
4010 foo B = 2 -- ...will produce a type error.
4011 </programlisting>
4012 Instead, you would have to write <literal>foo</literal> as a class operation, thus:
4013 <programlisting>
4014 class C a where
4015 foo :: T a -> Int
4016 instance Foo Int where
4017 foo A = 1
4018 instance Foo Char where
4019 foo B = 2
4020 </programlisting>
4021 (Given the functionality provided by GADTs (Generalised Algebraic Data
4022 Types), it might seem as if a definition, such as the above, should be
4023 feasible. However, type families are - in contrast to GADTs - are
4024 <emphasis>open;</emphasis> i.e., new instances can always be added,
4025 possibly in other
4026 modules. Supporting pattern matching across different data instances
4027 would require a form of extensible case construct.)
4028 </para>
4029
4030 <sect4 id="assoc-data-inst">
4031 <title>Associated data instances</title>
4032 <para>
4033 When an associated data family instance is declared within a type
4034 class instance, we drop the <literal>instance</literal> keyword in the
4035 family instance. So, the <literal>Either</literal> instance
4036 for <literal>GMap</literal> becomes:
4037 <programlisting>
4038 instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where
4039 data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
4040 ...
4041 </programlisting>
4042 The most important point about associated family instances is that the
4043 type indexes corresponding to class parameters must be identical to
4044 the type given in the instance head; here this is the first argument
4045 of <literal>GMap</literal>, namely <literal>Either a b</literal>,
4046 which coincides with the only class parameter. Any parameters to the
4047 family constructor that do not correspond to class parameters, need to
4048 be variables in every instance; here this is the
4049 variable <literal>v</literal>.
4050 </para>
4051 <para>
4052 Instances for an associated family can only appear as part of
4053 instances declarations of the class in which the family was declared -
4054 just as with the equations of the methods of a class. Also in
4055 correspondence to how methods are handled, declarations of associated
4056 types can be omitted in class instances. If an associated family
4057 instance is omitted, the corresponding instance type is not inhabited;
4058 i.e., only diverging expressions, such
4059 as <literal>undefined</literal>, can assume the type.
4060 </para>
4061 </sect4>
4062
4063 <sect4 id="scoping-class-params">
4064 <title>Scoping of class parameters</title>
4065 <para>
4066 In the case of multi-parameter type classes, the visibility of class
4067 parameters in the right-hand side of associated family instances
4068 depends <emphasis>solely</emphasis> on the parameters of the data
4069 family. As an example, consider the simple class declaration
4070 <programlisting>
4071 class C a b where
4072 data T a
4073 </programlisting>
4074 Only one of the two class parameters is a parameter to the data
4075 family. Hence, the following instance declaration is invalid:
4076 <programlisting>
4077 instance C [c] d where
4078 data T [c] = MkT (c, d) -- WRONG!! 'd' is not in scope
4079 </programlisting>
4080 Here, the right-hand side of the data instance mentions the type
4081 variable <literal>d</literal> that does not occur in its left-hand
4082 side. We cannot admit such data instances as they would compromise
4083 type safety.
4084 </para>
4085 </sect4>
4086
4087 <sect4 id="family-class-inst">
4088 <title>Type class instances of family instances</title>
4089 <para>
4090 Type class instances of instances of data families can be defined as
4091 usual, and in particular data instance declarations can
4092 have <literal>deriving</literal> clauses. For example, we can write
4093 <programlisting>
4094 data GMap () v = GMapUnit (Maybe v)
4095 deriving Show
4096 </programlisting>
4097 which implicitly defines an instance of the form
4098 <programlisting>
4099 instance Show v => Show (GMap () v) where ...
4100 </programlisting>
4101 </para>
4102 <para>
4103 Note that class instances are always for
4104 particular <emphasis>instances</emphasis> of a data family and never
4105 for an entire family as a whole. This is for essentially the same
4106 reasons that we cannot define a toplevel function that performs
4107 pattern matching on the data constructors
4108 of <emphasis>different</emphasis> instances of a single type family.
4109 It would require a form of extensible case construct.
4110 </para>
4111 </sect4>
4112
4113 <sect4 id="data-family-overlap">
4114 <title>