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>-XExplicitForAll</option>,
  82           <option>-XRankNTypes</option>,
  83           <option>-XImpredicativeTypes</option>,
  84           <option>-XTypeOperators</option>,
  85           <option>-XDoRec</option>,
  86           <option>-XParallelListComp</option>,
  87           <option>-XEmptyDataDecls</option>,
  88           <option>-XKindSignatures</option>,
  89           <option>-XGeneralizedNewtypeDeriving</option>,
  90           <option>-XTypeFamilies</option>.
  91             Enabling these options is the <emphasis>only</emphasis>
  92             effect of <option>-fglasgow-exts</option>.
  93           We are trying to move away from this portmanteau flag,
  94           and towards enabling features individually.</para>
  95
  96   </sect1>
  97
  98 <!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS -->
  99 <sect1 id="primitives">
 100   <title>Unboxed types and primitive operations</title>
 101
 102 <para>GHC is built on a raft of primitive data types and operations;
 103 "primitive" in the sense that they cannot be defined in Haskell itself.
 104 While you really can use this stuff to write fast code,
 105   we generally find it a lot less painful, and more satisfying in the
 106   long run, to use higher-level language features and libraries.  With
 107   any luck, the code you write will be optimised to the efficient
 108   unboxed version in any case.  And if it isn't, we'd like to know
 109   about it.</para>
 110
 111 <para>All these primitive data types and operations are exported by the
 112 library <literal>GHC.Prim</literal>, for which there is
 113 <ulink url="&libraryGhcPrimLocation;/GHC-Prim.html">detailed online documentation</ulink>.
 114 (This documentation is generated from the file <filename>compiler/prelude/primops.txt.pp</filename>.)
 115 </para>
 116 <para>
 117 If you want to mention any of the primitive data types or operations in your
 118 program, you must first import <literal>GHC.Prim</literal> to bring them
 119 into scope.  Many of them have names ending in "&num;", and to mention such
 120 names you need the <option>-XMagicHash</option> extension (<xref linkend="magic-hash"/>).
 121 </para>
 122
 123 <para>The primops make extensive use of <link linkend="glasgow-unboxed">unboxed types</link>
 124 and <link linkend="unboxed-tuples">unboxed tuples</link>, which
 125 we briefly summarise here. </para>
 126
 127 <sect2 id="glasgow-unboxed">
 128 <title>Unboxed types
 129 </title>
 130
 131 <para>
 132 <indexterm><primary>Unboxed types (Glasgow extension)</primary></indexterm>
 133 </para>
 134
 135 <para>Most types in GHC are <firstterm>boxed</firstterm>, which means
 136 that values of that type are represented by a pointer to a heap
 137 object.  The representation of a Haskell <literal>Int</literal>, for
 138 example, is a two-word heap object.  An <firstterm>unboxed</firstterm>
 139 type, however, is represented by the value itself, no pointers or heap
 140 allocation are involved.
 141 </para>
 142
 143 <para>
 144 Unboxed types correspond to the &ldquo;raw machine&rdquo; types you
 145 would use in C: <literal>Int&num;</literal> (long int),
 146 <literal>Double&num;</literal> (double), <literal>Addr&num;</literal>
 147 (void *), etc.  The <emphasis>primitive operations</emphasis>
 148 (PrimOps) on these types are what you might expect; e.g.,
 149 <literal>(+&num;)</literal> is addition on
 150 <literal>Int&num;</literal>s, and is the machine-addition that we all
 151 know and love&mdash;usually one instruction.
 152 </para>
 153
 154 <para>
 155 Primitive (unboxed) types cannot be defined in Haskell, and are
 156 therefore built into the language and compiler.  Primitive types are
 157 always unlifted; that is, a value of a primitive type cannot be
 158 bottom.  We use the convention (but it is only a convention)
 159 that primitive types, values, and
 160 operations have a <literal>&num;</literal> suffix (see <xref linkend="magic-hash"/>).
 161 For some primitive types we have special syntax for literals, also
 162 described in the <link linkend="magic-hash">same section</link>.
 163 </para>
 164
 165 <para>
 166 Primitive values are often represented by a simple bit-pattern, such
 167 as <literal>Int&num;</literal>, <literal>Float&num;</literal>,
 168 <literal>Double&num;</literal>.  But this is not necessarily the case:
 169 a primitive value might be represented by a pointer to a
 170 heap-allocated object.  Examples include
 171 <literal>Array&num;</literal>, the type of primitive arrays.  A
 172 primitive array is heap-allocated because it is too big a value to fit
 173 in a register, and would be too expensive to copy around; in a sense,
 174 it is accidental that it is represented by a pointer.  If a pointer
 175 represents a primitive value, then it really does point to that value:
 176 no unevaluated thunks, no indirections&hellip;nothing can be at the
 177 other end of the pointer than the primitive value.
 178 A numerically-intensive program using unboxed types can
 179 go a <emphasis>lot</emphasis> faster than its &ldquo;standard&rdquo;
 180 counterpart&mdash;we saw a threefold speedup on one example.
 181 </para>
 182
 183 <para>
 184 There are some restrictions on the use of primitive types:
 185 <itemizedlist>
 186 <listitem><para>The main restriction
 187 is that you can't pass a primitive value to a polymorphic
 188 function or store one in a polymorphic data type.  This rules out
 189 things like <literal>[Int&num;]</literal> (i.e. lists of primitive
 190 integers).  The reason for this restriction is that polymorphic
 191 arguments and constructor fields are assumed to be pointers: if an
 192 unboxed integer is stored in one of these, the garbage collector would
 193 attempt to follow it, leading to unpredictable space leaks.  Or a
 194 <function>seq</function> operation on the polymorphic component may
 195 attempt to dereference the pointer, with disastrous results.  Even
 196 worse, the unboxed value might be larger than a pointer
 197 (<literal>Double&num;</literal> for instance).
 198 </para>
 199 </listitem>
 200 <listitem><para> You cannot define a newtype whose representation type
 201 (the argument type of the data constructor) is an unboxed type.  Thus,
 202 this is illegal:
 203 <programlisting>
 204   newtype A = MkA Int#
 205 </programlisting>
 206 </para></listitem>
 207 <listitem><para> You cannot bind a variable with an unboxed type
 208 in a <emphasis>top-level</emphasis> binding.
 209 </para></listitem>
 210 <listitem><para> You cannot bind a variable with an unboxed type
 211 in a <emphasis>recursive</emphasis> binding.
 212 </para></listitem>
 213 <listitem><para> You may bind unboxed variables in a (non-recursive,
 214 non-top-level) pattern binding, but you must make any such pattern-match
 215 strict.  For example, rather than:
 216 <programlisting>
 217   data Foo = Foo Int Int#
 218
 219   f x = let (Foo a b, w) = ..rhs.. in ..body..
 220 </programlisting>
 221 you must write:
 222 <programlisting>
 223   data Foo = Foo Int Int#
 224
 225   f x = let !(Foo a b, w) = ..rhs.. in ..body..
 226 </programlisting>
 227 since <literal>b</literal> has type <literal>Int#</literal>.
 228 </para>
 229 </listitem>
 230 </itemizedlist>
 231 </para>
 232
 233 </sect2>
 234
 235 <sect2 id="unboxed-tuples">
 236 <title>Unboxed Tuples
 237 </title>
 238
 239 <para>
 240 Unboxed tuples aren't really exported by <literal>GHC.Exts</literal>,
 241 they're available by default with <option>-fglasgow-exts</option>.  An
 242 unboxed tuple looks like this:
 243 </para>
 244
 245 <para>
 246
 247 <programlisting>
 248 (# e_1, ..., e_n #)
 249 </programlisting>
 250
 251 </para>
 252
 253 <para>
 254 where <literal>e&lowbar;1..e&lowbar;n</literal> are expressions of any
 255 type (primitive or non-primitive).  The type of an unboxed tuple looks
 256 the same.
 257 </para>
 258
 259 <para>
 260 Unboxed tuples are used for functions that need to return multiple
 261 values, but they avoid the heap allocation normally associated with
 262 using fully-fledged tuples.  When an unboxed tuple is returned, the
 263 components are put directly into registers or on the stack; the
 264 unboxed tuple itself does not have a composite representation.  Many
 265 of the primitive operations listed in <literal>primops.txt.pp</literal> return unboxed
 266 tuples.
 267 In particular, the <literal>IO</literal> and <literal>ST</literal> monads use unboxed
 268 tuples to avoid unnecessary allocation during sequences of operations.
 269 </para>
 270
 271 <para>
 272 There are some pretty stringent restrictions on the use of unboxed tuples:
 273 <itemizedlist>
 274 <listitem>
 275
 276 <para>
 277 Values of unboxed tuple types are subject to the same restrictions as
 278 other unboxed types; i.e. they may not be stored in polymorphic data
 279 structures or passed to polymorphic functions.
 280
 281 </para>
 282 </listitem>
 283 <listitem>
 284
 285 <para>
 286 No variable can have an unboxed tuple type, nor may a constructor or function
 287 argument have an unboxed tuple type.  The following are all illegal:
 288
 289
 290 <programlisting>
 291   data Foo = Foo (# Int, Int #)
 292
 293   f :: (# Int, Int #) -&#62; (# Int, Int #)
 294   f x = x
 295
 296   g :: (# Int, Int #) -&#62; Int
 297   g (# a,b #) = a
 298
 299   h x = let y = (# x,x #) in ...
 300 </programlisting>
 301 </para>
 302 </listitem>
 303 </itemizedlist>
 304 </para>
 305 <para>
 306 The typical use of unboxed tuples is simply to return multiple values,
 307 binding those multiple results with a <literal>case</literal> expression, thus:
 308 <programlisting>
 309   f x y = (# x+1, y-1 #)
 310   g x = case f x x of { (# a, b #) -&#62; a + b }
 311 </programlisting>
 312 You can have an unboxed tuple in a pattern binding, thus
 313 <programlisting>
 314   f x = let (# p,q #) = h x in ..body..
 315 </programlisting>
 316 If the types of <literal>p</literal> and <literal>q</literal> are not unboxed,
 317 the resulting binding is lazy like any other Haskell pattern binding.  The
 318 above example desugars like this:
 319 <programlisting>
 320   f x = let t = case h x o f{ (# p,q #) -> (p,q)
 321             p = fst t
 322             q = snd t
 323         in ..body..
 324 </programlisting>
 325 Indeed, the bindings can even be recursive.
 326 </para>
 327
 328 </sect2>
 329 </sect1>
 330
 331
 332 <!-- ====================== SYNTACTIC EXTENSIONS =======================  -->
 333
 334 <sect1 id="syntax-extns">
 335 <title>Syntactic extensions</title>
 336
 337     <sect2 id="unicode-syntax">
 338       <title>Unicode syntax</title>
 339       <para>The language
 340       extension <option>-XUnicodeSyntax</option><indexterm><primary><option>-XUnicodeSyntax</option></primary></indexterm>
 341       enables Unicode characters to be used to stand for certain ASCII
 342       character sequences.  The following alternatives are provided:</para>
 343
 344       <informaltable>
 345         <tgroup cols="2" align="left" colsep="1" rowsep="1">
 346           <thead>
 347             <row>
 348               <entry>ASCII</entry>
 349               <entry>Unicode alternative</entry>
 350               <entry>Code point</entry>
 351               <entry>Name</entry>
 352             </row>
 353           </thead>
 354
 355 <!--
 356                to find the DocBook entities for these characters, find
 357                the Unicode code point (e.g. 0x2237), and grep for it in
 358                /usr/share/sgml/docbook/xml-dtd-*/ent/* (or equivalent on
 359                your system.  Some of these Unicode code points don't have
 360                equivalent DocBook entities.
 361             -->
 362
 363           <tbody>
 364             <row>
 365               <entry><literal>::</literal></entry>
 366               <entry>::</entry> <!-- no special char, apparently -->
 367               <entry>0x2237</entry>
 368               <entry>PROPORTION</entry>
 369             </row>
 370           </tbody>
 371           <tbody>
 372             <row>
 373               <entry><literal>=&gt;</literal></entry>
 374               <entry>&rArr;</entry>
 375               <entry>0x21D2</entry>
 376               <entry>RIGHTWARDS DOUBLE ARROW</entry>
 377             </row>
 378           </tbody>
 379           <tbody>
 380             <row>
 381               <entry><literal>forall</literal></entry>
 382               <entry>&forall;</entry>
 383               <entry>0x2200</entry>
 384               <entry>FOR ALL</entry>
 385             </row>
 386           </tbody>
 387           <tbody>
 388             <row>
 389               <entry><literal>-&gt;</literal></entry>
 390               <entry>&rarr;</entry>
 391               <entry>0x2192</entry>
 392               <entry>RIGHTWARDS ARROW</entry>
 393             </row>
 394           </tbody>
 395           <tbody>
 396             <row>
 397               <entry><literal>&lt;-</literal></entry>
 398               <entry>&larr;</entry>
 399               <entry>0x2190</entry>
 400               <entry>LEFTWARDS ARROW</entry>
 401             </row>
 402           </tbody>
 403
 404           <tbody>
 405             <row>
 406               <entry>-&lt;</entry>
 407               <entry>&larrtl;</entry>
 408               <entry>0x2919</entry>
 409               <entry>LEFTWARDS ARROW-TAIL</entry>
 410             </row>
 411           </tbody>
 412
 413           <tbody>
 414             <row>
 415               <entry>&gt;-</entry>
 416               <entry>&rarrtl;</entry>
 417               <entry>0x291A</entry>
 418               <entry>RIGHTWARDS ARROW-TAIL</entry>
 419             </row>
 420           </tbody>
 421
 422           <tbody>
 423             <row>
 424               <entry>-&lt;&lt;</entry>
 425               <entry></entry>
 426               <entry>0x291B</entry>
 427               <entry>LEFTWARDS DOUBLE ARROW-TAIL</entry>
 428             </row>
 429           </tbody>
 430
 431           <tbody>
 432             <row>
 433               <entry>&gt;&gt;-</entry>
 434               <entry></entry>
 435               <entry>0x291C</entry>
 436               <entry>RIGHTWARDS DOUBLE ARROW-TAIL</entry>
 437             </row>
 438           </tbody>
 439
 440           <tbody>
 441             <row>
 442               <entry>*</entry>
 443               <entry>&starf;</entry>
 444               <entry>0x2605</entry>
 445               <entry>BLACK STAR</entry>
 446             </row>
 447           </tbody>
 448
 449         </tgroup>
 450       </informaltable>
 451     </sect2>
 452
 453     <sect2 id="magic-hash">
 454       <title>The magic hash</title>
 455       <para>The language extension <option>-XMagicHash</option> allows "&num;" as a
 456         postfix modifier to identifiers.  Thus, "x&num;" is a valid variable, and "T&num;" is
 457         a valid type constructor or data constructor.</para>
 458
 459       <para>The hash sign does not change sematics at all.  We tend to use variable
 460         names ending in "&num;" for unboxed values or types (e.g. <literal>Int&num;</literal>),
 461         but there is no requirement to do so; they are just plain ordinary variables.
 462         Nor does the <option>-XMagicHash</option> extension bring anything into scope.
 463         For example, to bring <literal>Int&num;</literal> into scope you must
 464         import <literal>GHC.Prim</literal> (see <xref linkend="primitives"/>);
 465         the <option>-XMagicHash</option> extension
 466         then allows you to <emphasis>refer</emphasis> to the <literal>Int&num;</literal>
 467         that is now in scope.</para>
 468       <para> The <option>-XMagicHash</option> also enables some new forms of literals (see <xref linkend="glasgow-unboxed"/>):
 469         <itemizedlist>
 470           <listitem><para> <literal>'x'&num;</literal> has type <literal>Char&num;</literal></para> </listitem>
 471           <listitem><para> <literal>&quot;foo&quot;&num;</literal> has type <literal>Addr&num;</literal></para> </listitem>
 472           <listitem><para> <literal>3&num;</literal> has type <literal>Int&num;</literal>. In general,
 473           any Haskell 98 integer lexeme followed by a <literal>&num;</literal> is an <literal>Int&num;</literal> literal, e.g.
 474             <literal>-0x3A&num;</literal> as well as <literal>32&num;</literal></para>.</listitem>
 475           <listitem><para> <literal>3&num;&num;</literal> has type <literal>Word&num;</literal>. In general,
 476           any non-negative Haskell 98 integer lexeme followed by <literal>&num;&num;</literal>
 477               is a <literal>Word&num;</literal>. </para> </listitem>
 478           <listitem><para> <literal>3.2&num;</literal> has type <literal>Float&num;</literal>.</para> </listitem>
 479           <listitem><para> <literal>3.2&num;&num;</literal> has type <literal>Double&num;</literal></para> </listitem>
 480           </itemizedlist>
 481       </para>
 482    </sect2>
 483
 484     <sect2 id="new-qualified-operators">
 485       <title>New qualified operator syntax</title>
 486
 487       <para>A new syntax for referencing qualified operators is
 488         planned to be introduced by Haskell', and is enabled in GHC
 489         with
 490         the <option>-XNewQualifiedOperators</option><indexterm><primary><option>-XNewQualifiedOperators</option></primary></indexterm>
 491         option.  In the new syntax, the prefix form of a qualified
 492         operator is
 493         written <literal><replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)</literal>
 494         (in Haskell 98 this would
 495         be <literal>(<replaceable>module</replaceable>.<replaceable>symbol</replaceable>)</literal>),
 496         and the infix form is
 497         written <literal>`<replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)`</literal>
 498         (in Haskell 98 this would
 499         be <literal>`<replaceable>module</replaceable>.<replaceable>symbol</replaceable>`</literal>.
 500         For example:
 501 <programlisting>
 502   add x y = Prelude.(+) x y
 503   subtract y = (`Prelude.(-)` y)
 504 </programlisting>
 505         The new form of qualified operators is intended to regularise
 506         the syntax by eliminating odd cases
 507         like <literal>Prelude..</literal>.  For example,
 508         when <literal>NewQualifiedOperators</literal> is on, it is possible to
 509         write the enumerated sequence <literal>[Monday..]</literal>
 510         without spaces, whereas in Haskell 98 this would be a
 511         reference to the operator &lsquo;<literal>.</literal>&lsquo;
 512         from module <literal>Monday</literal>.</para>
 513
 514       <para>When <option>-XNewQualifiedOperators</option> is on, the old Haskell
 515         98 syntax for qualified operators is not accepted, so this
 516         option may cause existing Haskell 98 code to break.</para>
 517
 518     </sect2>
 519
 520
 521     <!-- ====================== HIERARCHICAL MODULES =======================  -->
 522
 523
 524     <sect2 id="hierarchical-modules">
 525       <title>Hierarchical Modules</title>
 526
 527       <para>GHC supports a small extension to the syntax of module
 528       names: a module name is allowed to contain a dot
 529       <literal>&lsquo;.&rsquo;</literal>.  This is also known as the
 530       &ldquo;hierarchical module namespace&rdquo; extension, because
 531       it extends the normally flat Haskell module namespace into a
 532       more flexible hierarchy of modules.</para>
 533
 534       <para>This extension has very little impact on the language
 535       itself; modules names are <emphasis>always</emphasis> fully
 536       qualified, so you can just think of the fully qualified module
 537       name as <quote>the module name</quote>.  In particular, this
 538       means that the full module name must be given after the
 539       <literal>module</literal> keyword at the beginning of the
 540       module; for example, the module <literal>A.B.C</literal> must
 541       begin</para>
 542
 543 <programlisting>module A.B.C</programlisting>
 544
 545
 546       <para>It is a common strategy to use the <literal>as</literal>
 547       keyword to save some typing when using qualified names with
 548       hierarchical modules.  For example:</para>
 549
 550 <programlisting>
 551 import qualified Control.Monad.ST.Strict as ST
 552 </programlisting>
 553
 554       <para>For details on how GHC searches for source and interface
 555       files in the presence of hierarchical modules, see <xref
 556       linkend="search-path"/>.</para>
 557
 558       <para>GHC comes with a large collection of libraries arranged
 559       hierarchically; see the accompanying <ulink
 560       url="../libraries/index.html">library
 561       documentation</ulink>.  More libraries to install are available
 562       from <ulink
 563       url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para>
 564     </sect2>
 565
 566     <!-- ====================== PATTERN GUARDS =======================  -->
 567
 568 <sect2 id="pattern-guards">
 569 <title>Pattern guards</title>
 570
 571 <para>
 572 <indexterm><primary>Pattern guards (Glasgow extension)</primary></indexterm>
 573 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.)
 574 </para>
 575
 576 <para>
 577 Suppose we have an abstract data type of finite maps, with a
 578 lookup operation:
 579
 580 <programlisting>
 581 lookup :: FiniteMap -> Int -> Maybe Int
 582 </programlisting>
 583
 584 The lookup returns <function>Nothing</function> if the supplied key is not in the domain of the mapping, and <function>(Just v)</function> otherwise,
 585 where <varname>v</varname> is the value that the key maps to.  Now consider the following definition:
 586 </para>
 587
 588 <programlisting>
 589 clunky env var1 var2 | ok1 &amp;&amp; ok2 = val1 + val2
 590 | otherwise  = var1 + var2
 591 where
 592   m1 = lookup env var1
 593   m2 = lookup env var2
 594   ok1 = maybeToBool m1
 595   ok2 = maybeToBool m2
 596   val1 = expectJust m1
 597   val2 = expectJust m2
 598 </programlisting>
 599
 600 <para>
 601 The auxiliary functions are
 602 </para>
 603
 604 <programlisting>
 605 maybeToBool :: Maybe a -&gt; Bool
 606 maybeToBool (Just x) = True
 607 maybeToBool Nothing  = False
 608
 609 expectJust :: Maybe a -&gt; a
 610 expectJust (Just x) = x
 611 expectJust Nothing  = error "Unexpected Nothing"
 612 </programlisting>
 613
 614 <para>
 615 What is <function>clunky</function> doing? The guard <literal>ok1 &amp;&amp;
 616 ok2</literal> checks that both lookups succeed, using
 617 <function>maybeToBool</function> to convert the <function>Maybe</function>
 618 types to booleans. The (lazily evaluated) <function>expectJust</function>
 619 calls extract the values from the results of the lookups, and binds the
 620 returned values to <varname>val1</varname> and <varname>val2</varname>
 621 respectively.  If either lookup fails, then clunky takes the
 622 <literal>otherwise</literal> case and returns the sum of its arguments.
 623 </para>
 624
 625 <para>
 626 This is certainly legal Haskell, but it is a tremendously verbose and
 627 un-obvious way to achieve the desired effect.  Arguably, a more direct way
 628 to write clunky would be to use case expressions:
 629 </para>
 630
 631 <programlisting>
 632 clunky env var1 var2 = case lookup env var1 of
 633   Nothing -&gt; fail
 634   Just val1 -&gt; case lookup env var2 of
 635     Nothing -&gt; fail
 636     Just val2 -&gt; val1 + val2
 637 where
 638   fail = var1 + var2
 639 </programlisting>
 640
 641 <para>
 642 This is a bit shorter, but hardly better.  Of course, we can rewrite any set
 643 of pattern-matching, guarded equations as case expressions; that is
 644 precisely what the compiler does when compiling equations! The reason that
 645 Haskell provides guarded equations is because they allow us to write down
 646 the cases we want to consider, one at a time, independently of each other.
 647 This structure is hidden in the case version.  Two of the right-hand sides
 648 are really the same (<function>fail</function>), and the whole expression
 649 tends to become more and more indented.
 650 </para>
 651
 652 <para>
 653 Here is how I would write clunky:
 654 </para>
 655
 656 <programlisting>
 657 clunky env var1 var2
 658   | Just val1 &lt;- lookup env var1
 659   , Just val2 &lt;- lookup env var2
 660   = val1 + val2
 661 ...other equations for clunky...
 662 </programlisting>
 663
 664 <para>
 665 The semantics should be clear enough.  The qualifiers are matched in order.
 666 For a <literal>&lt;-</literal> qualifier, which I call a pattern guard, the
 667 right hand side is evaluated and matched against the pattern on the left.
 668 If the match fails then the whole guard fails and the next equation is
 669 tried.  If it succeeds, then the appropriate binding takes place, and the
 670 next qualifier is matched, in the augmented environment.  Unlike list
 671 comprehensions, however, the type of the expression to the right of the
 672 <literal>&lt;-</literal> is the same as the type of the pattern to its
 673 left.  The bindings introduced by pattern guards scope over all the
 674 remaining guard qualifiers, and over the right hand side of the equation.
 675 </para>
 676
 677 <para>
 678 Just as with list comprehensions, boolean expressions can be freely mixed
 679 with among the pattern guards.  For example:
 680 </para>
 681
 682 <programlisting>
 683 f x | [y] &lt;- x
 684     , y > 3
 685     , Just z &lt;- h y
 686     = ...
 687 </programlisting>
 688
 689 <para>
 690 Haskell's current guards therefore emerge as a special case, in which the
 691 qualifier list has just one element, a boolean expression.
 692 </para>
 693 </sect2>
 694
 695     <!-- ===================== View patterns ===================  -->
 696
 697 <sect2 id="view-patterns">
 698 <title>View patterns
 699 </title>
 700
 701 <para>
 702 View patterns are enabled by the flag <literal>-XViewPatterns</literal>.
 703 More information and examples of view patterns can be found on the
 704 <ulink url="http://hackage.haskell.org/trac/ghc/wiki/ViewPatterns">Wiki
 705 page</ulink>.
 706 </para>
 707
 708 <para>
 709 View patterns are somewhat like pattern guards that can be nested inside
 710 of other patterns.  They are a convenient way of pattern-matching
 711 against values of abstract types. For example, in a programming language
 712 implementation, we might represent the syntax of the types of the
 713 language as follows:
 714
 715 <programlisting>
 716 type Typ
 717
 718 data TypView = Unit
 719              | Arrow Typ Typ
 720
 721 view :: Type -> TypeView
 722
 723 -- additional operations for constructing Typ's ...
 724 </programlisting>
 725
 726 The representation of Typ is held abstract, permitting implementations
 727 to use a fancy representation (e.g., hash-consing to manage sharing).
 728
 729 Without view patterns, using this signature a little inconvenient:
 730 <programlisting>
 731 size :: Typ -> Integer
 732 size t = case view t of
 733   Unit -> 1
 734   Arrow t1 t2 -> size t1 + size t2
 735 </programlisting>
 736
 737 It is necessary to iterate the case, rather than using an equational
 738 function definition. And the situation is even worse when the matching
 739 against <literal>t</literal> is buried deep inside another pattern.
 740 </para>
 741
 742 <para>
 743 View patterns permit calling the view function inside the pattern and
 744 matching against the result:
 745 <programlisting>
 746 size (view -> Unit) = 1
 747 size (view -> Arrow t1 t2) = size t1 + size t2
 748 </programlisting>
 749
 750 That is, we add a new form of pattern, written
 751 <replaceable>expression</replaceable> <literal>-></literal>
 752 <replaceable>pattern</replaceable> that means "apply the expression to
 753 whatever we're trying to match against, and then match the result of
 754 that application against the pattern". The expression can be any Haskell
 755 expression of function type, and view patterns can be used wherever
 756 patterns are used.
 757 </para>
 758
 759 <para>
 760 The semantics of a pattern <literal>(</literal>
 761 <replaceable>exp</replaceable> <literal>-></literal>
 762 <replaceable>pat</replaceable> <literal>)</literal> are as follows:
 763
 764 <itemizedlist>
 765
 766 <listitem> Scoping:
 767
 768 <para>The variables bound by the view pattern are the variables bound by
 769 <replaceable>pat</replaceable>.
 770 </para>
 771
 772 <para>
 773 Any variables in <replaceable>exp</replaceable> are bound occurrences,
 774 but variables bound "to the left" in a pattern are in scope.  This
 775 feature permits, for example, one argument to a function to be used in
 776 the view of another argument.  For example, the function
 777 <literal>clunky</literal> from <xref linkend="pattern-guards" /> can be
 778 written using view patterns as follows:
 779
 780 <programlisting>
 781 clunky env (lookup env -> Just val1) (lookup env -> Just val2) = val1 + val2
 782 ...other equations for clunky...
 783 </programlisting>
 784 </para>
 785
 786 <para>
 787 More precisely, the scoping rules are:
 788 <itemizedlist>
 789 <listitem>
 790 <para>
 791 In a single pattern, variables bound by patterns to the left of a view
 792 pattern expression are in scope. For example:
 793 <programlisting>
 794 example :: Maybe ((String -> Integer,Integer), String) -> Bool
 795 example Just ((f,_), f -> 4) = True
 796 </programlisting>
 797
 798 Additionally, in function definitions, variables bound by matching earlier curried
 799 arguments may be used in view pattern expressions in later arguments:
 800 <programlisting>
 801 example :: (String -> Integer) -> String -> Bool
 802 example f (f -> 4) = True
 803 </programlisting>
 804 That is, the scoping is the same as it would be if the curried arguments
 805 were collected into a tuple.
 806 </para>
 807 </listitem>
 808
 809 <listitem>
 810 <para>
 811 In mutually recursive bindings, such as <literal>let</literal>,
 812 <literal>where</literal>, or the top level, view patterns in one
 813 declaration may not mention variables bound by other declarations.  That
 814 is, each declaration must be self-contained.  For example, the following
 815 program is not allowed:
 816 <programlisting>
 817 let {(x -> y) = e1 ;
 818      (y -> x) = e2 } in x
 819 </programlisting>
 820
 821 (For some amplification on this design choice see
 822 <ulink url="http://hackage.haskell.org/trac/ghc/ticket/4061">Trac #4061</ulink>.)
 823
 824 </para>
 825 </listitem>
 826 </itemizedlist>
 827
 828 </para>
 829 </listitem>
 830
 831 <listitem><para> Typing: If <replaceable>exp</replaceable> has type
 832 <replaceable>T1</replaceable> <literal>-></literal>
 833 <replaceable>T2</replaceable> and <replaceable>pat</replaceable> matches
 834 a <replaceable>T2</replaceable>, then the whole view pattern matches a
 835 <replaceable>T1</replaceable>.
 836 </para></listitem>
 837
 838 <listitem><para> Matching: To the equations in Section 3.17.3 of the
 839 <ulink url="http://www.haskell.org/onlinereport/">Haskell 98
 840 Report</ulink>, add the following:
 841 <programlisting>
 842 case v of { (e -> p) -> e1 ; _ -> e2 }
 843  =
 844 case (e v) of { p -> e1 ; _ -> e2 }
 845 </programlisting>
 846 That is, to match a variable <replaceable>v</replaceable> against a pattern
 847 <literal>(</literal> <replaceable>exp</replaceable>
 848 <literal>-></literal> <replaceable>pat</replaceable>
 849 <literal>)</literal>, evaluate <literal>(</literal>
 850 <replaceable>exp</replaceable> <replaceable> v</replaceable>
 851 <literal>)</literal> and match the result against
 852 <replaceable>pat</replaceable>.
 853 </para></listitem>
 854
 855 <listitem><para> Efficiency: When the same view function is applied in
 856 multiple branches of a function definition or a case expression (e.g.,
 857 in <literal>size</literal> above), GHC makes an attempt to collect these
 858 applications into a single nested case expression, so that the view
 859 function is only applied once.  Pattern compilation in GHC follows the
 860 matrix algorithm described in Chapter 4 of <ulink
 861 url="http://research.microsoft.com/~simonpj/Papers/slpj-book-1987/">The
 862 Implementation of Functional Programming Languages</ulink>.  When the
 863 top rows of the first column of a matrix are all view patterns with the
 864 "same" expression, these patterns are transformed into a single nested
 865 case.  This includes, for example, adjacent view patterns that line up
 866 in a tuple, as in
 867 <programlisting>
 868 f ((view -> A, p1), p2) = e1
 869 f ((view -> B, p3), p4) = e2
 870 </programlisting>
 871 </para>
 872
 873 <para> The current notion of when two view pattern expressions are "the
 874 same" is very restricted: it is not even full syntactic equality.
 875 However, it does include variables, literals, applications, and tuples;
 876 e.g., two instances of <literal>view ("hi", "there")</literal> will be
 877 collected.  However, the current implementation does not compare up to
 878 alpha-equivalence, so two instances of <literal>(x, view x ->
 879 y)</literal> will not be coalesced.
 880 </para>
 881
 882 </listitem>
 883
 884 </itemizedlist>
 885 </para>
 886
 887 </sect2>
 888
 889     <!-- ===================== n+k patterns ===================  -->
 890
 891 <sect2 id="n-k-patterns">
 892 <title>n+k patterns</title>
 893 <indexterm><primary><option>-XNoNPlusKPatterns</option></primary></indexterm>
 894
 895 <para>
 896 <literal>n+k</literal> pattern support is enabled by default. To disable
 897 it, you can use the <option>-XNoNPlusKPatterns</option> flag.
 898 </para>
 899
 900 </sect2>
 901
 902     <!-- ===================== Recursive do-notation ===================  -->
 903
 904 <sect2 id="recursive-do-notation">
 905 <title>The recursive do-notation
 906 </title>
 907
 908 <para>
 909 The do-notation of Haskell 98 does not allow <emphasis>recursive bindings</emphasis>,
 910 that is, the variables bound in a do-expression are visible only in the textually following
 911 code block. Compare this to a let-expression, where bound variables are visible in the entire binding
 912 group. It turns out that several applications can benefit from recursive bindings in
 913 the do-notation.  The <option>-XDoRec</option> flag provides the necessary syntactic support.
 914 </para>
 915 <para>
 916 Here is a simple (albeit contrived) example:
 917 <programlisting>
 918 {-# LANGUAGE DoRec #-}
 919 justOnes = do { rec { xs &lt;- Just (1:xs) }
 920               ; return (map negate xs) }
 921 </programlisting>
 922 As you can guess <literal>justOnes</literal> will evaluate to <literal>Just [-1,-1,-1,...</literal>.
 923 </para>
 924 <para>
 925 The background and motivation for recursive do-notation is described in
 926 <ulink url="http://sites.google.com/site/leventerkok/">A recursive do for Haskell</ulink>,
 927 by Levent Erkok, John Launchbury,
 928 Haskell Workshop 2002, pages: 29-37. Pittsburgh, Pennsylvania.
 929 The theory behind monadic value recursion is explained further in Erkok's thesis
 930 <ulink url="http://sites.google.com/site/leventerkok/erkok-thesis.pdf">Value Recursion in Monadic Computations</ulink>.
 931 However, note that GHC uses a different syntax than the one described in these documents.
 932 </para>
 933
 934 <sect3>
 935 <title>Details of recursive do-notation</title>
 936 <para>
 937 The recursive do-notation is enabled with the flag <option>-XDoRec</option> or, equivalently,
 938 the LANGUAGE pragma <option>DoRec</option>.  It introduces the single new keyword "<literal>rec</literal>",
 939 which wraps a mutually-recursive group of monadic statements,
 940 producing a single statement.
 941 </para>
 942 <para>Similar to a <literal>let</literal>
 943 statement, the variables bound in the <literal>rec</literal> are
 944 visible throughout the <literal>rec</literal> group, and below it.
 945 For example, compare
 946 <programlisting>
 947 do { a &lt;- getChar              do { a &lt;- getChar
 948    ; let { r1 = f a r2             ; rec { r1 &lt;- f a r2
 949          ; r2 = g r1 }                   ; r2 &lt;- g r1 }
 950    ; return (r1 ++ r2) }          ; return (r1 ++ r2) }
 951 </programlisting>
 952 In both cases, <literal>r1</literal> and <literal>r2</literal> are
 953 available both throughout the <literal>let</literal> or <literal>rec</literal> block, and
 954 in the statements that follow it.  The difference is that <literal>let</literal> is non-monadic,
 955 while <literal>rec</literal> is monadic.  (In Haskell <literal>let</literal> is
 956 really <literal>letrec</literal>, of course.)
 957 </para>
 958 <para>
 959 The static and dynamic semantics of <literal>rec</literal> can be described as follows:
 960 <itemizedlist>
 961 <listitem><para>
 962 First,
 963 similar to let-bindings, the <literal>rec</literal> is broken into
 964 minimal recursive groups, a process known as <emphasis>segmentation</emphasis>.
 965 For example:
 966 <programlisting>
 967 rec { a &lt;- getChar      ===>     a &lt;- getChar
 968     ; b &lt;- f a c                 rec { b &lt;- f a c
 969     ; c &lt;- f b a                     ; c &lt;- f b a }
 970     ; putChar c }                putChar c
 971 </programlisting>
 972 The details of segmentation are described in Section 3.2 of
 973 <ulink url="http://sites.google.com/site/leventerkok/">A recursive do for Haskell</ulink>.
 974 Segmentation improves polymorphism, reduces the size of the recursive "knot", and, as the paper
 975 describes, also has a semantic effect (unless the monad satisfies the right-shrinking law).
 976 </para></listitem>
 977 <listitem><para>
 978 Then each resulting <literal>rec</literal> is desugared, using a call to <literal>Control.Monad.Fix.mfix</literal>.
 979 For example, the <literal>rec</literal> group in the preceding example is desugared like this:
 980 <programlisting>
 981 rec { b &lt;- f a c     ===>    (b,c) &lt;- mfix (\~(b,c) -> do { b &lt;- f a c
 982     ; c &lt;- f b a }                                        ; c &lt;- f b a
 983                                                           ; return (b,c) })
 984 </programlisting>
 985 In general, the statment <literal>rec <replaceable>ss</replaceable></literal>
 986 is desugared to the statement
 987 <programlisting>
 988 <replaceable>vs</replaceable> &lt;- mfix (\~<replaceable>vs</replaceable> -&gt; do { <replaceable>ss</replaceable>; return <replaceable>vs</replaceable> })
 989 </programlisting>
 990 where <replaceable>vs</replaceable> is a tuple of the variables bound by <replaceable>ss</replaceable>.
 991 </para><para>
 992 The original <literal>rec</literal> typechecks exactly
 993 when the above desugared version would do so.  For example, this means that
 994 the variables <replaceable>vs</replaceable> are all monomorphic in the statements
 995 following the <literal>rec</literal>, because they are bound by a lambda.
 996 </para>
 997 <para>
 998 The <literal>mfix</literal> function is defined in the <literal>MonadFix</literal>
 999 class, in <literal>Control.Monad.Fix</literal>, thus:
1000 <programlisting>
1001 class Monad m => MonadFix m where
1002    mfix :: (a -> m a) -> m a
1003 </programlisting>
1004 </para>
1005 </listitem>
1006 </itemizedlist>
1007 </para>
1008 <para>
1009 Here are some other important points in using the recursive-do notation:
1010 <itemizedlist>
1011 <listitem><para>
1012 It is enabled with the flag <literal>-XDoRec</literal>, which is in turn implied by
1013 <literal>-fglasgow-exts</literal>.
1014 </para></listitem>
1015
1016 <listitem><para>
1017 If recursive bindings are required for a monad,
1018 then that monad must be declared an instance of the <literal>MonadFix</literal> class.
1019 </para></listitem>
1020
1021 <listitem><para>
1022 The following instances of <literal>MonadFix</literal> are automatically provided: List, Maybe, IO.
1023 Furthermore, the Control.Monad.ST and Control.Monad.ST.Lazy modules provide the instances of the MonadFix class
1024 for Haskell's internal state monad (strict and lazy, respectively).
1025 </para></listitem>
1026
1027 <listitem><para>
1028 Like <literal>let</literal> and <literal>where</literal> bindings,
1029 name shadowing is not allowed within a <literal>rec</literal>;
1030 that is, all the names bound in a single <literal>rec</literal> must
1031 be distinct (Section 3.3 of the paper).
1032 </para></listitem>
1033 <listitem><para>
1034 It supports rebindable syntax (see <xref linkend="rebindable-syntax"/>).
1035 </para></listitem>
1036 </itemizedlist>
1037 </para>
1038 </sect3>
1039
1040 <sect3 id="mdo-notation"> <title> Mdo-notation (deprecated) </title>
1041
1042 <para> GHC used to support the flag <option>-XRecursiveDo</option>,
1043 which enabled the keyword <literal>mdo</literal>, precisely as described in
1044 <ulink url="http://sites.google.com/site/leventerkok/">A recursive do for Haskell</ulink>,
1045 but this is now deprecated.  Instead of <literal>mdo { Q; e }</literal>, write
1046 <literal>do { rec Q; e }</literal>.
1047 </para>
1048 <para>
1049 Historical note: The old implementation of the mdo-notation (and most
1050 of the existing documents) used the name
1051 <literal>MonadRec</literal> for the class and the corresponding library.
1052 This name is not supported by GHC.
1053 </para>
1054 </sect3>
1055
1056 </sect2>
1057
1058
1059    <!-- ===================== PARALLEL LIST COMPREHENSIONS ===================  -->
1060
1061   <sect2 id="parallel-list-comprehensions">
1062     <title>Parallel List Comprehensions</title>
1063     <indexterm><primary>list comprehensions</primary><secondary>parallel</secondary>
1064     </indexterm>
1065     <indexterm><primary>parallel list comprehensions</primary>
1066     </indexterm>
1067
1068     <para>Parallel list comprehensions are a natural extension to list
1069     comprehensions.  List comprehensions can be thought of as a nice
1070     syntax for writing maps and filters.  Parallel comprehensions
1071     extend this to include the zipWith family.</para>
1072
1073     <para>A parallel list comprehension has multiple independent
1074     branches of qualifier lists, each separated by a `|' symbol.  For
1075     example, the following zips together two lists:</para>
1076
1077 <programlisting>
1078    [ (x, y) | x &lt;- xs | y &lt;- ys ]
1079 </programlisting>
1080
1081     <para>The behavior of parallel list comprehensions follows that of
1082     zip, in that the resulting list will have the same length as the
1083     shortest branch.</para>
1084
1085     <para>We can define parallel list comprehensions by translation to
1086     regular comprehensions.  Here's the basic idea:</para>
1087
1088     <para>Given a parallel comprehension of the form: </para>
1089
1090 <programlisting>
1091    [ e | p1 &lt;- e11, p2 &lt;- e12, ...
1092        | q1 &lt;- e21, q2 &lt;- e22, ...
1093        ...
1094    ]
1095 </programlisting>
1096
1097     <para>This will be translated to: </para>
1098
1099 <programlisting>
1100    [ e | ((p1,p2), (q1,q2), ...) &lt;- zipN [(p1,p2) | p1 &lt;- e11, p2 &lt;- e12, ...]
1101                                          [(q1,q2) | q1 &lt;- e21, q2 &lt;- e22, ...]
1102                                          ...
1103    ]
1104 </programlisting>
1105
1106     <para>where `zipN' is the appropriate zip for the given number of
1107     branches.</para>
1108
1109   </sect2>
1110
1111   <!-- ===================== TRANSFORM LIST COMPREHENSIONS ===================  -->
1112
1113   <sect2 id="generalised-list-comprehensions">
1114     <title>Generalised (SQL-Like) List Comprehensions</title>
1115     <indexterm><primary>list comprehensions</primary><secondary>generalised</secondary>
1116     </indexterm>
1117     <indexterm><primary>extended list comprehensions</primary>
1118     </indexterm>
1119     <indexterm><primary>group</primary></indexterm>
1120     <indexterm><primary>sql</primary></indexterm>
1121
1122
1123     <para>Generalised list comprehensions are a further enhancement to the
1124     list comprehension syntactic sugar to allow operations such as sorting
1125     and grouping which are familiar from SQL.   They are fully described in the
1126         paper <ulink url="http://research.microsoft.com/~simonpj/papers/list-comp">
1127           Comprehensive comprehensions: comprehensions with "order by" and "group by"</ulink>,
1128     except that the syntax we use differs slightly from the paper.</para>
1129 <para>The extension is enabled with the flag <option>-XTransformListComp</option>.</para>
1130 <para>Here is an example:
1131 <programlisting>
1132 employees = [ ("Simon", "MS", 80)
1133 , ("Erik", "MS", 100)
1134 , ("Phil", "Ed", 40)
1135 , ("Gordon", "Ed", 45)
1136 , ("Paul", "Yale", 60)]
1137
1138 output = [ (the dept, sum salary)
1139 | (name, dept, salary) &lt;- employees
1140 , then group by dept
1141 , then sortWith by (sum salary)
1142 , then take 5 ]
1143 </programlisting>
1144 In this example, the list <literal>output</literal> would take on
1145     the value:
1146
1147 <programlisting>
1148 [("Yale", 60), ("Ed", 85), ("MS", 180)]
1149 </programlisting>
1150 </para>
1151 <para>There are three new keywords: <literal>group</literal>, <literal>by</literal>, and <literal>using</literal>.
1152 (The function <literal>sortWith</literal> is not a keyword; it is an ordinary
1153 function that is exported by <literal>GHC.Exts</literal>.)</para>
1154
1155 <para>There are five new forms of comprehension qualifier,
1156 all introduced by the (existing) keyword <literal>then</literal>:
1157     <itemizedlist>
1158     <listitem>
1159
1160 <programlisting>
1161 then f
1162 </programlisting>
1163
1164     This statement requires that <literal>f</literal> have the type <literal>
1165     forall a. [a] -> [a]</literal>. You can see an example of its use in the
1166     motivating example, as this form is used to apply <literal>take 5</literal>.
1167
1168     </listitem>
1169
1170
1171     <listitem>
1172 <para>
1173 <programlisting>
1174 then f by e
1175 </programlisting>
1176
1177     This form is similar to the previous one, but allows you to create a function
1178     which will be passed as the first argument to f. As a consequence f must have
1179     the type <literal>forall a. (a -> t) -> [a] -> [a]</literal>. As you can see
1180     from the type, this function lets f &quot;project out&quot; some information
1181     from the elements of the list it is transforming.</para>
1182
1183     <para>An example is shown in the opening example, where <literal>sortWith</literal>
1184     is supplied with a function that lets it find out the <literal>sum salary</literal>
1185     for any item in the list comprehension it transforms.</para>
1186
1187     </listitem>
1188
1189
1190     <listitem>
1191
1192 <programlisting>
1193 then group by e using f
1194 </programlisting>
1195
1196     <para>This is the most general of the grouping-type statements. In this form,
1197     f is required to have type <literal>forall a. (a -> t) -> [a] -> [[a]]</literal>.
1198     As with the <literal>then f by e</literal> case above, the first argument
1199     is a function supplied to f by the compiler which lets it compute e on every
1200     element of the list being transformed. However, unlike the non-grouping case,
1201     f additionally partitions the list into a number of sublists: this means that
1202     at every point after this statement, binders occurring before it in the comprehension
1203     refer to <emphasis>lists</emphasis> of possible values, not single values. To help understand
1204     this, let's look at an example:</para>
1205
1206 <programlisting>
1207 -- This works similarly to groupWith in GHC.Exts, but doesn't sort its input first
1208 groupRuns :: Eq b => (a -> b) -> [a] -> [[a]]
1209 groupRuns f = groupBy (\x y -> f x == f y)
1210
1211 output = [ (the x, y)
1212 | x &lt;- ([1..3] ++ [1..2])
1213 , y &lt;- [4..6]
1214 , then group by x using groupRuns ]
1215 </programlisting>
1216
1217     <para>This results in the variable <literal>output</literal> taking on the value below:</para>
1218
1219 <programlisting>
1220 [(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])]
1221 </programlisting>
1222
1223     <para>Note that we have used the <literal>the</literal> function to change the type
1224     of x from a list to its original numeric type. The variable y, in contrast, is left
1225     unchanged from the list form introduced by the grouping.</para>
1226
1227     </listitem>
1228
1229     <listitem>
1230
1231 <programlisting>
1232 then group by e
1233 </programlisting>
1234
1235     <para>This form of grouping is essentially the same as the one described above. However,
1236     since no function to use for the grouping has been supplied it will fall back on the
1237     <literal>groupWith</literal> function defined in
1238     <ulink url="&libraryBaseLocation;/GHC-Exts.html"><literal>GHC.Exts</literal></ulink>. This
1239     is the form of the group statement that we made use of in the opening example.</para>
1240
1241     </listitem>
1242
1243
1244     <listitem>
1245
1246 <programlisting>
1247 then group using f
1248 </programlisting>
1249
1250     <para>With this form of the group statement, f is required to simply have the type
1251     <literal>forall a. [a] -> [[a]]</literal>, which will be used to group up the
1252     comprehension so far directly. An example of this form is as follows:</para>
1253
1254 <programlisting>
1255 output = [ x
1256 | y &lt;- [1..5]
1257 , x &lt;- "hello"
1258 , then group using inits]
1259 </programlisting>
1260
1261     <para>This will yield a list containing every prefix of the word "hello" written out 5 times:</para>
1262
1263 <programlisting>
1264 ["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...]
1265 </programlisting>
1266
1267     </listitem>
1268 </itemizedlist>
1269 </para>
1270   </sect2>
1271
1272    <!-- ===================== REBINDABLE SYNTAX ===================  -->
1273
1274 <sect2 id="rebindable-syntax">
1275 <title>Rebindable syntax and the implicit Prelude import</title>
1276
1277  <para><indexterm><primary>-XNoImplicitPrelude
1278  option</primary></indexterm> GHC normally imports
1279  <filename>Prelude.hi</filename> files for you.  If you'd
1280  rather it didn't, then give it a
1281  <option>-XNoImplicitPrelude</option> option.  The idea is
1282  that you can then import a Prelude of your own.  (But don't
1283  call it <literal>Prelude</literal>; the Haskell module
1284  namespace is flat, and you must not conflict with any
1285  Prelude module.)</para>
1286
1287             <para>Suppose you are importing a Prelude of your own
1288               in order to define your own numeric class
1289             hierarchy.  It completely defeats that purpose if the
1290             literal "1" means "<literal>Prelude.fromInteger
1291             1</literal>", which is what the Haskell Report specifies.
1292             So the <option>-XNoImplicitPrelude</option>
1293               flag <emphasis>also</emphasis> causes
1294             the following pieces of built-in syntax to refer to
1295             <emphasis>whatever is in scope</emphasis>, not the Prelude
1296             versions:
1297             <itemizedlist>
1298               <listitem>
1299                 <para>An integer literal <literal>368</literal> means
1300                 "<literal>fromInteger (368::Integer)</literal>", rather than
1301                 "<literal>Prelude.fromInteger (368::Integer)</literal>".
1302 </para> </listitem>
1303
1304       <listitem><para>Fractional literals are handed in just the same way,
1305           except that the translation is
1306               <literal>fromRational (3.68::Rational)</literal>.
1307 </para> </listitem>
1308
1309           <listitem><para>The equality test in an overloaded numeric pattern
1310               uses whatever <literal>(==)</literal> is in scope.
1311 </para> </listitem>
1312
1313           <listitem><para>The subtraction operation, and the
1314           greater-than-or-equal test, in <literal>n+k</literal> patterns
1315               use whatever <literal>(-)</literal> and <literal>(>=)</literal> are in scope.
1316               </para></listitem>
1317
1318               <listitem>
1319                 <para>Negation (e.g. "<literal>- (f x)</literal>")
1320                 means "<literal>negate (f x)</literal>", both in numeric
1321                 patterns, and expressions.
1322               </para></listitem>
1323
1324               <listitem>
1325           <para>"Do" notation is translated using whatever
1326               functions <literal>(>>=)</literal>,
1327               <literal>(>>)</literal>, and <literal>fail</literal>,
1328               are in scope (not the Prelude
1329               versions).  List comprehensions, mdo (<xref linkend="mdo-notation"/>), and parallel array
1330               comprehensions, are unaffected.  </para></listitem>
1331
1332               <listitem>
1333                 <para>Arrow
1334                 notation (see <xref linkend="arrow-notation"/>)
1335                 uses whatever <literal>arr</literal>,
1336                 <literal>(>>>)</literal>, <literal>first</literal>,
1337                 <literal>app</literal>, <literal>(|||)</literal> and
1338                 <literal>loop</literal> functions are in scope. But unlike the
1339                 other constructs, the types of these functions must match the
1340                 Prelude types very closely.  Details are in flux; if you want
1341                 to use this, ask!
1342               </para></listitem>
1343             </itemizedlist>
1344 In all cases (apart from arrow notation), the static semantics should be that of the desugared form,
1345 even if that is a little unexpected. For example, the
1346 static semantics of the literal <literal>368</literal>
1347 is exactly that of <literal>fromInteger (368::Integer)</literal>; it's fine for
1348 <literal>fromInteger</literal> to have any of the types:
1349 <programlisting>
1350 fromInteger :: Integer -> Integer
1351 fromInteger :: forall a. Foo a => Integer -> a
1352 fromInteger :: Num a => a -> Integer
1353 fromInteger :: Integer -> Bool -> Bool
1354 </programlisting>
1355 </para>
1356
1357              <para>Be warned: this is an experimental facility, with
1358              fewer checks than usual.  Use <literal>-dcore-lint</literal>
1359              to typecheck the desugared program.  If Core Lint is happy
1360              you should be all right.</para>
1361
1362 </sect2>
1363
1364 <sect2 id="postfix-operators">
1365 <title>Postfix operators</title>
1366
1367 <para>
1368   The <option>-XPostfixOperators</option> flag enables a small
1369 extension to the syntax of left operator sections, which allows you to
1370 define postfix operators.  The extension is this: the left section
1371 <programlisting>
1372   (e !)
1373 </programlisting>
1374 is equivalent (from the point of view of both type checking and execution) to the expression
1375 <programlisting>
1376   ((!) e)
1377 </programlisting>
1378 (for any expression <literal>e</literal> and operator <literal>(!)</literal>.
1379 The strict Haskell 98 interpretation is that the section is equivalent to
1380 <programlisting>
1381   (\y -> (!) e y)
1382 </programlisting>
1383 That is, the operator must be a function of two arguments.  GHC allows it to
1384 take only one argument, and that in turn allows you to write the function
1385 postfix.
1386 </para>
1387 <para>The extension does not extend to the left-hand side of function
1388 definitions; you must define such a function in prefix form.</para>
1389
1390 </sect2>
1391
1392 <sect2 id="tuple-sections">
1393 <title>Tuple sections</title>
1394
1395 <para>
1396   The <option>-XTupleSections</option> flag enables Python-style partially applied
1397   tuple constructors. For example, the following program
1398 <programlisting>
1399   (, True)
1400 </programlisting>
1401   is considered to be an alternative notation for the more unwieldy alternative
1402 <programlisting>
1403   \x -> (x, True)
1404 </programlisting>
1405 You can omit any combination of arguments to the tuple, as in the following
1406 <programlisting>
1407   (, "I", , , "Love", , 1337)
1408 </programlisting>
1409 which translates to
1410 <programlisting>
1411   \a b c d -> (a, "I", b, c, "Love", d, 1337)
1412 </programlisting>
1413 </para>
1414
1415 <para>
1416   If you have <link linkend="unboxed-tuples">unboxed tuples</link> enabled, tuple sections
1417   will also be available for them, like so
1418 <programlisting>
1419   (# , True #)
1420 </programlisting>
1421 Because there is no unboxed unit tuple, the following expression
1422 <programlisting>
1423   (# #)
1424 </programlisting>
1425 continues to stand for the unboxed singleton tuple data constructor.
1426 </para>
1427
1428 </sect2>
1429
1430 <sect2 id="disambiguate-fields">
1431 <title>Record field disambiguation</title>
1432 <para>
1433 In record construction and record pattern matching
1434 it is entirely unambiguous which field is referred to, even if there are two different
1435 data types in scope with a common field name.  For example:
1436 <programlisting>
1437 module M where
1438   data S = MkS { x :: Int, y :: Bool }
1439
1440 module Foo where
1441   import M
1442
1443   data T = MkT { x :: Int }
1444
1445   ok1 (MkS { x = n }) = n+1   -- Unambiguous
1446   ok2 n = MkT { x = n+1 }     -- Unambiguous
1447
1448   bad1 k = k { x = 3 }  -- Ambiguous
1449   bad2 k = x k          -- Ambiguous
1450 </programlisting>
1451 Even though there are two <literal>x</literal>'s in scope,
1452 it is clear that the <literal>x</literal> in the pattern in the
1453 definition of <literal>ok1</literal> can only mean the field
1454 <literal>x</literal> from type <literal>S</literal>. Similarly for
1455 the function <literal>ok2</literal>.  However, in the record update
1456 in <literal>bad1</literal> and the record selection in <literal>bad2</literal>
1457 it is not clear which of the two types is intended.
1458 </para>
1459 <para>
1460 Haskell 98 regards all four as ambiguous, but with the
1461 <option>-XDisambiguateRecordFields</option> flag, GHC will accept
1462 the former two.  The rules are precisely the same as those for instance
1463 declarations in Haskell 98, where the method names on the left-hand side
1464 of the method bindings in an instance declaration refer unambiguously
1465 to the method of that class (provided they are in scope at all), even
1466 if there are other variables in scope with the same name.
1467 This reduces the clutter of qualified names when you import two
1468 records from different modules that use the same field name.
1469 </para>
1470 <para>
1471 Some details:
1472 <itemizedlist>
1473 <listitem><para>
1474 Field disambiguation can be combined with punning (see <xref linkend="record-puns"/>). For exampe:
1475 <programlisting>
1476 module Foo where
1477   import M
1478   x=True
1479   ok3 (MkS { x }) = x+1   -- Uses both disambiguation and punning
1480 </programlisting>
1481 </para></listitem>
1482
1483 <listitem><para>
1484 With <option>-XDisambiguateRecordFields</option> you can use <emphasis>unqualifed</emphasis>
1485 field names even if the correponding selector is only in scope <emphasis>qualified</emphasis>
1486 For example, assuming the same module <literal>M</literal> as in our earlier example, this is legal:
1487 <programlisting>
1488 module Foo where
1489   import qualified M    -- Note qualified
1490
1491   ok4 (M.MkS { x = n }) = n+1   -- Unambiguous
1492 </programlisting>
1493 Since the constructore <literal>MkS</literal> is only in scope qualified, you must
1494 name it <literal>M.MkS</literal>, but the field <literal>x</literal> does not need
1495 to be qualified even though <literal>M.x</literal> is in scope but <literal>x</literal>
1496 is not.  (In effect, it is qualified by the constructor.)
1497 </para></listitem>
1498 </itemizedlist>
1499 </para>
1500
1501 </sect2>
1502
1503     <!-- ===================== Record puns ===================  -->
1504
1505 <sect2 id="record-puns">
1506 <title>Record puns
1507 </title>
1508
1509 <para>
1510 Record puns are enabled by the flag <literal>-XNamedFieldPuns</literal>.
1511 </para>
1512
1513 <para>
1514 When using records, it is common to write a pattern that binds a
1515 variable with the same name as a record field, such as:
1516
1517 <programlisting>
1518 data C = C {a :: Int}
1519 f (C {a = a}) = a
1520 </programlisting>
1521 </para>
1522
1523 <para>
1524 Record punning permits the variable name to be elided, so one can simply
1525 write
1526
1527 <programlisting>
1528 f (C {a}) = a
1529 </programlisting>
1530
1531 to mean the same pattern as above.  That is, in a record pattern, the
1532 pattern <literal>a</literal> expands into the pattern <literal>a =
1533 a</literal> for the same name <literal>a</literal>.
1534 </para>
1535
1536 <para>
1537 Note that:
1538 <itemizedlist>
1539 <listitem><para>
1540 Record punning can also be used in an expression, writing, for example,
1541 <programlisting>
1542 let a = 1 in C {a}
1543 </programlisting>
1544 instead of
1545 <programlisting>
1546 let a = 1 in C {a = a}
1547 </programlisting>
1548 The expansion is purely syntactic, so the expanded right-hand side
1549 expression refers to the nearest enclosing variable that is spelled the
1550 same as the field name.
1551 </para></listitem>
1552
1553 <listitem><para>
1554 Puns and other patterns can be mixed in the same record:
1555 <programlisting>
1556 data C = C {a :: Int, b :: Int}
1557 f (C {a, b = 4}) = a
1558 </programlisting>
1559 </para></listitem>
1560
1561 <listitem><para>
1562 Puns can be used wherever record patterns occur (e.g. in
1563 <literal>let</literal> bindings or at the top-level).
1564 </para></listitem>
1565
1566 <listitem><para>
1567 A pun on a qualified field name is expanded by stripping off the module qualifier.
1568 For example:
1569 <programlisting>
1570 f (C {M.a}) = a
1571 </programlisting>
1572 means
1573 <programlisting>
1574 f (M.C {M.a = a}) = a
1575 </programlisting>
1576 (This is useful if the field selector <literal>a</literal> for constructor <literal>M.C</literal>
1577 is only in scope in qualified form.)
1578 </para></listitem>
1579 </itemizedlist>
1580 </para>
1581
1582
1583 </sect2>
1584
1585     <!-- ===================== Record wildcards ===================  -->
1586
1587 <sect2 id="record-wildcards">
1588 <title>Record wildcards
1589 </title>
1590
1591 <para>
1592 Record wildcards are enabled by the flag <literal>-XRecordWildCards</literal>.
1593 This flag implies <literal>-XDisambiguateRecordFields</literal>.
1594 </para>
1595
1596 <para>
1597 For records with many fields, it can be tiresome to write out each field
1598 individually in a record pattern, as in
1599 <programlisting>
1600 data C = C {a :: Int, b :: Int, c :: Int, d :: Int}
1601 f (C {a = 1, b = b, c = c, d = d}) = b + c + d
1602 </programlisting>
1603 </para>
1604
1605 <para>
1606 Record wildcard syntax permits a "<literal>..</literal>" in a record
1607 pattern, where each elided field <literal>f</literal> is replaced by the
1608 pattern <literal>f = f</literal>.  For example, the above pattern can be
1609 written as
1610 <programlisting>
1611 f (C {a = 1, ..}) = b + c + d
1612 </programlisting>
1613 </para>
1614
1615 <para>
1616 More details:
1617 <itemizedlist>
1618 <listitem><para>
1619 Wildcards can be mixed with other patterns, including puns
1620 (<xref linkend="record-puns"/>); for example, in a pattern <literal>C {a
1621 = 1, b, ..})</literal>.  Additionally, record wildcards can be used
1622 wherever record patterns occur, including in <literal>let</literal>
1623 bindings and at the top-level.  For example, the top-level binding
1624 <programlisting>
1625 C {a = 1, ..} = e
1626 </programlisting>
1627 defines <literal>b</literal>, <literal>c</literal>, and
1628 <literal>d</literal>.
1629 </para></listitem>
1630
1631 <listitem><para>
1632 Record wildcards can also be used in expressions, writing, for example,
1633 <programlisting>
1634 let {a = 1; b = 2; c = 3; d = 4} in C {..}
1635 </programlisting>
1636 in place of
1637 <programlisting>
1638 let {a = 1; b = 2; c = 3; d = 4} in C {a=a, b=b, c=c, d=d}
1639 </programlisting>
1640 The expansion is purely syntactic, so the record wildcard
1641 expression refers to the nearest enclosing variables that are spelled
1642 the same as the omitted field names.
1643 </para></listitem>
1644
1645 <listitem><para>
1646 The "<literal>..</literal>" expands to the missing
1647 <emphasis>in-scope</emphasis> record fields, where "in scope"
1648 includes both unqualified and qualified-only.
1649 Any fields that are not in scope are not filled in.  For example
1650 <programlisting>
1651 module M where
1652   data R = R { a,b,c :: Int }
1653 module X where
1654   import qualified M( R(a,b) )
1655   f a b = R { .. }
1656 </programlisting>
1657 The <literal>{..}</literal> expands to <literal>{M.a=a,M.b=b}</literal>,
1658 omitting <literal>c</literal> since it is not in scope at all.
1659 </para></listitem>
1660 </itemizedlist>
1661 </para>
1662
1663 </sect2>
1664
1665     <!-- ===================== Local fixity declarations ===================  -->
1666
1667 <sect2 id="local-fixity-declarations">
1668 <title>Local Fixity Declarations
1669 </title>
1670
1671 <para>A careful reading of the Haskell 98 Report reveals that fixity
1672 declarations (<literal>infix</literal>, <literal>infixl</literal>, and
1673 <literal>infixr</literal>) are permitted to appear inside local bindings
1674 such those introduced by <literal>let</literal> and
1675 <literal>where</literal>.  However, the Haskell Report does not specify
1676 the semantics of such bindings very precisely.
1677 </para>
1678
1679 <para>In GHC, a fixity declaration may accompany a local binding:
1680 <programlisting>
1681 let f = ...
1682     infixr 3 `f`
1683 in
1684     ...
1685 </programlisting>
1686 and the fixity declaration applies wherever the binding is in scope.
1687 For example, in a <literal>let</literal>, it applies in the right-hand
1688 sides of other <literal>let</literal>-bindings and the body of the
1689 <literal>let</literal>C. Or, in recursive <literal>do</literal>
1690 expressions (<xref linkend="recursive-do-notation"/>), the local fixity
1691 declarations of a <literal>let</literal> statement scope over other
1692 statements in the group, just as the bound name does.
1693 </para>
1694
1695 <para>
1696 Moreover, a local fixity declaration *must* accompany a local binding of
1697 that name: it is not possible to revise the fixity of name bound
1698 elsewhere, as in
1699 <programlisting>
1700 let infixr 9 $ in ...
1701 </programlisting>
1702
1703 Because local fixity declarations are technically Haskell 98, no flag is
1704 necessary to enable them.
1705 </para>
1706 </sect2>
1707
1708 <sect2 id="package-imports">
1709   <title>Package-qualified imports</title>
1710
1711   <para>With the <option>-XPackageImports</option> flag, GHC allows
1712   import declarations to be qualified by the package name that the
1713     module is intended to be imported from.  For example:</para>
1714
1715 <programlisting>
1716 import "network" Network.Socket
1717 </programlisting>
1718
1719   <para>would import the module <literal>Network.Socket</literal> from
1720     the package <literal>network</literal> (any version).  This may
1721     be used to disambiguate an import when the same module is
1722     available from multiple packages, or is present in both the
1723     current package being built and an external package.</para>
1724
1725   <para>Note: you probably don't need to use this feature, it was
1726     added mainly so that we can build backwards-compatible versions of
1727     packages when APIs change.  It can lead to fragile dependencies in
1728     the common case: modules occasionally move from one package to
1729     another, rendering any package-qualified imports broken.</para>
1730 </sect2>
1731
1732 <sect2 id="syntax-stolen">
1733 <title>Summary of stolen syntax</title>
1734
1735     <para>Turning on an option that enables special syntax
1736     <emphasis>might</emphasis> cause working Haskell 98 code to fail
1737     to compile, perhaps because it uses a variable name which has
1738     become a reserved word.  This section lists the syntax that is
1739     "stolen" by language extensions.
1740      We use
1741     notation and nonterminal names from the Haskell 98 lexical syntax
1742     (see the Haskell 98 Report).
1743     We only list syntax changes here that might affect
1744     existing working programs (i.e. "stolen" syntax).  Many of these
1745     extensions will also enable new context-free syntax, but in all
1746     cases programs written to use the new syntax would not be
1747     compilable without the option enabled.</para>
1748
1749 <para>There are two classes of special
1750     syntax:
1751
1752     <itemizedlist>
1753       <listitem>
1754         <para>New reserved words and symbols: character sequences
1755         which are no longer available for use as identifiers in the
1756         program.</para>
1757       </listitem>
1758       <listitem>
1759         <para>Other special syntax: sequences of characters that have
1760         a different meaning when this particular option is turned
1761         on.</para>
1762       </listitem>
1763     </itemizedlist>
1764
1765 The following syntax is stolen:
1766
1767     <variablelist>
1768       <varlistentry>
1769         <term>
1770           <literal>forall</literal>
1771           <indexterm><primary><literal>forall</literal></primary></indexterm>
1772         </term>
1773         <listitem><para>
1774         Stolen (in types) by: <option>-XExplicitForAll</option>, and hence by
1775             <option>-XScopedTypeVariables</option>,
1776             <option>-XLiberalTypeSynonyms</option>,
1777             <option>-XRank2Types</option>,
1778             <option>-XRankNTypes</option>,
1779             <option>-XPolymorphicComponents</option>,
1780             <option>-XExistentialQuantification</option>
1781           </para></listitem>
1782       </varlistentry>
1783
1784       <varlistentry>
1785         <term>
1786           <literal>mdo</literal>
1787           <indexterm><primary><literal>mdo</literal></primary></indexterm>
1788         </term>
1789         <listitem><para>
1790         Stolen by: <option>-XRecursiveDo</option>,
1791           </para></listitem>
1792       </varlistentry>
1793
1794       <varlistentry>
1795         <term>
1796           <literal>foreign</literal>
1797           <indexterm><primary><literal>foreign</literal></primary></indexterm>
1798         </term>
1799         <listitem><para>
1800         Stolen by: <option>-XForeignFunctionInterface</option>,
1801           </para></listitem>
1802       </varlistentry>
1803
1804       <varlistentry>
1805         <term>
1806           <literal>rec</literal>,
1807           <literal>proc</literal>, <literal>-&lt;</literal>,
1808           <literal>&gt;-</literal>, <literal>-&lt;&lt;</literal>,
1809           <literal>&gt;&gt;-</literal>, and <literal>(|</literal>,
1810           <literal>|)</literal> brackets
1811           <indexterm><primary><literal>proc</literal></primary></indexterm>
1812         </term>
1813         <listitem><para>
1814         Stolen by: <option>-XArrows</option>,
1815           </para></listitem>
1816       </varlistentry>
1817
1818       <varlistentry>
1819         <term>
1820           <literal>?<replaceable>varid</replaceable></literal>,
1821           <literal>%<replaceable>varid</replaceable></literal>
1822           <indexterm><primary>implicit parameters</primary></indexterm>
1823         </term>
1824         <listitem><para>
1825         Stolen by: <option>-XImplicitParams</option>,
1826           </para></listitem>
1827       </varlistentry>
1828
1829       <varlistentry>
1830         <term>
1831           <literal>[|</literal>,
1832           <literal>[e|</literal>, <literal>[p|</literal>,
1833           <literal>[d|</literal>, <literal>[t|</literal>,
1834           <literal>$(</literal>,
1835           <literal>$<replaceable>varid</replaceable></literal>
1836           <indexterm><primary>Template Haskell</primary></indexterm>
1837         </term>
1838         <listitem><para>
1839         Stolen by: <option>-XTemplateHaskell</option>,
1840           </para></listitem>
1841       </varlistentry>
1842
1843       <varlistentry>
1844         <term>
1845           <literal>[:<replaceable>varid</replaceable>|</literal>
1846           <indexterm><primary>quasi-quotation</primary></indexterm>
1847         </term>
1848         <listitem><para>
1849         Stolen by: <option>-XQuasiQuotes</option>,
1850           </para></listitem>
1851       </varlistentry>
1852
1853       <varlistentry>
1854         <term>
1855               <replaceable>varid</replaceable>{<literal>&num;</literal>},
1856               <replaceable>char</replaceable><literal>&num;</literal>,
1857               <replaceable>string</replaceable><literal>&num;</literal>,
1858               <replaceable>integer</replaceable><literal>&num;</literal>,
1859               <replaceable>float</replaceable><literal>&num;</literal>,
1860               <replaceable>float</replaceable><literal>&num;&num;</literal>,
1861               <literal>(&num;</literal>, <literal>&num;)</literal>,
1862         </term>
1863         <listitem><para>
1864         Stolen by: <option>-XMagicHash</option>,
1865           </para></listitem>
1866       </varlistentry>
1867     </variablelist>
1868 </para>
1869 </sect2>
1870 </sect1>
1871
1872
1873 <!-- TYPE SYSTEM EXTENSIONS -->
1874 <sect1 id="data-type-extensions">
1875 <title>Extensions to data types and type synonyms</title>
1876
1877 <sect2 id="nullary-types">
1878 <title>Data types with no constructors</title>
1879
1880 <para>With the <option>-fglasgow-exts</option> flag, GHC lets you declare
1881 a data type with no constructors.  For example:</para>
1882
1883 <programlisting>
1884   data S      -- S :: *
1885   data T a    -- T :: * -> *
1886 </programlisting>
1887
1888 <para>Syntactically, the declaration lacks the "= constrs" part.  The
1889 type can be parameterised over types of any kind, but if the kind is
1890 not <literal>*</literal> then an explicit kind annotation must be used
1891 (see <xref linkend="kinding"/>).</para>
1892
1893 <para>Such data types have only one value, namely bottom.
1894 Nevertheless, they can be useful when defining "phantom types".</para>
1895 </sect2>
1896
1897 <sect2 id="infix-tycons">
1898 <title>Infix type constructors, classes, and type variables</title>
1899
1900 <para>
1901 GHC allows type constructors, classes, and type variables to be operators, and
1902 to be written infix, very much like expressions.  More specifically:
1903 <itemizedlist>
1904 <listitem><para>
1905   A type constructor or class can be an operator, beginning with a colon; e.g. <literal>:*:</literal>.
1906   The lexical syntax is the same as that for data constructors.
1907   </para></listitem>
1908 <listitem><para>
1909   Data type and type-synonym declarations can be written infix, parenthesised
1910   if you want further arguments.  E.g.
1911 <screen>
1912   data a :*: b = Foo a b
1913   type a :+: b = Either a b
1914   class a :=: b where ...
1915
1916   data (a :**: b) x = Baz a b x
1917   type (a :++: b) y = Either (a,b) y
1918 </screen>
1919   </para></listitem>
1920 <listitem><para>
1921   Types, and class constraints, can be written infix.  For example
1922   <screen>
1923         x :: Int :*: Bool
1924         f :: (a :=: b) => a -> b
1925   </screen>
1926   </para></listitem>
1927 <listitem><para>
1928   A type variable can be an (unqualified) operator e.g. <literal>+</literal>.
1929   The lexical syntax is the same as that for variable operators, excluding "(.)",
1930   "(!)", and "(*)".  In a binding position, the operator must be
1931   parenthesised.  For example:
1932 <programlisting>
1933    type T (+) = Int + Int
1934    f :: T Either
1935    f = Left 3
1936
1937    liftA2 :: Arrow (~>)
1938           => (a -> b -> c) -> (e ~> a) -> (e ~> b) -> (e ~> c)
1939    liftA2 = ...
1940 </programlisting>
1941   </para></listitem>
1942 <listitem><para>
1943   Back-quotes work
1944   as for expressions, both for type constructors and type variables;  e.g. <literal>Int `Either` Bool</literal>, or
1945   <literal>Int `a` Bool</literal>.  Similarly, parentheses work the same; e.g.  <literal>(:*:) Int Bool</literal>.
1946   </para></listitem>
1947 <listitem><para>
1948   Fixities may be declared for type constructors, or classes, just as for data constructors.  However,
1949   one cannot distinguish between the two in a fixity declaration; a fixity declaration
1950   sets the fixity for a data constructor and the corresponding type constructor.  For example:
1951 <screen>
1952   infixl 7 T, :*:
1953 </screen>
1954   sets the fixity for both type constructor <literal>T</literal> and data constructor <literal>T</literal>,
1955   and similarly for <literal>:*:</literal>.
1956   <literal>Int `a` Bool</literal>.
1957   </para></listitem>
1958 <listitem><para>
1959   Function arrow is <literal>infixr</literal> with fixity 0.  (This might change; I'm not sure what it should be.)
1960   </para></listitem>
1961
1962 </itemizedlist>
1963 </para>
1964 </sect2>
1965
1966 <sect2 id="type-synonyms">
1967 <title>Liberalised type synonyms</title>
1968
1969 <para>
1970 Type synonyms are like macros at the type level, but Haskell 98 imposes many rules
1971 on individual synonym declarations.
1972 With the <option>-XLiberalTypeSynonyms</option> extension,
1973 GHC does validity checking on types <emphasis>only after expanding type synonyms</emphasis>.
1974 That means that GHC can be very much more liberal about type synonyms than Haskell 98.
1975
1976 <itemizedlist>
1977 <listitem> <para>You can write a <literal>forall</literal> (including overloading)
1978 in a type synonym, thus:
1979 <programlisting>
1980   type Discard a = forall b. Show b => a -> b -> (a, String)
1981
1982   f :: Discard a
1983   f x y = (x, show y)
1984
1985   g :: Discard Int -> (Int,String)    -- A rank-2 type
1986   g f = f 3 True
1987 </programlisting>
1988 </para>
1989 </listitem>
1990
1991 <listitem><para>
1992 If you also use <option>-XUnboxedTuples</option>,
1993 you can write an unboxed tuple in a type synonym:
1994 <programlisting>
1995   type Pr = (# Int, Int #)
1996
1997   h :: Int -> Pr
1998   h x = (# x, x #)
1999 </programlisting>
2000 </para></listitem>
2001
2002 <listitem><para>
2003 You can apply a type synonym to a forall type:
2004 <programlisting>
2005   type Foo a = a -> a -> Bool
2006
2007   f :: Foo (forall b. b->b)
2008 </programlisting>
2009 After expanding the synonym, <literal>f</literal> has the legal (in GHC) type:
2010 <programlisting>
2011   f :: (forall b. b->b) -> (forall b. b->b) -> Bool
2012 </programlisting>
2013 </para></listitem>
2014
2015 <listitem><para>
2016 You can apply a type synonym to a partially applied type synonym:
2017 <programlisting>
2018   type Generic i o = forall x. i x -> o x
2019   type Id x = x
2020
2021   foo :: Generic Id []
2022 </programlisting>
2023 After expanding the synonym, <literal>foo</literal> has the legal (in GHC) type:
2024 <programlisting>
2025   foo :: forall x. x -> [x]
2026 </programlisting>
2027 </para></listitem>
2028
2029 </itemizedlist>
2030 </para>
2031
2032 <para>
2033 GHC currently does kind checking before expanding synonyms (though even that
2034 could be changed.)
2035 </para>
2036 <para>
2037 After expanding type synonyms, GHC does validity checking on types, looking for
2038 the following mal-formedness which isn't detected simply by kind checking:
2039 <itemizedlist>
2040 <listitem><para>
2041 Type constructor applied to a type involving for-alls.
2042 </para></listitem>
2043 <listitem><para>
2044 Unboxed tuple on left of an arrow.
2045 </para></listitem>
2046 <listitem><para>
2047 Partially-applied type synonym.
2048 </para></listitem>
2049 </itemizedlist>
2050 So, for example,
2051 this will be rejected:
2052 <programlisting>
2053   type Pr = (# Int, Int #)
2054
2055   h :: Pr -> Int
2056   h x = ...
2057 </programlisting>
2058 because GHC does not allow  unboxed tuples on the left of a function arrow.
2059 </para>
2060 </sect2>
2061
2062
2063 <sect2 id="existential-quantification">
2064 <title>Existentially quantified data constructors
2065 </title>
2066
2067 <para>
2068 The idea of using existential quantification in data type declarations
2069 was suggested by Perry, and implemented in Hope+ (Nigel Perry, <emphasis>The Implementation
2070 of Practical Functional Programming Languages</emphasis>, PhD Thesis, University of
2071 London, 1991). It was later formalised by Laufer and Odersky
2072 (<emphasis>Polymorphic type inference and abstract data types</emphasis>,
2073 TOPLAS, 16(5), pp1411-1430, 1994).
2074 It's been in Lennart
2075 Augustsson's <command>hbc</command> Haskell compiler for several years, and
2076 proved very useful.  Here's the idea.  Consider the declaration:
2077 </para>
2078
2079 <para>
2080
2081 <programlisting>
2082   data Foo = forall a. MkFoo a (a -> Bool)
2083            | Nil
2084 </programlisting>
2085
2086 </para>
2087
2088 <para>
2089 The data type <literal>Foo</literal> has two constructors with types:
2090 </para>
2091
2092 <para>
2093
2094 <programlisting>
2095   MkFoo :: forall a. a -> (a -> Bool) -> Foo
2096   Nil   :: Foo
2097 </programlisting>
2098
2099 </para>
2100
2101 <para>
2102 Notice that the type variable <literal>a</literal> in the type of <function>MkFoo</function>
2103 does not appear in the data type itself, which is plain <literal>Foo</literal>.
2104 For example, the following expression is fine:
2105 </para>
2106
2107 <para>
2108
2109 <programlisting>
2110   [MkFoo 3 even, MkFoo 'c' isUpper] :: [Foo]
2111 </programlisting>
2112
2113 </para>
2114
2115 <para>
2116 Here, <literal>(MkFoo 3 even)</literal> packages an integer with a function
2117 <function>even</function> that maps an integer to <literal>Bool</literal>; and <function>MkFoo 'c'
2118 isUpper</function> packages a character with a compatible function.  These
2119 two things are each of type <literal>Foo</literal> and can be put in a list.
2120 </para>
2121
2122 <para>
2123 What can we do with a value of type <literal>Foo</literal>?.  In particular,
2124 what happens when we pattern-match on <function>MkFoo</function>?
2125 </para>
2126
2127 <para>
2128
2129 <programlisting>
2130   f (MkFoo val fn) = ???
2131 </programlisting>
2132
2133 </para>
2134
2135 <para>
2136 Since all we know about <literal>val</literal> and <function>fn</function> is that they
2137 are compatible, the only (useful) thing we can do with them is to
2138 apply <function>fn</function> to <literal>val</literal> to get a boolean.  For example:
2139 </para>
2140
2141 <para>
2142
2143 <programlisting>
2144   f :: Foo -> Bool
2145   f (MkFoo val fn) = fn val
2146 </programlisting>
2147
2148 </para>
2149
2150 <para>
2151 What this allows us to do is to package heterogeneous values
2152 together with a bunch of functions that manipulate them, and then treat
2153 that collection of packages in a uniform manner.  You can express
2154 quite a bit of object-oriented-like programming this way.
2155 </para>
2156
2157 <sect3 id="existential">
2158 <title>Why existential?
2159 </title>
2160
2161 <para>
2162 What has this to do with <emphasis>existential</emphasis> quantification?
2163 Simply that <function>MkFoo</function> has the (nearly) isomorphic type
2164 </para>
2165
2166 <para>
2167
2168 <programlisting>
2169   MkFoo :: (exists a . (a, a -> Bool)) -> Foo
2170 </programlisting>
2171
2172 </para>
2173
2174 <para>
2175 But Haskell programmers can safely think of the ordinary
2176 <emphasis>universally</emphasis> quantified type given above, thereby avoiding
2177 adding a new existential quantification construct.
2178 </para>
2179
2180 </sect3>
2181
2182 <sect3 id="existential-with-context">
2183 <title>Existentials and type classes</title>
2184
2185 <para>
2186 An easy extension is to allow
2187 arbitrary contexts before the constructor.  For example:
2188 </para>
2189
2190 <para>
2191
2192 <programlisting>
2193 data Baz = forall a. Eq a => Baz1 a a
2194          | forall b. Show b => Baz2 b (b -> b)
2195 </programlisting>
2196
2197 </para>
2198
2199 <para>
2200 The two constructors have the types you'd expect:
2201 </para>
2202
2203 <para>
2204
2205 <programlisting>
2206 Baz1 :: forall a. Eq a => a -> a -> Baz
2207 Baz2 :: forall b. Show b => b -> (b -> b) -> Baz
2208 </programlisting>
2209
2210 </para>
2211
2212 <para>
2213 But when pattern matching on <function>Baz1</function> the matched values can be compared
2214 for equality, and when pattern matching on <function>Baz2</function> the first matched
2215 value can be converted to a string (as well as applying the function to it).
2216 So this program is legal:
2217 </para>
2218
2219 <para>
2220
2221 <programlisting>
2222   f :: Baz -> String
2223   f (Baz1 p q) | p == q    = "Yes"
2224                | otherwise = "No"
2225   f (Baz2 v fn)            = show (fn v)
2226 </programlisting>
2227
2228 </para>
2229
2230 <para>
2231 Operationally, in a dictionary-passing implementation, the
2232 constructors <function>Baz1</function> and <function>Baz2</function> must store the
2233 dictionaries for <literal>Eq</literal> and <literal>Show</literal> respectively, and
2234 extract it on pattern matching.
2235 </para>
2236
2237 </sect3>
2238
2239 <sect3 id="existential-records">
2240 <title>Record Constructors</title>
2241
2242 <para>
2243 GHC allows existentials to be used with records syntax as well.  For example:
2244
2245 <programlisting>
2246 data Counter a = forall self. NewCounter
2247     { _this    :: self
2248     , _inc     :: self -> self
2249     , _display :: self -> IO ()
2250     , tag      :: a
2251     }
2252 </programlisting>
2253 Here <literal>tag</literal> is a public field, with a well-typed selector
2254 function <literal>tag :: Counter a -> a</literal>.  The <literal>self</literal>
2255 type is hidden from the outside; any attempt to apply <literal>_this</literal>,
2256 <literal>_inc</literal> or <literal>_display</literal> as functions will raise a
2257 compile-time error.  In other words, <emphasis>GHC defines a record selector function
2258 only for fields whose type does not mention the existentially-quantified variables</emphasis>.
2259 (This example used an underscore in the fields for which record selectors
2260 will not be defined, but that is only programming style; GHC ignores them.)
2261 </para>
2262
2263 <para>
2264 To make use of these hidden fields, we need to create some helper functions:
2265
2266 <programlisting>
2267 inc :: Counter a -> Counter a
2268 inc (NewCounter x i d t) = NewCounter
2269     { _this = i x, _inc = i, _display = d, tag = t }
2270
2271 display :: Counter a -> IO ()
2272 display NewCounter{ _this = x, _display = d } = d x
2273 </programlisting>
2274
2275 Now we can define counters with different underlying implementations:
2276
2277 <programlisting>
2278 counterA :: Counter String
2279 counterA = NewCounter
2280     { _this = 0, _inc = (1+), _display = print, tag = "A" }
2281
2282 counterB :: Counter String
2283 counterB = NewCounter
2284     { _this = "", _inc = ('#':), _display = putStrLn, tag = "B" }
2285
2286 main = do
2287     display (inc counterA)         -- prints "1"
2288     display (inc (inc counterB))   -- prints "##"
2289 </programlisting>
2290
2291 Record update syntax is supported for existentials (and GADTs):
2292 <programlisting>
2293 setTag :: Counter a -> a -> Counter a
2294 setTag obj t = obj{ tag = t }
2295 </programlisting>
2296 The rule for record update is this: <emphasis>
2297 the types of the updated fields may
2298 mention only the universally-quantified type variables
2299 of the data constructor.  For GADTs, the field may mention only types
2300 that appear as a simple type-variable argument in the constructor's result
2301 type</emphasis>.  For example:
2302 <programlisting>
2303 data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b } -- c is existential
2304 upd1 t x = t { f1=x }   -- OK:   upd1 :: T a b -> a' -> T a' b
2305 upd2 t x = t { f3=x }   -- BAD   (f3's type mentions c, which is
2306                         --        existentially quantified)
2307
2308 data G a b where { G1 { g1::a, g2::c } :: G a [c] }
2309 upd3 g x = g { g1=x }   -- OK:   upd3 :: G a b -> c -> G c b
2310 upd4 g x = g { g2=x }   -- BAD (f2's type mentions c, which is not a simple
2311                         --      type-variable argument in G1's result type)
2312 </programlisting>
2313 </para>
2314
2315 </sect3>
2316
2317
2318 <sect3>
2319 <title>Restrictions</title>
2320
2321 <para>
2322 There are several restrictions on the ways in which existentially-quantified
2323 constructors can be use.
2324 </para>
2325
2326 <para>
2327
2328 <itemizedlist>
2329 <listitem>
2330
2331 <para>
2332  When pattern matching, each pattern match introduces a new,
2333 distinct, type for each existential type variable.  These types cannot
2334 be unified with any other type, nor can they escape from the scope of
2335 the pattern match.  For example, these fragments are incorrect:
2336
2337
2338 <programlisting>
2339 f1 (MkFoo a f) = a
2340 </programlisting>
2341
2342
2343 Here, the type bound by <function>MkFoo</function> "escapes", because <literal>a</literal>
2344 is the result of <function>f1</function>.  One way to see why this is wrong is to
2345 ask what type <function>f1</function> has:
2346
2347
2348 <programlisting>
2349   f1 :: Foo -> a             -- Weird!
2350 </programlisting>
2351
2352
2353 What is this "<literal>a</literal>" in the result type? Clearly we don't mean
2354 this:
2355
2356
2357 <programlisting>
2358   f1 :: forall a. Foo -> a   -- Wrong!
2359 </programlisting>
2360
2361
2362 The original program is just plain wrong.  Here's another sort of error
2363
2364
2365 <programlisting>
2366   f2 (Baz1 a b) (Baz1 p q) = a==q
2367 </programlisting>
2368
2369
2370 It's ok to say <literal>a==b</literal> or <literal>p==q</literal>, but
2371 <literal>a==q</literal> is wrong because it equates the two distinct types arising
2372 from the two <function>Baz1</function> constructors.
2373
2374
2375 </para>
2376 </listitem>
2377 <listitem>
2378
2379 <para>
2380 You can't pattern-match on an existentially quantified
2381 constructor in a <literal>let</literal> or <literal>where</literal> group of
2382 bindings. So this is illegal:
2383
2384
2385 <programlisting>
2386   f3 x = a==b where { Baz1 a b = x }
2387 </programlisting>
2388
2389 Instead, use a <literal>case</literal> expression:
2390
2391 <programlisting>
2392   f3 x = case x of Baz1 a b -> a==b
2393 </programlisting>
2394
2395 In general, you can only pattern-match
2396 on an existentially-quantified constructor in a <literal>case</literal> expression or
2397 in the patterns of a function definition.
2398
2399 The reason for this restriction is really an implementation one.
2400 Type-checking binding groups is already a nightmare without
2401 existentials complicating the picture.  Also an existential pattern
2402 binding at the top level of a module doesn't make sense, because it's
2403 not clear how to prevent the existentially-quantified type "escaping".
2404 So for now, there's a simple-to-state restriction.  We'll see how
2405 annoying it is.
2406
2407 </para>
2408 </listitem>
2409 <listitem>
2410
2411 <para>
2412 You can't use existential quantification for <literal>newtype</literal>
2413 declarations.  So this is illegal:
2414
2415
2416 <programlisting>
2417   newtype T = forall a. Ord a => MkT a
2418 </programlisting>
2419
2420
2421 Reason: a value of type <literal>T</literal> must be represented as a
2422 pair of a dictionary for <literal>Ord t</literal> and a value of type
2423 <literal>t</literal>.  That contradicts the idea that
2424 <literal>newtype</literal> should have no concrete representation.
2425 You can get just the same efficiency and effect by using
2426 <literal>data</literal> instead of <literal>newtype</literal>.  If
2427 there is no overloading involved, then there is more of a case for
2428 allowing an existentially-quantified <literal>newtype</literal>,
2429 because the <literal>data</literal> version does carry an
2430 implementation cost, but single-field existentially quantified
2431 constructors aren't much use.  So the simple restriction (no
2432 existential stuff on <literal>newtype</literal>) stands, unless there
2433 are convincing reasons to change it.
2434
2435
2436 </para>
2437 </listitem>
2438 <listitem>
2439
2440 <para>
2441  You can't use <literal>deriving</literal> to define instances of a
2442 data type with existentially quantified data constructors.
2443
2444 Reason: in most cases it would not make sense. For example:;
2445
2446 <programlisting>
2447 data T = forall a. MkT [a] deriving( Eq )
2448 </programlisting>
2449
2450 To derive <literal>Eq</literal> in the standard way we would need to have equality
2451 between the single component of two <function>MkT</function> constructors:
2452
2453 <programlisting>
2454 instance Eq T where
2455   (MkT a) == (MkT b) = ???
2456 </programlisting>
2457
2458 But <varname>a</varname> and <varname>b</varname> have distinct types, and so can't be compared.
2459 It's just about possible to imagine examples in which the derived instance
2460 would make sense, but it seems altogether simpler simply to prohibit such
2461 declarations.  Define your own instances!
2462 </para>
2463 </listitem>
2464
2465 </itemizedlist>
2466
2467 </para>
2468
2469 </sect3>
2470 </sect2>
2471
2472 <!-- ====================== Generalised algebraic data types =======================  -->
2473
2474 <sect2 id="gadt-style">
2475 <title>Declaring data types with explicit constructor signatures</title>
2476
2477 <para>GHC allows you to declare an algebraic data type by
2478 giving the type signatures of constructors explicitly.  For example:
2479 <programlisting>
2480   data Maybe a where
2481       Nothing :: Maybe a
2482       Just    :: a -> Maybe a
2483 </programlisting>
2484 The form is called a "GADT-style declaration"
2485 because Generalised Algebraic Data Types, described in <xref linkend="gadt"/>,
2486 can only be declared using this form.</para>
2487 <para>Notice that GADT-style syntax generalises existential types (<xref linkend="existential-quantification"/>).
2488 For example, these two declarations are equivalent:
2489 <programlisting>
2490   data Foo = forall a. MkFoo a (a -> Bool)
2491   data Foo' where { MKFoo :: a -> (a->Bool) -> Foo' }
2492 </programlisting>
2493 </para>
2494 <para>Any data type that can be declared in standard Haskell-98 syntax
2495 can also be declared using GADT-style syntax.
2496 The choice is largely stylistic, but GADT-style declarations differ in one important respect:
2497 they treat class constraints on the data constructors differently.
2498 Specifically, if the constructor is given a type-class context, that
2499 context is made available by pattern matching.  For example:
2500 <programlisting>
2501   data Set a where
2502     MkSet :: Eq a => [a] -> Set a
2503
2504   makeSet :: Eq a => [a] -> Set a
2505   makeSet xs = MkSet (nub xs)
2506
2507   insert :: a -> Set a -> Set a
2508   insert a (MkSet as) | a `elem` as = MkSet as
2509                       | otherwise   = MkSet (a:as)
2510 </programlisting>
2511 A use of <literal>MkSet</literal> as a constructor (e.g. in the definition of <literal>makeSet</literal>)
2512 gives rise to a <literal>(Eq a)</literal>
2513 constraint, as you would expect.  The new feature is that pattern-matching on <literal>MkSet</literal>
2514 (as in the definition of <literal>insert</literal>) makes <emphasis>available</emphasis> an <literal>(Eq a)</literal>
2515 context.  In implementation terms, the <literal>MkSet</literal> constructor has a hidden field that stores
2516 the <literal>(Eq a)</literal> dictionary that is passed to <literal>MkSet</literal>; so
2517 when pattern-matching that dictionary becomes available for the right-hand side of the match.
2518 In the example, the equality dictionary is used to satisfy the equality constraint
2519 generated by the call to <literal>elem</literal>, so that the type of
2520 <literal>insert</literal> itself has no <literal>Eq</literal> constraint.
2521 </para>
2522 <para>
2523 For example, one possible application is to reify dictionaries:
2524 <programlisting>
2525    data NumInst a where
2526      MkNumInst :: Num a => NumInst a
2527
2528    intInst :: NumInst Int
2529    intInst = MkNumInst
2530
2531    plus :: NumInst a -> a -> a -> a
2532    plus MkNumInst p q = p + q
2533 </programlisting>
2534 Here, a value of type <literal>NumInst a</literal> is equivalent
2535 to an explicit <literal>(Num a)</literal> dictionary.
2536 </para>
2537 <para>
2538 All this applies to constructors declared using the syntax of <xref linkend="existential-with-context"/>.
2539 For example, the <literal>NumInst</literal> data type above could equivalently be declared
2540 like this:
2541 <programlisting>
2542    data NumInst a
2543       = Num a => MkNumInst (NumInst a)
2544 </programlisting>
2545 Notice that, unlike the situation when declaring an existential, there is
2546 no <literal>forall</literal>, because the <literal>Num</literal> constrains the
2547 data type's universally quantified type variable <literal>a</literal>.
2548 A constructor may have both universal and existential type variables: for example,
2549 the following two declarations are equivalent:
2550 <programlisting>
2551    data T1 a
2552         = forall b. (Num a, Eq b) => MkT1 a b
2553    data T2 a where
2554         MkT2 :: (Num a, Eq b) => a -> b -> T2 a
2555 </programlisting>
2556 </para>
2557 <para>All this behaviour contrasts with Haskell 98's peculiar treatment of
2558 contexts on a data type declaration (Section 4.2.1 of the Haskell 98 Report).
2559 In Haskell 98 the definition
2560 <programlisting>
2561   data Eq a => Set' a = MkSet' [a]
2562 </programlisting>
2563 gives <literal>MkSet'</literal> the same type as <literal>MkSet</literal> above.  But instead of
2564 <emphasis>making available</emphasis> an <literal>(Eq a)</literal> constraint, pattern-matching
2565 on <literal>MkSet'</literal> <emphasis>requires</emphasis> an <literal>(Eq a)</literal> constraint!
2566 GHC faithfully implements this behaviour, odd though it is.  But for GADT-style declarations,
2567 GHC's behaviour is much more useful, as well as much more intuitive.
2568 </para>
2569
2570 <para>
2571 The rest of this section gives further details about GADT-style data
2572 type declarations.
2573
2574 <itemizedlist>
2575 <listitem><para>
2576 The result type of each data constructor must begin with the type constructor being defined.
2577 If the result type of all constructors
2578 has the form <literal>T a1 ... an</literal>, where <literal>a1 ... an</literal>
2579 are distinct type variables, then the data type is <emphasis>ordinary</emphasis>;
2580 otherwise is a <emphasis>generalised</emphasis> data type (<xref linkend="gadt"/>).
2581 </para></listitem>
2582
2583 <listitem><para>
2584 As with other type signatures, you can give a single signature for several data constructors.
2585 In this example we give a single signature for <literal>T1</literal> and <literal>T2</literal>:
2586 <programlisting>
2587   data T a where
2588     T1,T2 :: a -> T a
2589     T3 :: T a
2590 </programlisting>
2591 </para></listitem>
2592
2593 <listitem><para>
2594 The type signature of
2595 each constructor is independent, and is implicitly universally quantified as usual.
2596 In particular, the type variable(s) in the "<literal>data T a where</literal>" header
2597 have no scope, and different constructors may have different universally-quantified type variables:
2598 <programlisting>
2599   data T a where        -- The 'a' has no scope
2600     T1,T2 :: b -> T b   -- Means forall b. b -> T b
2601     T3 :: T a           -- Means forall a. T a
2602 </programlisting>
2603 </para></listitem>
2604
2605 <listitem><para>
2606 A constructor signature may mention type class constraints, which can differ for
2607 different constructors.  For example, this is fine:
2608 <programlisting>
2609   data T a where
2610     T1 :: Eq b => b -> b -> T b
2611     T2 :: (Show c, Ix c) => c -> [c] -> T c
2612 </programlisting>
2613 When patten matching, these constraints are made available to discharge constraints
2614 in the body of the match. For example:
2615 <programlisting>
2616   f :: T a -> String
2617   f (T1 x y) | x==y      = "yes"
2618              | otherwise = "no"
2619   f (T2 a b)             = show a
2620 </programlisting>
2621 Note that <literal>f</literal> is not overloaded; the <literal>Eq</literal> constraint arising
2622 from the use of <literal>==</literal> is discharged by the pattern match on <literal>T1</literal>
2623 and similarly the <literal>Show</literal> constraint arising from the use of <literal>show</literal>.
2624 </para></listitem>
2625
2626 <listitem><para>
2627 Unlike a Haskell-98-style
2628 data type declaration, the type variable(s) in the "<literal>data Set a where</literal>" header
2629 have no scope.  Indeed, one can write a kind signature instead:
2630 <programlisting>
2631   data Set :: * -> * where ...
2632 </programlisting>
2633 or even a mixture of the two:
2634 <programlisting>
2635   data Bar a :: (* -> *) -> * where ...
2636 </programlisting>
2637 The type variables (if given) may be explicitly kinded, so we could also write the header for <literal>Foo</literal>
2638 like this:
2639 <programlisting>
2640   data Bar a (b :: * -> *) where ...
2641 </programlisting>
2642 </para></listitem>
2643
2644
2645 <listitem><para>
2646 You can use strictness annotations, in the obvious places
2647 in the constructor type:
2648 <programlisting>
2649   data Term a where
2650       Lit    :: !Int -> Term Int
2651       If     :: Term Bool -> !(Term a) -> !(Term a) -> Term a
2652       Pair   :: Term a -> Term b -> Term (a,b)
2653 </programlisting>
2654 </para></listitem>
2655
2656 <listitem><para>
2657 You can use a <literal>deriving</literal> clause on a GADT-style data type
2658 declaration.   For example, these two declarations are equivalent
2659 <programlisting>
2660   data Maybe1 a where {
2661       Nothing1 :: Maybe1 a ;
2662       Just1    :: a -> Maybe1 a
2663     } deriving( Eq, Ord )
2664
2665   data Maybe2 a = Nothing2 | Just2 a
2666        deriving( Eq, Ord )
2667 </programlisting>
2668 </para></listitem>
2669
2670 <listitem><para>
2671 The type signature may have quantified type variables that do not appear
2672 in the result type:
2673 <programlisting>
2674   data Foo where
2675      MkFoo :: a -> (a->Bool) -> Foo
2676      Nil   :: Foo
2677 </programlisting>
2678 Here the type variable <literal>a</literal> does not appear in the result type
2679 of either constructor.
2680 Although it is universally quantified in the type of the constructor, such
2681 a type variable is often called "existential".
2682 Indeed, the above declaration declares precisely the same type as
2683 the <literal>data Foo</literal> in <xref linkend="existential-quantification"/>.
2684 </para><para>
2685 The type may contain a class context too, of course:
2686 <programlisting>
2687   data Showable where
2688     MkShowable :: Show a => a -> Showable
2689 </programlisting>
2690 </para></listitem>
2691
2692 <listitem><para>
2693 You can use record syntax on a GADT-style data type declaration:
2694
2695 <programlisting>
2696   data Person where
2697       Adult :: { name :: String, children :: [Person] } -> Person
2698       Child :: Show a => { name :: !String, funny :: a } -> Person
2699 </programlisting>
2700 As usual, for every constructor that has a field <literal>f</literal>, the type of
2701 field <literal>f</literal> must be the same (modulo alpha conversion).
2702 The <literal>Child</literal> constructor above shows that the signature
2703 may have a context, existentially-quantified variables, and strictness annotations,
2704 just as in the non-record case.  (NB: the "type" that follows the double-colon
2705 is not really a type, because of the record syntax and strictness annotations.
2706 A "type" of this form can appear only in a constructor signature.)
2707 </para></listitem>
2708
2709 <listitem><para>
2710 Record updates are allowed with GADT-style declarations,
2711 only fields that have the following property: the type of the field
2712 mentions no existential type variables.
2713 </para></listitem>
2714
2715 <listitem><para>
2716 As in the case of existentials declared using the Haskell-98-like record syntax
2717 (<xref linkend="existential-records"/>),
2718 record-selector functions are generated only for those fields that have well-typed
2719 selectors.
2720 Here is the example of that section, in GADT-style syntax:
2721 <programlisting>
2722 data Counter a where
2723     NewCounter { _this    :: self
2724                , _inc     :: self -> self
2725                , _display :: self -> IO ()
2726                , tag      :: a
2727                }
2728         :: Counter a
2729 </programlisting>
2730 As before, only one selector function is generated here, that for <literal>tag</literal>.
2731 Nevertheless, you can still use all the field names in pattern matching and record construction.
2732 </para></listitem>
2733 </itemizedlist></para>
2734 </sect2>
2735
2736 <sect2 id="gadt">
2737 <title>Generalised Algebraic Data Types (GADTs)</title>
2738
2739 <para>Generalised Algebraic Data Types generalise ordinary algebraic data types
2740 by allowing constructors to have richer return types.  Here is an example:
2741 <programlisting>
2742   data Term a where
2743       Lit    :: Int -> Term Int
2744       Succ   :: Term Int -> Term Int
2745       IsZero :: Term Int -> Term Bool
2746       If     :: Term Bool -> Term a -> Term a -> Term a
2747       Pair   :: Term a -> Term b -> Term (a,b)
2748 </programlisting>
2749 Notice that the return type of the constructors is not always <literal>Term a</literal>, as is the
2750 case with ordinary data types.  This generality allows us to
2751 write a well-typed <literal>eval</literal> function
2752 for these <literal>Terms</literal>:
2753 <programlisting>
2754   eval :: Term a -> a
2755   eval (Lit i)      = i
2756   eval (Succ t)     = 1 + eval t
2757   eval (IsZero t)   = eval t == 0
2758   eval (If b e1 e2) = if eval b then eval e1 else eval e2
2759   eval (Pair e1 e2) = (eval e1, eval e2)
2760 </programlisting>
2761 The key point about GADTs is that <emphasis>pattern matching causes type refinement</emphasis>.
2762 For example, in the right hand side of the equation
2763 <programlisting>
2764   eval :: Term a -> a
2765   eval (Lit i) =  ...
2766 </programlisting>
2767 the type <literal>a</literal> is refined to <literal>Int</literal>.  That's the whole point!
2768 A precise specification of the type rules is beyond what this user manual aspires to,
2769 but the design closely follows that described in
2770 the paper <ulink
2771 url="http://research.microsoft.com/%7Esimonpj/papers/gadt/">Simple
2772 unification-based type inference for GADTs</ulink>,
2773 (ICFP 2006).
2774 The general principle is this: <emphasis>type refinement is only carried out
2775 based on user-supplied type annotations</emphasis>.
2776 So if no type signature is supplied for <literal>eval</literal>, no type refinement happens,
2777 and lots of obscure error messages will
2778 occur.  However, the refinement is quite general.  For example, if we had:
2779 <programlisting>
2780   eval :: Term a -> a -> a
2781   eval (Lit i) j =  i+j
2782 </programlisting>
2783 the pattern match causes the type <literal>a</literal> to be refined to <literal>Int</literal> (because of the type
2784 of the constructor <literal>Lit</literal>), and that refinement also applies to the type of <literal>j</literal>, and
2785 the result type of the <literal>case</literal> expression.  Hence the addition <literal>i+j</literal> is legal.
2786 </para>
2787 <para>
2788 These and many other examples are given in papers by Hongwei Xi, and
2789 Tim Sheard. There is a longer introduction
2790 <ulink url="http://www.haskell.org/haskellwiki/GADT">on the wiki</ulink>,
2791 and Ralf Hinze's
2792 <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
2793 may use different notation to that implemented in GHC.
2794 </para>
2795 <para>
2796 The rest of this section outlines the extensions to GHC that support GADTs.   The extension is enabled with
2797 <option>-XGADTs</option>.  The <option>-XGADTs</option> flag also sets <option>-XRelaxedPolyRec</option>.
2798 <itemizedlist>
2799 <listitem><para>
2800 A GADT can only be declared using GADT-style syntax (<xref linkend="gadt-style"/>);
2801 the old Haskell-98 syntax for data declarations always declares an ordinary data type.
2802 The result type of each constructor must begin with the type constructor being defined,
2803 but for a GADT the arguments to the type constructor can be arbitrary monotypes.
2804 For example, in the <literal>Term</literal> data
2805 type above, the type of each constructor must end with <literal>Term ty</literal>, but
2806 the <literal>ty</literal> need not be a type variable (e.g. the <literal>Lit</literal>
2807 constructor).
2808 </para></listitem>
2809
2810 <listitem><para>
2811 It is permitted to declare an ordinary algebraic data type using GADT-style syntax.
2812 What makes a GADT into a GADT is not the syntax, but rather the presence of data constructors
2813 whose result type is not just <literal>T a b</literal>.
2814 </para></listitem>
2815
2816 <listitem><para>
2817 You cannot use a <literal>deriving</literal> clause for a GADT; only for
2818 an ordinary data type.
2819 </para></listitem>
2820
2821 <listitem><para>
2822 As mentioned in <xref linkend="gadt-style"/>, record syntax is supported.
2823 For example:
2824 <programlisting>
2825   data Term a where
2826       Lit    { val  :: Int }      :: Term Int
2827       Succ   { num  :: Term Int } :: Term Int
2828       Pred   { num  :: Term Int } :: Term Int
2829       IsZero { arg  :: Term Int } :: Term Bool
2830       Pair   { arg1 :: Term a
2831              , arg2 :: Term b
2832              }                    :: Term (a,b)
2833       If     { cnd  :: Term Bool
2834              , tru  :: Term a
2835              , fls  :: Term a
2836              }                    :: Term a
2837 </programlisting>
2838 However, for GADTs there is the following additional constraint:
2839 every constructor that has a field <literal>f</literal> must have
2840 the same result type (modulo alpha conversion)
2841 Hence, in the above example, we cannot merge the <literal>num</literal>
2842 and <literal>arg</literal> fields above into a
2843 single name.  Although their field types are both <literal>Term Int</literal>,
2844 their selector functions actually have different types:
2845
2846 <programlisting>
2847   num :: Term Int -> Term Int
2848   arg :: Term Bool -> Term Int
2849 </programlisting>
2850 </para></listitem>
2851
2852 <listitem><para>
2853 When pattern-matching against data constructors drawn from a GADT,
2854 for example in a <literal>case</literal> expression, the following rules apply:
2855 <itemizedlist>
2856 <listitem><para>The type of the scrutinee must be rigid.</para></listitem>
2857 <listitem><para>The type of the entire <literal>case</literal> expression must be rigid.</para></listitem>
2858 <listitem><para>The type of any free variable mentioned in any of
2859 the <literal>case</literal> alternatives must be rigid.</para></listitem>
2860 </itemizedlist>
2861 A type is "rigid" if it is completely known to the compiler at its binding site.  The easiest
2862 way to ensure that a variable a rigid type is to give it a type signature.
2863 For more precise details see <ulink url="http://research.microsoft.com/%7Esimonpj/papers/gadt">
2864 Simple unification-based type inference for GADTs
2865 </ulink>. The criteria implemented by GHC are given in the Appendix.
2866
2867 </para></listitem>
2868
2869 </itemizedlist>
2870 </para>
2871
2872 </sect2>
2873 </sect1>
2874
2875 <!-- ====================== End of Generalised algebraic data types =======================  -->
2876
2877 <sect1 id="deriving">
2878 <title>Extensions to the "deriving" mechanism</title>
2879
2880 <sect2 id="deriving-inferred">
2881 <title>Inferred context for deriving clauses</title>
2882
2883 <para>
2884 The Haskell Report is vague about exactly when a <literal>deriving</literal> clause is
2885 legal.  For example:
2886 <programlisting>
2887   data T0 f a = MkT0 a         deriving( Eq )
2888   data T1 f a = MkT1 (f a)     deriving( Eq )
2889   data T2 f a = MkT2 (f (f a)) deriving( Eq )
2890 </programlisting>
2891 The natural generated <literal>Eq</literal> code would result in these instance declarations:
2892 <programlisting>
2893   instance Eq a         => Eq (T0 f a) where ...
2894   instance Eq (f a)     => Eq (T1 f a) where ...
2895   instance Eq (f (f a)) => Eq (T2 f a) where ...
2896 </programlisting>
2897 The first of these is obviously fine. The second is still fine, although less obviously.
2898 The third is not Haskell 98, and risks losing termination of instances.
2899 </para>
2900 <para>
2901 GHC takes a conservative position: it accepts the first two, but not the third.  The  rule is this:
2902 each constraint in the inferred instance context must consist only of type variables,
2903 with no repetitions.
2904 </para>
2905 <para>
2906 This rule is applied regardless of flags.  If you want a more exotic context, you can write
2907 it yourself, using the <link linkend="stand-alone-deriving">standalone deriving mechanism</link>.
2908 </para>
2909 </sect2>
2910
2911 <sect2 id="stand-alone-deriving">
2912 <title>Stand-alone deriving declarations</title>
2913
2914 <para>
2915 GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by <literal>-XStandaloneDeriving</literal>:
2916 <programlisting>
2917   data Foo a = Bar a | Baz String
2918
2919   deriving instance Eq a => Eq (Foo a)
2920 </programlisting>
2921 The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword
2922 <literal>deriving</literal>, and (b) the absence of the <literal>where</literal> part.
2923 Note the following points:
2924 <itemizedlist>
2925 <listitem><para>
2926 You must supply an explicit context (in the example the context is <literal>(Eq a)</literal>),
2927 exactly as you would in an ordinary instance declaration.
2928 (In contrast, in a <literal>deriving</literal> clause
2929 attached to a data type declaration, the context is inferred.)
2930 </para></listitem>
2931
2932 <listitem><para>
2933 A <literal>deriving instance</literal> declaration
2934 must obey the same rules concerning form and termination as ordinary instance declarations,
2935 controlled by the same flags; see <xref linkend="instance-decls"/>.
2936 </para></listitem>
2937
2938 <listitem><para>
2939 Unlike a <literal>deriving</literal>
2940 declaration attached to a <literal>data</literal> declaration, the instance can be more specific
2941 than the data type (assuming you also use
2942 <literal>-XFlexibleInstances</literal>, <xref linkend="instance-rules"/>).  Consider
2943 for example
2944 <programlisting>
2945   data Foo a = Bar a | Baz String
2946
2947   deriving instance Eq a => Eq (Foo [a])
2948   deriving instance Eq a => Eq (Foo (Maybe a))
2949 </programlisting>
2950 This will generate a derived instance for <literal>(Foo [a])</literal> and <literal>(Foo (Maybe a))</literal>,
2951 but other types such as <literal>(Foo (Int,Bool))</literal> will not be an instance of <literal>Eq</literal>.
2952 </para></listitem>
2953
2954 <listitem><para>
2955 Unlike a <literal>deriving</literal>
2956 declaration attached to a <literal>data</literal> declaration,
2957 GHC does not restrict the form of the data type.  Instead, GHC simply generates the appropriate
2958 boilerplate code for the specified class, and typechecks it. If there is a type error, it is
2959 your problem. (GHC will show you the offending code if it has a type error.)
2960 The merit of this is that you can derive instances for GADTs and other exotic
2961 data types, providing only that the boilerplate code does indeed typecheck.  For example:
2962 <programlisting>
2963   data T a where
2964      T1 :: T Int
2965      T2 :: T Bool
2966
2967   deriving instance Show (T a)
2968 </programlisting>
2969 In this example, you cannot say <literal>... deriving( Show )</literal> on the
2970 data type declaration for <literal>T</literal>,
2971 because <literal>T</literal> is a GADT, but you <emphasis>can</emphasis> generate
2972 the instance declaration using stand-alone deriving.
2973 </para>
2974 </listitem>
2975
2976 <listitem>
2977 <para>The stand-alone syntax is generalised for newtypes in exactly the same
2978 way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>).
2979 For example:
2980 <programlisting>
2981   newtype Foo a = MkFoo (State Int a)
2982
2983   deriving instance MonadState Int Foo
2984 </programlisting>
2985 GHC always treats the <emphasis>last</emphasis> parameter of the instance
2986 (<literal>Foo</literal> in this example) as the type whose instance is being derived.
2987 </para></listitem>
2988 </itemizedlist></para>
2989
2990 </sect2>
2991
2992
2993 <sect2 id="deriving-typeable">
2994 <title>Deriving clause for extra classes (<literal>Typeable</literal>, <literal>Data</literal>, etc)</title>
2995
2996 <para>
2997 Haskell 98 allows the programmer to add "<literal>deriving( Eq, Ord )</literal>" to a data type
2998 declaration, to generate a standard instance declaration for classes specified in the <literal>deriving</literal> clause.
2999 In Haskell 98, the only classes that may appear in the <literal>deriving</literal> clause are the standard
3000 classes <literal>Eq</literal>, <literal>Ord</literal>,
3001 <literal>Enum</literal>, <literal>Ix</literal>, <literal>Bounded</literal>, <literal>Read</literal>, and <literal>Show</literal>.
3002 </para>
3003 <para>
3004 GHC extends this list with several more classes that may be automatically derived:
3005 <itemizedlist>
3006 <listitem><para> With <option>-XDeriveDataTypeable</option>, you can derive instances of the classes
3007 <literal>Typeable</literal>, and <literal>Data</literal>, defined in the library
3008 modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> respectively.
3009 </para>
3010 <para>An instance of <literal>Typeable</literal> can only be derived if the
3011 data type has seven or fewer type parameters, all of kind <literal>*</literal>.
3012 The reason for this is that the <literal>Typeable</literal> class is derived using the scheme
3013 described in
3014 <ulink url="http://research.microsoft.com/%7Esimonpj/papers/hmap/gmap2.ps">
3015 Scrap More Boilerplate: Reflection, Zips, and Generalised Casts
3016 </ulink>.
3017 (Section 7.4 of the paper describes the multiple <literal>Typeable</literal> classes that
3018 are used, and only <literal>Typeable1</literal> up to
3019 <literal>Typeable7</literal> are provided in the library.)
3020 In other cases, there is nothing to stop the programmer writing a <literal>TypableX</literal>
3021 class, whose kind suits that of the data type constructor, and
3022 then writing the data type instance by hand.
3023 </para>
3024 </listitem>
3025
3026 <listitem><para> With <option>-XDeriveFunctor</option>, you can derive instances of
3027 the class <literal>Functor</literal>,
3028 defined in <literal>GHC.Base</literal>.
3029 </para></listitem>
3030
3031 <listitem><para> With <option>-XDeriveFoldable</option>, you can derive instances of
3032 the class <literal>Foldable</literal>,
3033 defined in <literal>Data.Foldable</literal>.
3034 </para></listitem>
3035
3036 <listitem><para> With <option>-XDeriveTraversable</option>, you can derive instances of
3037 the class <literal>Traversable</literal>,
3038 defined in <literal>Data.Traversable</literal>.
3039 </para></listitem>
3040 </itemizedlist>
3041 In each case the appropriate class must be in scope before it
3042 can be mentioned in the <literal>deriving</literal> clause.
3043 </para>
3044 </sect2>
3045
3046 <sect2 id="newtype-deriving">
3047 <title>Generalised derived instances for newtypes</title>
3048
3049 <para>
3050 When you define an abstract type using <literal>newtype</literal>, you may want
3051 the new type to inherit some instances from its representation. In
3052 Haskell 98, you can inherit instances of <literal>Eq</literal>, <literal>Ord</literal>,
3053 <literal>Enum</literal> and <literal>Bounded</literal> by deriving them, but for any
3054 other classes you have to write an explicit instance declaration. For
3055 example, if you define
3056
3057 <programlisting>
3058   newtype Dollars = Dollars Int
3059 </programlisting>
3060
3061 and you want to use arithmetic on <literal>Dollars</literal>, you have to
3062 explicitly define an instance of <literal>Num</literal>:
3063
3064 <programlisting>
3065   instance Num Dollars where
3066     Dollars a + Dollars b = Dollars (a+b)
3067     ...
3068 </programlisting>
3069 All the instance does is apply and remove the <literal>newtype</literal>
3070 constructor. It is particularly galling that, since the constructor
3071 doesn't appear at run-time, this instance declaration defines a
3072 dictionary which is <emphasis>wholly equivalent</emphasis> to the <literal>Int</literal>
3073 dictionary, only slower!
3074 </para>
3075
3076
3077 <sect3> <title> Generalising the deriving clause </title>
3078 <para>
3079 GHC now permits such instances to be derived instead,
3080 using the flag <option>-XGeneralizedNewtypeDeriving</option>,
3081 so one can write
3082 <programlisting>
3083   newtype Dollars = Dollars Int deriving (Eq,Show,Num)
3084 </programlisting>
3085
3086 and the implementation uses the <emphasis>same</emphasis> <literal>Num</literal> dictionary
3087 for <literal>Dollars</literal> as for <literal>Int</literal>. Notionally, the compiler
3088 derives an instance declaration of the form
3089
3090 <programlisting>
3091   instance Num Int => Num Dollars
3092 </programlisting>
3093
3094 which just adds or removes the <literal>newtype</literal> constructor according to the type.
3095 </para>
3096 <para>
3097
3098 We can also derive instances of constructor classes in a similar
3099 way. For example, suppose we have implemented state and failure monad
3100 transformers, such that
3101
3102 <programlisting>
3103   instance Monad m => Monad (State s m)
3104   instance Monad m => Monad (Failure m)
3105 </programlisting>
3106 In Haskell 98, we can define a parsing monad by
3107 <programlisting>
3108   type Parser tok m a = State [tok] (Failure m) a
3109 </programlisting>
3110
3111 which is automatically a monad thanks to the instance declarations
3112 above. With the extension, we can make the parser type abstract,
3113 without needing to write an instance of class <literal>Monad</literal>, via
3114
3115 <programlisting>
3116   newtype Parser tok m a = Parser (State [tok] (Failure m) a)
3117                          deriving Monad
3118 </programlisting>
3119 In this case the derived instance declaration is of the form
3120 <programlisting>
3121   instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)
3122 </programlisting>
3123
3124 Notice that, since <literal>Monad</literal> is a constructor class, the
3125 instance is a <emphasis>partial application</emphasis> of the new type, not the
3126 entire left hand side. We can imagine that the type declaration is
3127 "eta-converted" to generate the context of the instance
3128 declaration.
3129 </para>
3130 <para>
3131
3132 We can even derive instances of multi-parameter classes, provided the
3133 newtype is the last class parameter. In this case, a ``partial
3134 application'' of the class appears in the <literal>deriving</literal>
3135 clause. For example, given the class
3136
3137 <programlisting>
3138   class StateMonad s m | m -> s where ...
3139   instance Monad m => StateMonad s (State s m) where ...
3140 </programlisting>
3141 then we can derive an instance of <literal>StateMonad</literal> for <literal>Parser</literal>s by
3142 <programlisting>
3143   newtype Parser tok m a = Parser (State [tok] (Failure m) a)
3144                          deriving (Monad, StateMonad [tok])
3145 </programlisting>
3146
3147 The derived instance is obtained by completing the application of the
3148 class to the new type:
3149
3150 <programlisting>
3151   instance StateMonad [tok] (State [tok] (Failure m)) =>
3152            StateMonad [tok] (Parser tok m)
3153 </programlisting>
3154 </para>
3155 <para>
3156
3157 As a result of this extension, all derived instances in newtype
3158  declarations are treated uniformly (and implemented just by reusing
3159 the dictionary for the representation type), <emphasis>except</emphasis>
3160 <literal>Show</literal> and <literal>Read</literal>, which really behave differently for
3161 the newtype and its representation.
3162 </para>
3163 </sect3>
3164
3165 <sect3> <title> A more precise specification </title>
3166 <para>
3167 Derived instance declarations are constructed as follows. Consider the
3168 declaration (after expansion of any type synonyms)
3169
3170 <programlisting>
3171   newtype T v1...vn = T' (t vk+1...vn) deriving (c1...cm)
3172 </programlisting>
3173
3174 where
3175  <itemizedlist>
3176 <listitem><para>
3177   The <literal>ci</literal> are partial applications of
3178   classes of the form <literal>C t1'...tj'</literal>, where the arity of <literal>C</literal>
3179   is exactly <literal>j+1</literal>.  That is, <literal>C</literal> lacks exactly one type argument.
3180 </para></listitem>
3181 <listitem><para>
3182   The <literal>k</literal> is chosen so that <literal>ci (T v1...vk)</literal> is well-kinded.
3183 </para></listitem>
3184 <listitem><para>
3185   The type <literal>t</literal> is an arbitrary type.
3186 </para></listitem>
3187 <listitem><para>
3188   The type variables <literal>vk+1...vn</literal> do not occur in <literal>t</literal>,
3189   nor in the <literal>ci</literal>, and
3190 </para></listitem>
3191 <listitem><para>
3192   None of the <literal>ci</literal> is <literal>Read</literal>, <literal>Show</literal>,
3193                 <literal>Typeable</literal>, or <literal>Data</literal>.  These classes
3194                 should not "look through" the type or its constructor.  You can still
3195                 derive these classes for a newtype, but it happens in the usual way, not
3196                 via this new mechanism.
3197 </para></listitem>
3198 </itemizedlist>
3199 Then, for each <literal>ci</literal>, the derived instance
3200 declaration is:
3201 <programlisting>
3202   instance ci t => ci (T v1...vk)
3203 </programlisting>
3204 As an example which does <emphasis>not</emphasis> work, consider
3205 <programlisting>
3206   newtype NonMonad m s = NonMonad (State s m s) deriving Monad
3207 </programlisting>
3208 Here we cannot derive the instance
3209 <programlisting>
3210   instance Monad (State s m) => Monad (NonMonad m)
3211 </programlisting>
3212
3213 because the type variable <literal>s</literal> occurs in <literal>State s m</literal>,
3214 and so cannot be "eta-converted" away. It is a good thing that this
3215 <literal>deriving</literal> clause is rejected, because <literal>NonMonad m</literal> is
3216 not, in fact, a monad --- for the same reason. Try defining
3217 <literal>>>=</literal> with the correct type: you won't be able to.
3218 </para>
3219 <para>
3220
3221 Notice also that the <emphasis>order</emphasis> of class parameters becomes
3222 important, since we can only derive instances for the last one. If the
3223 <literal>StateMonad</literal> class above were instead defined as
3224
3225 <programlisting>
3226   class StateMonad m s | m -> s where ...
3227 </programlisting>
3228
3229 then we would not have been able to derive an instance for the
3230 <literal>Parser</literal> type above. We hypothesise that multi-parameter
3231 classes usually have one "main" parameter for which deriving new
3232 instances is most interesting.
3233 </para>
3234 <para>Lastly, all of this applies only for classes other than
3235 <literal>Read</literal>, <literal>Show</literal>, <literal>Typeable</literal>,
3236 and <literal>Data</literal>, for which the built-in derivation applies (section
3237 4.3.3. of the Haskell Report).
3238 (For the standard classes <literal>Eq</literal>, <literal>Ord</literal>,
3239 <literal>Ix</literal>, and <literal>Bounded</literal> it is immaterial whether
3240 the standard method is used or the one described here.)
3241 </para>
3242 </sect3>
3243 </sect2>
3244 </sect1>
3245
3246
3247 <!-- TYPE SYSTEM EXTENSIONS -->
3248 <sect1 id="type-class-extensions">
3249 <title>Class and instances declarations</title>
3250
3251 <sect2 id="multi-param-type-classes">
3252 <title>Class declarations</title>
3253
3254 <para>
3255 This section, and the next one, documents GHC's type-class extensions.
3256 There's lots of background in the paper <ulink
3257 url="http://research.microsoft.com/~simonpj/Papers/type-class-design-space/">Type
3258 classes: exploring the design space</ulink> (Simon Peyton Jones, Mark
3259 Jones, Erik Meijer).
3260 </para>
3261 <para>
3262 All the extensions are enabled by the <option>-fglasgow-exts</option> flag.
3263 </para>
3264
3265 <sect3>
3266 <title>Multi-parameter type classes</title>
3267 <para>
3268 Multi-parameter type classes are permitted, with flag <option>-XMultiParamTypeClasses</option>.
3269 For example:
3270
3271
3272 <programlisting>
3273   class Collection c a where
3274     union :: c a -> c a -> c a
3275     ...etc.
3276 </programlisting>
3277
3278 </para>
3279 </sect3>
3280
3281 <sect3 id="superclass-rules">
3282 <title>The superclasses of a class declaration</title>
3283
3284 <para>
3285 In Haskell 98 the context of a class declaration (which introduces superclasses)
3286 must be simple; that is, each predicate must consist of a class applied to
3287 type variables.  The flag <option>-XFlexibleContexts</option>
3288 (<xref linkend="flexible-contexts"/>)
3289 lifts this restriction,
3290 so that the only restriction on the context in a class declaration is
3291 that the class hierarchy must be acyclic.  So these class declarations are OK:
3292
3293
3294 <programlisting>
3295   class Functor (m k) => FiniteMap m k where
3296     ...
3297
3298   class (Monad m, Monad (t m)) => Transform t m where
3299     lift :: m a -> (t m) a
3300 </programlisting>
3301
3302
3303 </para>
3304 <para>
3305 As in Haskell 98, The class hierarchy must be acyclic.  However, the definition
3306 of "acyclic" involves only the superclass relationships.  For example,
3307 this is OK:
3308
3309
3310 <programlisting>
3311   class C a where {
3312     op :: D b => a -> b -> b
3313   }
3314
3315   class C a => D a where { ... }
3316 </programlisting>
3317
3318
3319 Here, <literal>C</literal> is a superclass of <literal>D</literal>, but it's OK for a
3320 class operation <literal>op</literal> of <literal>C</literal> to mention <literal>D</literal>.  (It
3321 would not be OK for <literal>D</literal> to be a superclass of <literal>C</literal>.)
3322 </para>
3323 </sect3>
3324
3325
3326
3327
3328 <sect3 id="class-method-types">
3329 <title>Class method types</title>
3330
3331 <para>
3332 Haskell 98 prohibits class method types to mention constraints on the
3333 class type variable, thus:
3334 <programlisting>
3335   class Seq s a where
3336     fromList :: [a] -> s a
3337     elem     :: Eq a => a -> s a -> Bool
3338 </programlisting>
3339 The type of <literal>elem</literal> is illegal in Haskell 98, because it
3340 contains the constraint <literal>Eq a</literal>, constrains only the
3341 class type variable (in this case <literal>a</literal>).
3342 GHC lifts this restriction (flag <option>-XConstrainedClassMethods</option>).
3343 </para>
3344
3345
3346 </sect3>
3347 </sect2>
3348
3349 <sect2 id="functional-dependencies">
3350 <title>Functional dependencies
3351 </title>
3352
3353 <para> Functional dependencies are implemented as described by Mark Jones
3354 in &ldquo;<ulink url="http://citeseer.ist.psu.edu/jones00type.html">Type Classes with Functional Dependencies</ulink>&rdquo;, Mark P. Jones,
3355 In Proceedings of the 9th European Symposium on Programming,
3356 ESOP 2000, Berlin, Germany, March 2000, Springer-Verlag LNCS 1782,
3357 .
3358 </para>
3359 <para>
3360 Functional dependencies are introduced by a vertical bar in the syntax of a
3361 class declaration;  e.g.
3362 <programlisting>
3363   class (Monad m) => MonadState s m | m -> s where ...
3364
3365   class Foo a b c | a b -> c where ...
3366 </programlisting>
3367 There should be more documentation, but there isn't (yet).  Yell if you need it.
3368 </para>
3369
3370 <sect3><title>Rules for functional dependencies </title>
3371 <para>
3372 In a class declaration, all of the class type variables must be reachable (in the sense
3373 mentioned in <xref linkend="flexible-contexts"/>)
3374 from the free variables of each method type.
3375 For example:
3376
3377 <programlisting>
3378   class Coll s a where
3379     empty  :: s
3380     insert :: s -> a -> s
3381 </programlisting>
3382
3383 is not OK, because the type of <literal>empty</literal> doesn't mention
3384 <literal>a</literal>.  Functional dependencies can make the type variable
3385 reachable:
3386 <programlisting>
3387   class Coll s a | s -> a where
3388     empty  :: s
3389     insert :: s -> a -> s
3390 </programlisting>
3391
3392 Alternatively <literal>Coll</literal> might be rewritten
3393
3394 <programlisting>
3395   class Coll s a where
3396     empty  :: s a
3397     insert :: s a -> a -> s a
3398 </programlisting>
3399
3400
3401 which makes the connection between the type of a collection of
3402 <literal>a</literal>'s (namely <literal>(s a)</literal>) and the element type <literal>a</literal>.
3403 Occasionally this really doesn't work, in which case you can split the
3404 class like this:
3405
3406
3407 <programlisting>
3408   class CollE s where
3409     empty  :: s
3410
3411   class CollE s => Coll s a where
3412     insert :: s -> a -> s
3413 </programlisting>
3414 </para>
3415 </sect3>
3416
3417
3418 <sect3>
3419 <title>Background on functional dependencies</title>
3420
3421 <para>The following description of the motivation and use of functional dependencies is taken
3422 from the Hugs user manual, reproduced here (with minor changes) by kind
3423 permission of Mark Jones.
3424 </para>
3425 <para>
3426 Consider the following class, intended as part of a
3427 library for collection types:
3428 <programlisting>
3429    class Collects e ce where
3430        empty  :: ce
3431        insert :: e -> ce -> ce
3432        member :: e -> ce -> Bool
3433 </programlisting>
3434 The type variable e used here represents the element type, while ce is the type
3435 of the container itself. Within this framework, we might want to define
3436 instances of this class for lists or characteristic functions (both of which
3437 can be used to represent collections of any equality type), bit sets (which can
3438 be used to represent collections of characters), or hash tables (which can be
3439 used to represent any collection whose elements have a hash function). Omitting
3440 standard implementation details, this would lead to the following declarations:
3441 <programlisting>
3442    instance Eq e => Collects e [e] where ...
3443    instance Eq e => Collects e (e -> Bool) where ...
3444    instance Collects Char BitSet where ...
3445    instance (Hashable e, Collects a ce)
3446               => Collects e (Array Int ce) where ...
3447 </programlisting>
3448 All this looks quite promising; we have a class and a range of interesting
3449 implementations. Unfortunately, there are some serious problems with the class
3450 declaration. First, the empty function has an ambiguous type:
3451 <programlisting>
3452    empty :: Collects e ce => ce
3453 </programlisting>
3454 By "ambiguous" we mean that there is a type variable e that appears on the left
3455 of the <literal>=&gt;</literal> symbol, but not on the right. The problem with
3456 this is that, according to the theoretical foundations of Haskell overloading,
3457 we cannot guarantee a well-defined semantics for any term with an ambiguous
3458 type.
3459 </para>
3460 <para>
3461 We can sidestep this specific problem by removing the empty member from the
3462 class declaration. However, although the remaining members, insert and member,
3463 do not have ambiguous types, we still run into problems when we try to use
3464 them. For example, consider the following two functions:
3465 <programlisting>
3466    f x y = insert x . insert y
3467    g     = f True 'a'
3468 </programlisting>
3469 for which GHC infers the following types:
3470 <programlisting>
3471    f :: (Collects a c, Collects b c) => a -> b -> c -> c
3472    g :: (Collects Bool c, Collects Char c) => c -> c
3473 </programlisting>
3474 Notice that the type for f allows the two parameters x and y to be assigned
3475 different types, even though it attempts to insert each of the two values, one
3476 after the other, into the same collection. If we're trying to model collections
3477 that contain only one type of value, then this is clearly an inaccurate
3478 type. Worse still, the definition for g is accepted, without causing a type
3479 error. As a result, the error in this code will not be flagged at the point
3480 where it appears. Instead, it will show up only when we try to use g, which
3481 might even be in a different module.
3482 </para>
3483
3484 <sect4><title>An attempt to use constructor classes</title>
3485
3486 <para>
3487 Faced with the problems described above, some Haskell programmers might be
3488 tempted to use something like the following version of the class declaration:
3489 <programlisting>
3490    class Collects e c where
3491       empty  :: c e
3492       insert :: e -> c e -> c e
3493       member :: e -> c e -> Bool
3494 </programlisting>
3495 The key difference here is that we abstract over the type constructor c that is
3496 used to form the collection type c e, and not over that collection type itself,
3497 represented by ce in the original class declaration. This avoids the immediate
3498 problems that we mentioned above: empty has type <literal>Collects e c => c
3499 e</literal>, which is not ambiguous.
3500 </para>
3501 <para>
3502 The function f from the previous section has a more accurate type:
3503 <programlisting>
3504    f :: (Collects e c) => e -> e -> c e -> c e
3505 </programlisting>
3506 The function g from the previous section is now rejected with a type error as
3507 we would hope because the type of f does not allow the two arguments to have
3508 different types.
3509 This, then, is an example of a multiple parameter class that does actually work
3510 quite well in practice, without ambiguity problems.
3511 There is, however, a catch. This version of the Collects class is nowhere near
3512 as general as the original class seemed to be: only one of the four instances
3513 for <literal>Collects</literal>
3514 given above can be used with this version of Collects because only one of
3515 them---the instance for lists---has a collection type that can be written in
3516 the form c e, for some type constructor c, and element type e.
3517 </para>
3518 </sect4>
3519
3520 <sect4><title>Adding functional dependencies</title>
3521
3522 <para>
3523 To get a more useful version of the Collects class, Hugs provides a mechanism
3524 that allows programmers to specify dependencies between the parameters of a
3525 multiple parameter class (For readers with an interest in theoretical
3526 foundations and previous work: The use of dependency information can be seen
3527 both as a generalization of the proposal for `parametric type classes' that was
3528 put forward by Chen, Hudak, and Odersky, or as a special case of Mark Jones's
3529 later framework for "improvement" of qualified types. The
3530 underlying ideas are also discussed in a more theoretical and abstract setting
3531 in a manuscript [implparam], where they are identified as one point in a
3532 general design space for systems of implicit parameterization.).
3533
3534 To start with an abstract example, consider a declaration such as:
3535 <programlisting>
3536    class C a b where ...
3537 </programlisting>
3538 which tells us simply that C can be thought of as a binary relation on types
3539 (or type constructors, depending on the kinds of a and b). Extra clauses can be
3540 included in the definition of classes to add information about dependencies
3541 between parameters, as in the following examples:
3542 <programlisting>
3543    class D a b | a -> b where ...
3544    class E a b | a -> b, b -> a where ...
3545 </programlisting>
3546 The notation <literal>a -&gt; b</literal> used here between the | and where
3547 symbols --- not to be
3548 confused with a function type --- indicates that the a parameter uniquely
3549 determines the b parameter, and might be read as "a determines b." Thus D is
3550 not just a relation, but actually a (partial) function. Similarly, from the two
3551 dependencies that are included in the definition of E, we can see that E
3552 represents a (partial) one-one mapping between types.
3553 </para>
3554 <para>
3555 More generally, dependencies take the form <literal>x1 ... xn -&gt; y1 ... ym</literal>,
3556 where x1, ..., xn, and y1, ..., yn are type variables with n&gt;0 and
3557 m&gt;=0, meaning that the y parameters are uniquely determined by the x
3558 parameters. Spaces can be used as separators if more than one variable appears
3559 on any single side of a dependency, as in <literal>t -&gt; a b</literal>. Note that a class may be
3560 annotated with multiple dependencies using commas as separators, as in the
3561 definition of E above. Some dependencies that we can write in this notation are
3562 redundant, and will be rejected because they don't serve any useful
3563 purpose, and may instead indicate an error in the program. Examples of
3564 dependencies like this include  <literal>a -&gt; a </literal>,
3565 <literal>a -&gt; a a </literal>,
3566 <literal>a -&gt; </literal>, etc. There can also be
3567 some redundancy if multiple dependencies are given, as in
3568 <literal>a-&gt;b</literal>,
3569  <literal>b-&gt;c </literal>,  <literal>a-&gt;c </literal>, and
3570 in which some subset implies the remaining dependencies. Examples like this are
3571 not treated as errors. Note that dependencies appear only in class
3572 declarations, and not in any other part of the language. In particular, the
3573 syntax for instance declarations, class constraints, and types is completely
3574 unchanged.
3575 </para>
3576 <para>
3577 By including dependencies in a class declaration, we provide a mechanism for
3578 the programmer to specify each multiple parameter class more precisely. The
3579 compiler, on the other hand, is responsible for ensuring that the set of
3580 instances that are in scope at any given point in the program is consistent
3581 with any declared dependencies. For example, the following pair of instance
3582 declarations cannot appear together in the same scope because they violate the
3583 dependency for D, even though either one on its own would be acceptable:
3584 <programlisting>
3585    instance D Bool Int where ...
3586    instance D Bool Char where ...
3587 </programlisting>
3588 Note also that the following declaration is not allowed, even by itself:
3589 <programlisting>
3590    instance D [a] b where ...
3591 </programlisting>
3592 The problem here is that this instance would allow one particular choice of [a]
3593 to be associated with more than one choice for b, which contradicts the
3594 dependency specified in the definition of D. More generally, this means that,
3595 in any instance of the form:
3596 <programlisting>
3597    instance D t s where ...
3598 </programlisting>
3599 for some particular types t and s, the only variables that can appear in s are
3600 the ones that appear in t, and hence, if the type t is known, then s will be
3601 uniquely determined.
3602 </para>
3603 <para>
3604 The benefit of including dependency information is that it allows us to define
3605 more general multiple parameter classes, without ambiguity problems, and with
3606 the benefit of more accurate types. To illustrate this, we return to the
3607 collection class example, and annotate the original definition of <literal>Collects</literal>
3608 with a simple dependency:
3609 <programlisting>
3610    class Collects e ce | ce -> e where
3611       empty  :: ce
3612       insert :: e -> ce -> ce
3613       member :: e -> ce -> Bool
3614 </programlisting>
3615 The dependency <literal>ce -&gt; e</literal> here specifies that the type e of elements is uniquely
3616 determined by the type of the collection ce. Note that both parameters of
3617 Collects are of kind *; there are no constructor classes here. Note too that
3618 all of the instances of Collects that we gave earlier can be used
3619 together with this new definition.
3620 </para>
3621 <para>
3622 What about the ambiguity problems that we encountered with the original
3623 definition? The empty function still has type Collects e ce => ce, but it is no
3624 longer necessary to regard that as an ambiguous type: Although the variable e
3625 does not appear on the right of the => symbol, the dependency for class
3626 Collects tells us that it is uniquely determined by ce, which does appear on
3627 the right of the => symbol. Hence the context in which empty is used can still
3628 give enough information to determine types for both ce and e, without
3629 ambiguity. More generally, we need only regard a type as ambiguous if it
3630 contains a variable on the left of the => that is not uniquely determined
3631 (either directly or indirectly) by the variables on the right.
3632 </para>
3633 <para>
3634 Dependencies also help to produce more accurate types for user defined
3635 functions, and hence to provide earlier detection of errors, and less cluttered
3636 types for programmers to work with. Recall the previous definition for a
3637 function f:
3638 <programlisting>
3639    f x y = insert x y = insert x . insert y
3640 </programlisting>
3641 for which we originally obtained a type:
3642 <programlisting>
3643    f :: (Collects a c, Collects b c) => a -> b -> c -> c
3644 </programlisting>
3645 Given the dependency information that we have for Collects, however, we can
3646 deduce that a and b must be equal because they both appear as the second
3647 parameter in a Collects constraint with the same first parameter c. Hence we
3648 can infer a shorter and more accurate type for f:
3649 <programlisting>
3650    f :: (Collects a c) => a -> a -> c -> c
3651 </programlisting>
3652 In a similar way, the earlier definition of g will now be flagged as a type error.
3653 </para>
3654 <para>
3655 Although we have given only a few examples here, it should be clear that the
3656 addition of dependency information can help to make multiple parameter classes
3657 more useful in practice, avoiding ambiguity problems, and allowing more general
3658 sets of instance declarations.
3659 </para>
3660 </sect4>
3661 </sect3>
3662 </sect2>
3663
3664 <sect2 id="instance-decls">
3665 <title>Instance declarations</title>
3666
3667 <para>An instance declaration has the form
3668 <screen>
3669   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 ...
3670 </screen>
3671 The part before the "<literal>=&gt;</literal>" is the
3672 <emphasis>context</emphasis>, while the part after the
3673 "<literal>=&gt;</literal>" is the <emphasis>head</emphasis> of the instance declaration.
3674 </para>
3675
3676 <sect3 id="flexible-instance-head">
3677 <title>Relaxed rules for the instance head</title>
3678
3679 <para>
3680 In Haskell 98 the head of an instance declaration
3681 must be of the form <literal>C (T a1 ... an)</literal>, where
3682 <literal>C</literal> is the class, <literal>T</literal> is a data type constructor,
3683 and the <literal>a1 ... an</literal> are distinct type variables.
3684 GHC relaxes these rules in two ways.
3685 <itemizedlist>
3686 <listitem>
3687 <para>
3688 The <option>-XFlexibleInstances</option> flag allows the head of the instance
3689 declaration to mention arbitrary nested types.
3690 For example, this becomes a legal instance declaration
3691 <programlisting>
3692   instance C (Maybe Int) where ...
3693 </programlisting>
3694 See also the <link linkend="instance-overlap">rules on overlap</link>.
3695 </para></listitem>
3696 <listitem><para>
3697 With the <option>-XTypeSynonymInstances</option> flag, instance heads may use type
3698 synonyms. As always, using a type synonym is just shorthand for
3699 writing the RHS of the type synonym definition.  For example:
3700
3701
3702 <programlisting>
3703   type Point = (Int,Int)
3704   instance C Point   where ...
3705   instance C [Point] where ...
3706 </programlisting>
3707
3708
3709 is legal.  However, if you added
3710
3711
3712 <programlisting>
3713   instance C (Int,Int) where ...
3714 </programlisting>
3715
3716
3717 as well, then the compiler will complain about the overlapping
3718 (actually, identical) instance declarations.  As always, type synonyms
3719 must be fully applied.  You cannot, for example, write:
3720
3721 <programlisting>
3722   type P a = [[a]]
3723   instance Monad P where ...
3724 </programlisting>
3725
3726 </para></listitem>
3727 </itemizedlist>
3728 </para>
3729 </sect3>
3730
3731 <sect3 id="instance-rules">
3732 <title>Relaxed rules for instance contexts</title>
3733
3734 <para>In Haskell 98, the assertions in the context of the instance declaration
3735 must be of the form <literal>C a</literal> where <literal>a</literal>
3736 is a type variable that occurs in the head.
3737 </para>
3738
3739 <para>
3740 The <option>-XFlexibleContexts</option> flag relaxes this rule, as well
3741 as the corresponding rule for type signatures (see <xref linkend="flexible-contexts"/>).
3742 With this flag the context of the instance declaration can each consist of arbitrary
3743 (well-kinded) assertions <literal>(C t1 ... tn)</literal> subject only to the
3744 following rules:
3745 <orderedlist>
3746 <listitem><para>
3747 The Paterson Conditions: for each assertion in the context
3748 <orderedlist>
3749 <listitem><para>No type variable has more occurrences in the assertion than in the head</para></listitem>
3750 <listitem><para>The assertion has fewer constructors and variables (taken together
3751       and counting repetitions) than the head</para></listitem>
3752 </orderedlist>
3753 </para></listitem>
3754
3755 <listitem><para>The Coverage Condition.  For each functional dependency,
3756 <replaceable>tvs</replaceable><subscript>left</subscript> <literal>-&gt;</literal>
3757 <replaceable>tvs</replaceable><subscript>right</subscript>,  of the class,
3758 every type variable in
3759 S(<replaceable>tvs</replaceable><subscript>right</subscript>) must appear in
3760 S(<replaceable>tvs</replaceable><subscript>left</subscript>), where S is the
3761 substitution mapping each type variable in the class declaration to the
3762 corresponding type in the instance declaration.
3763 </para></listitem>
3764 </orderedlist>
3765 These restrictions ensure that context reduction terminates: each reduction
3766 step makes the problem smaller by at least one
3767 constructor.  Both the Paterson Conditions and the Coverage Condition are lifted
3768 if you give the <option>-XUndecidableInstances</option>
3769 flag (<xref linkend="undecidable-instances"/>).
3770 You can find lots of background material about the reason for these
3771 restrictions in the paper <ulink
3772 url="http://research.microsoft.com/%7Esimonpj/papers/fd%2Dchr/">
3773 Understanding functional dependencies via Constraint Handling Rules</ulink>.
3774 </para>
3775 <para>
3776 For example, these are OK:
3777 <programlisting>
3778   instance C Int [a]          -- Multiple parameters
3779   instance Eq (S [a])         -- Structured type in head
3780
3781       -- Repeated type variable in head
3782   instance C4 a a => C4 [a] [a]
3783   instance Stateful (ST s) (MutVar s)
3784
3785       -- Head can consist of type variables only
3786   instance C a
3787   instance (Eq a, Show b) => C2 a b
3788
3789       -- Non-type variables in context
3790   instance Show (s a) => Show (Sized s a)
3791   instance C2 Int a => C3 Bool [a]
3792   instance C2 Int a => C3 [a] b
3793 </programlisting>
3794 But these are not:
3795 <programlisting>
3796       -- Context assertion no smaller than head
3797   instance C a => C a where ...
3798       -- (C b b) has more more occurrences of b than the head
3799   instance C b b => Foo [b] where ...
3800 </programlisting>
3801 </para>
3802
3803 <para>
3804 The same restrictions apply to instances generated by
3805 <literal>deriving</literal> clauses.  Thus the following is accepted:
3806 <programlisting>
3807   data MinHeap h a = H a (h a)
3808     deriving (Show)
3809 </programlisting>
3810 because the derived instance
3811 <programlisting>
3812   instance (Show a, Show (h a)) => Show (MinHeap h a)
3813 </programlisting>
3814 conforms to the above rules.
3815 </para>
3816
3817 <para>
3818 A useful idiom permitted by the above rules is as follows.
3819 If one allows overlapping instance declarations then it's quite
3820 convenient to have a "default instance" declaration that applies if
3821 something more specific does not:
3822 <programlisting>
3823   instance C a where
3824     op = ... -- Default
3825 </programlisting>
3826 </para>
3827 </sect3>
3828
3829 <sect3 id="undecidable-instances">
3830 <title>Undecidable instances</title>
3831
3832 <para>
3833 Sometimes even the rules of <xref linkend="instance-rules"/> are too onerous.
3834 For example, sometimes you might want to use the following to get the
3835 effect of a "class synonym":
3836 <programlisting>
3837   class (C1 a, C2 a, C3 a) => C a where { }
3838
3839   instance (C1 a, C2 a, C3 a) => C a where { }
3840 </programlisting>
3841 This allows you to write shorter signatures:
3842 <programlisting>
3843   f :: C a => ...
3844 </programlisting>
3845 instead of
3846 <programlisting>
3847   f :: (C1 a, C2 a, C3 a) => ...
3848 </programlisting>
3849 The restrictions on functional dependencies (<xref
3850 linkend="functional-dependencies"/>) are particularly troublesome.
3851 It is tempting to introduce type variables in the context that do not appear in
3852 the head, something that is excluded by the normal rules. For example:
3853 <programlisting>
3854   class HasConverter a b | a -> b where
3855      convert :: a -> b
3856
3857   data Foo a = MkFoo a
3858
3859   instance (HasConverter a b,Show b) => Show (Foo a) where
3860      show (MkFoo value) = show (convert value)
3861 </programlisting>
3862 This is dangerous territory, however. Here, for example, is a program that would make the
3863 typechecker loop:
3864 <programlisting>
3865   class D a
3866   class F a b | a->b
3867   instance F [a] [[a]]
3868   instance (D c, F a c) => D [a]   -- 'c' is not mentioned in the head
3869 </programlisting>
3870 Similarly, it can be tempting to lift the coverage condition:
3871 <programlisting>
3872   class Mul a b c | a b -> c where
3873         (.*.) :: a -> b -> c
3874
3875   instance Mul Int Int Int where (.*.) = (*)
3876   instance Mul Int Float Float where x .*. y = fromIntegral x * y
3877   instance Mul a b c => Mul a [b] [c] where x .*. v = map (x.*.) v
3878 </programlisting>
3879 The third instance declaration does not obey the coverage condition;
3880 and indeed the (somewhat strange) definition:
3881 <programlisting>
3882   f = \ b x y -> if b then x .*. [y] else y
3883 </programlisting>
3884 makes instance inference go into a loop, because it requires the constraint
3885 <literal>(Mul a [b] b)</literal>.
3886 </para>
3887 <para>
3888 Nevertheless, GHC allows you to experiment with more liberal rules.  If you use
3889 the experimental flag <option>-XUndecidableInstances</option>
3890 <indexterm><primary>-XUndecidableInstances</primary></indexterm>,
3891 both the Paterson Conditions and the Coverage Condition
3892 (described in <xref linkend="instance-rules"/>) are lifted.  Termination is ensured by having a
3893 fixed-depth recursion stack.  If you exceed the stack depth you get a
3894 sort of backtrace, and the opportunity to increase the stack depth
3895 with <option>-fcontext-stack=</option><emphasis>N</emphasis>.
3896 </para>
3897
3898 </sect3>
3899
3900
3901 <sect3 id="instance-overlap">
3902 <title>Overlapping instances</title>
3903 <para>
3904 In general, <emphasis>GHC requires that that it be unambiguous which instance
3905 declaration
3906 should be used to resolve a type-class constraint</emphasis>. This behaviour
3907 can be modified by two flags: <option>-XOverlappingInstances</option>
3908 <indexterm><primary>-XOverlappingInstances
3909 </primary></indexterm>
3910 and <option>-XIncoherentInstances</option>
3911 <indexterm><primary>-XIncoherentInstances
3912 </primary></indexterm>, as this section discusses.  Both these
3913 flags are dynamic flags, and can be set on a per-module basis, using
3914 an <literal>OPTIONS_GHC</literal> pragma if desired (<xref linkend="source-file-options"/>).</para>
3915 <para>
3916 When GHC tries to resolve, say, the constraint <literal>C Int Bool</literal>,
3917 it tries to match every instance declaration against the
3918 constraint,
3919 by instantiating the head of the instance declaration.  For example, consider
3920 these declarations:
3921 <programlisting>
3922   instance context1 => C Int a     where ...  -- (A)
3923   instance context2 => C a   Bool  where ...  -- (B)
3924   instance context3 => C Int [a]   where ...  -- (C)
3925   instance context4 => C Int [Int] where ...  -- (D)
3926 </programlisting>
3927 The instances (A) and (B) match the constraint <literal>C Int Bool</literal>,
3928 but (C) and (D) do not.  When matching, GHC takes
3929 no account of the context of the instance declaration
3930 (<literal>context1</literal> etc).
3931 GHC's default behaviour is that <emphasis>exactly one instance must match the
3932 constraint it is trying to resolve</emphasis>.
3933 It is fine for there to be a <emphasis>potential</emphasis> of overlap (by
3934 including both declarations (A) and (B), say); an error is only reported if a
3935 particular constraint matches more than one.
3936 </para>
3937
3938 <para>
3939 The <option>-XOverlappingInstances</option> flag instructs GHC to allow
3940 more than one instance to match, provided there is a most specific one.  For
3941 example, the constraint <literal>C Int [Int]</literal> matches instances (A),
3942 (C) and (D), but the last is more specific, and hence is chosen.  If there is no
3943 most-specific match, the program is rejected.
3944 </para>
3945 <para>
3946 However, GHC is conservative about committing to an overlapping instance.  For example:
3947 <programlisting>
3948   f :: [b] -> [b]
3949   f x = ...
3950 </programlisting>
3951 Suppose that from the RHS of <literal>f</literal> we get the constraint
3952 <literal>C Int [b]</literal>.  But
3953 GHC does not commit to instance (C), because in a particular
3954 call of <literal>f</literal>, <literal>b</literal> might be instantiate
3955 to <literal>Int</literal>, in which case instance (D) would be more specific still.
3956 So GHC rejects the program.
3957 (If you add the flag <option>-XIncoherentInstances</option>,
3958 GHC will instead pick (C), without complaining about
3959 the problem of subsequent instantiations.)
3960 </para>
3961 <para>
3962 Notice that we gave a type signature to <literal>f</literal>, so GHC had to
3963 <emphasis>check</emphasis> that <literal>f</literal> has the specified type.
3964 Suppose instead we do not give a type signature, asking GHC to <emphasis>infer</emphasis>
3965 it instead.  In this case, GHC will refrain from
3966 simplifying the constraint <literal>C Int [b]</literal> (for the same reason
3967 as before) but, rather than rejecting the program, it will infer the type
3968 <programlisting>
3969   f :: C Int [b] => [b] -> [b]
3970 </programlisting>
3971 That postpones the question of which instance to pick to the
3972 call site for <literal>f</literal>
3973 by which time more is known about the type <literal>b</literal>.
3974 You can write this type signature yourself if you use the
3975 <link linkend="flexible-contexts"><option>-XFlexibleContexts</option></link>
3976 flag.
3977 </para>
3978 <para>
3979 Exactly the same situation can arise in instance declarations themselves.  Suppose we have
3980 <programlisting>
3981   class Foo a where
3982      f :: a -> a
3983   instance Foo [b] where
3984      f x = ...
3985 </programlisting>
3986 and, as before, the constraint <literal>C Int [b]</literal> arises from <literal>f</literal>'s
3987 right hand side.  GHC will reject the instance, complaining as before that it does not know how to resolve
3988 the constraint <literal>C Int [b]</literal>, because it matches more than one instance
3989 declaration.  The solution is to postpone the choice by adding the constraint to the context
3990 of the instance declaration, thus:
3991 <programlisting>
3992   instance C Int [b] => Foo [b] where
3993      f x = ...
3994 </programlisting>
3995 (You need <link linkend="instance-rules"><option>-XFlexibleInstances</option></link> to do this.)
3996 </para>
3997 <para>
3998 Warning: overlapping instances must be used with care.  They
3999 can give rise to incoherence (ie different instance choices are made
4000 in different parts of the program) even without <option>-XIncoherentInstances</option>. Consider:
4001 <programlisting>
4002 {-# LANGUAGE OverlappingInstances #-}
4003 module Help where
4004
4005     class MyShow a where
4006       myshow :: a -> String
4007
4008     instance MyShow a => MyShow [a] where
4009       myshow xs = concatMap myshow xs
4010
4011     showHelp :: MyShow a => [a] -> String
4012     showHelp xs = myshow xs
4013
4014 {-# LANGUAGE FlexibleInstances, OverlappingInstances #-}
4015 module Main where
4016     import Help
4017
4018     data T = MkT
4019
4020     instance MyShow T where
4021       myshow x = "Used generic instance"
4022
4023     instance MyShow [T] where
4024       myshow xs = "Used more specific instance"
4025
4026     main = do { print (myshow [MkT]); print (showHelp [MkT]) }
4027 </programlisting>
4028 In function <literal>showHelp</literal> GHC sees no overlapping
4029 instances, and so uses the <literal>MyShow [a]</literal> instance
4030 without complaint.  In the call to <literal>myshow</literal> in <literal>main</literal>,
4031 GHC resolves the <literal>MyShow [T]</literal> constraint using the overlapping
4032 instance declaration in module <literal>Main</literal>. As a result,
4033 the program prints
4034 <programlisting>
4035   "Used more specific instance"
4036   "Used generic instance"
4037 </programlisting>
4038 (An alternative possible behaviour, not currently implemented,
4039 would be to reject module <literal>Help</literal>
4040 on the grounds that a later instance declaration might overlap the local one.)
4041 </para>
4042 <para>
4043 The willingness to be overlapped or incoherent is a property of
4044 the <emphasis>instance declaration</emphasis> itself, controlled by the
4045 presence or otherwise of the <option>-XOverlappingInstances</option>
4046 and <option>-XIncoherentInstances</option> flags when that module is
4047 being defined.  Neither flag is required in a module that imports and uses the
4048 instance declaration.  Specifically, during the lookup process:
4049 <itemizedlist>
4050 <listitem><para>
4051 An instance declaration is ignored during the lookup process if (a) a more specific
4052 match is found, and (b) the instance declaration was compiled with
4053 <option>-XOverlappingInstances</option>.  The flag setting for the
4054 more-specific instance does not matter.
4055 </para></listitem>
4056 <listitem><para>
4057 Suppose an instance declaration does not match the constraint being looked up, but
4058 does unify with it, so that it might match when the constraint is further
4059 instantiated.  Usually GHC will regard this as a reason for not committing to
4060 some other constraint.  But if the instance declaration was compiled with
4061 <option>-XIncoherentInstances</option>, GHC will skip the "does-it-unify?"
4062 check for that declaration.
4063 </para></listitem>
4064 </itemizedlist>
4065 These rules make it possible for a library author to design a library that relies on
4066 overlapping instances without the library client having to know.
4067 </para>
4068 <para>
4069 If an instance declaration is compiled without
4070 <option>-XOverlappingInstances</option>,
4071 then that instance can never be overlapped.  This could perhaps be
4072 inconvenient.  Perhaps the rule should instead say that the
4073 <emphasis>overlapping</emphasis> instance declaration should be compiled in
4074 this way, rather than the <emphasis>overlapped</emphasis> one.  Perhaps overlap
4075 at a usage site should be permitted regardless of how the instance declarations
4076 are compiled, if the <option>-XOverlappingInstances</option> flag is
4077 used at the usage site.  (Mind you, the exact usage site can occasionally be
4078 hard to pin down.)  We are interested to receive feedback on these points.
4079 </para>
4080 <para>The <option>-XIncoherentInstances</option> flag implies the
4081 <option>-XOverlappingInstances</option> flag, but not vice versa.
4082 </para>
4083 </sect3>
4084
4085
4086
4087 </sect2>
4088
4089 <sect2 id="overloaded-strings">
4090 <title>Overloaded string literals
4091 </title>
4092
4093 <para>
4094 GHC supports <emphasis>overloaded string literals</emphasis>.  Normally a
4095 string literal has type <literal>String</literal>, but with overloaded string
4096 literals enabled (with <literal>-XOverloadedStrings</literal>)
4097  a string literal has type <literal>(IsString a) => a</literal>.
4098 </para>
4099 <para>
4100 This means that the usual string syntax can be used, e.g., for packed strings
4101 and other variations of string like types.  String literals behave very much
4102 like integer literals, i.e., they can be used in both expressions and patterns.
4103 If used in a pattern the literal with be replaced by an equality test, in the same
4104 way as an integer literal is.
4105 </para>
4106 <para>
4107 The class <literal>IsString</literal> is defined as:
4108 <programlisting>
4109 class IsString a where
4110     fromString :: String -> a
4111 </programlisting>
4112 The only predefined instance is the obvious one to make strings work as usual:
4113 <programlisting>
4114 instance IsString [Char] where
4115     fromString cs = cs
4116 </programlisting>
4117 The class <literal>IsString</literal> is not in scope by default.  If you want to mention
4118 it explicitly (for example, to give an instance declaration for it), you can import it
4119 from module <literal>GHC.Exts</literal>.
4120 </para>
4121 <para>
4122 Haskell's defaulting mechanism is extended to cover string literals, when <option>-XOverloadedStrings</option> is specified.
4123 Specifically:
4124 <itemizedlist>
4125 <listitem><para>
4126 Each type in a default declaration must be an
4127 instance of <literal>Num</literal> <emphasis>or</emphasis> of <literal>IsString</literal>.
4128 </para></listitem>
4129
4130 <listitem><para>
4131 The standard defaulting rule (<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.3.4">Haskell Report, Section 4.3.4</ulink>)
4132 is extended thus: defaulting applies when all the unresolved constraints involve standard classes
4133 <emphasis>or</emphasis> <literal>IsString</literal>; and at least one is a numeric class
4134 <emphasis>or</emphasis> <literal>IsString</literal>.
4135 </para></listitem>
4136 </itemizedlist>
4137 </para>
4138 <para>
4139 A small example:
4140 <programlisting>
4141 module Main where
4142
4143 import GHC.Exts( IsString(..) )
4144
4145 newtype MyString = MyString String deriving (Eq, Show)
4146 instance IsString MyString where
4147     fromString = MyString
4148
4149 greet :: MyString -> MyString
4150 greet "hello" = "world"
4151 greet other = other
4152
4153 main = do
4154     print $ greet "hello"
4155     print $ greet "fool"
4156 </programlisting>
4157 </para>
4158 <para>
4159 Note that deriving <literal>Eq</literal> is necessary for the pattern matching
4160 to work since it gets translated into an equality comparison.
4161 </para>
4162 </sect2>
4163
4164 </sect1>
4165
4166 <sect1 id="type-families">
4167 <title>Type families</title>
4168
4169 <para>
4170   <firstterm>Indexed type families</firstterm> are a new GHC extension to
4171   facilitate type-level
4172   programming. Type families are a generalisation of <firstterm>associated
4173   data types</firstterm>
4174   (&ldquo;<ulink url="http://www.cse.unsw.edu.au/~chak/papers/CKPM05.html">Associated
4175   Types with Class</ulink>&rdquo;, M. Chakravarty, G. Keller, S. Peyton Jones,
4176   and S. Marlow. In Proceedings of &ldquo;The 32nd Annual ACM SIGPLAN-SIGACT
4177      Symposium on Principles of Programming Languages (POPL'05)&rdquo;, pages
4178   1-13, ACM Press, 2005) and <firstterm>associated type synonyms</firstterm>
4179   (&ldquo;<ulink url="http://www.cse.unsw.edu.au/~chak/papers/CKP05.html">Type
4180   Associated Type Synonyms</ulink>&rdquo;. M. Chakravarty, G. Keller, and
4181   S. Peyton Jones.
4182   In Proceedings of &ldquo;The Tenth ACM SIGPLAN International Conference on
4183   Functional Programming&rdquo;, ACM Press, pages 241-253, 2005).  Type families
4184   themselves are described in the paper &ldquo;<ulink
4185   url="http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html">Type
4186   Checking with Open Type Functions</ulink>&rdquo;, T. Schrijvers,
4187   S. Peyton-Jones,
4188   M. Chakravarty, and M. Sulzmann, in Proceedings of &ldquo;ICFP 2008: The
4189   13th ACM SIGPLAN International Conference on Functional
4190   Programming&rdquo;, ACM Press, pages 51-62, 2008. Type families
4191   essentially provide type-indexed data types and named functions on types,
4192   which are useful for generic programming and highly parameterised library
4193   interfaces as well as interfaces with enhanced static information, much like
4194   dependent types. They might also be regarded as an alternative to functional
4195   dependencies, but provide a more functional style of type-level programming
4196   than the relational style of functional dependencies.
4197 </para>
4198 <para>
4199   Indexed type families, or type families for short, are type constructors that
4200   represent sets of types. Set members are denoted by supplying the type family
4201   constructor with type parameters, which are called <firstterm>type
4202   indices</firstterm>. The
4203   difference between vanilla parametrised type constructors and family
4204   constructors is much like between parametrically polymorphic functions and
4205   (ad-hoc polymorphic) methods of type classes. Parametric polymorphic functions
4206   behave the same at all type instances, whereas class methods can change their
4207   behaviour in dependence on the class type parameters. Similarly, vanilla type
4208   constructors imply the same data representation for all type instances, but
4209   family constructors can have varying representation types for varying type
4210   indices.
4211 </para>
4212 <para>
4213   Indexed type families come in two flavours: <firstterm>data
4214     families</firstterm> and <firstterm>type synonym
4215     families</firstterm>. They are the indexed family variants of algebraic
4216   data types and type synonyms, respectively. The instances of data families
4217   can be data types and newtypes.
4218 </para>
4219 <para>
4220   Type families are enabled by the flag <option>-XTypeFamilies</option>.
4221   Additional information on the use of type families in GHC is available on
4222   <ulink url="http://www.haskell.org/haskellwiki/GHC/Indexed_types">the
4223   Haskell wiki page on type families</ulink>.
4224 </para>
4225
4226 <sect2 id="data-families">
4227   <title>Data families</title>
4228
4229   <para>
4230     Data families appear in two flavours: (1) they can be defined on the
4231     toplevel
4232     or (2) they can appear inside type classes (in which case they are known as
4233     associated types). The former is the more general variant, as it lacks the
4234     requirement for the type-indexes to coincide with the class
4235     parameters. However, the latter can lead to more clearly structured code and
4236     compiler warnings if some type instances were - possibly accidentally -
4237     omitted. In the following, we always discuss the general toplevel form first
4238     and then cover the additional constraints placed on associated types.
4239   </para>
4240
4241   <sect3 id="data-family-declarations">
4242     <title>Data family declarations</title>
4243
4244     <para>
4245       Indexed data families are introduced by a signature, such as
4246 <programlisting>
4247 data family GMap k :: * -> *
4248 </programlisting>
4249       The special <literal>family</literal> distinguishes family from standard
4250       data declarations.  The result kind annotation is optional and, as
4251       usual, defaults to <literal>*</literal> if omitted.  An example is
4252 <programlisting>
4253 data family Array e
4254 </programlisting>
4255       Named arguments can also be given explicit kind signatures if needed.
4256       Just as with
4257       [http://www.haskell.org/ghc/docs/latest/html/users_guide/gadt.html GADT
4258       declarations] named arguments are entirely optional, so that we can
4259       declare <literal>Array</literal> alternatively with
4260 <programlisting>
4261 data family Array :: * -> *
4262 </programlisting>
4263     </para>
4264
4265     <sect4 id="assoc-data-family-decl">
4266       <title>Associated data family declarations</title>
4267       <para>
4268         When a data family is declared as part of a type class, we drop
4269         the <literal>family</literal> special.  The <literal>GMap</literal>
4270         declaration takes the following form
4271 <programlisting>
4272 class GMapKey k where
4273   data GMap k :: * -> *
4274   ...
4275 </programlisting>
4276         In contrast to toplevel declarations, named arguments must be used for
4277         all type parameters that are to be used as type-indexes.  Moreover,
4278         the argument names must be class parameters.  Each class parameter may
4279         only be used at most once per associated type, but some may be omitted
4280         and they may be in an order other than in the class head.  Hence, the
4281         following contrived example is admissible:
4282 <programlisting>
4283   class C a b c where
4284   data T c a :: *
4285 </programlisting>
4286       </para>
4287     </sect4>
4288   </sect3>
4289
4290   <sect3 id="data-instance-declarations">
4291     <title>Data instance declarations</title>
4292
4293     <para>
4294       Instance declarations of data and newtype families are very similar to
4295       standard data and newtype declarations.  The only two differences are
4296       that the keyword <literal>data</literal> or <literal>newtype</literal>
4297       is followed by <literal>instance</literal> and that some or all of the
4298       type arguments can be non-variable types, but may not contain forall
4299       types or type synonym families.  However, data families are generally
4300       allowed in type parameters, and type synonyms are allowed as long as
4301       they are fully applied and expand to a type that is itself admissible -
4302       exactly as this is required for occurrences of type synonyms in class
4303       instance parameters.  For example, the <literal>Either</literal>
4304       instance for <literal>GMap</literal> is
4305 <programlisting>
4306 data instance GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
4307 </programlisting>
4308       In this example, the declaration has only one variant.  In general, it
4309       can be any number.
4310     </para>
4311     <para>
4312       Data and newtype instance declarations are only permitted when an
4313       appropriate family declaration is in scope - just as a class instance declaratoin
4314       requires the class declaration to be visible.  Moreover, each instance
4315       declaration has to conform to the kind determined by its family
4316       declaration.  This implies that the number of parameters of an instance
4317       declaration matches the arity determined by the kind of the family.
4318     </para>
4319     <para>
4320       A data family instance declaration can use the full exprssiveness of
4321       ordinary <literal>data</literal> or <literal>newtype</literal> declarations:
4322       <itemizedlist>
4323       <listitem><para> Although, a data family is <emphasis>introduced</emphasis> with
4324       the keyword "<literal>data</literal>", a data family <emphasis>instance</emphasis> can
4325       use either <literal>data</literal> or <literal>newtype</literal>. For example:
4326 <programlisting>
4327 data family T a
4328 data    instance T Int  = T1 Int | T2 Bool
4329 newtype instance T Char = TC Bool
4330 </programlisting>
4331       </para></listitem>
4332       <listitem><para> A <literal>data instance</literal> can use GADT syntax for the data constructors,
4333       and indeed can define a GADT.  For example:
4334 <programlisting>
4335 data family G a b
4336 data instance G [a] b where
4337    G1 :: c -> G [Int] b
4338    G2 :: G [a] Bool
4339 </programlisting>
4340       </para></listitem>
4341       <listitem><para> You can use a <literal>deriving</literal> clause on a
4342       <literal>data instance</literal> or <literal>newtype instance</literal>
4343       declaration.
4344       </para></listitem>
4345       </itemizedlist>
4346     </para>
4347
4348     <para>
4349       Even if type families are defined as toplevel declarations, functions
4350       that perform different computations for different family instances may still
4351       need to be defined as methods of type classes.  In particular, the
4352       following is not possible:
4353 <programlisting>
4354 data family T a
4355 data instance T Int  = A
4356 data instance T Char = B
4357 foo :: T a -> Int
4358 foo A = 1             -- WRONG: These two equations together...
4359 foo B = 2             -- ...will produce a type error.
4360 </programlisting>
4361 Instead, you would have to write <literal>foo</literal> as a class operation, thus:
4362 <programlisting>
4363 class C a where
4364   foo :: T a -> Int
4365 instance Foo Int where
4366   foo A = 1
4367 instance Foo Char where
4368   foo B = 2
4369 </programlisting>
4370       (Given the functionality provided by GADTs (Generalised Algebraic Data
4371       Types), it might seem as if a definition, such as the above, should be
4372       feasible.  However, type families are - in contrast to GADTs - are
4373       <emphasis>open;</emphasis> i.e., new instances can always be added,
4374       possibly in other
4375       modules.  Supporting pattern matching across different data instances
4376       would require a form of extensible case construct.)
4377     </para>
4378
4379     <sect4 id="assoc-data-inst">
4380       <title>Associated data instances</title>
4381       <para>
4382         When an associated data family instance is declared within a type
4383         class instance, we drop the <literal>instance</literal> keyword in the
4384         family instance.  So, the <literal>Either</literal> instance
4385         for <literal>GMap</literal> becomes:
4386 <programlisting>
4387 instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where
4388   data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
4389   ...
4390 </programlisting>
4391         The most important point about associated family instances is that the
4392         type indexes corresponding to class parameters must be identical to
4393         the type given in the instance head; here this is the first argument
4394         of <literal>GMap</literal>, namely <literal>Either a b</literal>,
4395         which coincides with the only class parameter.  Any parameters to the
4396         family constructor that do not correspond to class parameters, need to
4397         be variables in every instance; here this is the
4398         variable <literal>v</literal>.
4399       </para>
4400       <para>
4401         Instances for an associated family can only appear as part of
4402         instances declarations of the class in which the family was declared -
4403         just as with the equations of the methods of a class.  Also in
4404         correspondence to how methods are handled, declarations of associated
4405         types can be omitted in class instances.  If an associated family
4406         instance is omitted, the corresponding instance type is not inhabited;
4407         i.e., only diverging expressions, such
4408         as <literal>undefined</literal>, can assume the type.
4409       </para>
4410     </sect4>
4411
4412     <sect4 id="scoping-class-params">
4413       <title>Scoping of class parameters</title>
4414       <para>
4415         In the case of multi-parameter type classes, the visibility of class
4416         parameters in the right-hand side of associated family instances
4417         depends <emphasis>solely</emphasis> on the parameters of the data
4418         family.  As an example, consider the simple class declaration
4419 <programlisting>
4420 class C a b where
4421   data T a
4422 </programlisting>
4423         Only one of the two class parameters is a parameter to the data
4424         family.  Hence, the following instance declaration is invalid:
4425 <programlisting>
4426 instance C [c] d where
4427   data T [c] = MkT (c, d)    -- WRONG!!  'd' is not in scope
4428 </programlisting>
4429         Here, the right-hand side of the data instance mentions the type
4430         variable <literal>d</literal> that does not occur in its left-hand
4431         side.  We cannot admit such data instances as they would compromise
4432         type safety.
4433       </para>
4434     </sect4>
4435
4436     <sect4 id="family-class-inst">
4437       <title>Type class instances of family instances</title>
4438       <para>
4439         Type class instances of instances of data families can be defined as
4440         usual, and in particular data instance declarations can
4441         have <literal>deriving</literal> clauses.  For example, we can write
4442 <programlisting>
4443 data GMap () v = GMapUnit (Maybe v)
4444                deriving Show
4445 </programlisting>
4446         which implicitly defines an instance of the form
4447 <programlisting>
4448 instance Show v => Show (GMap () v) where ...
4449 </programlisting>
4450       </para>
4451       <para>
4452         Note that class instances are always for
4453         particular <emphasis>instances</emphasis> of a data family and never
4454         for an entire family as a whole.  This is for essentially the same
4455         reasons that we cannot define a toplevel function that performs
4456         pattern matching on the data constructors
4457         of <emphasis>different</emphasis> instances of a single type family.
4458         It would require a form of extensible case construct.
4459       </para>
4460     </sect4>
4461
4462     <sect4 id="data-family-overlap">
4463       <title>Overlap of data instances</title>
4464       <para>
4465         The instance declarations of a data family used in a single program
4466         may not overlap at all, independent of whether they are associated or
4467         not.  In contrast to type class instances, this is not only a matter
4468         of consistency, but one of type safety.
4469       </para>
4470     </sect4>
4471
4472   </sect3>
4473
4474   <sect3 id="data-family-import-export">
4475     <title>Import and export</title>
4476
4477     <para>
4478       The association of data constructors with type families is more dynamic
4479       than that is the case with standard data and newtype declarations.  In
4480       the standard case, the notation <literal>T(..)</literal> in an import or
4481       export list denotes the type constructor and all the data constructors
4482       introduced in its declaration.  However, a family declaration never
4483       introduces any data constructors; instead, data constructors are
4484       introduced by family instances.  As a result, which data constructors
4485       are associated with a type family depends on the currently visible
4486       instance declarations for that family.  Consequently, an import or
4487       export item of the form <literal>T(..)</literal> denotes the family
4488       constructor and all currently visible data constructors - in the case of
4489       an export item, these may be either imported or defined in the current
4490       module.  The treatment of import and export items that explicitly list
4491       data constructors, such as <literal>GMap(GMapEither)</literal>, is
4492       analogous.
4493     </para>
4494
4495     <sect4 id="data-family-impexp-assoc">
4496       <title>Associated families</title>
4497       <para>
4498         As expected, an import or export item of the
4499         form <literal>C(..)</literal> denotes all of the class' methods and
4500         associated types.  However, when associated types are explicitly
4501         listed as subitems of a class, we need some new syntax, as uppercase
4502         identifiers as subitems are usually data constructors, not type
4503         constructors.  To clarify that we denote types here, each associated
4504         type name needs to be prefixed by the keyword <literal>type</literal>.
4505         So for example, when explicitly listing the components of
4506         the <literal>GMapKey</literal> class, we write <literal>GMapKey(type
4507         GMap, empty, lookup, insert)</literal>.
4508       </para>
4509     </sect4>
4510
4511     <sect4 id="data-family-impexp-examples">
4512       <title>Examples</title>
4513       <para>
4514         Assuming our running <literal>GMapKey</literal> class example, let us
4515         look at some export lists and their meaning:
4516         <itemizedlist>
4517           <listitem>
4518             <para><literal>module GMap (GMapKey) where...</literal>: Exports
4519               just the class name.</para>
4520           </listitem>
4521           <listitem>
4522             <para><literal>module GMap (GMapKey(..)) where...</literal>:
4523               Exports the class, the associated type <literal>GMap</literal>
4524               and the member
4525               functions <literal>empty</literal>, <literal>lookup</literal>,
4526               and <literal>insert</literal>.  None of the data constructors is
4527               exported.</para>
4528           </listitem>
4529           <listitem>
4530             <para><literal>module GMap (GMapKey(..), GMap(..))
4531                 where...</literal>: As before, but also exports all the data
4532               constructors <literal>GMapInt</literal>,
4533               <literal>GMapChar</literal>,
4534               <literal>GMapUnit</literal>, <literal>GMapPair</literal>,
4535               and <literal>GMapUnit</literal>.</para>
4536           </listitem>
4537           <listitem>
4538             <para><literal>module GMap (GMapKey(empty, lookup, insert),
4539             GMap(..)) where...</literal>: As before.</para>
4540           </listitem>
4541           <listitem>
4542             <para><literal>module GMap (GMapKey, empty, lookup, insert, GMap(..))
4543                 where...</literal>: As before.</para>
4544           </listitem>
4545         </itemizedlist>
4546       </para>
4547       <para>
4548         Finally, you can write <literal>GMapKey(type GMap)</literal> to denote
4549         both the class <literal>GMapKey</literal> as well as its associated
4550         type <literal>GMap</literal>.  However, you cannot
4551         write <literal>GMapKey(type GMap(..))</literal> &mdash; i.e.,
4552         sub-component specifications cannot be nested.  To
4553         specify <literal>GMap</literal>'s data constructors, you have to list
4554         it separately.
4555       </para>
4556     </sect4>
4557
4558     <sect4 id="data-family-impexp-instances">
4559       <title>Instances</title>
4560       <para>
4561         Family instances are implicitly exported, just like class instances.
4562         However, this applies only to the heads of instances, not to the data
4563         constructors an instance defines.
4564       </para>
4565     </sect4>
4566
4567   </sect3>
4568
4569 </sect2>
4570
4571 <sect2 id="synonym-families">
4572   <title>Synonym families</title>
4573
4574   <para>
4575     Type families appear in two flavours: (1) they can be defined on the
4576     toplevel or (2) they can appear inside type classes (in which case they
4577     are known as associated type synonyms).  The former is the more general
4578     variant, as it lacks the requirement for the type-indexes to coincide with
4579     the class parameters.  However, the latter can lead to more clearly
4580     structured code and compiler warnings if some type instances were -
4581     possibly accidentally - omitted.  In the following, we always discuss the
4582     general toplevel form first and then cover the additional constraints
4583     placed on associated types.
4584   </para>
4585
4586   <sect3 id="type-family-declarations">
4587     <title>Type family declarations</title>
4588
4589     <para>
4590       Indexed type families are introduced by a signature, such as
4591 <programlisting>
4592 type family Elem c :: *
4593 </programlisting>
4594       The special <literal>family</literal> distinguishes family from standard
4595       type declarations.  The result kind annotation is optional and, as
4596       usual, defaults to <literal>*</literal> if omitted.  An example is
4597 <programlisting>
4598 type family Elem c
4599 </programlisting>
4600       Parameters can also be given explicit kind signatures if needed.  We
4601       call the number of parameters in a type family declaration, the family's
4602       arity, and all applications of a type family must be fully saturated
4603       w.r.t. to that arity.  This requirement is unlike ordinary type synonyms
4604       and it implies that the kind of a type family is not sufficient to
4605       determine a family's arity, and hence in general, also insufficient to
4606       determine whether a type family application is well formed.  As an
4607       example, consider the following declaration:
4608 <programlisting>
4609 type family F a b :: * -> *   -- F's arity is 2,
4610                               -- although its overall kind is * -> * -> * -> *
4611 </programlisting>
4612       Given this declaration the following are examples of well-formed and
4613       malformed types:
4614 <programlisting>
4615 F Char [Int]       -- OK!  Kind: * -> *
4616 F Char [Int] Bool  -- OK!  Kind: *
4617 F IO Bool          -- WRONG: kind mismatch in the first argument
4618 F Bool             -- WRONG: unsaturated application
4619 </programlisting>
4620       </para>
4621
4622     <sect4 id="assoc-type-family-decl">
4623       <title>Associated type family declarations</title>
4624       <para>
4625         When a type family is declared as part of a type class, we drop
4626         the <literal>family</literal> special.  The <literal>Elem</literal>
4627         declaration takes the following form
4628 <programlisting>
4629 class Collects ce where
4630   type Elem ce :: *
4631   ...
4632 </programlisting>
4633         The argument names of the type family must be class parameters.  Each
4634         class parameter may only be used at most once per associated type, but
4635         some may be omitted and they may be in an order other than in the
4636         class head.  Hence, the following contrived example is admissible:
4637 <programlisting>
4638 class C a b c where
4639   type T c a :: *
4640 </programlisting>
4641         These rules are exactly as for associated data families.
4642       </para>
4643     </sect4>
4644   </sect3>
4645
4646   <sect3 id="type-instance-declarations">
4647     <title>Type instance declarations</title>
4648     <para>
4649       Instance declarations of type families are very similar to standard type
4650       synonym declarations.  The only two differences are that the
4651       keyword <literal>type</literal> is followed
4652       by <literal>instance</literal> and that some or all of the type
4653       arguments can be non-variable types, but may not contain forall types or
4654       type synonym families. However, data families are generally allowed, and
4655       type synonyms are allowed as long as they are fully applied and expand
4656       to a type that is admissible - these are the exact same requirements as
4657       for data instances.  For example, the <literal>[e]</literal> instance
4658       for <literal>Elem</literal> is
4659 <programlisting>
4660 type instance Elem [e] = e
4661 </programlisting>
4662     </para>
4663     <para>
4664       Type family instance declarations are only legitimate when an
4665       appropriate family declaration is in scope - just like class instances
4666       require the class declaration to be visible.  Moreover, each instance
4667       declaration has to conform to the kind determined by its family
4668       declaration, and the number of type parameters in an instance
4669       declaration must match the number of type parameters in the family
4670       declaration.   Finally, the right-hand side of a type instance must be a
4671       monotype (i.e., it may not include foralls) and after the expansion of
4672       all saturated vanilla type synonyms, no synonyms, except family synonyms
4673       may remain.  Here are some examples of admissible and illegal type
4674       instances:
4675 <programlisting>
4676 type family F a :: *
4677 type instance F [Int]              = Int         -- OK!
4678 type instance F String             = Char        -- OK!
4679 type instance F (F a)              = a           -- WRONG: type parameter mentions a type family
4680 type instance F (forall a. (a, b)) = b           -- WRONG: a forall type appears in a type parameter
4681 type instance F Float              = forall a.a  -- WRONG: right-hand side may not be a forall type
4682
4683 type family G a b :: * -> *
4684 type instance G Int            = (,)     -- WRONG: must be two type parameters
4685 type instance G Int Char Float = Double  -- WRONG: must be two type parameters
4686 </programlisting>
4687     </para>
4688
4689     <sect4 id="assoc-type-instance">
4690       <title>Associated type instance declarations</title>
4691       <para>
4692         When an associated family instance is declared within a type class
4693         instance, we drop the <literal>instance</literal> keyword in the family
4694         instance.  So, the <literal>[e]</literal> instance
4695         for <literal>Elem</literal> becomes:
4696 <programlisting>
4697 instance (Eq (Elem [e])) => Collects ([e]) where
4698   type Elem [e] = e
4699   ...
4700 </programlisting>
4701         The most important point about associated family instances is that the
4702         type indexes corresponding to class parameters must be identical to the
4703         type given in the instance head; here this is <literal>[e]</literal>,
4704         which coincides with the only class parameter.
4705       </para>
4706       <para>
4707         Instances for an associated family can only appear as part of  instances
4708         declarations of the class in which the family was declared - just as
4709         with the equations of the methods of a class.  Also in correspondence to
4710         how methods are handled, declarations of associated types can be omitted
4711         in class instances.  If an associated family instance is omitted, the
4712         corresponding instance type is not inhabited; i.e., only diverging
4713         expressions, such as <literal>undefined</literal>, can assume the type.
4714       </para>
4715     </sect4>
4716
4717     <sect4 id="type-family-overlap">
4718       <title>Overlap of type synonym instances</title>
4719       <para>
4720         The instance declarations of a type family used in a single program
4721         may only overlap if the right-hand sides of the overlapping instances
4722         coincide for the overlapping types.  More formally, two instance
4723         declarations overlap if there is a substitution that makes the
4724         left-hand sides of the instances syntactically the same.  Whenever
4725         that is the case, the right-hand sides of the instances must also be
4726         syntactically equal under the same substitution.  This condition is
4727         independent of whether the type family is associated or not, and it is
4728         not only a matter of consistency, but one of type safety.
4729       </para>
4730       <para>
4731         Here are two example to illustrate the condition under which overlap
4732         is permitted.
4733 <programlisting>
4734 type instance F (a, Int) = [a]
4735 type instance F (Int, b) = [b]   -- overlap permitted
4736
4737 type instance G (a, Int)  = [a]
4738 type instance G (Char, a) = [a]  -- ILLEGAL overlap, as [Char] /= [Int]
4739 </programlisting>
4740       </para>
4741     </sect4>
4742
4743     <sect4 id="type-family-decidability">
4744       <title>Decidability of type synonym instances</title>
4745       <para>
4746         In order to guarantee that type inference in the presence of type
4747         families decidable, we need to place a number of additional
4748         restrictions on the formation of type instance declarations (c.f.,
4749         Definition 5 (Relaxed Conditions) of &ldquo;<ulink
4750         url="http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html">Type
4751           Checking with Open Type Functions</ulink>&rdquo;).  Instance
4752           declarations have the general form
4753 <programlisting>
4754 type instance F t1 .. tn = t
4755 </programlisting>
4756         where we require that for every type family application <literal>(G s1
4757         .. sm)</literal> in <literal>t</literal>,
4758         <orderedlist>
4759           <listitem>
4760             <para><literal>s1 .. sm</literal> do not contain any type family
4761             constructors,</para>
4762           </listitem>
4763           <listitem>
4764             <para>the total number of symbols (data type constructors and type
4765             variables) in <literal>s1 .. sm</literal> is strictly smaller than
4766             in <literal>t1 .. tn</literal>, and</para>
4767           </listitem>
4768           <listitem>
4769             <para>for every type
4770             variable <literal>a</literal>, <literal>a</literal> occurs
4771             in <literal>s1 .. sm</literal> at most as often as in <literal>t1
4772             .. tn</literal>.</para>
4773           </listitem>
4774         </orderedlist>
4775         These restrictions are easily verified and ensure termination of type
4776         inference.  However, they are not sufficient to guarantee completeness
4777         of type inference in the presence of, so called, ''loopy equalities'',
4778         such as <literal>a ~ [F a]</literal>, where a recursive occurrence of
4779         a type variable is underneath a family application and data
4780         constructor application - see the above mentioned paper for details.
4781       </para>
4782       <para>
4783         If the option <option>-XUndecidableInstances</option> is passed to the
4784         compiler, the above restrictions are not enforced and it is on the
4785         programmer to ensure termination of the normalisation of type families
4786         during type inference.
4787       </para>
4788     </sect4>
4789   </sect3>
4790
4791   <sect3 id-="equality-constraints">
4792     <title>Equality constraints</title>
4793     <para>
4794       Type context can include equality constraints of the form <literal>t1 ~
4795       t2</literal>, which denote that the types <literal>t1</literal>
4796       and <literal>t2</literal> need to be the same.  In the presence of type
4797       families, whether two types are equal cannot generally be decided
4798       locally.  Hence, the contexts of function signatures may include
4799       equality constraints, as in the following example:
4800 <programlisting>
4801 sumCollects :: (Collects c1, Collects c2, Elem c1 ~ Elem c2) => c1 -> c2 -> c2
4802 </programlisting>
4803       where we require that the element type of <literal>c1</literal>
4804       and <literal>c2</literal> are the same.  In general, the
4805       types <literal>t1</literal> and <literal>t2</literal> of an equality
4806       constraint may be arbitrary monotypes; i.e., they may not contain any
4807       quantifiers, independent of whether higher-rank types are otherwise
4808       enabled.
4809     </para>
4810     <para>
4811       Equality constraints can also appear in class and instance contexts.
4812       The former enable a simple translation of programs using functional
4813       dependencies into programs using family synonyms instead.  The general
4814       idea is to rewrite a class declaration of the form
4815 <programlisting>
4816 class C a b | a -> b
4817 </programlisting>
4818       to
4819 <programlisting>
4820 class (F a ~ b) => C a b where
4821   type F a
4822 </programlisting>
4823       That is, we represent every functional dependency (FD) <literal>a1 .. an
4824       -> b</literal> by an FD type family <literal>F a1 .. an</literal> and a
4825       superclass context equality <literal>F a1 .. an ~ b</literal>,
4826       essentially giving a name to the functional dependency.  In class
4827       instances, we define the type instances of FD families in accordance
4828       with the class head.  Method signatures are not affected by that
4829       process.
4830     </para>
4831     <para>
4832       NB: Equalities in superclass contexts are not fully implemented in
4833       GHC 6.10.
4834     </para>
4835   </sect3>
4836
4837   <sect3 id-="ty-fams-in-instances">
4838     <title>Type families and instance declarations</title>
4839     <para>Type families require us to extend the rules for
4840       the form of instance heads, which are given
4841       in <xref linkend="flexible-instance-head"/>.
4842       Specifically:
4843 <itemizedlist>
4844  <listitem><para>Data type families may appear in an instance head</para></listitem>
4845  <listitem><para>Type synonym families may not appear (at all) in an instance head</para></listitem>
4846 </itemizedlist>
4847 The reason for the latter restriction is that there is no way to check for. Consider
4848 <programlisting>
4849    type family F a
4850    type instance F Bool = Int
4851
4852    class C a
4853
4854    instance C Int
4855    instance C (F a)
4856 </programlisting>
4857 Now a constraint <literal>(C (F Bool))</literal> would match both instances.
4858 The situation is especially bad because the type instance for <literal>F Bool</literal>
4859 might be in another module, or even in a module that is not yet written.
4860 </para>
4861 </sect3>
4862 </sect2>
4863
4864 </sect1>
4865
4866 <sect1 id="other-type-extensions">
4867 <title>Other type system extensions</title>
4868
4869 <sect2 id="explicit-foralls"><title>Explicit universal quantification (forall)</title>
4870 <para>
4871 Haskell type signatures are implicitly quantified.  When the language option <option>-XExplicitForAll</option>
4872 is used, the keyword <literal>forall</literal>
4873 allows us to say exactly what this means.  For example:
4874 </para>
4875 <para>
4876 <programlisting>
4877         g :: b -> b
4878 </programlisting>
4879 means this:
4880 <programlisting>
4881         g :: forall b. (b -> b)
4882 </programlisting>
4883 The two are treated identically.
4884 </para>
4885 <para>
4886 Of course <literal>forall</literal> becomes a keyword; you can't use <literal>forall</literal> as
4887 a type variable any more!
4888 </para>
4889 </sect2>
4890
4891
4892 <sect2 id="flexible-contexts"><title>The context of a type signature</title>
4893 <para>
4894 The <option>-XFlexibleContexts</option> flag lifts the Haskell 98 restriction
4895 that the type-class constraints in a type signature must have the
4896 form <emphasis>(class type-variable)</emphasis> or
4897 <emphasis>(class (type-variable type-variable ...))</emphasis>.
4898 With <option>-XFlexibleContexts</option>
4899 these type signatures are perfectly OK
4900 <programlisting>
4901   g :: Eq [a] => ...
4902   g :: Ord (T a ()) => ...
4903 </programlisting>
4904 The flag <option>-XFlexibleContexts</option> also lifts the corresponding
4905 restriction on class declarations (<xref linkend="superclass-rules"/>) and instance declarations
4906 (<xref linkend="instance-rules"/>).
4907 </para>
4908
4909 <para>
4910 GHC imposes the following restrictions on the constraints in a type signature.
4911 Consider the type:
4912
4913 <programlisting>
4914   forall tv1..tvn (c1, ...,cn) => type
4915 </programlisting>
4916
4917 (Here, we write the "foralls" explicitly, although the Haskell source
4918 language omits them; in Haskell 98, all the free type variables of an
4919 explicit source-language type signature are universally quantified,
4920 except for the class type variables in a class declaration.  However,
4921 in GHC, you can give the foralls if you want.  See <xref linkend="explicit-foralls"/>).
4922 </para>
4923
4924 <para>
4925
4926 <orderedlist>
4927 <listitem>
4928
4929 <para>
4930  <emphasis>Each universally quantified type variable
4931 <literal>tvi</literal> must be reachable from <literal>type</literal></emphasis>.
4932
4933 A type variable <literal>a</literal> is "reachable" if it appears
4934 in the same constraint as either a type variable free in
4935 <literal>type</literal>, or another reachable type variable.
4936 A value with a type that does not obey
4937 this reachability restriction cannot be used without introducing
4938 ambiguity; that is why the type is rejected.
4939 Here, for example, is an illegal type:
4940
4941
4942 <programlisting>
4943   forall a. Eq a => Int
4944 </programlisting>
4945
4946
4947 When a value with this type was used, the constraint <literal>Eq tv</literal>
4948 would be introduced where <literal>tv</literal> is a fresh type variable, and
4949 (in the dictionary-translation implementation) the value would be
4950 applied to a dictionary for <literal>Eq tv</literal>.  The difficulty is that we
4951 can never know which instance of <literal>Eq</literal> to use because we never
4952 get any more information about <literal>tv</literal>.
4953 </para>
4954 <para>
4955 Note
4956 that the reachability condition is weaker than saying that <literal>a</literal> is
4957 functionally dependent on a type variable free in
4958 <literal>type</literal> (see <xref
4959 linkend="functional-dependencies"/>).  The reason for this is there
4960 might be a "hidden" dependency, in a superclass perhaps.  So
4961 "reachable" is a conservative approximation to "functionally dependent".
4962 For example, consider:
4963 <programlisting>
4964   class C a b | a -> b where ...
4965   class C a b => D a b where ...
4966   f :: forall a b. D a b => a -> a
4967 </programlisting>
4968 This is fine, because in fact <literal>a</literal> does functionally determine <literal>b</literal>
4969 but that is not immediately apparent from <literal>f</literal>'s type.
4970 </para>
4971 </listitem>
4972 <listitem>
4973
4974 <para>
4975  <emphasis>Every constraint <literal>ci</literal> must mention at least one of the
4976 universally quantified type variables <literal>tvi</literal></emphasis>.
4977
4978 For example, this type is OK because <literal>C a b</literal> mentions the
4979 universally quantified type variable <literal>b</literal>:
4980
4981
4982 <programlisting>
4983   forall a. C a b => burble
4984 </programlisting>
4985
4986
4987 The next type is illegal because the constraint <literal>Eq b</literal> does not
4988 mention <literal>a</literal>:
4989
4990
4991 <programlisting>
4992   forall a. Eq b => burble
4993 </programlisting>
4994
4995
4996 The reason for this restriction is milder than the other one.  The
4997 excluded types are never useful or necessary (because the offending
4998 context doesn't need to be witnessed at this point; it can be floated
4999 out).  Furthermore, floating them out increases sharing. Lastly,
5000 excluding them is a conservative choice; it leaves a patch of
5001 territory free in case we need it later.
5002
5003 </para>
5004 </listitem>
5005
5006 </orderedlist>
5007
5008 </para>
5009
5010 </sect2>
5011
5012 <sect2 id="implicit-parameters">
5013 <title>Implicit parameters</title>
5014
5015 <para> Implicit parameters are implemented as described in
5016 "Implicit parameters: dynamic scoping with static types",
5017 J Lewis, MB Shields, E Meijer, J Launchbury,
5018 27th ACM Symposium on Principles of Programming Languages (POPL'00),
5019 Boston, Jan 2000.
5020 </para>
5021
5022 <para>(Most of the following, still rather incomplete, documentation is
5023 due to Jeff Lewis.)</para>
5024
5025 <para>Implicit parameter support is enabled with the option
5026 <option>-XImplicitParams</option>.</para>
5027
5028 <para>
5029 A variable is called <emphasis>dynamically bound</emphasis> when it is bound by the calling
5030 context of a function and <emphasis>statically bound</emphasis> when bound by the callee's
5031 context. In Haskell, all variables are statically bound. Dynamic
5032 binding of variables is a notion that goes back to Lisp, but was later
5033 discarded in more modern incarnations, such as Scheme. Dynamic binding
5034 can be very confusing in an untyped language, and unfortunately, typed
5035 languages, in particular Hindley-Milner typed languages like Haskell,
5036 only support static scoping of variables.
5037 </para>
5038 <para>
5039 However, by a simple extension to the type class system of Haskell, we
5040 can support dynamic binding. Basically, we express the use of a
5041 dynamically bound variable as a constraint on the type. These
5042 constraints lead to types of the form <literal>(?x::t') => t</literal>, which says "this
5043 function uses a dynamically-bound variable <literal>?x</literal>
5044 of type <literal>t'</literal>". For
5045 example, the following expresses the type of a sort function,
5046 implicitly parameterized by a comparison function named <literal>cmp</literal>.
5047 <programlisting>
5048   sort :: (?cmp :: a -> a -> Bool) => [a] -> [a]
5049 </programlisting>
5050 The dynamic binding constraints are just a new form of predicate in the type class system.
5051 </para>
5052 <para>
5053 An implicit parameter occurs in an expression using the special form <literal>?x</literal>,
5054 where <literal>x</literal> is
5055 any valid identifier (e.g. <literal>ord ?x</literal> is a valid expression).
5056 Use of this construct also introduces a new
5057 dynamic-binding constraint in the type of the expression.
5058 For example, the following definition
5059 shows how we can define an implicitly parameterized sort function in
5060 terms of an explicitly parameterized <literal>sortBy</literal> function:
5061 <programlisting>
5062   sortBy :: (a -> a -> Bool) -> [a] -> [a]
5063
5064   sort   :: (?cmp :: a -> a -> Bool) => [a] -> [a]
5065   sort    = sortBy ?cmp
5066 </programlisting>
5067 </para>
5068
5069 <sect3>
5070 <title>Implicit-parameter type constraints</title>
5071 <para>
5072 Dynamic binding constraints behave just like other type class
5073 constraints in that they are automatically propagated. Thus, when a
5074 function is used, its implicit parameters are inherited by the
5075 function that called it. For example, our <literal>sort</literal> function might be used
5076 to pick out the least value in a list:
5077 <programlisting>
5078   least   :: (?cmp :: a -> a -> Bool) => [a] -> a
5079   least xs = head (sort xs)
5080 </programlisting>
5081 Without lifting a finger, the <literal>?cmp</literal> parameter is
5082 propagated to become a parameter of <literal>least</literal> as well. With explicit
5083 parameters, the default is that parameters must always be explicit
5084 propagated. With implicit parameters, the default is to always
5085 propagate them.
5086 </para>
5087 <para>
5088 An implicit-parameter type constraint differs from other type class constraints in the
5089 following way: All uses of a particular implicit parameter must have
5090 the same type. This means that the type of <literal>(?x, ?x)</literal>
5091 is <literal>(?x::a) => (a,a)</literal>, and not
5092 <literal>(?x::a, ?x::b) => (a, b)</literal>, as would be the case for type
5093 class constraints.
5094 </para>
5095
5096 <para> You can't have an implicit parameter in the context of a class or instance
5097 declaration.  For example, both these declarations are illegal:
5098 <programlisting>
5099   class (?x::Int) => C a where ...
5100   instance (?x::a) => Foo [a] where ...
5101 </programlisting>
5102 Reason: exactly which implicit parameter you pick up depends on exactly where
5103 you invoke a function. But the ``invocation'' of instance declarations is done
5104 behind the scenes by the compiler, so it's hard to figure out exactly where it is done.
5105 Easiest thing is to outlaw the offending types.</para>
5106 <para>
5107 Implicit-parameter constraints do not cause ambiguity.  For example, consider:
5108 <programlisting>
5109    f :: (?x :: [a]) => Int -> Int
5110    f n = n + length ?x
5111
5112    g :: (Read a, Show a) => String -> String
5113    g s = show (read s)
5114 </programlisting>
5115 Here, <literal>g</literal> has an ambiguous type, and is rejected, but <literal>f</literal>
5116 is fine.  The binding for <literal>?x</literal> at <literal>f</literal>'s call site is
5117 quite unambiguous, and fixes the type <literal>a</literal>.
5118 </para>
5119 </sect3>
5120
5121 <sect3>
5122 <title>Implicit-parameter bindings</title>
5123
5124 <para>
5125 An implicit parameter is <emphasis>bound</emphasis> using the standard
5126 <literal>let</literal> or <literal>where</literal> binding forms.
5127 For example, we define the <literal>min</literal> function by binding
5128 <literal>cmp</literal>.
5129 <programlisting>
5130   min :: [a] -> a
5131   min  = let ?cmp = (&lt;=) in least
5132 </programlisting>
5133 </para>
5134 <para>
5135 A group of implicit-parameter bindings may occur anywhere a normal group of Haskell
5136 bindings can occur, except at top level.  That is, they can occur in a <literal>let</literal>
5137 (including in a list comprehension, or do-notation, or pattern guards),
5138 or a <literal>where</literal> clause.
5139 Note the following points:
5140 <itemizedlist>
5141 <listitem><para>
5142 An implicit-parameter binding group must be a
5143 collection of simple bindings to implicit-style variables (no
5144 function-style bindings, and no type signatures); these bindings are
5145 neither polymorphic or recursive.
5146 </para></listitem>
5147 <listitem><para>
5148 You may not mix implicit-parameter bindings with ordinary bindings in a
5149 single <literal>let</literal>
5150 expression; use two nested <literal>let</literal>s instead.
5151 (In the case of <literal>where</literal> you are stuck, since you can't nest <literal>where</literal> clauses.)
5152 </para></listitem>
5153
5154 <listitem><para>
5155 You may put multiple implicit-parameter bindings in a
5156 single binding group; but they are <emphasis>not</emphasis> treated
5157 as a mutually recursive group (as ordinary <literal>let</literal> bindings are).
5158 Instead they are treated as a non-recursive group, simultaneously binding all the implicit
5159 parameter.  The bindings are not nested, and may be re-ordered without changing
5160 the meaning of the program.
5161 For example, consider:
5162 <programlisting>
5163   f t = let { ?x = t; ?y = ?x+(1::Int) } in ?x + ?y
5164 </programlisting>
5165 The use of <literal>?x</literal> in the binding for <literal>?y</literal> does not "see"
5166 the binding for <literal>?x</literal>, so the type of <literal>f</literal> is
5167 <programlisting>
5168   f :: (?x::Int) => Int -> Int
5169 </programlisting>
5170 </para></listitem>
5171 </itemizedlist>
5172 </para>
5173
5174 </sect3>
5175
5176 <sect3><title>Implicit parameters and polymorphic recursion</title>
5177
5178 <para>
5179 Consider these two definitions:
5180 <programlisting>
5181   len1 :: [a] -> Int
5182   len1 xs = let ?acc = 0 in len_acc1 xs
5183
5184   len_acc1 [] = ?acc
5185   len_acc1 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc1 xs
5186
5187   ------------
5188
5189   len2 :: [a] -> Int
5190   len2 xs = let ?acc = 0 in len_acc2 xs
5191
5192   len_acc2 :: (?acc :: Int) => [a] -> Int
5193   len_acc2 [] = ?acc
5194   len_acc2 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc2 xs
5195 </programlisting>
5196 The only difference between the two groups is that in the second group
5197 <literal>len_acc</literal> is given a type signature.
5198 In the former case, <literal>len_acc1</literal> is monomorphic in its own
5199 right-hand side, so the implicit parameter <literal>?acc</literal> is not
5200 passed to the recursive call.  In the latter case, because <literal>len_acc2</literal>
5201 has a type signature, the recursive call is made to the
5202 <emphasis>polymorphic</emphasis> version, which takes <literal>?acc</literal>
5203 as an implicit parameter.  So we get the following results in GHCi:
5204 <programlisting>
5205   Prog> len1 "hello"
5206   0
5207   Prog> len2 "hello"
5208   5
5209 </programlisting>
5210 Adding a type signature dramatically changes the result!  This is a rather
5211 counter-intuitive phenomenon, worth watching out for.
5212 </para>
5213 </sect3>
5214
5215 <sect3><title>Implicit parameters and monomorphism</title>
5216
5217 <para>GHC applies the dreaded Monomorphism Restriction (section 4.5.5 of the
5218 Haskell Report) to implicit parameters.  For example, consider:
5219 <programlisting>
5220  f :: Int -> Int
5221   f v = let ?x = 0     in
5222         let y = ?x + v in
5223         let ?x = 5     in
5224         y
5225 </programlisting>
5226 Since the binding for <literal>y</literal> falls under the Monomorphism
5227 Restriction it is not generalised, so the type of <literal>y</literal> is
5228 simply <literal>Int</literal>, not <literal>(?x::Int) => Int</literal>.
5229 Hence, <literal>(f 9)</literal> returns result <literal>9</literal>.
5230 If you add a type signature for <literal>y</literal>, then <literal>y</literal>
5231 will get type <literal>(?x::Int) => Int</literal>, so the occurrence of
5232 <literal>y</literal> in the body of the <literal>let</literal> will see the
5233 inner binding of <literal>?x</literal>, so <literal>(f 9)</literal> will return
5234 <literal>14</literal>.
5235 </para>
5236 </sect3>
5237 </sect2>
5238
5239     <!--   ======================= COMMENTED OUT ========================
5240
5241     We intend to remove linear implicit parameters, so I'm at least removing
5242     them from the 6.6 user manual
5243
5244 <sect2 id="linear-implicit-parameters">
5245 <title>Linear implicit parameters</title>
5246 <para>
5247 Linear implicit parameters are an idea developed by Koen Claessen,
5248 Mark Shields, and Simon PJ.  They address the long-standing
5249 problem that monads seem over-kill for certain sorts of problem, notably:
5250 </para>
5251 <itemizedlist>
5252 <listitem> <para> distributing a supply of unique names </para> </listitem>
5253 <listitem> <para> distributing a supply of random numbers </para> </listitem>
5254 <listitem> <para> distributing an oracle (as in QuickCheck) </para> </listitem>
5255 </itemizedlist>
5256
5257 <para>
5258 Linear implicit parameters are just like ordinary implicit parameters,
5259 except that they are "linear"; that is, they cannot be copied, and
5260 must be explicitly "split" instead.  Linear implicit parameters are
5261 written '<literal>%x</literal>' instead of '<literal>?x</literal>'.
5262 (The '/' in the '%' suggests the split!)
5263 </para>
5264 <para>
5265 For example:
5266 <programlisting>
5267     import GHC.Exts( Splittable )
5268
5269     data NameSupply = ...
5270
5271     splitNS :: NameSupply -> (NameSupply, NameSupply)
5272     newName :: NameSupply -> Name
5273
5274     instance Splittable NameSupply where
5275         split = splitNS
5276
5277
5278     f :: (%ns :: NameSupply) => Env -> Expr -> Expr
5279     f env (Lam x e) = Lam x' (f env e)
5280                     where
5281                       x'   = newName %ns
5282                       env' = extend env x x'
5283     ...more equations for f...
5284 </programlisting>
5285 Notice that the implicit parameter %ns is consumed
5286 <itemizedlist>
5287 <listitem> <para> once by the call to <literal>newName</literal> </para> </listitem>
5288 <listitem> <para> once by the recursive call to <literal>f</literal> </para></listitem>
5289 </itemizedlist>
5290 </para>
5291 <para>
5292 So the translation done by the type checker makes
5293 the parameter explicit:
5294 <programlisting>
5295     f :: NameSupply -> Env -> Expr -> Expr
5296     f ns env (Lam x e) = Lam x' (f ns1 env e)
5297                        where
5298                          (ns1,ns2) = splitNS ns
5299                          x' = newName ns2
5300                          env = extend env x x'
5301 </programlisting>
5302 Notice the call to 'split' introduced by the type checker.
5303 How did it know to use 'splitNS'?  Because what it really did
5304 was to introduce a call to the overloaded function 'split',
5305 defined by the class <literal>Splittable</literal>:
5306 <programlisting>
5307         class Splittable a where
5308           split :: a -> (a,a)
5309 </programlisting>
5310 The instance for <literal>Splittable NameSupply</literal> tells GHC how to implement
5311 split for name supplies.  But we can simply write
5312 <programlisting>
5313         g x = (x, %ns, %ns)
5314 </programlisting>
5315 and GHC will infer
5316 <programlisting>
5317         g :: (Splittable a, %ns :: a) => b -> (b,a,a)
5318 </programlisting>
5319 The <literal>Splittable</literal> class is built into GHC.  It's exported by module
5320 <literal>GHC.Exts</literal>.
5321 </para>
5322 <para>
5323 Other points:
5324 <itemizedlist>
5325 <listitem> <para> '<literal>?x</literal>' and '<literal>%x</literal>'
5326 are entirely distinct implicit parameters: you
5327   can use them together and they won't interfere with each other. </para>
5328 </listitem>
5329
5330 <listitem> <para> You can bind linear implicit parameters in 'with' clauses. </para> </listitem>
5331
5332 <listitem> <para>You cannot have implicit parameters (whether linear or not)
5333   in the context of a class or instance declaration. </para></listitem>
5334 </itemizedlist>
5335 </para>
5336
5337 <sect3><title>Warnings</title>
5338
5339 <para>
5340 The monomorphism restriction is even more important than usual.
5341 Consider the example above:
5342 <programlisting>
5343     f :: (%ns :: NameSupply) => Env -> Expr -> Expr
5344     f env (Lam x e) = Lam x' (f env e)
5345                     where
5346                       x'   = newName %ns
5347                       env' = extend env x x'
5348 </programlisting>
5349 If we replaced the two occurrences of x' by (newName %ns), which is
5350 usually a harmless thing to do, we get:
5351 <programlisting>
5352     f :: (%ns :: NameSupply) => Env -> Expr -> Expr
5353     f env (Lam x e) = Lam (newName %ns) (f env e)
5354                     where
5355                       env' = extend env x (newName %ns)
5356 </programlisting>
5357 But now the name supply is consumed in <emphasis>three</emphasis> places
5358 (the two calls to newName,and the recursive call to f), so
5359 the result is utterly different.  Urk!  We don't even have
5360 the beta rule.
5361 </para>
5362 <para>
5363 Well, this is an experimental change.  With implicit
5364 parameters we have already lost beta reduction anyway, and
5365 (as John Launchbury puts it) we can't sensibly reason about
5366 Haskell programs without knowing their typing.
5367 </para>
5368
5369 </sect3>
5370
5371 <sect3><title>Recursive functions</title>
5372 <para>Linear implicit parameters can be particularly tricky when you have a recursive function
5373 Consider
5374 <programlisting>
5375         foo :: %x::T => Int -> [Int]
5376         foo 0 = []
5377         foo n = %x : foo (n-1)
5378 </programlisting>
5379 where T is some type in class Splittable.</para>
5380 <para>
5381 Do you get a list of all the same T's or all different T's
5382 (assuming that split gives two distinct T's back)?
5383 </para><para>
5384 If you supply the type signature, taking advantage of polymorphic
5385 recursion, you get what you'd probably expect.  Here's the
5386 translated term, where the implicit param is made explicit:
5387 <programlisting>
5388         foo x 0 = []
5389         foo x n = let (x1,x2) = split x
5390                   in x1 : foo x2 (n-1)
5391 </programlisting>
5392 But if you don't supply a type signature, GHC uses the Hindley
5393 Milner trick of using a single monomorphic instance of the function
5394 for the recursive calls. That is what makes Hindley Milner type inference
5395 work.  So the translation becomes
5396 <programlisting>
5397         foo x = let
5398                   foom 0 = []
5399                   foom n = x : foom (n-1)
5400                 in
5401                 foom
5402 </programlisting>
5403 Result: 'x' is not split, and you get a list of identical T's.  So the
5404 semantics of the program depends on whether or not foo has a type signature.
5405 Yikes!
5406 </para><para>
5407 You may say that this is a good reason to dislike linear implicit parameters
5408 and you'd be right.  That is why they are an experimental feature.
5409 </para>
5410 </sect3>
5411
5412 </sect2>
5413
5414 ================ END OF Linear Implicit Parameters commented out -->
5415
5416 <sect2 id="kinding">
5417 <title>Explicitly-kinded quantification</title>
5418
5419 <para>
5420 Haskell infers the kind of each type variable.  Sometimes it is nice to be able
5421 to give the kind explicitly as (machine-checked) documentation,
5422 just as it is nice to give a type signature for a function.  On some occasions,
5423 it is essential to do so.  For example, in his paper "Restricted Data Types in Haskell" (Haskell Workshop 1999)
5424 John Hughes had to define the data type:
5425 <screen>
5426      data Set cxt a = Set [a]
5427                     | Unused (cxt a -> ())
5428 </screen>
5429 The only use for the <literal>Unused</literal> constructor was to force the correct
5430 kind for the type variable <literal>cxt</literal>.
5431 </para>
5432 <para>
5433 GHC now instead allows you to specify the kind of a type variable directly, wherever
5434 a type variable is explicitly bound, with the flag <option>-XKindSignatures</option>.
5435 </para>
5436 <para>
5437 This flag enables kind signatures in the following places:
5438 <itemizedlist>
5439 <listitem><para><literal>data</literal> declarations:
5440 <screen>
5441   data Set (cxt :: * -> *) a = Set [a]
5442 </screen></para></listitem>
5443 <listitem><para><literal>type</literal> declarations:
5444 <screen>
5445   type T (f :: * -> *) = f Int
5446 </screen></para></listitem>
5447 <listitem><para><literal>class</literal> declarations:
5448 <screen>
5449   class (Eq a) => C (f :: * -> *) a where ...
5450 </screen></para></listitem>
5451 <listitem><para><literal>forall</literal>'s in type signatures:
5452 <screen>
5453   f :: forall (cxt :: * -> *). Set cxt Int
5454 </screen></para></listitem>
5455 </itemizedlist>
5456 </para>
5457
5458 <para>
5459 The parentheses are required.  Some of the spaces are required too, to
5460 separate the lexemes.  If you write <literal>(f::*->*)</literal> you
5461 will get a parse error, because "<literal>::*->*</literal>" is a
5462 single lexeme in Haskell.
5463 </para>
5464
5465 <para>
5466 As part of the same extension, you can put kind annotations in types
5467 as well.  Thus:
5468 <screen>
5469    f :: (Int :: *) -> Int
5470    g :: forall a. a -> (a :: *)
5471 </screen>
5472 The syntax is
5473 <screen>
5474    atype ::= '(' ctype '::' kind ')
5475 </screen>
5476 The parentheses are required.
5477 </para>
5478 </sect2>
5479
5480
5481 <sect2 id="universal-quantification">
5482 <title>Arbitrary-rank polymorphism
5483 </title>
5484
5485 <para>
5486 GHC's type system supports <emphasis>arbitrary-rank</emphasis>
5487 explicit universal quantification in
5488 types.
5489 For example, all the following types are legal:
5490 <programlisting>
5491     f1 :: forall a b. a -> b -> a
5492     g1 :: forall a b. (Ord a, Eq  b) => a -> b -> a
5493
5494     f2 :: (forall a. a->a) -> Int -> Int
5495     g2 :: (forall a. Eq a => [a] -> a -> Bool) -> Int -> Int
5496
5497     f3 :: ((forall a. a->a) -> Int) -> Bool -> Bool
5498
5499     f4 :: Int -> (forall a. a -> a)
5500 </programlisting>
5501 Here, <literal>f1</literal> and <literal>g1</literal> are rank-1 types, and
5502 can be written in standard Haskell (e.g. <literal>f1 :: a->b->a</literal>).
5503 The <literal>forall</literal> makes explicit the universal quantification that
5504 is implicitly added by Haskell.
5505 </para>
5506 <para>
5507 The functions <literal>f2</literal> and <literal>g2</literal> have rank-2 types;
5508 the <literal>forall</literal> is on the left of a function arrow.  As <literal>g2</literal>
5509 shows, the polymorphic type on the left of the function arrow can be overloaded.
5510 </para>
5511 <para>
5512 The function <literal>f3</literal> has a rank-3 type;
5513 it has rank-2 types on the left of a function arrow.
5514 </para>
5515 <para>
5516 GHC has three flags to control higher-rank types:
5517 <itemizedlist>
5518 <listitem><para>
5519  <option>-XPolymorphicComponents</option>: data constructors (only) can have polymorphic argument types.
5520 </para></listitem>
5521 <listitem><para>
5522  <option>-XRank2Types</option>: any function (including data constructors) can have a rank-2 type.
5523 </para></listitem>
5524 <listitem><para>
5525  <option>-XRankNTypes</option>: any function (including data constructors) can have an arbitrary-rank type.
5526 That is,  you can nest <literal>forall</literal>s
5527 arbitrarily deep in function arrows.
5528 In particular, a forall-type (also called a "type scheme"),
5529 including an operational type class context, is legal:
5530 <itemizedlist>
5531 <listitem> <para> On the left or right (see <literal>f4</literal>, for example)
5532 of a function arrow </para> </listitem>
5533 <listitem> <para> As the argument of a constructor, or type of a field, in a data type declaration. For
5534 example, any of the <literal>f1,f2,f3,g1,g2</literal> above would be valid
5535 field type signatures.</para> </listitem>
5536 <listitem> <para> As the type of an implicit parameter </para> </listitem>
5537 <listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables"/>) </para> </listitem>
5538 </itemizedlist>
5539 </para></listitem>
5540 </itemizedlist>
5541 </para>
5542
5543
5544 <sect3 id="univ">
5545 <title>Examples
5546 </title>
5547
5548 <para>
5549 In a <literal>data</literal> or <literal>newtype</literal> declaration one can quantify
5550 the types of the constructor arguments.  Here are several examples:
5551 </para>
5552
5553 <para>
5554
5555 <programlisting>
5556 data T a = T1 (forall b. b -> b -> b) a
5557
5558 data MonadT m = MkMonad { return :: forall a. a -> m a,
5559                           bind   :: forall a b. m a -> (a -> m b) -> m b
5560                         }
5561
5562 newtype Swizzle = MkSwizzle (Ord a => [a] -> [a])
5563 </programlisting>
5564
5565 </para>
5566
5567 <para>
5568 The constructors have rank-2 types:
5569 </para>
5570
5571 <para>
5572
5573 <programlisting>
5574 T1 :: forall a. (forall b. b -> b -> b) -> a -> T a
5575 MkMonad :: forall m. (forall a. a -> m a)
5576                   -> (forall a b. m a -> (a -> m b) -> m b)
5577                   -> MonadT m
5578 MkSwizzle :: (Ord a => [a] -> [a]) -> Swizzle
5579 </programlisting>
5580
5581 </para>
5582
5583 <para>
5584 Notice that you don't need to use a <literal>forall</literal> if there's an
5585 explicit context.  For example in the first argument of the
5586 constructor <function>MkSwizzle</function>, an implicit "<literal>forall a.</literal>" is
5587 prefixed to the argument type.  The implicit <literal>forall</literal>
5588 quantifies all type variables that are not already in scope, and are
5589 mentioned in the type quantified over.
5590 </para>
5591
5592 <para>
5593 As for type signatures, implicit quantification happens for non-overloaded
5594 types too.  So if you write this:
5595
5596 <programlisting>
5597   data T a = MkT (Either a b) (b -> b)
5598 </programlisting>
5599
5600 it's just as if you had written this:
5601
5602 <programlisting>
5603   data T a = MkT (forall b. Either a b) (forall b. b -> b)
5604 </programlisting>
5605
5606 That is, since the type variable <literal>b</literal> isn't in scope, it's
5607 implicitly universally quantified.  (Arguably, it would be better
5608 to <emphasis>require</emphasis> explicit quantification on constructor arguments
5609 where that is what is wanted.  Feedback welcomed.)
5610 </para>
5611
5612 <para>
5613 You construct values of types <literal>T1, MonadT, Swizzle</literal> by applying
5614 the constructor to suitable values, just as usual.  For example,
5615 </para>
5616
5617 <para>
5618
5619 <programlisting>
5620     a1 :: T Int
5621     a1 = T1 (\xy->x) 3
5622
5623     a2, a3 :: Swizzle
5624     a2 = MkSwizzle sort
5625     a3 = MkSwizzle reverse
5626
5627     a4 :: MonadT Maybe
5628     a4 = let r x = Just x
5629              b m k = case m of
5630                        Just y -> k y
5631                        Nothing -> Nothing
5632          in
5633          MkMonad r b
5634
5635     mkTs :: (forall b. b -> b -> b) -> a -> [T a]
5636     mkTs f x y = [T1 f x, T1 f y]
5637 </programlisting>
5638
5639 </para>
5640
5641 <para>
5642 The type of the argument can, as usual, be more general than the type
5643 required, as <literal>(MkSwizzle reverse)</literal> shows.  (<function>reverse</function>
5644 does not need the <literal>Ord</literal> constraint.)
5645 </para>
5646
5647 <para>
5648 When you use pattern matching, the bound variables may now have
5649 polymorphic types.  For example:
5650 </para>
5651
5652 <para>
5653
5654 <programlisting>
5655     f :: T a -> a -> (a, Char)
5656     f (T1 w k) x = (w k x, w 'c' 'd')
5657
5658     g :: (Ord a, Ord b) => Swizzle -> [a] -> (a -> b) -> [b]
5659     g (MkSwizzle s) xs f = s (map f (s xs))
5660
5661     h :: MonadT m -> [m a] -> m [a]
5662     h m [] = return m []
5663     h m (x:xs) = bind m x          $ \y ->
5664                  bind m (h m xs)   $ \ys ->
5665                  return m (y:ys)
5666 </programlisting>
5667
5668 </para>
5669
5670 <para>
5671 In the function <function>h</function> we use the record selectors <literal>return</literal>
5672 and <literal>bind</literal> to extract the polymorphic bind and return functions
5673 from the <literal>MonadT</literal> data structure, rather than using pattern
5674 matching.
5675 </para>
5676 </sect3>
5677
5678 <sect3>
5679 <title>Type inference</title>
5680
5681 <para>
5682 In general, type inference for arbitrary-rank types is undecidable.
5683 GHC uses an algorithm proposed by Odersky and Laufer ("Putting type annotations to work", POPL'96)
5684 to get a decidable algorithm by requiring some help from the programmer.
5685 We do not yet have a formal specification of "some help" but the rule is this:
5686 </para>
5687 <para>
5688 <emphasis>For a lambda-bound or case-bound variable, x, either the programmer
5689 provides an explicit polymorphic type for x, or GHC's type inference will assume
5690 that x's type has no foralls in it</emphasis>.
5691 </para>
5692 <para>
5693 What does it mean to "provide" an explicit type for x?  You can do that by
5694 giving a type signature for x directly, using a pattern type signature
5695 (<xref linkend="scoped-type-variables"/>), thus:
5696 <programlisting>
5697      \ f :: (forall a. a->a) -> (f True, f 'c')
5698 </programlisting>
5699 Alternatively, you can give a type signature to the enclosing
5700 context, which GHC can "push down" to find the type for the variable:
5701 <programlisting>
5702      (\ f -> (f True, f 'c')) :: (forall a. a->a) -> (Bool,Char)
5703 </programlisting>
5704 Here the type signature on the expression can be pushed inwards
5705 to give a type signature for f.  Similarly, and more commonly,
5706 one can give a type signature for the function itself:
5707 <programlisting>
5708      h :: (forall a. a->a) -> (Bool,Char)
5709      h f = (f True, f 'c')
5710 </programlisting>
5711 You don't need to give a type signature if the lambda bound variable
5712 is a constructor argument.  Here is an example we saw earlier:
5713 <programlisting>
5714     f :: T a -> a -> (a, Char)
5715     f (T1 w k) x = (w k x, w 'c' 'd')
5716 </programlisting>
5717 Here we do not need to give a type signature to <literal>w</literal>, because
5718 it is an argument of constructor <literal>T1</literal> and that tells GHC all
5719 it needs to know.
5720 </para>
5721
5722 </sect3>
5723
5724
5725 <sect3 id="implicit-quant">
5726 <title>Implicit quantification</title>
5727
5728 <para>
5729 GHC performs implicit quantification as follows.  <emphasis>At the top level (only) of
5730 user-written types, if and only if there is no explicit <literal>forall</literal>,
5731 GHC finds all the type variables mentioned in the type that are not already
5732 in scope, and universally quantifies them.</emphasis>  For example, the following pairs are
5733 equivalent:
5734 <programlisting>
5735   f :: a -> a
5736   f :: forall a. a -> a
5737
5738   g (x::a) = let
5739                 h :: a -> b -> b
5740                 h x y = y
5741              in ...
5742   g (x::a) = let
5743                 h :: forall b. a -> b -> b
5744                 h x y = y
5745              in ...
5746 </programlisting>
5747 </para>
5748 <para>
5749 Notice that GHC does <emphasis>not</emphasis> find the innermost possible quantification
5750 point.  For example:
5751 <programlisting>
5752   f :: (a -> a) -> Int
5753            -- MEANS
5754   f :: forall a. (a -> a) -> Int
5755            -- NOT
5756   f :: (forall a. a -> a) -> Int
5757
5758
5759   g :: (Ord a => a -> a) -> Int
5760            -- MEANS the illegal type
5761   g :: forall a. (Ord a => a -> a) -> Int
5762            -- NOT
5763   g :: (forall a. Ord a => a -> a) -> Int
5764 </programlisting>
5765 The latter produces an illegal type, which you might think is silly,
5766 but at least the rule is simple.  If you want the latter type, you
5767 can write your for-alls explicitly.  Indeed, doing so is strongly advised
5768 for rank-2 types.
5769 </para>
5770 </sect3>
5771 </sect2>
5772
5773
5774 <sect2 id="impredicative-polymorphism">
5775 <title>Impredicative polymorphism
5776 </title>
5777 <para><emphasis>NOTE: the impredicative-polymorphism feature is deprecated in GHC 6.12, and
5778 will be removed or replaced in GHC 6.14.</emphasis></para>
5779
5780 <para>GHC supports <emphasis>impredicative polymorphism</emphasis>,
5781 enabled with <option>-XImpredicativeTypes</option>.
5782 This means
5783 that you can call a polymorphic function at a polymorphic type, and
5784 parameterise data structures over polymorphic types.  For example:
5785 <programlisting>
5786   f :: Maybe (forall a. [a] -> [a]) -> Maybe ([Int], [Char])
5787   f (Just g) = Just (g [3], g "hello")
5788   f Nothing  = Nothing
5789 </programlisting>
5790 Notice here that the <literal>Maybe</literal> type is parameterised by the
5791 <emphasis>polymorphic</emphasis> type <literal>(forall a. [a] ->
5792 [a])</literal>.
5793 </para>
5794 <para>The technical details of this extension are described in the paper
5795 <ulink url="http://research.microsoft.com/%7Esimonpj/papers/boxy/">Boxy types:
5796 type inference for higher-rank types and impredicativity</ulink>,
5797 which appeared at ICFP 2006.
5798 </para>
5799 </sect2>
5800
5801 <sect2 id="scoped-type-variables">
5802 <title>Lexically scoped type variables
5803 </title>
5804
5805 <para>
5806 GHC supports <emphasis>lexically scoped type variables</emphasis>, without
5807 which some type signatures are simply impossible to write. For example:
5808 <programlisting>
5809 f :: forall a. [a] -> [a]
5810 f xs = ys ++ ys
5811      where
5812        ys :: [a]
5813        ys = reverse xs
5814 </programlisting>
5815 The type signature for <literal>f</literal> brings the type variable <literal>a</literal> into scope,
5816 because of the explicit <literal>forall</literal> (<xref linkend="decl-type-sigs"/>).
5817 The type variables bound by a <literal>forall</literal> scope over
5818 the entire definition of the accompanying value declaration.
5819 In this example, the type variable <literal>a</literal> scopes over the whole
5820 definition of <literal>f</literal>, including over
5821 the type signature for <varname>ys</varname>.
5822 In Haskell 98 it is not possible to declare
5823 a type for <varname>ys</varname>; a major benefit of scoped type variables is that
5824 it becomes possible to do so.
5825 </para>
5826 <para>Lexically-scoped type variables are enabled by
5827 <option>-XScopedTypeVariables</option>.  This flag implies <option>-XRelaxedPolyRec</option>.
5828 </para>
5829 <para>Note: GHC 6.6 contains substantial changes to the way that scoped type
5830 variables work, compared to earlier releases.  Read this section
5831 carefully!</para>
5832
5833 <sect3>
5834 <title>Overview</title>
5835
5836 <para>The design follows the following principles
5837 <itemizedlist>
5838 <listitem><para>A scoped type variable stands for a type <emphasis>variable</emphasis>, and not for
5839 a <emphasis>type</emphasis>. (This is a change from GHC's earlier
5840 design.)</para></listitem>
5841 <listitem><para>Furthermore, distinct lexical type variables stand for distinct
5842 type variables.  This means that every programmer-written type signature
5843 (including one that contains free scoped type variables) denotes a
5844 <emphasis>rigid</emphasis> type; that is, the type is fully known to the type
5845 checker, and no inference is involved.</para></listitem>
5846 <listitem><para>Lexical type variables may be alpha-renamed freely, without
5847 changing the program.</para></listitem>
5848 </itemizedlist>
5849 </para>
5850 <para>
5851 A <emphasis>lexically scoped type variable</emphasis> can be bound by:
5852 <itemizedlist>
5853 <listitem><para>A declaration type signature (<xref linkend="decl-type-sigs"/>)</para></listitem>
5854 <listitem><para>An expression type signature (<xref linkend="exp-type-sigs"/>)</para></listitem>
5855 <listitem><para>A pattern type signature (<xref linkend="pattern-type-sigs"/>)</para></listitem>
5856 <listitem><para>Class and instance declarations (<xref linkend="cls-inst-scoped-tyvars"/>)</para></listitem>
5857 </itemizedlist>
5858 </para>
5859 <para>
5860 In Haskell, a programmer-written type signature is implicitly quantified over
5861 its free type variables (<ulink
5862 url="http://www.haskell.org/onlinereport/decls.html#sect4.1.2">Section
5863 4.1.2</ulink>
5864 of the Haskell Report).
5865 Lexically scoped type variables affect this implicit quantification rules
5866 as follows: any type variable that is in scope is <emphasis>not</emphasis> universally
5867 quantified. For example, if type variable <literal>a</literal> is in scope,
5868 then
5869 <programlisting>
5870   (e :: a -> a)     means     (e :: a -> a)
5871   (e :: b -> b)     means     (e :: forall b. b->b)
5872   (e :: a -> b)     means     (e :: forall b. a->b)
5873 </programlisting>
5874 </para>
5875
5876
5877 </sect3>
5878
5879
5880 <sect3 id="decl-type-sigs">
5881 <title>Declaration type signatures</title>
5882 <para>A declaration type signature that has <emphasis>explicit</emphasis>
5883 quantification (using <literal>forall</literal>) brings into scope the
5884 explicitly-quantified
5885 type variables, in the definition of the named function.  For example:
5886 <programlisting>
5887   f :: forall a. [a] -> [a]
5888   f (x:xs) = xs ++ [ x :: a ]
5889 </programlisting>
5890 The "<literal>forall a</literal>" brings "<literal>a</literal>" into scope in
5891 the definition of "<literal>f</literal>".
5892 </para>
5893 <para>This only happens if:
5894 <itemizedlist>
5895 <listitem><para> The quantification in <literal>f</literal>'s type
5896 signature is explicit.  For example:
5897 <programlisting>
5898   g :: [a] -> [a]
5899   g (x:xs) = xs ++ [ x :: a ]
5900 </programlisting>
5901 This program will be rejected, because "<literal>a</literal>" does not scope
5902 over the definition of "<literal>f</literal>", so "<literal>x::a</literal>"
5903 means "<literal>x::forall a. a</literal>" by Haskell's usual implicit
5904 quantification rules.
5905 </para></listitem>
5906 <listitem><para> The signature gives a type for a function binding or a bare variable binding,
5907 not a pattern binding.
5908 For example:
5909 <programlisting>
5910   f1 :: forall a. [a] -> [a]
5911   f1 (x:xs) = xs ++ [ x :: a ]   -- OK
5912
5913   f2 :: forall a. [a] -> [a]
5914   f2 = \(x:xs) -> xs ++ [ x :: a ]   -- OK
5915
5916   f3 :: forall a. [a] -> [a]
5917   Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ])   -- Not OK!
5918 </programlisting>
5919 The binding for <literal>f3</literal> is a pattern binding, and so its type signature
5920 does not bring <literal>a</literal> into scope.   However <literal>f1</literal> is a
5921 function binding, and <literal>f2</literal> binds a bare variable; in both cases
5922 the type signature brings <literal>a</literal> into scope.
5923 </para></listitem>
5924 </itemizedlist>
5925 </para>
5926 </sect3>
5927
5928 <sect3 id="exp-type-sigs">
5929 <title>Expression type signatures</title>
5930
5931 <para>An expression type signature that has <emphasis>explicit</emphasis>
5932 quantification (using <literal>forall</literal>) brings into scope the
5933 explicitly-quantified
5934 type variables, in the annotated expression.  For example:
5935 <programlisting>
5936   f = runST ( (op >>= \(x :: STRef s Int) -> g x) :: forall s. ST s Bool )
5937 </programlisting>
5938 Here, the type signature <literal>forall a. ST s Bool</literal> brings the
5939 type variable <literal>s</literal> into scope, in the annotated expression
5940 <literal>(op >>= \(x :: STRef s Int) -> g x)</literal>.
5941 </para>
5942
5943 </sect3>
5944
5945 <sect3 id="pattern-type-sigs">
5946 <title>Pattern type signatures</title>
5947 <para>
5948 A type signature may occur in any pattern; this is a <emphasis>pattern type
5949 signature</emphasis>.
5950 For example:
5951 <programlisting>
5952   -- f and g assume that 'a' is already in scope
5953   f = \(x::Int, y::a) -> x
5954   g (x::a) = x
5955   h ((x,y) :: (Int,Bool)) = (y,x)
5956 </programlisting>
5957 In the case where all the type variables in the pattern type signature are
5958 already in scope (i.e. bound by the enclosing context), matters are simple: the
5959 signature simply constrains the type of the pattern in the obvious way.
5960 </para>
5961 <para>
5962 Unlike expression and declaration type signatures, pattern type signatures are not implicitly generalised.
5963 The pattern in a <emphasis>pattern binding</emphasis> may only mention type variables
5964 that are already in scope.  For example:
5965 <programlisting>
5966   f :: forall a. [a] -> (Int, [a])
5967   f xs = (n, zs)
5968     where
5969       (ys::[a], n) = (reverse xs, length xs) -- OK
5970       zs::[a] = xs ++ ys                     -- OK
5971
5972       Just (v::b) = ...  -- Not OK; b is not in scope
5973 </programlisting>
5974 Here, the pattern signatures for <literal>ys</literal> and <literal>zs</literal>
5975 are fine, but the one for <literal>v</literal> is not because <literal>b</literal> is
5976 not in scope.
5977 </para>
5978 <para>
5979 However, in all patterns <emphasis>other</emphasis> than pattern bindings, a pattern
5980 type signature may mention a type variable that is not in scope; in this case,
5981 <emphasis>the signature brings that type variable into scope</emphasis>.
5982 This is particularly important for existential data constructors.  For example:
5983 <programlisting>
5984   data T = forall a. MkT [a]
5985
5986   k :: T -> T
5987   k (MkT [t::a]) = MkT t3
5988                  where
5989                    t3::[a] = [t,t,t]
5990 </programlisting>
5991 Here, the pattern type signature <literal>(t::a)</literal> mentions a lexical type
5992 variable that is not already in scope.  Indeed, it <emphasis>cannot</emphasis> already be in scope,
5993 because it is bound by the pattern match.  GHC's rule is that in this situation
5994 (and only then), a pattern type signature can mention a type variable that is
5995 not already in scope; the effect is to bring it into scope, standing for the
5996 existentially-bound type variable.
5997 </para>
5998 <para>
5999 When a pattern type signature binds a type variable in this way, GHC insists that the
6000 type variable is bound to a <emphasis>rigid</emphasis>, or fully-known, type variable.
6001 This means that any user-written type signature always stands for a completely known type.
6002 </para>
6003 <para>
6004 If all this seems a little odd, we think so too.  But we must have
6005 <emphasis>some</emphasis> way to bring such type variables into scope, else we
6006 could not name existentially-bound type variables in subsequent type signatures.
6007 </para>
6008 <para>
6009 This is (now) the <emphasis>only</emphasis> situation in which a pattern type
6010 signature is allowed to mention a lexical variable that is not already in
6011 scope.
6012 For example, both <literal>f</literal> and <literal>g</literal> would be
6013 illegal if <literal>a</literal> was not already in scope.
6014 </para>
6015
6016
6017 </sect3>
6018
6019 <!-- ==================== Commented out part about result type signatures
6020
6021 <sect3 id="result-type-sigs">
6022 <title>Result type signatures</title>
6023
6024 <para>
6025 The result type of a function, lambda, or case expression alternative can be given a signature, thus:
6026
6027 <programlisting>
6028   {- f assumes that 'a' is already in scope -}
6029   f x y :: [a] = [x,y,x]
6030
6031   g = \ x :: [Int] -> [3,4]
6032
6033   h :: forall a. [a] -> a
6034   h xs = case xs of
6035             (y:ys) :: a -> y
6036 </programlisting>
6037 The final <literal>:: [a]</literal> after the patterns of <literal>f</literal> gives the type of
6038 the result of the function.  Similarly, the body of the lambda in the RHS of
6039 <literal>g</literal> is <literal>[Int]</literal>, and the RHS of the case
6040 alternative in <literal>h</literal> is <literal>a</literal>.
6041 </para>
6042 <para> A result type signature never brings new type variables into scope.</para>
6043 <para>
6044 There are a couple of syntactic wrinkles.  First, notice that all three
6045 examples would parse quite differently with parentheses:
6046 <programlisting>
6047   {- f assumes that 'a' is already in scope -}
6048   f x (y :: [a]) = [x,y,x]
6049
6050   g = \ (x :: [Int]) -> [3,4]
6051
6052   h :: forall a. [a] -> a
6053   h xs = case xs of
6054             ((y:ys) :: a) -> y
6055 </programlisting>
6056 Now the signature is on the <emphasis>pattern</emphasis>; and
6057 <literal>h</literal> would certainly be ill-typed (since the pattern
6058 <literal>(y:ys)</literal> cannot have the type <literal>a</literal>.
6059
6060 Second, to avoid ambiguity, the type after the &ldquo;<literal>::</literal>&rdquo; in a result
6061 pattern signature on a lambda or <literal>case</literal> must be atomic (i.e. a single
6062 token or a parenthesised type of some sort).  To see why,
6063 consider how one would parse this:
6064 <programlisting>
6065   \ x :: a -> b -> x
6066 </programlisting>
6067 </para>
6068 </sect3>
6069
6070  -->
6071
6072 <sect3 id="cls-inst-scoped-tyvars">
6073 <title>Class and instance declarations</title>
6074 <para>
6075
6076 The type variables in the head of a <literal>class</literal> or <literal>instance</literal> declaration
6077 scope over the methods defined in the <literal>where</literal> part.  For example:
6078
6079
6080 <programlisting>
6081   class C a where
6082     op :: [a] -> a
6083
6084     op xs = let ys::[a]
6085                 ys = reverse xs
6086             in
6087             head ys
6088 </programlisting>
6089 </para>
6090 </sect3>
6091
6092 </sect2>
6093
6094
6095 <sect2 id="typing-binds">
6096 <title>Generalised typing of mutually recursive bindings</title>
6097
6098 <para>
6099 The Haskell Report specifies that a group of bindings (at top level, or in a
6100 <literal>let</literal> or <literal>where</literal>) should be sorted into
6101 strongly-connected components, and then type-checked in dependency order
6102 (<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.1">Haskell
6103 Report, Section 4.5.1</ulink>).
6104 As each group is type-checked, any binders of the group that
6105 have
6106 an explicit type signature are put in the type environment with the specified
6107 polymorphic type,
6108 and all others are monomorphic until the group is generalised
6109 (<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.2">Haskell Report, Section 4.5.2</ulink>).
6110 </para>
6111
6112 <para>Following a suggestion of Mark Jones, in his paper
6113 <ulink url="http://citeseer.ist.psu.edu/424440.html">Typing Haskell in
6114 Haskell</ulink>,
6115 GHC implements a more general scheme.  If <option>-XRelaxedPolyRec</option> is
6116 specified:
6117 <emphasis>the dependency analysis ignores references to variables that have an explicit
6118 type signature</emphasis>.
6119 As a result of this refined dependency analysis, the dependency groups are smaller, and more bindings will
6120 typecheck.  For example, consider:
6121 <programlisting>
6122   f :: Eq a =&gt; a -> Bool
6123   f x = (x == x) || g True || g "Yes"
6124
6125   g y = (y &lt;= y) || f True
6126 </programlisting>
6127 This is rejected by Haskell 98, but under Jones's scheme the definition for
6128 <literal>g</literal> is typechecked first, separately from that for
6129 <literal>f</literal>,
6130 because the reference to <literal>f</literal> in <literal>g</literal>'s right
6131 hand side is ignored by the dependency analysis.  Then <literal>g</literal>'s
6132 type is generalised, to get
6133 <programlisting>
6134   g :: Ord a =&gt; a -> Bool
6135 </programlisting>
6136 Now, the definition for <literal>f</literal> is typechecked, with this type for
6137 <literal>g</literal> in the type environment.
6138 </para>
6139
6140 <para>
6141 The same refined dependency analysis also allows the type signatures of
6142 mutually-recursive functions to have different contexts, something that is illegal in
6143 Haskell 98 (Section 4.5.2, last sentence).  With
6144 <option>-XRelaxedPolyRec</option>
6145 GHC only insists that the type signatures of a <emphasis>refined</emphasis> group have identical
6146 type signatures; in practice this means that only variables bound by the same
6147 pattern binding must have the same context.  For example, this is fine:
6148 <programlisting>
6149   f :: Eq a =&gt; a -> Bool
6150   f x = (x == x) || g True
6151
6152   g :: Ord a =&gt; a -> Bool
6153   g y = (y &lt;= y) || f True
6154 </programlisting>
6155 </para>
6156 </sect2>
6157
6158 <sect2 id="mono-local-binds">
6159 <title>Monomorphic local bindings</title>
6160 <para>
6161 We are actively thinking of simplifying GHC's type system, by <emphasis>not generalising local bindings</emphasis>.
6162 The rationale is described in the paper
6163 <ulink url="http://research.microsoft.com/~simonpj/papers/constraints/index.htm">Let should not be generalised</ulink>.
6164 </para>
6165 <para>
6166 The experimental new behaviour is enabled by the flag <option>-XMonoLocalBinds</option>.  The effect is
6167 that local (that is, non-top-level) bindings without a type signature are not generalised at all.  You can
6168 think of it as an extreme (but much more predictable) version of the Monomorphism Restriction.
6169 If you supply a type signature, then the flag has no effect.
6170 </para>
6171 </sect2>
6172
6173 </sect1>
6174 <!-- ==================== End of type system extensions =================  -->
6175
6176 <!-- ====================== TEMPLATE HASKELL =======================  -->
6177
6178 <sect1 id="template-haskell">
6179 <title>Template Haskell</title>
6180
6181 <para>Template Haskell allows you to do compile-time meta-programming in
6182 Haskell.
6183 The background to
6184 the main technical innovations is discussed in "<ulink
6185 url="http://research.microsoft.com/~simonpj/papers/meta-haskell/">
6186 Template Meta-programming for Haskell</ulink>" (Proc Haskell Workshop 2002).
6187 </para>
6188 <para>
6189 There is a Wiki page about
6190 Template Haskell at <ulink url="http://www.haskell.org/haskellwiki/Template_Haskell">
6191 http://www.haskell.org/haskellwiki/Template_Haskell</ulink>, and that is the best place to look for
6192 further details.
6193 You may also
6194 consult the <ulink
6195 url="http://www.haskell.org/ghc/docs/latest/html/libraries/index.html">online
6196 Haskell library reference material</ulink>
6197 (look for module <literal>Language.Haskell.TH</literal>).
6198 Many changes to the original design are described in
6199       <ulink url="http://research.microsoft.com/~simonpj/papers/meta-haskell/notes2.ps">
6200 Notes on Template Haskell version 2</ulink>.
6201 Not all of these changes are in GHC, however.
6202 </para>
6203
6204 <para> The first example from that paper is set out below (<xref linkend="th-example"/>)
6205 as a worked example to help get you started.
6206 </para>
6207
6208 <para>
6209 The documentation here describes the realisation of Template Haskell in GHC.  It is not detailed enough to
6210 understand Template Haskell; see the <ulink url="http://haskell.org/haskellwiki/Template_Haskell">
6211 Wiki page</ulink>.
6212 </para>
6213
6214     <sect2>
6215       <title>Syntax</title>
6216
6217       <para> Template Haskell has the following new syntactic
6218       constructions.  You need to use the flag
6219       <option>-XTemplateHaskell</option>
6220         <indexterm><primary><option>-XTemplateHaskell</option></primary>
6221       </indexterm>to switch these syntactic extensions on
6222       (<option>-XTemplateHaskell</option> is no longer implied by
6223       <option>-fglasgow-exts</option>).</para>
6224
6225         <itemizedlist>
6226               <listitem><para>
6227                   A splice is written <literal>$x</literal>, where <literal>x</literal> is an
6228                   identifier, or <literal>$(...)</literal>, where the "..." is an arbitrary expression.
6229                   There must be no space between the "$" and the identifier or parenthesis.  This use
6230                   of "$" overrides its meaning as an infix operator, just as "M.x" overrides the meaning
6231                   of "." as an infix operator.  If you want the infix operator, put spaces around it.
6232                   </para>
6233               <para> A splice can occur in place of
6234                   <itemizedlist>
6235                     <listitem><para> an expression; the spliced expression must
6236                     have type <literal>Q Exp</literal></para></listitem>
6237                     <listitem><para> an type; the spliced expression must
6238                     have type <literal>Q Typ</literal></para></listitem>
6239                     <listitem><para> a list of top-level declarations; the spliced expression
6240                     must have type <literal>Q [Dec]</literal></para></listitem>
6241                     </itemizedlist>
6242             Note that pattern splices are not supported.
6243             Inside a splice you can can only call functions defined in imported modules,
6244             not functions defined elsewhere in the same module.</para></listitem>
6245
6246               <listitem><para>
6247                   A expression quotation is written in Oxford brackets, thus:
6248                   <itemizedlist>
6249                     <listitem><para> <literal>[| ... |]</literal>, or <literal>[e| ... |]</literal>,
6250                              where the "..." is an expression;
6251                              the quotation has type <literal>Q Exp</literal>.</para></listitem>
6252                     <listitem><para> <literal>[d| ... |]</literal>, where the "..." is a list of top-level declarations;
6253                              the quotation has type <literal>Q [Dec]</literal>.</para></listitem>
6254                     <listitem><para> <literal>[t| ... |]</literal>, where the "..." is a type;
6255                              the quotation has type <literal>Q Type</literal>.</para></listitem>
6256                     <listitem><para> <literal>[p| ... |]</literal>, where the "..." is a pattern;
6257                              the quotation has type <literal>Q Pat</literal>.</para></listitem>
6258                   </itemizedlist></para></listitem>
6259
6260               <listitem><para>
6261                   A quasi-quotation can appear in either a pattern context or an
6262                   expression context and is also written in Oxford brackets:
6263                   <itemizedlist>
6264                     <listitem><para> <literal>[<replaceable>varid</replaceable>| ... |]</literal>,
6265                         where the "..." is an arbitrary string; a full description of the
6266                         quasi-quotation facility is given in <xref linkend="th-quasiquotation"/>.</para></listitem>
6267                   </itemizedlist></para></listitem>
6268
6269               <listitem><para>
6270                   A name can be quoted with either one or two prefix single quotes:
6271                   <itemizedlist>
6272                     <listitem><para> <literal>'f</literal> has type <literal>Name</literal>, and names the function <literal>f</literal>.
6273                   Similarly <literal>'C</literal> has type <literal>Name</literal> and names the data constructor <literal>C</literal>.
6274                   In general <literal>'</literal><replaceable>thing</replaceable> interprets <replaceable>thing</replaceable> in an expression context.
6275                      </para></listitem>
6276                     <listitem><para> <literal>''T</literal> has type <literal>Name</literal>, and names the type constructor  <literal>T</literal>.
6277                   That is, <literal>''</literal><replaceable>thing</replaceable> interprets <replaceable>thing</replaceable> in a type context.
6278                      </para></listitem>
6279                   </itemizedlist>
6280                   These <literal>Names</literal> can be used to construct Template Haskell expressions, patterns, declarations etc.  They
6281                   may also be given as an argument to the <literal>reify</literal> function.
6282                  </para>
6283                 </listitem>
6284
6285               <listitem><para> You may omit the <literal>$(...)</literal> in a top-level declaration splice.
6286               Simply writing an expression (rather than a declaration) implies a splice.  For example, you can write
6287 <programlisting>
6288 module Foo where
6289 import Bar
6290
6291 f x = x
6292
6293 $(deriveStuff 'f)   -- Uses the $(...) notation
6294
6295 g y = y+1
6296
6297 deriveStuff 'g      -- Omits the $(...)
6298
6299 h z = z-1
6300 </programlisting>
6301             This abbreviation makes top-level declaration slices quieter and less intimidating.
6302             </para></listitem>
6303
6304
6305         </itemizedlist>
6306 (Compared to the original paper, there are many differences of detail.
6307 The syntax for a declaration splice uses "<literal>$</literal>" not "<literal>splice</literal>".
6308 The type of the enclosed expression must be  <literal>Q [Dec]</literal>, not  <literal>[Q Dec]</literal>.
6309 Pattern splices and quotations are not implemented.)
6310
6311 </sect2>
6312
6313 <sect2>  <title> Using Template Haskell </title>
6314 <para>
6315 <itemizedlist>
6316     <listitem><para>
6317     The data types and monadic constructor functions for Template Haskell are in the library
6318     <literal>Language.Haskell.THSyntax</literal>.
6319     </para></listitem>
6320
6321     <listitem><para>
6322     You can only run a function at compile time if it is imported from another module.  That is,
6323             you can't define a function in a module, and call it from within a splice in the same module.
6324             (It would make sense to do so, but it's hard to implement.)
6325    </para></listitem>
6326
6327    <listitem><para>
6328    You can only run a function at compile time if it is imported
6329    from another module <emphasis>that is not part of a mutually-recursive group of modules
6330    that includes the module currently being compiled</emphasis>.  Furthermore, all of the modules of
6331    the mutually-recursive group must be reachable by non-SOURCE imports from the module where the
6332    splice is to be run.</para>
6333    <para>
6334    For example, when compiling module A,
6335    you can only run Template Haskell functions imported from B if B does not import A (directly or indirectly).
6336    The reason should be clear: to run B we must compile and run A, but we are currently type-checking A.
6337    </para></listitem>
6338
6339     <listitem><para>
6340             The flag <literal>-ddump-splices</literal> shows the expansion of all top-level splices as they happen.
6341    </para></listitem>
6342     <listitem><para>
6343             If you are building GHC from source, you need at least a stage-2 bootstrap compiler to
6344               run Template Haskell.  A stage-1 compiler will reject the TH constructs.  Reason: TH
6345               compiles and runs a program, and then looks at the result.  So it's important that
6346               the program it compiles produces results whose representations are identical to
6347               those of the compiler itself.
6348    </para></listitem>
6349 </itemizedlist>
6350 </para>
6351 <para> Template Haskell works in any mode (<literal>--make</literal>, <literal>--interactive</literal>,
6352         or file-at-a-time).  There used to be a restriction to the former two, but that restriction
6353         has been lifted.
6354 </para>
6355 </sect2>
6356
6357 <sect2 id="th-example">  <title> A Template Haskell Worked Example </title>
6358 <para>To help you get over the confidence barrier, try out this skeletal worked example.
6359   First cut and paste the two modules below into "Main.hs" and "Printf.hs":</para>
6360
6361 <programlisting>
6362
6363 {- Main.hs -}
6364 module Main where
6365
6366 -- Import our template "pr"
6367 import Printf ( pr )
6368
6369 -- The splice operator $ takes the Haskell source code
6370 -- generated at compile time by "pr" and splices it into
6371 -- the argument of "putStrLn".
6372 main = putStrLn ( $(pr "Hello") )
6373
6374
6375 {- Printf.hs -}
6376 module Printf where
6377
6378 -- Skeletal printf from the paper.
6379 -- It needs to be in a separate module to the one where
6380 -- you intend to use it.
6381
6382 -- Import some Template Haskell syntax
6383 import Language.Haskell.TH
6384
6385 -- Describe a format string
6386 data Format = D | S | L String
6387
6388 -- Parse a format string.  This is left largely to you
6389 -- as we are here interested in building our first ever
6390 -- Template Haskell program and not in building printf.
6391 parse :: String -> [Format]
6392 parse s   = [ L s ]
6393
6394 -- Generate Haskell source code from a parsed representation
6395 -- of the format string.  This code will be spliced into
6396 -- the module which calls "pr", at compile time.
6397 gen :: [Format] -> Q Exp
6398 gen [D]   = [| \n -> show n |]
6399 gen [S]   = [| \s -> s |]
6400 gen [L s] = stringE s
6401
6402 -- Here we generate the Haskell code for the splice
6403 -- from an input format string.
6404 pr :: String -> Q Exp
6405 pr s = gen (parse s)
6406 </programlisting>
6407
6408 <para>Now run the compiler (here we are a Cygwin prompt on Windows):
6409 </para>
6410 <programlisting>
6411 $ ghc --make -XTemplateHaskell main.hs -o main.exe
6412 </programlisting>
6413
6414 <para>Run "main.exe" and here is your output:</para>
6415
6416 <programlisting>
6417 $ ./main
6418 Hello
6419 </programlisting>
6420
6421 </sect2>
6422
6423 <sect2>
6424 <title>Using Template Haskell with Profiling</title>
6425 <indexterm><primary>profiling</primary><secondary>with Template Haskell</secondary></indexterm>
6426
6427 <para>Template Haskell relies on GHC's built-in bytecode compiler and
6428 interpreter to run the splice expressions.  The bytecode interpreter
6429 runs the compiled expression on top of the same runtime on which GHC
6430 itself is running; this means that the compiled code referred to by
6431 the interpreted expression must be compatible with this runtime, and
6432 in particular this means that object code that is compiled for
6433 profiling <emphasis>cannot</emphasis> be loaded and used by a splice
6434 expression, because profiled object code is only compatible with the
6435 profiling version of the runtime.</para>
6436
6437 <para>This causes difficulties if you have a multi-module program
6438 containing Template Haskell code and you need to compile it for
6439 profiling, because GHC cannot load the profiled object code and use it
6440 when executing the splices.  Fortunately GHC provides a workaround.
6441 The basic idea is to compile the program twice:</para>
6442
6443 <orderedlist>
6444 <listitem>
6445   <para>Compile the program or library first the normal way, without
6446   <option>-prof</option><indexterm><primary><option>-prof</option></primary></indexterm>.</para>
6447 </listitem>
6448 <listitem>
6449   <para>Then compile it again with <option>-prof</option>, and
6450   additionally use <option>-osuf
6451   p_o</option><indexterm><primary><option>-osuf</option></primary></indexterm>
6452   to name the object files differently (you can choose any suffix
6453   that isn't the normal object suffix here).  GHC will automatically
6454   load the object files built in the first step when executing splice
6455   expressions.  If you omit the <option>-osuf</option> flag when
6456   building with <option>-prof</option> and Template Haskell is used,
6457   GHC will emit an error message. </para>
6458 </listitem>
6459 </orderedlist>
6460 </sect2>
6461
6462 <sect2 id="th-quasiquotation">  <title> Template Haskell Quasi-quotation </title>
6463 <para>Quasi-quotation allows patterns and expressions to be written using
6464 programmer-defined concrete syntax; the motivation behind the extension and
6465 several examples are documented in
6466 "<ulink url="http://www.eecs.harvard.edu/~mainland/ghc-quasiquoting/">Why It's
6467 Nice to be Quoted: Quasiquoting for Haskell</ulink>" (Proc Haskell Workshop
6468 2007). The example below shows how to write a quasiquoter for a simple
6469 expression language.</para>
6470 <para>
6471 Here are the salient features
6472 <itemizedlist>
6473 <listitem><para>
6474 A quasi-quote has the form
6475 <literal>[<replaceable>quoter</replaceable>| <replaceable>string</replaceable> |]</literal>.
6476 <itemizedlist>
6477 <listitem><para>
6478 The <replaceable>quoter</replaceable> must be the (unqualified) name of an imported
6479 quoter; it cannot be an arbitrary expression.
6480 </para></listitem>
6481 <listitem><para>
6482 The <replaceable>quoter</replaceable> cannot be "<literal>e</literal>",
6483 "<literal>t</literal>", "<literal>d</literal>", or "<literal>p</literal>", since
6484 those overlap with Template Haskell quotations.
6485 </para></listitem>
6486 <listitem><para>
6487 There must be no spaces in the token
6488 <literal>[<replaceable>quoter</replaceable>|</literal>.
6489 </para></listitem>
6490 <listitem><para>
6491 The quoted <replaceable>string</replaceable>
6492 can be arbitrary, and may contain newlines.
6493 </para></listitem>
6494 </itemizedlist>
6495 </para></listitem>
6496
6497 <listitem><para>
6498 A quasiquote may appear in place of
6499 <itemizedlist>
6500 <listitem><para>An expression</para></listitem>
6501 <listitem><para>A pattern</para></listitem>
6502 <listitem><para>A type</para></listitem>
6503 <listitem><para>A top-level declaration</para></listitem>
6504 </itemizedlist>
6505 (Only the first two are described in the paper.)
6506 </para></listitem>
6507
6508 <listitem><para>
6509 A quoter is a value of type <literal>Language.Haskell.TH.Quote.QuasiQuoter</literal>,
6510 which is defined thus:
6511 <programlisting>
6512 data QuasiQuoter = QuasiQuoter { quoteExp  :: String -> Q Exp,
6513                                  quotePat  :: String -> Q Pat,
6514                                  quoteType :: String -> Q Type,
6515                                  quoteDec  :: String -> Q [Dec] }
6516 </programlisting>
6517 That is, a quoter is a tuple of four parsers, one for each of the contexts
6518 in which a quasi-quote can occur.
6519 </para></listitem>
6520 <listitem><para>
6521 A quasi-quote is expanded by applying the appropriate parser to the string
6522 enclosed by the Oxford brackets.  The context of the quasi-quote (expression, pattern,
6523 type, declaration) determines which of the parsers is called.
6524 </para></listitem>
6525 </itemizedlist>
6526 </para>
6527 <para>
6528 The example below shows quasi-quotation in action.  The quoter <literal>expr</literal>
6529 is bound to a value of type <literal>QuasiQuoter</literal> defined in module <literal>Expr</literal>.
6530 The example makes use of an antiquoted
6531 variable <literal>n</literal>, indicated by the syntax <literal>'int:n</literal>
6532 (this syntax for anti-quotation was defined by the parser's
6533 author, <emphasis>not</emphasis> by GHC). This binds <literal>n</literal> to the
6534 integer value argument of the constructor <literal>IntExpr</literal> when
6535 pattern matching. Please see the referenced paper for further details regarding
6536 anti-quotation as well as the description of a technique that uses SYB to
6537 leverage a single parser of type <literal>String -> a</literal> to generate both
6538 an expression parser that returns a value of type <literal>Q Exp</literal> and a
6539 pattern parser that returns a value of type <literal>Q Pat</literal>.
6540 </para>
6541
6542 <para>
6543 Quasiquoters must obey the same stage restrictions as Template Haskell, e.g., in
6544 the example, <literal>expr</literal> cannot be defined
6545 in <literal>Main.hs</literal> where it is used, but must be imported.
6546 </para>
6547
6548 <programlisting>
6549 {- ------------- file Main.hs --------------- -}
6550 module Main where
6551
6552 import Expr
6553
6554 main :: IO ()
6555 main = do { print $ eval [expr|1 + 2|]
6556           ; case IntExpr 1 of
6557               { [expr|'int:n|] -> print n
6558               ;  _              -> return ()
6559               }
6560           }
6561
6562
6563 {- ------------- file Expr.hs --------------- -}
6564 module Expr where
6565
6566 import qualified Language.Haskell.TH as TH
6567 import Language.Haskell.TH.Quote
6568
6569 data Expr  =  IntExpr Integer
6570            |  AntiIntExpr String
6571            |  BinopExpr BinOp Expr Expr
6572            |  AntiExpr String
6573     deriving(Show, Typeable, Data)
6574
6575 data BinOp  =  AddOp
6576             |  SubOp
6577             |  MulOp
6578             |  DivOp
6579     deriving(Show, Typeable, Data)
6580
6581 eval :: Expr -> Integer
6582 eval (IntExpr n)        = n
6583 eval (BinopExpr op x y) = (opToFun op) (eval x) (eval y)
6584   where
6585     opToFun AddOp = (+)
6586     opToFun SubOp = (-)
6587     opToFun MulOp = (*)
6588     opToFun DivOp = div
6589
6590 expr = QuasiQuoter { quoteExp = parseExprExp, quotePat =  parseExprPat }
6591
6592 -- Parse an Expr, returning its representation as
6593 -- either a Q Exp or a Q Pat. See the referenced paper
6594 -- for how to use SYB to do this by writing a single
6595 -- parser of type String -> Expr instead of two
6596 -- separate parsers.
6597
6598 parseExprExp :: String -> Q Exp
6599 parseExprExp ...
6600
6601 parseExprPat :: String -> Q Pat
6602 parseExprPat ...
6603 </programlisting>
6604
6605 <para>Now run the compiler:
6606 <programlisting>
6607 $ ghc --make -XQuasiQuotes Main.hs -o main
6608 </programlisting>
6609 </para>
6610
6611 <para>Run "main" and here is your output:
6612 <programlisting>
6613 $ ./main
6614 3
6615 1
6616 </programlisting>
6617 </para>
6618 </sect2>
6619
6620 </sect1>
6621
6622 <!-- ===================== Arrow notation ===================  -->
6623
6624 <sect1 id="arrow-notation">
6625 <title>Arrow notation
6626 </title>
6627
6628 <para>Arrows are a generalization of monads introduced by John Hughes.
6629 For more details, see
6630 <itemizedlist>
6631
6632 <listitem>
6633 <para>
6634 &ldquo;Generalising Monads to Arrows&rdquo;,
6635 John Hughes, in <citetitle>Science of Computer Programming</citetitle> 37,
6636 pp67&ndash;111, May 2000.
6637 The paper that introduced arrows: a friendly introduction, motivated with
6638 programming examples.
6639 </para>
6640 </listitem>
6641
6642 <listitem>
6643 <para>
6644 &ldquo;<ulink url="http://www.soi.city.ac.uk/~ross/papers/notation.html">A New Notation for Arrows</ulink>&rdquo;,
6645 Ross Paterson, in <citetitle>ICFP</citetitle>, Sep 2001.
6646 Introduced the notation described here.
6647 </para>
6648 </listitem>
6649
6650 <listitem>
6651 <para>
6652 &ldquo;<ulink url="http://www.soi.city.ac.uk/~ross/papers/fop.html">Arrows and Computation</ulink>&rdquo;,
6653 Ross Paterson, in <citetitle>The Fun of Programming</citetitle>,
6654 Palgrave, 2003.
6655 </para>
6656 </listitem>
6657
6658 <listitem>
6659 <para>
6660 &ldquo;<ulink url="http://www.cs.chalmers.se/~rjmh/afp-arrows.pdf">Programming with Arrows</ulink>&rdquo;,
6661 John Hughes, in <citetitle>5th International Summer School on
6662 Advanced Functional Programming</citetitle>,
6663 <citetitle>Lecture Notes in Computer Science</citetitle> vol. 3622,
6664 Springer, 2004.
6665 This paper includes another introduction to the notation,
6666 with practical examples.
6667 </para>
6668 </listitem>
6669
6670 <listitem>
6671 <para>
6672 &ldquo;<ulink url="http://www.haskell.org/ghc/docs/papers/arrow-rules.pdf">Type and Translation Rules for Arrow Notation in GHC</ulink>&rdquo;,
6673 Ross Paterson and Simon Peyton Jones, September 16, 2004.
6674 A terse enumeration of the formal rules used
6675 (extracted from comments in the source code).
6676 </para>
6677 </listitem>
6678
6679 <listitem>
6680 <para>
6681 The arrows web page at
6682 <ulink url="http://www.haskell.org/arrows/"><literal>http://www.haskell.org/arrows/</literal></ulink>.
6683 </para>
6684 </listitem>
6685
6686 </itemizedlist>
6687 With the <option>-XArrows</option> flag, GHC supports the arrow
6688 notation described in the second of these papers,
6689 translating it using combinators from the
6690 <ulink url="&libraryBaseLocation;/Control-Arrow.html"><literal>Control.Arrow</literal></ulink>
6691 module.
6692 What follows is a brief introduction to the notation;
6693 it won't make much sense unless you've read Hughes's paper.
6694 </para>
6695
6696 <para>The extension adds a new kind of expression for defining arrows:
6697 <screen>
6698 <replaceable>exp</replaceable><superscript>10</superscript> ::= ...
6699        |  proc <replaceable>apat</replaceable> -> <replaceable>cmd</replaceable>
6700 </screen>
6701 where <literal>proc</literal> is a new keyword.
6702 The variables of the pattern are bound in the body of the
6703 <literal>proc</literal>-expression,
6704 which is a new sort of thing called a <firstterm>command</firstterm>.
6705 The syntax of commands is as follows:
6706 <screen>
6707 <replaceable>cmd</replaceable>   ::= <replaceable>exp</replaceable><superscript>10</superscript> -&lt;  <replaceable>exp</replaceable>
6708        |  <replaceable>exp</replaceable><superscript>10</superscript> -&lt;&lt; <replaceable>exp</replaceable>
6709        |  <replaceable>cmd</replaceable><superscript>0</superscript>
6710 </screen>
6711 with <replaceable>cmd</replaceable><superscript>0</superscript> up to
6712 <replaceable>cmd</replaceable><superscript>9</superscript> defined using
6713 infix operators as for expressions, and
6714 <screen>
6715 <replaceable>cmd</replaceable><superscript>10</superscript> ::= \ <replaceable>apat</replaceable> ... <replaceable>apat</replaceable> -> <replaceable>cmd</replaceable>
6716        |  let <replaceable>decls</replaceable> in <replaceable>cmd</replaceable>
6717        |  if <replaceable>exp</replaceable> then <replaceable>cmd</replaceable> else <replaceable>cmd</replaceable>
6718        |  case <replaceable>exp</replaceable> of { <replaceable>calts</replaceable> }
6719        |  do { <replaceable>cstmt</replaceable> ; ... <replaceable>cstmt</replaceable> ; <replaceable>cmd</replaceable> }
6720        |  <replaceable>fcmd</replaceable>
6721
6722 <replaceable>fcmd</replaceable>  ::= <replaceable>fcmd</replaceable> <replaceable>aexp</replaceable>
6723        |  ( <replaceable>cmd</replaceable> )
6724        |  (| <replaceable>aexp</replaceable> <replaceable>cmd</replaceable> ... <replaceable>cmd</replaceable> |)
6725
6726 <replaceable>cstmt</replaceable> ::= let <replaceable>decls</replaceable>
6727        |  <replaceable>pat</replaceable> &lt;- <replaceable>cmd</replaceable>
6728        |  rec { <replaceable>cstmt</replaceable> ; ... <replaceable>cstmt</replaceable> [;] }
6729        |  <replaceable>cmd</replaceable>
6730 </screen>
6731 where <replaceable>calts</replaceable> are like <replaceable>alts</replaceable>
6732 except that the bodies are commands instead of expressions.
6733 </para>
6734
6735 <para>
6736 Commands produce values, but (like monadic computations)
6737 may yield more than one value,
6738 or none, and may do other things as well.
6739 For the most part, familiarity with monadic notation is a good guide to
6740 using commands.
6741 However the values of expressions, even monadic ones,
6742 are determined by the values of the variables they contain;
6743 this is not necessarily the case for commands.
6744 </para>
6745
6746 <para>
6747 A simple example of the new notation is the expression
6748 <screen>
6749 proc x -> f -&lt; x+1
6750 </screen>
6751 We call this a <firstterm>procedure</firstterm> or
6752 <firstterm>arrow abstraction</firstterm>.
6753 As with a lambda expression, the variable <literal>x</literal>
6754 is a new variable bound within the <literal>proc</literal>-expression.
6755 It refers to the input to the arrow.
6756 In the above example, <literal>-&lt;</literal> is not an identifier but an
6757 new reserved symbol used for building commands from an expression of arrow
6758 type and an expression to be fed as input to that arrow.
6759 (The weird look will make more sense later.)
6760 It may be read as analogue of application for arrows.
6761 The above example is equivalent to the Haskell expression
6762 <screen>
6763 arr (\ x -> x+1) >>> f
6764 </screen>
6765 That would make no sense if the expression to the left of
6766 <literal>-&lt;</literal> involves the bound variable <literal>x</literal>.
6767 More generally, the expression to the left of <literal>-&lt;</literal>
6768 may not involve any <firstterm>local variable</firstterm>,
6769 i.e. a variable bound in the current arrow abstraction.
6770 For such a situation there is a variant <literal>-&lt;&lt;</literal>, as in
6771 <screen>
6772 proc x -> f x -&lt;&lt; x+1
6773 </screen>
6774 which is equivalent to
6775 <screen>
6776 arr (\ x -> (f x, x+1)) >>> app
6777 </screen>
6778 so in this case the arrow must belong to the <literal>ArrowApply</literal>
6779 class.
6780 Such an arrow is equivalent to a monad, so if you're using this form
6781 you may find a monadic formulation more convenient.
6782 </para>
6783
6784 <sect2>
6785 <title>do-notation for commands</title>
6786
6787 <para>
6788 Another form of command is a form of <literal>do</literal>-notation.
6789 For example, you can write
6790 <screen>
6791 proc x -> do
6792         y &lt;- f -&lt; x+1
6793         g -&lt; 2*y
6794         let z = x+y
6795         t &lt;- h -&lt; x*z
6796         returnA -&lt; t+z
6797 </screen>
6798 You can read this much like ordinary <literal>do</literal>-notation,
6799 but with commands in place of monadic expressions.
6800 The first line sends the value of <literal>x+1</literal> as an input to
6801 the arrow <literal>f</literal>, and matches its output against
6802 <literal>y</literal>.
6803 In the next line, the output is discarded.
6804 The arrow <function>returnA</function> is defined in the
6805 <ulink url="&libraryBaseLocation;/Control-Arrow.html"><literal>Control.Arrow</literal></ulink>
6806 module as <literal>arr id</literal>.
6807 The above example is treated as an abbreviation for
6808 <screen>
6809 arr (\ x -> (x, x)) >>>
6810         first (arr (\ x -> x+1) >>> f) >>>
6811         arr (\ (y, x) -> (y, (x, y))) >>>
6812         first (arr (\ y -> 2*y) >>> g) >>>
6813         arr snd >>>
6814         arr (\ (x, y) -> let z = x+y in ((x, z), z)) >>>
6815         first (arr (\ (x, z) -> x*z) >>> h) >>>
6816         arr (\ (t, z) -> t+z) >>>
6817         returnA
6818 </screen>
6819 Note that variables not used later in the composition are projected out.
6820 After simplification using rewrite rules (see <xref linkend="rewrite-rules"/>)
6821 defined in the
6822 <ulink url="&libraryBaseLocation;/Control-Arrow.html"><literal>Control.Arrow</literal></ulink>
6823 module, this reduces to
6824 <screen>
6825 arr (\ x -> (x+1, x)) >>>
6826         first f >>>
6827         arr (\ (y, x) -> (2*y, (x, y))) >>>
6828         first g >>>
6829         arr (\ (_, (x, y)) -> let z = x+y in (x*z, z)) >>>
6830         first h >>>
6831         arr (\ (t, z) -> t+z)
6832 </screen>
6833 which is what you might have written by hand.
6834 With arrow notation, GHC keeps track of all those tuples of variables for you.
6835 </para>
6836
6837 <para>
6838 Note that although the above translation suggests that
6839 <literal>let</literal>-bound variables like <literal>z</literal> must be
6840 monomorphic, the actual translation produces Core,
6841 so polymorphic variables are allowed.
6842 </para>
6843
6844 <para>
6845 It's also possible to have mutually recursive bindings,
6846 using the new <literal>rec</literal> keyword, as in the following example:
6847 <programlisting>
6848 counter :: ArrowCircuit a => a Bool Int
6849 counter = proc reset -> do
6850         rec     output &lt;- returnA -&lt; if reset then 0 else next
6851                 next &lt;- delay 0 -&lt; output+1
6852         returnA -&lt; output
6853 </programlisting>
6854 The translation of such forms uses the <function>loop</function> combinator,
6855 so the arrow concerned must belong to the <literal>ArrowLoop</literal> class.
6856 </para>
6857
6858 </sect2>
6859
6860 <sect2>
6861 <title>Conditional commands</title>
6862
6863 <para>
6864 In the previous example, we used a conditional expression to construct the
6865 input for an arrow.
6866 Sometimes we want to conditionally execute different commands, as in
6867 <screen>
6868 proc (x,y) ->
6869         if f x y
6870         then g -&lt; x+1
6871         else h -&lt; y+2
6872 </screen>
6873 which is translated to
6874 <screen>
6875 arr (\ (x,y) -> if f x y then Left x else Right y) >>>
6876         (arr (\x -> x+1) >>> f) ||| (arr (\y -> y+2) >>> g)
6877 </screen>
6878 Since the translation uses <function>|||</function>,
6879 the arrow concerned must belong to the <literal>ArrowChoice</literal> class.
6880 </para>
6881
6882 <para>
6883 There are also <literal>case</literal> commands, like
6884 <screen>
6885 case input of
6886     [] -> f -&lt; ()
6887     [x] -> g -&lt; x+1
6888     x1:x2:xs -> do
6889         y &lt;- h -&lt; (x1, x2)
6890         ys &lt;- k -&lt; xs
6891         returnA -&lt; y:ys
6892 </screen>
6893 The syntax is the same as for <literal>case</literal> expressions,
6894 except that the bodies of the alternatives are commands rather than expressions.
6895 The translation is similar to that of <literal>if</literal> commands.
6896 </para>
6897
6898 </sect2>
6899
6900 <sect2>
6901 <title>Defining your own control structures</title>
6902
6903 <para>
6904 As we're seen, arrow notation provides constructs,
6905 modelled on those for expressions,
6906 for sequencing, value recursion and conditionals.
6907 But suitable combinators,
6908 which you can define in ordinary Haskell,
6909 may also be used to build new commands out of existing ones.
6910 The basic idea is that a command defines an arrow from environments to values.
6911 These environments assign values to the free local variables of the command.
6912 Thus combinators that produce arrows from arrows
6913 may also be used to build commands from commands.
6914 For example, the <literal>ArrowChoice</literal> class includes a combinator
6915 <programlisting>
6916 ArrowChoice a => (&lt;+>) :: a e c -> a e c -> a e c
6917 </programlisting>
6918 so we can use it to build commands:
6919 <programlisting>
6920 expr' = proc x -> do
6921                 returnA -&lt; x
6922         &lt;+> do
6923                 symbol Plus -&lt; ()
6924                 y &lt;- term -&lt; ()
6925                 expr' -&lt; x + y
6926         &lt;+> do
6927                 symbol Minus -&lt; ()
6928                 y &lt;- term -&lt; ()
6929                 expr' -&lt; x - y
6930 </programlisting>
6931 (The <literal>do</literal> on the first line is needed to prevent the first
6932 <literal>&lt;+> ...</literal> from being interpreted as part of the
6933 expression on the previous line.)
6934 This is equivalent to
6935 <programlisting>
6936 expr' = (proc x -> returnA -&lt; x)
6937         &lt;+> (proc x -> do
6938                 symbol Plus -&lt; ()
6939                 y &lt;- term -&lt; ()
6940                 expr' -&lt; x + y)
6941         &lt;+> (proc x -> do
6942                 symbol Minus -&lt; ()
6943                 y &lt;- term -&lt; ()
6944                 expr' -&lt; x - y)
6945 </programlisting>
6946 It is essential that this operator be polymorphic in <literal>e</literal>
6947 (representing the environment input to the command
6948 and thence to its subcommands)
6949 and satisfy the corresponding naturality property
6950 <screen>
6951 arr k >>> (f &lt;+> g) = (arr k >>> f) &lt;+> (arr k >>> g)
6952 </screen>
6953 at least for strict <literal>k</literal>.
6954 (This should be automatic if you're not using <function>seq</function>.)
6955 This ensures that environments seen by the subcommands are environments
6956 of the whole command,
6957 and also allows the translation to safely trim these environments.
6958 The operator must also not use any variable defined within the current
6959 arrow abstraction.
6960 </para>
6961
6962 <para>
6963 We could define our own operator
6964 <programlisting>
6965 untilA :: ArrowChoice a => a e () -> a e Bool -> a e ()
6966 untilA body cond = proc x ->
6967         b &lt;- cond -&lt; x
6968         if b then returnA -&lt; ()
6969         else do
6970                 body -&lt; x
6971                 untilA body cond -&lt; x
6972 </programlisting>
6973 and use it in the same way.
6974 Of course this infix syntax only makes sense for binary operators;
6975 there is also a more general syntax involving special brackets:
6976 <screen>
6977 proc x -> do
6978         y &lt;- f -&lt; x+1
6979         (|untilA (increment -&lt; x+y) (within 0.5 -&lt; x)|)
6980 </screen>
6981 </para>
6982
6983 </sect2>
6984
6985 <sect2>
6986 <title>Primitive constructs</title>
6987
6988 <para>
6989 Some operators will need to pass additional inputs to their subcommands.
6990 For example, in an arrow type supporting exceptions,
6991 the operator that attaches an exception handler will wish to pass the
6992 exception that occurred to the handler.
6993 Such an operator might have a type
6994 <screen>
6995 handleA :: ... => a e c -> a (e,Ex) c -> a e c
6996 </screen>
6997 where <literal>Ex</literal> is the type of exceptions handled.
6998 You could then use this with arrow notation by writing a command
6999 <screen>
7000 body `handleA` \ ex -> handler
7001 </screen>
7002 so that if an exception is raised in the command <literal>body</literal>,
7003 the variable <literal>ex</literal> is bound to the value of the exception
7004 and the command <literal>handler</literal>,
7005 which typically refers to <literal>ex</literal>, is entered.
7006 Though the syntax here looks like a functional lambda,
7007 we are talking about commands, and something different is going on.
7008 The input to the arrow represented by a command consists of values for
7009 the free local variables in the command, plus a stack of anonymous values.
7010 In all the prior examples, this stack was empty.
7011 In the second argument to <function>handleA</function>,
7012 this stack consists of one value, the value of the exception.
7013 The command form of lambda merely gives this value a name.
7014 </para>
7015
7016 <para>
7017 More concretely,
7018 the values on the stack are paired to the right of the environment.
7019 So operators like <function>handleA</function> that pass
7020 extra inputs to their subcommands can be designed for use with the notation
7021 by pairing the values with the environment in this way.
7022 More precisely, the type of each argument of the operator (and its result)
7023 should have the form
7024 <screen>
7025 a (...(e,t1), ... tn) t
7026 </screen>
7027 where <replaceable>e</replaceable> is a polymorphic variable
7028 (representing the environment)
7029 and <replaceable>ti</replaceable> are the types of the values on the stack,
7030 with <replaceable>t1</replaceable> being the <quote>top</quote>.
7031 The polymorphic variable <replaceable>e</replaceable> must not occur in
7032 <replaceable>a</replaceable>, <replaceable>ti</replaceable> or
7033 <replaceable>t</replaceable>.
7034 However the arrows involved need not be the same.
7035 Here are some more examples of suitable operators:
7036 <screen>
7037 bracketA :: ... => a e b -> a (e,b) c -> a (e,c) d -> a e d
7038 runReader :: ... => a e c -> a' (e,State) c
7039 runState :: ... => a e c -> a' (e,State) (c,State)
7040 </screen>
7041 We can supply the extra input required by commands built with the last two
7042 by applying them to ordinary expressions, as in
7043 <screen>
7044 proc x -> do
7045         s &lt;- ...
7046         (|runReader (do { ... })|) s
7047 </screen>
7048 which adds <literal>s</literal> to the stack of inputs to the command
7049 built using <function>runReader</function>.
7050 </para>
7051
7052 <para>
7053 The command versions of lambda abstraction and application are analogous to
7054 the expression versions.
7055 In particular, the beta and eta rules describe equivalences of commands.
7056 These three features (operators, lambda abstraction and application)
7057 are the core of the notation; everything else can be built using them,
7058 though the results would be somewhat clumsy.
7059 For example, we could simulate <literal>do</literal>-notation by defining
7060 <programlisting>
7061 bind :: Arrow a => a e b -> a (e,b) c -> a e c
7062 u `bind` f = returnA &amp;&amp;&amp; u >>> f
7063
7064 bind_ :: Arrow a => a e b -> a e c -> a e c
7065 u `bind_` f = u `bind` (arr fst >>> f)
7066 </programlisting>
7067 We could simulate <literal>if</literal> by defining
7068 <programlisting>
7069 cond :: ArrowChoice a => a e b -> a e b -> a (e,Bool) b
7070 cond f g = arr (\ (e,b) -> if b then Left e else Right e) >>> f ||| g
7071 </programlisting>
7072 </para>
7073
7074 </sect2>
7075
7076 <sect2>
7077 <title>Differences with the paper</title>
7078
7079 <itemizedlist>
7080
7081 <listitem>
7082 <para>Instead of a single form of arrow application (arrow tail) with two
7083 translations, the implementation provides two forms
7084 <quote><literal>-&lt;</literal></quote> (first-order)
7085 and <quote><literal>-&lt;&lt;</literal></quote> (higher-order).
7086 </para>
7087 </listitem>
7088
7089 <listitem>
7090 <para>User-defined operators are flagged with banana brackets instead of
7091 a new <literal>form</literal> keyword.
7092 </para>
7093 </listitem>
7094
7095 </itemizedlist>
7096
7097 </sect2>
7098
7099 <sect2>
7100 <title>Portability</title>
7101
7102 <para>
7103 Although only GHC implements arrow notation directly,
7104 there is also a preprocessor
7105 (available from the
7106 <ulink url="http://www.haskell.org/arrows/">arrows web page</ulink>)
7107 that translates arrow notation into Haskell 98
7108 for use with other Haskell systems.
7109 You would still want to check arrow programs with GHC;
7110 tracing type errors in the preprocessor output is not easy.
7111 Modules intended for both GHC and the preprocessor must observe some
7112 additional restrictions:
7113 <itemizedlist>
7114
7115 <listitem>
7116 <para>
7117 The module must import
7118 <ulink url="&libraryBaseLocation;/Control-Arrow.html"><literal>Control.Arrow</literal></ulink>.
7119 </para>
7120 </listitem>
7121
7122 <listitem>
7123 <para>
7124 The preprocessor cannot cope with other Haskell extensions.
7125 These would have to go in separate modules.
7126 </para>
7127 </listitem>
7128
7129 <listitem>
7130 <para>
7131 Because the preprocessor targets Haskell (rather than Core),
7132 <literal>let</literal>-bound variables are monomorphic.
7133 </para>
7134 </listitem>
7135
7136 </itemizedlist>
7137 </para>
7138
7139 </sect2>
7140
7141 </sect1>
7142
7143 <!-- ==================== BANG PATTERNS =================  -->
7144
7145 <sect1 id="bang-patterns">
7146 <title>Bang patterns
7147 <indexterm><primary>Bang patterns</primary></indexterm>
7148 </title>
7149 <para>GHC supports an extension of pattern matching called <emphasis>bang
7150 patterns</emphasis>, written <literal>!<replaceable>pat</replaceable></literal>.
7151 Bang patterns are under consideration for Haskell Prime.
7152 The <ulink
7153 url="http://hackage.haskell.org/trac/haskell-prime/wiki/BangPatterns">Haskell
7154 prime feature description</ulink> contains more discussion and examples
7155 than the material below.
7156 </para>
7157 <para>
7158 The key change is the addition of a new rule to the
7159 <ulink url="http://haskell.org/onlinereport/exps.html#sect3.17.2">semantics of pattern matching in the Haskell 98 report</ulink>.
7160 Add new bullet 10, saying: Matching the pattern <literal>!</literal><replaceable>pat</replaceable>
7161 against a value <replaceable>v</replaceable> behaves as follows:
7162 <itemizedlist>
7163 <listitem><para>if <replaceable>v</replaceable> is bottom, the match diverges</para></listitem>
7164 <listitem><para>otherwise, <replaceable>pat</replaceable> is matched against <replaceable>v</replaceable>  </para></listitem>
7165 </itemizedlist>
7166 </para>
7167 <para>
7168 Bang patterns are enabled by the flag <option>-XBangPatterns</option>.
7169 </para>
7170
7171 <sect2 id="bang-patterns-informal">
7172 <title>Informal description of bang patterns
7173 </title>
7174 <para>
7175 The main idea is to add a single new production to the syntax of patterns:
7176 <programlisting>
7177   pat ::= !pat
7178 </programlisting>
7179 Matching an expression <literal>e</literal> against a pattern <literal>!p</literal> is done by first
7180 evaluating <literal>e</literal> (to WHNF) and then matching the result against <literal>p</literal>.
7181 Example:
7182 <programlisting>
7183 f1 !x = True
7184 </programlisting>
7185 This definition makes <literal>f1</literal> is strict in <literal>x</literal>,
7186 whereas without the bang it would be lazy.
7187 Bang patterns can be nested of course:
7188 <programlisting>
7189 f2 (!x, y) = [x,y]
7190 </programlisting>
7191 Here, <literal>f2</literal> is strict in <literal>x</literal> but not in
7192 <literal>y</literal>.
7193 A bang only really has an effect if it precedes a variable or wild-card pattern:
7194 <programlisting>
7195 f3 !(x,y) = [x,y]
7196 f4 (x,y)  = [x,y]
7197 </programlisting>
7198 Here, <literal>f3</literal> and <literal>f4</literal> are identical;
7199 putting a bang before a pattern that
7200 forces evaluation anyway does nothing.
7201 </para>
7202 <para>
7203 There is one (apparent) exception to this general rule that a bang only
7204 makes a difference when it precedes a variable or wild-card: a bang at the
7205 top level of a <literal>let</literal> or <literal>where</literal>
7206 binding makes the binding strict, regardless of the pattern. For example:
7207 <programlisting>
7208 let ![x,y] = e in b
7209 </programlisting>
7210 is a strict binding: operationally, it evaluates <literal>e</literal>, matches
7211 it against the pattern <literal>[x,y]</literal>, and then evaluates <literal>b</literal>.
7212 (We say "apparent" exception because the Right Way to think of it is that the bang
7213 at the top of a binding is not part of the <emphasis>pattern</emphasis>; rather it
7214 is part of the syntax of the <emphasis>binding</emphasis>.)
7215 Nested bangs in a pattern binding behave uniformly with all other forms of
7216 pattern matching.  For example
7217 <programlisting>
7218 let (!x,[y]) = e in b
7219 </programlisting>
7220 is equivalent to this:
7221 <programlisting>
7222 let { t = case e of (x,[y]) -> x `seq` (x,y)
7223       x = fst t
7224       y = snd t }
7225 in b
7226 </programlisting>
7227 The binding is lazy, but when either <literal>x</literal> or <literal>y</literal> is
7228 evaluated by <literal>b</literal> the entire pattern is matched, including forcing the
7229 evaluation of <literal>x</literal>.
7230 </para>
7231 <para>
7232 Bang patterns work in <literal>case</literal> expressions too, of course:
7233 <programlisting>
7234 g5 x = let y = f x in body
7235 g6 x = case f x of { y -&gt; body }
7236 g7 x = case f x of { !y -&gt; body }
7237 </programlisting>
7238 The functions <literal>g5</literal> and <literal>g6</literal> mean exactly the same thing.
7239 But <literal>g7</literal> evaluates <literal>(f x)</literal>, binds <literal>y</literal> to the
7240 result, and then evaluates <literal>body</literal>.
7241 </para>
7242 </sect2>
7243
7244
7245 <sect2 id="bang-patterns-sem">
7246 <title>Syntax and semantics
7247 </title>
7248 <para>
7249
7250 We add a single new production to the syntax of patterns:
7251 <programlisting>
7252   pat ::= !pat
7253 </programlisting>
7254 There is one problem with syntactic ambiguity.  Consider:
7255 <programlisting>
7256 f !x = 3
7257 </programlisting>
7258 Is this a definition of the infix function "<literal>(!)</literal>",
7259 or of the "<literal>f</literal>" with a bang pattern? GHC resolves this
7260 ambiguity in favour of the latter.  If you want to define
7261 <literal>(!)</literal> with bang-patterns enabled, you have to do so using
7262 prefix notation:
7263 <programlisting>
7264 (!) f x = 3
7265 </programlisting>
7266 The semantics of Haskell pattern matching is described in <ulink
7267 url="http://www.haskell.org/onlinereport/exps.html#sect3.17.2">
7268 Section 3.17.2</ulink> of the Haskell Report.  To this description add
7269 one extra item 10, saying:
7270 <itemizedlist><listitem><para>Matching
7271 the pattern <literal>!pat</literal> against a value <literal>v</literal> behaves as follows:
7272 <itemizedlist><listitem><para>if <literal>v</literal> is bottom, the match diverges</para></listitem>
7273                 <listitem><para>otherwise, <literal>pat</literal> is matched against
7274                 <literal>v</literal></para></listitem>
7275 </itemizedlist>
7276 </para></listitem></itemizedlist>
7277 Similarly, in Figure 4 of  <ulink url="http://www.haskell.org/onlinereport/exps.html#sect3.17.3">
7278 Section 3.17.3</ulink>, add a new case (t):
7279 <programlisting>
7280 case v of { !pat -> e; _ -> e' }
7281    = v `seq` case v of { pat -> e; _ -> e' }
7282 </programlisting>
7283 </para><para>
7284 That leaves let expressions, whose translation is given in
7285 <ulink url="http://www.haskell.org/onlinereport/exps.html#sect3.12">Section
7286 3.12</ulink>
7287 of the Haskell Report.
7288 In the translation box, first apply
7289 the following transformation:  for each pattern <literal>pi</literal> that is of
7290 form <literal>!qi = ei</literal>, transform it to <literal>(xi,!qi) = ((),ei)</literal>, and and replace <literal>e0</literal>
7291 by <literal>(xi `seq` e0)</literal>.  Then, when none of the left-hand-side patterns
7292 have a bang at the top, apply the rules in the existing box.
7293 </para>
7294 <para>The effect of the let rule is to force complete matching of the pattern
7295 <literal>qi</literal> before evaluation of the body is begun.  The bang is
7296 retained in the translated form in case <literal>qi</literal> is a variable,
7297 thus:
7298 <programlisting>
7299   let !y = f x in b
7300 </programlisting>
7301
7302 </para>
7303 <para>
7304 The let-binding can be recursive.  However, it is much more common for
7305 the let-binding to be non-recursive, in which case the following law holds:
7306 <literal>(let !p = rhs in body)</literal>
7307      is equivalent to
7308 <literal>(case rhs of !p -> body)</literal>
7309 </para>
7310 <para>
7311 A pattern with a bang at the outermost level is not allowed at the top level of
7312 a module.
7313 </para>
7314 </sect2>
7315 </sect1>
7316
7317 <!-- ==================== ASSERTIONS =================  -->
7318
7319 <sect1 id="assertions">
7320 <title>Assertions
7321 <indexterm><primary>Assertions</primary></indexterm>
7322 </title>
7323
7324 <para>
7325 If you want to make use of assertions in your standard Haskell code, you
7326 could define a function like the following:
7327 </para>
7328
7329 <para>
7330
7331 <programlisting>
7332 assert :: Bool -> a -> a
7333 assert False x = error "assertion failed!"
7334 assert _     x = x
7335 </programlisting>
7336
7337 </para>
7338
7339 <para>
7340 which works, but gives you back a less than useful error message --
7341 an assertion failed, but which and where?
7342 </para>
7343
7344 <para>
7345 One way out is to define an extended <function>assert</function> function which also
7346 takes a descriptive string to include in the error message and
7347 perhaps combine this with the use of a pre-processor which inserts
7348 the source location where <function>assert</function> was used.
7349 </para>
7350
7351 <para>
7352 Ghc offers a helping hand here, doing all of this for you. For every
7353 use of <function>assert</function> in the user's source:
7354 </para>
7355
7356 <para>
7357
7358 <programlisting>
7359 kelvinToC :: Double -> Double
7360 kelvinToC k = assert (k &gt;= 0.0) (k+273.15)
7361 </programlisting>
7362
7363 </para>
7364
7365 <para>
7366 Ghc will rewrite this to also include the source location where the
7367 assertion was made,
7368 </para>
7369
7370 <para>
7371
7372 <programlisting>
7373 assert pred val ==> assertError "Main.hs|15" pred val
7374 </programlisting>
7375
7376 </para>
7377
7378 <para>
7379 The rewrite is only performed by the compiler when it spots
7380 applications of <function>Control.Exception.assert</function>, so you
7381 can still define and use your own versions of
7382 <function>assert</function>, should you so wish. If not, import
7383 <literal>Control.Exception</literal> to make use
7384 <function>assert</function> in your code.
7385 </para>
7386
7387 <para>
7388 GHC ignores assertions when optimisation is turned on with the
7389       <option>-O</option><indexterm><primary><option>-O</option></primary></indexterm> flag.  That is, expressions of the form
7390 <literal>assert pred e</literal> will be rewritten to
7391 <literal>e</literal>.  You can also disable assertions using the
7392       <option>-fignore-asserts</option>
7393       option<indexterm><primary><option>-fignore-asserts</option></primary>
7394       </indexterm>.</para>
7395
7396 <para>
7397 Assertion failures can be caught, see the documentation for the
7398 <literal>Control.Exception</literal> library for the details.
7399 </para>
7400
7401 </sect1>
7402
7403
7404 <!-- =============================== PRAGMAS ===========================  -->
7405
7406   <sect1 id="pragmas">
7407     <title>Pragmas</title>
7408
7409     <indexterm><primary>pragma</primary></indexterm>
7410
7411     <para>GHC supports several pragmas, or instructions to the
7412     compiler placed in the source code.  Pragmas don't normally affect
7413     the meaning of the program, but they might affect the efficiency
7414     of the generated code.</para>
7415
7416     <para>Pragmas all take the form
7417
7418 <literal>{-# <replaceable>word</replaceable> ... #-}</literal>
7419
7420     where <replaceable>word</replaceable> indicates the type of
7421     pragma, and is followed optionally by information specific to that
7422     type of pragma.  Case is ignored in
7423     <replaceable>word</replaceable>.  The various values for
7424     <replaceable>word</replaceable> that GHC understands are described
7425     in the following sections; any pragma encountered with an
7426     unrecognised <replaceable>word</replaceable> is
7427     ignored. The layout rule applies in pragmas, so the closing <literal>#-}</literal>
7428     should start in a column to the right of the opening <literal>{-#</literal>. </para>
7429
7430     <para>Certain pragmas are <emphasis>file-header pragmas</emphasis>:
7431       <itemizedlist>
7432       <listitem><para>
7433           A file-header
7434           pragma must precede the <literal>module</literal> keyword in the file.
7435           </para></listitem>
7436       <listitem><para>
7437       There can be as many file-header pragmas as you please, and they can be
7438       preceded or followed by comments.
7439           </para></listitem>
7440       <listitem><para>
7441       File-header pragmas are read once only, before
7442       pre-processing the file (e.g. with cpp).
7443           </para></listitem>
7444       <listitem><para>
7445          The file-header pragmas are: <literal>{-# LANGUAGE #-}</literal>,
7446         <literal>{-# OPTIONS_GHC #-}</literal>, and
7447         <literal>{-# INCLUDE #-}</literal>.
7448           </para></listitem>
7449       </itemizedlist>
7450       </para>
7451
7452     <sect2 id="language-pragma">
7453       <title>LANGUAGE pragma</title>
7454
7455       <indexterm><primary>LANGUAGE</primary><secondary>pragma</secondary></indexterm>
7456       <indexterm><primary>pragma</primary><secondary>LANGUAGE</secondary></indexterm>
7457
7458       <para>The <literal>LANGUAGE</literal> pragma allows language extensions to be enabled
7459         in a portable way.
7460         It is the intention that all Haskell compilers support the
7461         <literal>LANGUAGE</literal> pragma with the same syntax, although not
7462         all extensions are supported by all compilers, of
7463         course.  The <literal>LANGUAGE</literal> pragma should be used instead
7464         of <literal>OPTIONS_GHC</literal>, if possible.</para>
7465
7466       <para>For example, to enable the FFI and preprocessing with CPP:</para>
7467
7468 <programlisting>{-# LANGUAGE ForeignFunctionInterface, CPP #-}</programlisting>
7469
7470         <para><literal>LANGUAGE</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
7471
7472       <para>Every language extension can also be turned into a command-line flag
7473         by prefixing it with "<literal>-X</literal>"; for example <option>-XForeignFunctionInterface</option>.
7474         (Similarly, all "<literal>-X</literal>" flags can be written as <literal>LANGUAGE</literal> pragmas.
7475       </para>
7476
7477       <para>A list of all supported language extensions can be obtained by invoking
7478         <literal>ghc --supported-languages</literal> (see <xref linkend="modes"/>).</para>
7479
7480       <para>Any extension from the <literal>Extension</literal> type defined in
7481         <ulink
7482           url="&libraryCabalLocation;/Language-Haskell-Extension.html"><literal>Language.Haskell.Extension</literal></ulink>
7483         may be used.  GHC will report an error if any of the requested extensions are not supported.</para>
7484     </sect2>
7485
7486
7487     <sect2 id="options-pragma">
7488       <title>OPTIONS_GHC pragma</title>
7489       <indexterm><primary>OPTIONS_GHC</primary>
7490       </indexterm>
7491       <indexterm><primary>pragma</primary><secondary>OPTIONS_GHC</secondary>
7492       </indexterm>
7493
7494       <para>The <literal>OPTIONS_GHC</literal> pragma is used to specify
7495       additional options that are given to the compiler when compiling
7496       this source file.  See <xref linkend="source-file-options"/> for
7497       details.</para>
7498
7499       <para>Previous versions of GHC accepted <literal>OPTIONS</literal> rather
7500         than <literal>OPTIONS_GHC</literal>, but that is now deprecated.</para>
7501     </sect2>
7502
7503         <para><literal>OPTIONS_GHC</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
7504
7505     <sect2 id="include-pragma">
7506       <title>INCLUDE pragma</title>
7507
7508       <para>The <literal>INCLUDE</literal> used to be necessary for
7509         specifying header files to be included when using the FFI and
7510         compiling via C.  It is no longer required for GHC, but is
7511         accepted (and ignored) for compatibility with other
7512         compilers.</para>
7513     </sect2>
7514
7515     <sect2 id="warning-deprecated-pragma">
7516       <title>WARNING and DEPRECATED pragmas</title>
7517       <indexterm><primary>WARNING</primary></indexterm>
7518       <indexterm><primary>DEPRECATED</primary></indexterm>
7519
7520       <para>The WARNING pragma allows you to attach an arbitrary warning
7521       to a particular function, class, or type.
7522       A DEPRECATED pragma lets you specify that
7523       a particular function, class, or type is deprecated.
7524       There are two ways of using these pragmas.
7525
7526       <itemizedlist>
7527         <listitem>
7528           <para>You can work on an entire module thus:</para>
7529 <programlisting>
7530    module Wibble {-# DEPRECATED "Use Wobble instead" #-} where
7531      ...
7532 </programlisting>
7533       <para>Or:</para>
7534 <programlisting>
7535    module Wibble {-# WARNING "This is an unstable interface." #-} where
7536      ...
7537 </programlisting>
7538           <para>When you compile any module that import
7539           <literal>Wibble</literal>, GHC will print the specified
7540           message.</para>
7541         </listitem>
7542
7543         <listitem>
7544           <para>You can attach a warning to a function, class, type, or data constructor, with the
7545           following top-level declarations:</para>
7546 <programlisting>
7547    {-# DEPRECATED f, C, T "Don't use these" #-}
7548    {-# WARNING unsafePerformIO "This is unsafe; I hope you know what you're doing" #-}
7549 </programlisting>
7550           <para>When you compile any module that imports and uses any
7551           of the specified entities, GHC will print the specified
7552           message.</para>
7553           <para> You can only attach to entities declared at top level in the module
7554           being compiled, and you can only use unqualified names in the list of
7555           entities. A capitalised name, such as <literal>T</literal>
7556           refers to <emphasis>either</emphasis> the type constructor <literal>T</literal>
7557           <emphasis>or</emphasis> the data constructor <literal>T</literal>, or both if
7558           both are in scope.  If both are in scope, there is currently no way to
7559       specify one without the other (c.f. fixities
7560       <xref linkend="infix-tycons"/>).</para>
7561         </listitem>
7562       </itemizedlist>
7563       Warnings and deprecations are not reported for
7564       (a) uses within the defining module, and
7565       (b) uses in an export list.
7566       The latter reduces spurious complaints within a library
7567       in which one module gathers together and re-exports
7568       the exports of several others.
7569       </para>
7570       <para>You can suppress the warnings with the flag
7571       <option>-fno-warn-warnings-deprecations</option>.</para>
7572     </sect2>
7573
7574     <sect2 id="inline-noinline-pragma">
7575       <title>INLINE and NOINLINE pragmas</title>
7576
7577       <para>These pragmas control the inlining of function
7578       definitions.</para>
7579
7580       <sect3 id="inline-pragma">
7581         <title>INLINE pragma</title>
7582         <indexterm><primary>INLINE</primary></indexterm>
7583
7584         <para>GHC (with <option>-O</option>, as always) tries to
7585         inline (or &ldquo;unfold&rdquo;) functions/values that are
7586         &ldquo;small enough,&rdquo; thus avoiding the call overhead
7587         and possibly exposing other more-wonderful optimisations.
7588         Normally, if GHC decides a function is &ldquo;too
7589         expensive&rdquo; to inline, it will not do so, nor will it
7590         export that unfolding for other modules to use.</para>
7591
7592         <para>The sledgehammer you can bring to bear is the
7593         <literal>INLINE</literal><indexterm><primary>INLINE
7594         pragma</primary></indexterm> pragma, used thusly:</para>
7595
7596 <programlisting>
7597 key_function :: Int -> String -> (Bool, Double)
7598 {-# INLINE key_function #-}
7599 </programlisting>
7600
7601         <para>The major effect of an <literal>INLINE</literal> pragma
7602         is to declare a function's &ldquo;cost&rdquo; to be very low.
7603         The normal unfolding machinery will then be very keen to
7604         inline it.  However, an <literal>INLINE</literal> pragma for a
7605         function "<literal>f</literal>" has a number of other effects:
7606 <itemizedlist>
7607 <listitem><para>
7608 No functions are inlined into <literal>f</literal>.  Otherwise
7609 GHC might inline a big function into <literal>f</literal>'s right hand side,
7610 making <literal>f</literal> big; and then inline <literal>f</literal> blindly.
7611 </para></listitem>
7612 <listitem><para>
7613 The float-in, float-out, and common-sub-expression transformations are not
7614 applied to the body of <literal>f</literal>.
7615 </para></listitem>
7616 <listitem><para>
7617 An INLINE function is not worker/wrappered by strictness analysis.
7618 It's going to be inlined wholesale instead.
7619 </para></listitem>
7620 </itemizedlist>
7621 All of these effects are aimed at ensuring that what gets inlined is
7622 exactly what you asked for, no more and no less.
7623 </para>
7624 <para>GHC ensures that inlining cannot go on forever: every mutually-recursive
7625 group is cut by one or more <emphasis>loop breakers</emphasis> that is never inlined
7626 (see <ulink url="http://research.microsoft.com/%7Esimonpj/Papers/inlining/index.htm">
7627 Secrets of the GHC inliner, JFP 12(4) July 2002</ulink>).
7628 GHC tries not to select a function with an INLINE pragma as a loop breaker, but
7629 when there is no choice even an INLINE function can be selected, in which case
7630 the INLINE pragma is ignored.
7631 For example, for a self-recursive function, the loop breaker can only be the function
7632 itself, so an INLINE pragma is always ignored.</para>
7633
7634         <para>Syntactically, an <literal>INLINE</literal> pragma for a
7635         function can be put anywhere its type signature could be
7636         put.</para>
7637
7638         <para><literal>INLINE</literal> pragmas are a particularly
7639         good idea for the
7640         <literal>then</literal>/<literal>return</literal> (or
7641         <literal>bind</literal>/<literal>unit</literal>) functions in
7642         a monad.  For example, in GHC's own
7643         <literal>UniqueSupply</literal> monad code, we have:</para>
7644
7645 <programlisting>
7646 {-# INLINE thenUs #-}
7647 {-# INLINE returnUs #-}
7648 </programlisting>
7649
7650         <para>See also the <literal>NOINLINE</literal> pragma (<xref
7651         linkend="noinline-pragma"/>).</para>
7652
7653         <para>Note: the HBC compiler doesn't like <literal>INLINE</literal> pragmas,
7654           so if you want your code to be HBC-compatible you'll have to surround
7655           the pragma with C pre-processor directives
7656           <literal>#ifdef __GLASGOW_HASKELL__</literal>...<literal>#endif</literal>.</para>
7657
7658       </sect3>
7659
7660       <sect3 id="noinline-pragma">
7661         <title>NOINLINE pragma</title>
7662
7663         <indexterm><primary>NOINLINE</primary></indexterm>
7664         <indexterm><primary>NOTINLINE</primary></indexterm>
7665
7666         <para>The <literal>NOINLINE</literal> pragma does exactly what
7667         you'd expect: it stops the named function from being inlined
7668         by the compiler.  You shouldn't ever need to do this, unless
7669         you're very cautious about code size.</para>
7670
7671         <para><literal>NOTINLINE</literal> is a synonym for
7672         <literal>NOINLINE</literal> (<literal>NOINLINE</literal> is
7673         specified by Haskell 98 as the standard way to disable
7674         inlining, so it should be used if you want your code to be
7675         portable).</para>
7676       </sect3>
7677
7678       <sect3 id="conlike-pragma">
7679         <title>CONLIKE modifier</title>
7680         <indexterm><primary>CONLIKE</primary></indexterm>
7681         <para>An INLINE or NOINLINE pragma may have a CONLIKE modifier,
7682         which affects matching in RULEs (only).  See <xref linkend="conlike"/>.
7683         </para>
7684       </sect3>
7685
7686       <sect3 id="phase-control">
7687         <title>Phase control</title>
7688
7689         <para> Sometimes you want to control exactly when in GHC's
7690         pipeline the INLINE pragma is switched on.  Inlining happens
7691         only during runs of the <emphasis>simplifier</emphasis>.  Each
7692         run of the simplifier has a different <emphasis>phase
7693         number</emphasis>; the phase number decreases towards zero.
7694         If you use <option>-dverbose-core2core</option> you'll see the
7695         sequence of phase numbers for successive runs of the
7696         simplifier.  In an INLINE pragma you can optionally specify a
7697         phase number, thus:
7698         <itemizedlist>
7699           <listitem>
7700             <para>"<literal>INLINE[k] f</literal>" means: do not inline
7701             <literal>f</literal>
7702               until phase <literal>k</literal>, but from phase
7703               <literal>k</literal> onwards be very keen to inline it.
7704             </para></listitem>
7705           <listitem>
7706             <para>"<literal>INLINE[~k] f</literal>" means: be very keen to inline
7707             <literal>f</literal>
7708               until phase <literal>k</literal>, but from phase
7709               <literal>k</literal> onwards do not inline it.
7710             </para></listitem>
7711           <listitem>
7712             <para>"<literal>NOINLINE[k] f</literal>" means: do not inline
7713             <literal>f</literal>
7714               until phase <literal>k</literal>, but from phase
7715               <literal>k</literal> onwards be willing to inline it (as if
7716               there was no pragma).
7717             </para></listitem>
7718             <listitem>
7719             <para>"<literal>NOINLINE[~k] f</literal>" means: be willing to inline
7720             <literal>f</literal>
7721               until phase <literal>k</literal>, but from phase
7722               <literal>k</literal> onwards do not inline it.
7723             </para></listitem>
7724         </itemizedlist>
7725 The same information is summarised here:
7726 <programlisting>
7727                            -- Before phase 2     Phase 2 and later
7728   {-# INLINE   [2]  f #-}  --      No                 Yes
7729   {-# INLINE   [~2] f #-}  --      Yes                No
7730   {-# NOINLINE [2]  f #-}  --      No                 Maybe
7731   {-# NOINLINE [~2] f #-}  --      Maybe              No
7732
7733   {-# INLINE   f #-}       --      Yes                Yes
7734   {-# NOINLINE f #-}       --      No                 No
7735 </programlisting>
7736 By "Maybe" we mean that the usual heuristic inlining rules apply (if the
7737 function body is small, or it is applied to interesting-looking arguments etc).
7738 Another way to understand the semantics is this:
7739 <itemizedlist>
7740 <listitem><para>For both INLINE and NOINLINE, the phase number says
7741 when inlining is allowed at all.</para></listitem>
7742 <listitem><para>The INLINE pragma has the additional effect of making the
7743 function body look small, so that when inlining is allowed it is very likely to
7744 happen.
7745 </para></listitem>
7746 </itemizedlist>
7747 </para>
7748 <para>The same phase-numbering control is available for RULES
7749         (<xref linkend="rewrite-rules"/>).</para>
7750       </sect3>
7751     </sect2>
7752
7753     <sect2 id="annotation-pragmas">
7754       <title>ANN pragmas</title>
7755
7756       <para>GHC offers the ability to annotate various code constructs with additional
7757       data by using three pragmas.  This data can then be inspected at a later date by
7758       using GHC-as-a-library.</para>
7759
7760       <sect3 id="ann-pragma">
7761         <title>Annotating values</title>
7762
7763         <indexterm><primary>ANN</primary></indexterm>
7764
7765         <para>Any expression that has both <literal>Typeable</literal> and <literal>Data</literal> instances may be attached to a top-level value
7766         binding using an <literal>ANN</literal> pragma. In particular, this means you can use <literal>ANN</literal>
7767         to annotate data constructors (e.g. <literal>Just</literal>) as well as normal values (e.g. <literal>take</literal>).
7768         By way of example, to annotate the function <literal>foo</literal> with the annotation <literal>Just "Hello"</literal>
7769         you would do this:</para>
7770
7771 <programlisting>
7772 {-# ANN foo (Just "Hello") #-}
7773 foo = ...
7774 </programlisting>
7775
7776         <para>
7777           A number of restrictions apply to use of annotations:
7778           <itemizedlist>
7779             <listitem><para>The binder being annotated must be at the top level (i.e. no nested binders)</para></listitem>
7780             <listitem><para>The binder being annotated must be declared in the current module</para></listitem>
7781             <listitem><para>The expression you are annotating with must have a type with <literal>Typeable</literal> and <literal>Data</literal> instances</para></listitem>
7782             <listitem><para>The <ulink linkend="using-template-haskell">Template Haskell staging restrictions</ulink> apply to the
7783             expression being annotated with, so for example you cannot run a function from the module being compiled.</para>
7784
7785             <para>To be precise, the annotation <literal>{-# ANN x e #-}</literal> is well staged if and only if <literal>$(e)</literal> would be
7786             (disregarding the usual type restrictions of the splice syntax, and the usual restriction on splicing inside a splice - <literal>$([|1|])</literal> is fine as an annotation, albeit redundant).</para></listitem>
7787           </itemizedlist>
7788
7789           If you feel strongly that any of these restrictions are too onerous, <ulink url="http://hackage.haskell.org/trac/ghc/wiki/MailingListsAndIRC">
7790           please give the GHC team a shout</ulink>.
7791         </para>
7792
7793         <para>However, apart from these restrictions, many things are allowed, including expressions which are not fully evaluated!
7794         Annotation expressions will be evaluated by the compiler just like Template Haskell splices are. So, this annotation is fine:</para>
7795
7796 <programlisting>
7797 {-# ANN f SillyAnnotation { foo = (id 10) + $([| 20 |]), bar = 'f } #-}
7798 f = ...
7799 </programlisting>
7800       </sect3>
7801
7802       <sect3 id="typeann-pragma">
7803         <title>Annotating types</title>
7804
7805         <indexterm><primary>ANN type</primary></indexterm>
7806         <indexterm><primary>ANN</primary></indexterm>
7807
7808         <para>You can annotate types with the <literal>ANN</literal> pragma by using the <literal>type</literal> keyword. For example:</para>
7809
7810 <programlisting>
7811 {-# ANN type Foo (Just "A `Maybe String' annotation") #-}
7812 data Foo = ...
7813 </programlisting>
7814       </sect3>
7815
7816       <sect3 id="modann-pragma">
7817         <title>Annotating modules</title>
7818
7819         <indexterm><primary>ANN module</primary></indexterm>
7820         <indexterm><primary>ANN</primary></indexterm>
7821
7822         <para>You can annotate modules with the <literal>ANN</literal> pragma by using the <literal>module</literal> keyword. For example:</para>
7823
7824 <programlisting>
7825 {-# ANN module (Just "A `Maybe String' annotation") #-}
7826 </programlisting>
7827       </sect3>
7828     </sect2>
7829
7830     <sect2 id="line-pragma">
7831       <title>LINE pragma</title>
7832
7833       <indexterm><primary>LINE</primary><secondary>pragma</secondary></indexterm>
7834       <indexterm><primary>pragma</primary><secondary>LINE</secondary></indexterm>
7835       <para>This pragma is similar to C's <literal>&num;line</literal>
7836       pragma, and is mainly for use in automatically generated Haskell
7837       code.  It lets you specify the line number and filename of the
7838       original code; for example</para>
7839
7840 <programlisting>{-# LINE 42 "Foo.vhs" #-}</programlisting>
7841
7842       <para>if you'd generated the current file from something called
7843       <filename>Foo.vhs</filename> and this line corresponds to line
7844       42 in the original.  GHC will adjust its error messages to refer
7845       to the line/file named in the <literal>LINE</literal>
7846       pragma.</para>
7847     </sect2>
7848
7849     <sect2 id="rules">
7850       <title>RULES pragma</title>
7851
7852       <para>The RULES pragma lets you specify rewrite rules.  It is
7853       described in <xref linkend="rewrite-rules"/>.</para>
7854     </sect2>
7855
7856     <sect2 id="specialize-pragma">
7857       <title>SPECIALIZE pragma</title>
7858
7859       <indexterm><primary>SPECIALIZE pragma</primary></indexterm>
7860       <indexterm><primary>pragma, SPECIALIZE</primary></indexterm>
7861       <indexterm><primary>overloading, death to</primary></indexterm>
7862
7863       <para>(UK spelling also accepted.)  For key overloaded
7864       functions, you can create extra versions (NB: more code space)
7865       specialised to particular types.  Thus, if you have an
7866       overloaded function:</para>
7867
7868 <programlisting>
7869   hammeredLookup :: Ord key => [(key, value)] -> key -> value
7870 </programlisting>
7871
7872       <para>If it is heavily used on lists with
7873       <literal>Widget</literal> keys, you could specialise it as
7874       follows:</para>
7875
7876 <programlisting>
7877   {-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-}
7878 </programlisting>
7879
7880       <para>A <literal>SPECIALIZE</literal> pragma for a function can
7881       be put anywhere its type signature could be put.</para>
7882
7883       <para>A <literal>SPECIALIZE</literal> has the effect of generating
7884       (a) a specialised version of the function and (b) a rewrite rule
7885       (see <xref linkend="rewrite-rules"/>) that rewrites a call to the
7886       un-specialised function into a call to the specialised one.</para>
7887
7888       <para>The type in a SPECIALIZE pragma can be any type that is less
7889         polymorphic than the type of the original function.  In concrete terms,
7890         if the original function is <literal>f</literal> then the pragma
7891 <programlisting>
7892   {-# SPECIALIZE f :: &lt;type&gt; #-}
7893 </programlisting>
7894       is valid if and only if the definition
7895 <programlisting>
7896   f_spec :: &lt;type&gt;
7897   f_spec = f
7898 </programlisting>
7899       is valid.  Here are some examples (where we only give the type signature
7900       for the original function, not its code):
7901 <programlisting>
7902   f :: Eq a => a -> b -> b
7903   {-# SPECIALISE f :: Int -> b -> b #-}
7904
7905   g :: (Eq a, Ix b) => a -> b -> b
7906   {-# SPECIALISE g :: (Eq a) => a -> Int -> Int #-}
7907
7908   h :: Eq a => a -> a -> a
7909   {-# SPECIALISE h :: (Eq a) => [a] -> [a] -> [a] #-}
7910 </programlisting>
7911 The last of these examples will generate a
7912 RULE with a somewhat-complex left-hand side (try it yourself), so it might not fire very
7913 well.  If you use this kind of specialisation, let us know how well it works.
7914 </para>
7915
7916 <para>A <literal>SPECIALIZE</literal> pragma can optionally be followed with a
7917 <literal>INLINE</literal> or <literal>NOINLINE</literal> pragma, optionally
7918 followed by a phase, as described in <xref linkend="inline-noinline-pragma"/>.
7919 The <literal>INLINE</literal> pragma affects the specialised version of the
7920 function (only), and applies even if the function is recursive.  The motivating
7921 example is this:
7922 <programlisting>
7923 -- A GADT for arrays with type-indexed representation
7924 data Arr e where
7925   ArrInt :: !Int -> ByteArray# -> Arr Int
7926   ArrPair :: !Int -> Arr e1 -> Arr e2 -> Arr (e1, e2)
7927
7928 (!:) :: Arr e -> Int -> e
7929 {-# SPECIALISE INLINE (!:) :: Arr Int -> Int -> Int #-}
7930 {-# SPECIALISE INLINE (!:) :: Arr (a, b) -> Int -> (a, b) #-}
7931 (ArrInt _ ba)     !: (I# i) = I# (indexIntArray# ba i)
7932 (ArrPair _ a1 a2) !: i      = (a1 !: i, a2 !: i)
7933 </programlisting>
7934 Here, <literal>(!:)</literal> is a recursive function that indexes arrays
7935 of type <literal>Arr e</literal>.  Consider a call to  <literal>(!:)</literal>
7936 at type <literal>(Int,Int)</literal>.  The second specialisation will fire, and
7937 the specialised function will be inlined.  It has two calls to
7938 <literal>(!:)</literal>,
7939 both at type <literal>Int</literal>.  Both these calls fire the first
7940 specialisation, whose body is also inlined.  The result is a type-based
7941 unrolling of the indexing function.</para>
7942 <para>Warning: you can make GHC diverge by using <literal>SPECIALISE INLINE</literal>
7943 on an ordinarily-recursive function.</para>
7944
7945       <para>Note: In earlier versions of GHC, it was possible to provide your own
7946       specialised function for a given type:
7947
7948 <programlisting>
7949 {-# SPECIALIZE hammeredLookup :: [(Int, value)] -> Int -> value = intLookup #-}
7950 </programlisting>
7951
7952       This feature has been removed, as it is now subsumed by the
7953       <literal>RULES</literal> pragma (see <xref linkend="rule-spec"/>).</para>
7954
7955     </sect2>
7956
7957 <sect2 id="specialize-instance-pragma">
7958 <title>SPECIALIZE instance pragma
7959 </title>
7960
7961 <para>
7962 <indexterm><primary>SPECIALIZE pragma</primary></indexterm>
7963 <indexterm><primary>overloading, death to</primary></indexterm>
7964 Same idea, except for instance declarations.  For example:
7965
7966 <programlisting>
7967 instance (Eq a) => Eq (Foo a) where {
7968    {-# SPECIALIZE instance Eq (Foo [(Int, Bar)]) #-}
7969    ... usual stuff ...
7970  }
7971 </programlisting>
7972 The pragma must occur inside the <literal>where</literal> part
7973 of the instance declaration.
7974 </para>
7975 <para>
7976 Compatible with HBC, by the way, except perhaps in the placement
7977 of the pragma.
7978 </para>
7979
7980 </sect2>
7981
7982     <sect2 id="unpack-pragma">
7983       <title>UNPACK pragma</title>
7984
7985       <indexterm><primary>UNPACK</primary></indexterm>
7986
7987       <para>The <literal>UNPACK</literal> indicates to the compiler
7988       that it should unpack the contents of a constructor field into
7989       the constructor itself, removing a level of indirection.  For
7990       example:</para>
7991
7992 <programlisting>
7993 data T = T {-# UNPACK #-} !Float
7994            {-# UNPACK #-} !Float
7995 </programlisting>
7996
7997       <para>will create a constructor <literal>T</literal> containing
7998       two unboxed floats.  This may not always be an optimisation: if
7999       the <function>T</function> constructor is scrutinised and the
8000       floats passed to a non-strict function for example, they will
8001       have to be reboxed (this is done automatically by the
8002       compiler).</para>
8003
8004       <para>Unpacking constructor fields should only be used in
8005       conjunction with <option>-O</option>, in order to expose
8006       unfoldings to the compiler so the reboxing can be removed as
8007       often as possible.  For example:</para>
8008
8009 <programlisting>
8010 f :: T -&#62; Float
8011 f (T f1 f2) = f1 + f2
8012 </programlisting>
8013
8014       <para>The compiler will avoid reboxing <function>f1</function>
8015       and <function>f2</function> by inlining <function>+</function>
8016       on floats, but only when <option>-O</option> is on.</para>
8017
8018       <para>Any single-constructor data is eligible for unpacking; for
8019       example</para>
8020
8021 <programlisting>
8022 data T = T {-# UNPACK #-} !(Int,Int)
8023 </programlisting>
8024
8025       <para>will store the two <literal>Int</literal>s directly in the
8026       <function>T</function> constructor, by flattening the pair.
8027       Multi-level unpacking is also supported:
8028
8029 <programlisting>
8030 data T = T {-# UNPACK #-} !S
8031 data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
8032 </programlisting>
8033
8034       will store two unboxed <literal>Int&num;</literal>s
8035       directly in the <function>T</function> constructor.  The
8036       unpacker can see through newtypes, too.</para>
8037
8038       <para>If a field cannot be unpacked, you will not get a warning,
8039       so it might be an idea to check the generated code with
8040       <option>-ddump-simpl</option>.</para>
8041
8042       <para>See also the <option>-funbox-strict-fields</option> flag,
8043       which essentially has the effect of adding
8044       <literal>{-#&nbsp;UNPACK&nbsp;#-}</literal> to every strict
8045       constructor field.</para>
8046     </sect2>
8047
8048     <sect2 id="source-pragma">
8049       <title>SOURCE pragma</title>
8050
8051       <indexterm><primary>SOURCE</primary></indexterm>
8052      <para>The <literal>{-# SOURCE #-}</literal> pragma is used only in <literal>import</literal> declarations,
8053      to break a module loop.  It is described in detail in <xref linkend="mutual-recursion"/>.
8054      </para>
8055 </sect2>
8056
8057 </sect1>
8058
8059 <!--  ======================= REWRITE RULES ======================== -->
8060
8061 <sect1 id="rewrite-rules">
8062 <title>Rewrite rules
8063
8064 <indexterm><primary>RULES pragma</primary></indexterm>
8065 <indexterm><primary>pragma, RULES</primary></indexterm>
8066 <indexterm><primary>rewrite rules</primary></indexterm></title>
8067
8068 <para>
8069 The programmer can specify rewrite rules as part of the source program
8070 (in a pragma).
8071 Here is an example:
8072
8073 <programlisting>
8074   {-# RULES
8075   "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
8076     #-}
8077 </programlisting>
8078 </para>
8079 <para>
8080 Use the debug flag <option>-ddump-simpl-stats</option> to see what rules fired.
8081 If you need more information, then <option>-ddump-rule-firings</option> shows you
8082 each individual rule firing in detail.
8083 </para>
8084
8085 <sect2>
8086 <title>Syntax</title>
8087
8088 <para>
8089 From a syntactic point of view:
8090
8091 <itemizedlist>
8092
8093 <listitem>
8094 <para>
8095  There may be zero or more rules in a <literal>RULES</literal> pragma, separated by semicolons (which
8096  may be generated by the layout rule).
8097 </para>
8098 </listitem>
8099
8100 <listitem>
8101 <para>
8102 The layout rule applies in a pragma.
8103 Currently no new indentation level
8104 is set, so if you put several rules in single RULES pragma and wish to use layout to separate them,
8105 you must lay out the starting in the same column as the enclosing definitions.
8106 <programlisting>
8107   {-# RULES
8108   "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
8109   "map/append" forall f xs ys. map f (xs ++ ys) = map f xs ++ map f ys
8110     #-}
8111 </programlisting>
8112 Furthermore, the closing <literal>#-}</literal>
8113 should start in a column to the right of the opening <literal>{-#</literal>.
8114 </para>
8115 </listitem>
8116
8117 <listitem>
8118 <para>
8119  Each rule has a name, enclosed in double quotes.  The name itself has
8120 no significance at all.  It is only used when reporting how many times the rule fired.
8121 </para>
8122 </listitem>
8123
8124 <listitem>
8125 <para>
8126 A rule may optionally have a phase-control number (see <xref linkend="phase-control"/>),
8127 immediately after the name of the rule.  Thus:
8128 <programlisting>
8129   {-# RULES
8130         "map/map" [2]  forall f g xs. map f (map g xs) = map (f.g) xs
8131     #-}
8132 </programlisting>
8133 The "[2]" means that the rule is active in Phase 2 and subsequent phases.  The inverse
8134 notation "[~2]" is also accepted, meaning that the rule is active up to, but not including,
8135 Phase 2.
8136 </para>
8137 </listitem>
8138
8139
8140
8141 <listitem>
8142 <para>
8143  Each variable mentioned in a rule must either be in scope (e.g. <function>map</function>),
8144 or bound by the <literal>forall</literal> (e.g. <function>f</function>, <function>g</function>, <function>xs</function>).  The variables bound by
8145 the <literal>forall</literal> are called the <emphasis>pattern</emphasis> variables.  They are separated
8146 by spaces, just like in a type <literal>forall</literal>.
8147 </para>
8148 </listitem>
8149 <listitem>
8150
8151 <para>
8152  A pattern variable may optionally have a type signature.
8153 If the type of the pattern variable is polymorphic, it <emphasis>must</emphasis> have a type signature.
8154 For example, here is the <literal>foldr/build</literal> rule:
8155
8156 <programlisting>
8157 "fold/build"  forall k z (g::forall b. (a->b->b) -> b -> b) .
8158               foldr k z (build g) = g k z
8159 </programlisting>
8160
8161 Since <function>g</function> has a polymorphic type, it must have a type signature.
8162
8163 </para>
8164 </listitem>
8165 <listitem>
8166
8167 <para>
8168 The left hand side of a rule must consist of a top-level variable applied
8169 to arbitrary expressions.  For example, this is <emphasis>not</emphasis> OK:
8170
8171 <programlisting>
8172 "wrong1"   forall e1 e2.  case True of { True -> e1; False -> e2 } = e1
8173 "wrong2"   forall f.      f True = True
8174 </programlisting>
8175
8176 In <literal>"wrong1"</literal>, the LHS is not an application; in <literal>"wrong2"</literal>, the LHS has a pattern variable
8177 in the head.
8178 </para>
8179 </listitem>
8180 <listitem>
8181
8182 <para>
8183  A rule does not need to be in the same module as (any of) the
8184 variables it mentions, though of course they need to be in scope.
8185 </para>
8186 </listitem>
8187 <listitem>
8188
8189 <para>
8190  All rules are implicitly exported from the module, and are therefore
8191 in force in any module that imports the module that defined the rule, directly
8192 or indirectly.  (That is, if A imports B, which imports C, then C's rules are
8193 in force when compiling A.)  The situation is very similar to that for instance
8194 declarations.
8195 </para>
8196 </listitem>
8197
8198 <listitem>
8199
8200 <para>
8201 Inside a RULE "<literal>forall</literal>" is treated as a keyword, regardless of
8202 any other flag settings.  Furthermore, inside a RULE, the language extension
8203 <option>-XScopedTypeVariables</option> is automatically enabled; see
8204 <xref linkend="scoped-type-variables"/>.
8205 </para>
8206 </listitem>
8207 <listitem>
8208
8209 <para>
8210 Like other pragmas, RULE pragmas are always checked for scope errors, and
8211 are typechecked. Typechecking means that the LHS and RHS of a rule are typechecked,
8212 and must have the same type.  However, rules are only <emphasis>enabled</emphasis>
8213 if the <option>-fenable-rewrite-rules</option> flag is
8214 on (see <xref linkend="rule-semantics"/>).
8215 </para>
8216 </listitem>
8217 </itemizedlist>
8218
8219 </para>
8220
8221 </sect2>
8222
8223 <sect2 id="rule-semantics">
8224 <title>Semantics</title>
8225
8226 <para>
8227 From a semantic point of view:
8228
8229 <itemizedlist>
8230 <listitem>
8231 <para>
8232 Rules are enabled (that is, used during optimisation)
8233 by the <option>-fenable-rewrite-rules</option> flag.
8234 This flag is implied by <option>-O</option>, and may be switched
8235 off (as usual) by <option>-fno-enable-rewrite-rules</option>.
8236 (NB: enabling <option>-fenable-rewrite-rules</option> without <option>-O</option>
8237 may not do what you expect, though, because without <option>-O</option> GHC
8238 ignores all optimisation information in interface files;
8239 see <option>-fignore-interface-pragmas</option>, <xref linkend="options-f"/>.)
8240 Note that <option>-fenable-rewrite-rules</option> is an <emphasis>optimisation</emphasis> flag, and
8241 has no effect on parsing or typechecking.
8242 </para>
8243 </listitem>
8244
8245 <listitem>
8246 <para>
8247  Rules are regarded as left-to-right rewrite rules.
8248 When GHC finds an expression that is a substitution instance of the LHS
8249 of a rule, it replaces the expression by the (appropriately-substituted) RHS.
8250 By "a substitution instance" we mean that the LHS can be made equal to the
8251 expression by substituting for the pattern variables.
8252
8253 </para>
8254 </listitem>
8255 <listitem>
8256
8257 <para>
8258  GHC makes absolutely no attempt to verify that the LHS and RHS
8259 of a rule have the same meaning.  That is undecidable in general, and
8260 infeasible in most interesting cases.  The responsibility is entirely the programmer's!
8261
8262 </para>
8263 </listitem>
8264 <listitem>
8265
8266 <para>
8267  GHC makes no attempt to make sure that the rules are confluent or
8268 terminating.  For example:
8269
8270 <programlisting>
8271   "loop"        forall x y.  f x y = f y x
8272 </programlisting>
8273
8274 This rule will cause the compiler to go into an infinite loop.
8275
8276 </para>
8277 </listitem>
8278 <listitem>
8279
8280 <para>
8281  If more than one rule matches a call, GHC will choose one arbitrarily to apply.
8282
8283 </para>
8284 </listitem>
8285 <listitem>
8286 <para>
8287  GHC currently uses a very simple, syntactic, matching algorithm
8288 for matching a rule LHS with an expression.  It seeks a substitution
8289 which makes the LHS and expression syntactically equal modulo alpha
8290 conversion.  The pattern (rule), but not the expression, is eta-expanded if
8291 necessary.  (Eta-expanding the expression can lead to laziness bugs.)
8292 But not beta conversion (that's called higher-order matching).
8293 </para>
8294
8295 <para>
8296 Matching is carried out on GHC's intermediate language, which includes
8297 type abstractions and applications.  So a rule only matches if the
8298 types match too.  See <xref linkend="rule-spec"/> below.
8299 </para>
8300 </listitem>
8301 <listitem>
8302
8303 <para>
8304  GHC keeps trying to apply the rules as it optimises the program.
8305 For example, consider:
8306
8307 <programlisting>
8308   let s = map f
8309       t = map g
8310   in
8311   s (t xs)
8312 </programlisting>
8313
8314 The expression <literal>s (t xs)</literal> does not match the rule <literal>"map/map"</literal>, but GHC
8315 will substitute for <varname>s</varname> and <varname>t</varname>, giving an expression which does match.
8316 If <varname>s</varname> or <varname>t</varname> was (a) used more than once, and (b) large or a redex, then it would
8317 not be substituted, and the rule would not fire.
8318
8319 </para>
8320 </listitem>
8321 </itemizedlist>
8322
8323 </para>
8324
8325 </sect2>
8326
8327 <sect2 id="conlike">
8328 <title>How rules interact with INLINE/NOINLINE and CONLIKE pragmas</title>
8329
8330 <para>
8331 Ordinary inlining happens at the same time as rule rewriting, which may lead to unexpected
8332 results.  Consider this (artificial) example
8333 <programlisting>
8334 f x = x
8335 g y = f y
8336 h z = g True
8337
8338 {-# RULES "f" f True = False #-}
8339 </programlisting>
8340 Since <literal>f</literal>'s right-hand side is small, it is inlined into <literal>g</literal>,
8341 to give
8342 <programlisting>
8343 g y = y
8344 </programlisting>
8345 Now <literal>g</literal> is inlined into <literal>h</literal>, but <literal>f</literal>'s RULE has
8346 no chance to fire.
8347 If instead GHC had first inlined <literal>g</literal> into <literal>h</literal> then there
8348 would have been a better chance that <literal>f</literal>'s RULE might fire.
8349 </para>
8350 <para>
8351 The way to get predictable behaviour is to use a NOINLINE
8352 pragma, or an INLINE[<replaceable>phase</replaceable>] pragma, on <literal>f</literal>, to ensure
8353 that it is not inlined until its RULEs have had a chance to fire.
8354 </para>
8355 <para>
8356 GHC is very cautious about duplicating work.  For example, consider
8357 <programlisting>
8358 f k z xs = let xs = build g
8359            in ...(foldr k z xs)...sum xs...
8360 {-# RULES "foldr/build" forall k z g. foldr k z (build g) = g k z #-}
8361 </programlisting>
8362 Since <literal>xs</literal> is used twice, GHC does not fire the foldr/build rule.  Rightly
8363 so, because it might take a lot of work to compute <literal>xs</literal>, which would be
8364 duplicated if the rule fired.
8365 </para>
8366 <para>
8367 Sometimes, however, this approach is over-cautious, and we <emphasis>do</emphasis> want the
8368 rule to fire, even though doing so would duplicate redex.  There is no way that GHC can work out
8369 when this is a good idea, so we provide the CONLIKE pragma to declare it, thus:
8370 <programlisting>
8371 {-# INLINE[1] CONLIKE f #-}
8372 f x = <replaceable>blah</replaceable>
8373 </programlisting>
8374 CONLIKE is a modifier to an INLINE or NOINLINE pragam.  It specifies that an application
8375 of f to one argument (in general, the number of arguments to the left of the '=' sign)
8376 should be considered cheap enough to duplicate, if such a duplication would make rule
8377 fire.  (The name "CONLIKE" is short for "constructor-like", because constructors certainly
8378 have such a property.)
8379 The CONLIKE pragam is a modifier to INLINE/NOINLINE because it really only makes sense to match
8380 <literal>f</literal> on the LHS of a rule if you are sure that <literal>f</literal> is
8381 not going to be inlined before the rule has a chance to fire.
8382 </para>
8383 </sect2>
8384
8385 <sect2>
8386 <title>List fusion</title>
8387
8388 <para>
8389 The RULES mechanism is used to implement fusion (deforestation) of common list functions.
8390 If a "good consumer" consumes an intermediate list constructed by a "good producer", the
8391 intermediate list should be eliminated entirely.
8392 </para>
8393
8394 <para>
8395 The following are good producers:
8396
8397 <itemizedlist>
8398 <listitem>
8399
8400 <para>
8401  List comprehensions
8402 </para>
8403 </listitem>
8404 <listitem>
8405
8406 <para>
8407  Enumerations of <literal>Int</literal> and <literal>Char</literal> (e.g. <literal>['a'..'z']</literal>).
8408 </para>
8409 </listitem>
8410 <listitem>
8411
8412 <para>
8413  Explicit lists (e.g. <literal>[True, False]</literal>)
8414 </para>
8415 </listitem>
8416 <listitem>
8417
8418 <para>
8419  The cons constructor (e.g <literal>3:4:[]</literal>)
8420 </para>
8421 </listitem>
8422 <listitem>
8423
8424 <para>
8425  <function>++</function>
8426 </para>
8427 </listitem>
8428
8429 <listitem>
8430 <para>
8431  <function>map</function>
8432 </para>
8433 </listitem>
8434
8435 <listitem>
8436 <para>
8437 <function>take</function>, <function>filter</function>
8438 </para>
8439 </listitem>
8440 <listitem>
8441
8442 <para>
8443  <function>iterate</function>, <function>repeat</function>
8444 </para>
8445 </listitem>
8446 <listitem>
8447
8448 <para>
8449  <function>zip</function>, <function>zipWith</function>
8450 </para>
8451 </listitem>
8452
8453 </itemizedlist>
8454
8455 </para>
8456
8457 <para>
8458 The following are good consumers:
8459
8460 <itemizedlist>
8461 <listitem>
8462
8463 <para>
8464  List comprehensions
8465 </para>
8466 </listitem>
8467 <listitem>
8468
8469 <para>
8470  <function>array</function> (on its second argument)
8471 </para>
8472 </listitem>
8473 <listitem>
8474
8475 <para>
8476  <function>++</function> (on its first argument)
8477 </para>
8478 </listitem>
8479
8480 <listitem>
8481 <para>
8482  <function>foldr</function>
8483 </para>
8484 </listitem>
8485
8486 <listitem>
8487 <para>
8488  <function>map</function>
8489 </para>
8490 </listitem>
8491 <listitem>
8492
8493 <para>
8494 <function>take</function>, <function>filter</function>
8495 </para>
8496 </listitem>
8497 <listitem>
8498
8499 <para>
8500  <function>concat</function>
8501 </para>
8502 </listitem>
8503 <listitem>
8504
8505 <para>
8506  <function>unzip</function>, <function>unzip2</function>, <function>unzip3</function>, <function>unzip4</function>
8507 </para>
8508 </listitem>
8509 <listitem>
8510
8511 <para>
8512  <function>zip</function>, <function>zipWith</function> (but on one argument only; if both are good producers, <function>zip</function>
8513 will fuse with one but not the other)
8514 </para>
8515 </listitem>
8516 <listitem>
8517
8518 <para>
8519  <function>partition</function>
8520 </para>
8521 </listitem>
8522 <listitem>
8523
8524 <para>
8525  <function>head</function>
8526 </para>
8527 </listitem>
8528 <listitem>
8529
8530 <para>
8531  <function>and</function>, <function>or</function>, <function>any</function>, <function>all</function>
8532 </para>
8533 </listitem>
8534 <listitem>
8535
8536 <para>
8537  <function>sequence&lowbar;</function>
8538 </para>
8539 </listitem>
8540 <listitem>
8541
8542 <para>
8543  <function>msum</function>
8544 </para>
8545 </listitem>
8546 <listitem>
8547
8548 <para>
8549  <function>sortBy</function>
8550 </para>
8551 </listitem>
8552
8553 </itemizedlist>
8554
8555 </para>
8556
8557  <para>
8558 So, for example, the following should generate no intermediate lists:
8559
8560 <programlisting>
8561 array (1,10) [(i,i*i) | i &#60;- map (+ 1) [0..9]]
8562 </programlisting>
8563
8564 </para>
8565
8566 <para>
8567 This list could readily be extended; if there are Prelude functions that you use
8568 a lot which are not included, please tell us.
8569 </para>
8570
8571 <para>
8572 If you want to write your own good consumers or producers, look at the
8573 Prelude definitions of the above functions to see how to do so.
8574 </para>
8575
8576 </sect2>
8577
8578 <sect2 id="rule-spec">
8579 <title>Specialisation
8580 </title>
8581
8582 <para>
8583 Rewrite rules can be used to get the same effect as a feature
8584 present in earlier versions of GHC.
8585 For example, suppose that:
8586
8587 <programlisting>
8588 genericLookup :: Ord a => Table a b   -> a   -> b
8589 intLookup     ::          Table Int b -> Int -> b
8590 </programlisting>
8591
8592 where <function>intLookup</function> is an implementation of
8593 <function>genericLookup</function> that works very fast for
8594 keys of type <literal>Int</literal>.  You might wish
8595 to tell GHC to use <function>intLookup</function> instead of
8596 <function>genericLookup</function> whenever the latter was called with
8597 type <literal>Table Int b -&gt; Int -&gt; b</literal>.
8598 It used to be possible to write
8599
8600 <programlisting>
8601 {-# SPECIALIZE genericLookup :: Table Int b -> Int -> b = intLookup #-}
8602 </programlisting>
8603
8604 This feature is no longer in GHC, but rewrite rules let you do the same thing:
8605
8606 <programlisting>
8607 {-# RULES "genericLookup/Int" genericLookup = intLookup #-}
8608 </programlisting>
8609
8610 This slightly odd-looking rule instructs GHC to replace
8611 <function>genericLookup</function> by <function>intLookup</function>
8612 <emphasis>whenever the types match</emphasis>.
8613 What is more, this rule does not need to be in the same
8614 file as <function>genericLookup</function>, unlike the
8615 <literal>SPECIALIZE</literal> pragmas which currently do (so that they
8616 have an original definition available to specialise).
8617 </para>
8618
8619 <para>It is <emphasis>Your Responsibility</emphasis> to make sure that
8620 <function>intLookup</function> really behaves as a specialised version
8621 of <function>genericLookup</function>!!!</para>
8622
8623 <para>An example in which using <literal>RULES</literal> for
8624 specialisation will Win Big:
8625
8626 <programlisting>
8627 toDouble :: Real a => a -> Double
8628 toDouble = fromRational . toRational
8629
8630 {-# RULES "toDouble/Int" toDouble = i2d #-}
8631 i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly
8632 </programlisting>
8633
8634 The <function>i2d</function> function is virtually one machine
8635 instruction; the default conversion&mdash;via an intermediate
8636 <literal>Rational</literal>&mdash;is obscenely expensive by
8637 comparison.
8638 </para>
8639
8640 </sect2>
8641
8642 <sect2 id="controlling-rules">
8643 <title>Controlling what's going on in rewrite rules</title>
8644
8645 <para>
8646
8647 <itemizedlist>
8648 <listitem>
8649
8650 <para>
8651 Use <option>-ddump-rules</option> to see the rules that are defined
8652 <emphasis>in this module</emphasis>.
8653 This includes rules generated by the specialisation pass, but excludes
8654 rules imported from other modules.
8655 </para>
8656 </listitem>
8657
8658 <listitem>
8659 <para>
8660  Use <option>-ddump-simpl-stats</option> to see what rules are being fired.
8661 If you add <option>-dppr-debug</option> you get a more detailed listing.
8662 </para>
8663 </listitem>
8664
8665 <listitem>
8666 <para>
8667  Use <option>-ddump-rule-firings</option> to see in great detail what rules are being fired.
8668 If you add <option>-dppr-debug</option> you get a still more detailed listing.
8669 </para>
8670 </listitem>
8671
8672 <listitem>
8673 <para>
8674  The definition of (say) <function>build</function> in <filename>GHC/Base.lhs</filename> looks like this:
8675
8676 <programlisting>
8677         build   :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
8678         {-# INLINE build #-}
8679         build g = g (:) []
8680 </programlisting>
8681
8682 Notice the <literal>INLINE</literal>!  That prevents <literal>(:)</literal> from being inlined when compiling
8683 <literal>PrelBase</literal>, so that an importing module will &ldquo;see&rdquo; the <literal>(:)</literal>, and can
8684 match it on the LHS of a rule.  <literal>INLINE</literal> prevents any inlining happening
8685 in the RHS of the <literal>INLINE</literal> thing.  I regret the delicacy of this.
8686
8687 </para>
8688 </listitem>
8689 <listitem>
8690
8691 <para>
8692  In <filename>libraries/base/GHC/Base.lhs</filename> look at the rules for <function>map</function> to
8693 see how to write rules that will do fusion and yet give an efficient
8694 program even if fusion doesn't happen.  More rules in <filename>GHC/List.lhs</filename>.
8695 </para>
8696 </listitem>
8697
8698 </itemizedlist>
8699
8700 </para>
8701
8702 </sect2>
8703
8704 <sect2 id="core-pragma">
8705   <title>CORE pragma</title>
8706
8707   <indexterm><primary>CORE pragma</primary></indexterm>
8708   <indexterm><primary>pragma, CORE</primary></indexterm>
8709   <indexterm><primary>core, annotation</primary></indexterm>
8710
8711 <para>
8712   The external core format supports <quote>Note</quote> annotations;
8713   the <literal>CORE</literal> pragma gives a way to specify what these
8714   should be in your Haskell source code.  Syntactically, core
8715   annotations are attached to expressions and take a Haskell string
8716   literal as an argument.  The following function definition shows an
8717   example:
8718
8719 <programlisting>
8720 f x = ({-# CORE "foo" #-} show) ({-# CORE "bar" #-} x)
8721 </programlisting>
8722
8723   Semantically, this is equivalent to:
8724
8725 <programlisting>
8726 g x = show x
8727 </programlisting>
8728 </para>
8729
8730 <para>
8731   However, when external core is generated (via
8732   <option>-fext-core</option>), there will be Notes attached to the
8733   expressions <function>show</function> and <varname>x</varname>.
8734   The core function declaration for <function>f</function> is:
8735 </para>
8736
8737 <programlisting>
8738   f :: %forall a . GHCziShow.ZCTShow a ->
8739                    a -> GHCziBase.ZMZN GHCziBase.Char =
8740     \ @ a (zddShow::GHCziShow.ZCTShow a) (eta::a) ->
8741         (%note "foo"
8742          %case zddShow %of (tpl::GHCziShow.ZCTShow a)
8743            {GHCziShow.ZCDShow
8744             (tpl1::GHCziBase.Int ->
8745                    a ->
8746                    GHCziBase.ZMZN GHCziBase.Char -> GHCziBase.ZMZN GHCziBase.Cha
8747 r)
8748             (tpl2::a -> GHCziBase.ZMZN GHCziBase.Char)
8749             (tpl3::GHCziBase.ZMZN a ->
8750                    GHCziBase.ZMZN GHCziBase.Char -> GHCziBase.ZMZN GHCziBase.Cha
8751 r) ->
8752               tpl2})
8753         (%note "bar"
8754          eta);
8755 </programlisting>
8756
8757 <para>
8758   Here, we can see that the function <function>show</function> (which
8759   has been expanded out to a case expression over the Show dictionary)
8760   has a <literal>%note</literal> attached to it, as does the
8761   expression <varname>eta</varname> (which used to be called
8762   <varname>x</varname>).
8763 </para>
8764
8765 </sect2>
8766
8767 </sect1>
8768
8769 <sect1 id="special-ids">
8770 <title>Special built-in functions</title>
8771 <para>GHC has a few built-in functions with special behaviour.  These
8772 are now described in the module <ulink
8773 url="&libraryGhcPrimLocation;/GHC-Prim.html"><literal>GHC.Prim</literal></ulink>
8774 in the library documentation.</para>
8775 </sect1>
8776
8777
8778 <sect1 id="generic-classes">
8779 <title>Generic classes</title>
8780
8781 <para>
8782 The ideas behind this extension are described in detail in "Derivable type classes",
8783 Ralf Hinze and Simon Peyton Jones, Haskell Workshop, Montreal Sept 2000, pp94-105.
8784 An example will give the idea:
8785 </para>
8786
8787 <programlisting>
8788   import Generics
8789
8790   class Bin a where
8791     toBin   :: a -> [Int]
8792     fromBin :: [Int] -> (a, [Int])
8793
8794     toBin {| Unit |}    Unit      = []
8795     toBin {| a :+: b |} (Inl x)   = 0 : toBin x
8796     toBin {| a :+: b |} (Inr y)   = 1 : toBin y
8797     toBin {| a :*: b |} (x :*: y) = toBin x ++ toBin y
8798
8799     fromBin {| Unit |}    bs      = (Unit, bs)
8800     fromBin {| a :+: b |} (0:bs)  = (Inl x, bs')    where (x,bs') = fromBin bs
8801     fromBin {| a :+: b |} (1:bs)  = (Inr y, bs')    where (y,bs') = fromBin bs
8802     fromBin {| a :*: b |} bs      = (x :*: y, bs'') where (x,bs' ) = fromBin bs
8803                                                           (y,bs'') = fromBin bs'
8804 </programlisting>
8805 <para>
8806 This class declaration explains how <literal>toBin</literal> and <literal>fromBin</literal>
8807 work for arbitrary data types.  They do so by giving cases for unit, product, and sum,
8808 which are defined thus in the library module <literal>Generics</literal>:
8809 </para>
8810 <programlisting>
8811   data Unit    = Unit
8812   data a :+: b = Inl a | Inr b
8813   data a :*: b = a :*: b
8814 </programlisting>
8815 <para>
8816 Now you can make a data type into an instance of Bin like this:
8817 <programlisting>
8818   instance (Bin a, Bin b) => Bin (a,b)
8819   instance Bin a => Bin [a]
8820 </programlisting>
8821 That is, just leave off the "where" clause.  Of course, you can put in the
8822 where clause and over-ride whichever methods you please.
8823 </para>
8824
8825     <sect2>
8826       <title> Using generics </title>
8827       <para>To use generics you need to</para>
8828       <itemizedlist>
8829         <listitem>
8830           <para>Use the flags <option>-fglasgow-exts</option> (to enable the extra syntax),
8831                 <option>-XGenerics</option> (to generate extra per-data-type code),
8832                 and <option>-package lang</option> (to make the <literal>Generics</literal> library
8833                 available.  </para>
8834         </listitem>
8835         <listitem>
8836           <para>Import the module <literal>Generics</literal> from the
8837           <literal>lang</literal> package.  This import brings into
8838           scope the data types <literal>Unit</literal>,
8839           <literal>:*:</literal>, and <literal>:+:</literal>.  (You
8840           don't need this import if you don't mention these types
8841           explicitly; for example, if you are simply giving instance
8842           declarations.)</para>
8843         </listitem>
8844       </itemizedlist>
8845     </sect2>
8846
8847 <sect2> <title> Changes wrt the paper </title>
8848 <para>
8849 Note that the type constructors <literal>:+:</literal> and <literal>:*:</literal>
8850 can be written infix (indeed, you can now use
8851 any operator starting in a colon as an infix type constructor).  Also note that
8852 the type constructors are not exactly as in the paper (Unit instead of 1, etc).
8853 Finally, note that the syntax of the type patterns in the class declaration
8854 uses "<literal>{|</literal>" and "<literal>|}</literal>" brackets; curly braces
8855 alone would ambiguous when they appear on right hand sides (an extension we
8856 anticipate wanting).
8857 </para>
8858 </sect2>
8859
8860 <sect2> <title>Terminology and restrictions</title>
8861 <para>
8862 Terminology.  A "generic default method" in a class declaration
8863 is one that is defined using type patterns as above.
8864 A "polymorphic default method" is a default method defined as in Haskell 98.
8865 A "generic class declaration" is a class declaration with at least one
8866 generic default method.
8867 </para>
8868
8869 <para>
8870 Restrictions:
8871 <itemizedlist>
8872 <listitem>
8873 <para>
8874 Alas, we do not yet implement the stuff about constructor names and
8875 field labels.
8876 </para>
8877 </listitem>
8878
8879 <listitem>
8880 <para>
8881 A generic class can have only one parameter; you can't have a generic
8882 multi-parameter class.
8883 </para>
8884 </listitem>
8885
8886 <listitem>
8887 <para>
8888 A default method must be defined entirely using type patterns, or entirely
8889 without.  So this is illegal:
8890 <programlisting>
8891   class Foo a where
8892     op :: a -> (a, Bool)
8893     op {| Unit |} Unit = (Unit, True)
8894     op x               = (x,    False)
8895 </programlisting>
8896 However it is perfectly OK for some methods of a generic class to have
8897 generic default methods and others to have polymorphic default methods.
8898 </para>
8899 </listitem>
8900
8901 <listitem>
8902 <para>
8903 The type variable(s) in the type pattern for a generic method declaration
8904 scope over the right hand side.  So this is legal (note the use of the type variable ``p'' in a type signature on the right hand side:
8905 <programlisting>
8906   class Foo a where
8907     op :: a -> Bool
8908     op {| p :*: q |} (x :*: y) = op (x :: p)
8909     ...
8910 </programlisting>
8911 </para>
8912 </listitem>
8913
8914 <listitem>
8915 <para>
8916 The type patterns in a generic default method must take one of the forms:
8917 <programlisting>
8918        a :+: b
8919        a :*: b
8920        Unit
8921 </programlisting>
8922 where "a" and "b" are type variables.  Furthermore, all the type patterns for
8923 a single type constructor (<literal>:*:</literal>, say) must be identical; they
8924 must use the same type variables.  So this is illegal:
8925 <programlisting>
8926   class Foo a where
8927     op :: a -> Bool
8928     op {| a :+: b |} (Inl x) = True
8929     op {| p :+: q |} (Inr y) = False
8930 </programlisting>
8931 The type patterns must be identical, even in equations for different methods of the class.
8932 So this too is illegal:
8933 <programlisting>
8934   class Foo a where
8935     op1 :: a -> Bool
8936     op1 {| a :*: b |} (x :*: y) = True
8937
8938     op2 :: a -> Bool
8939     op2 {| p :*: q |} (x :*: y) = False
8940 </programlisting>
8941 (The reason for this restriction is that we gather all the equations for a particular type constructor
8942 into a single generic instance declaration.)
8943 </para>
8944 </listitem>
8945
8946 <listitem>
8947 <para>
8948 A generic method declaration must give a case for each of the three type constructors.
8949 </para>
8950 </listitem>
8951
8952 <listitem>
8953 <para>
8954 The type for a generic method can be built only from:
8955   <itemizedlist>
8956   <listitem> <para> Function arrows </para> </listitem>
8957   <listitem> <para> Type variables </para> </listitem>
8958   <listitem> <para> Tuples </para> </listitem>
8959   <listitem> <para> Arbitrary types not involving type variables </para> </listitem>
8960   </itemizedlist>
8961 Here are some example type signatures for generic methods:
8962 <programlisting>
8963     op1 :: a -> Bool
8964     op2 :: Bool -> (a,Bool)
8965     op3 :: [Int] -> a -> a
8966     op4 :: [a] -> Bool
8967 </programlisting>
8968 Here, op1, op2, op3 are OK, but op4 is rejected, because it has a type variable
8969 inside a list.
8970 </para>
8971 <para>
8972 This restriction is an implementation restriction: we just haven't got around to
8973 implementing the necessary bidirectional maps over arbitrary type constructors.
8974 It would be relatively easy to add specific type constructors, such as Maybe and list,
8975 to the ones that are allowed.</para>
8976 </listitem>
8977
8978 <listitem>
8979 <para>
8980 In an instance declaration for a generic class, the idea is that the compiler
8981 will fill in the methods for you, based on the generic templates.  However it can only
8982 do so if
8983   <itemizedlist>
8984   <listitem>
8985   <para>
8986   The instance type is simple (a type constructor applied to type variables, as in Haskell 98).
8987   </para>
8988   </listitem>
8989   <listitem>
8990   <para>
8991   No constructor of the instance type has unboxed fields.
8992   </para>
8993   </listitem>
8994   </itemizedlist>
8995 (Of course, these things can only arise if you are already using GHC extensions.)
8996 However, you can still give an instance declarations for types which break these rules,
8997 provided you give explicit code to override any generic default methods.
8998 </para>
8999 </listitem>
9000
9001 </itemizedlist>
9002 </para>
9003
9004 <para>
9005 The option <option>-ddump-deriv</option> dumps incomprehensible stuff giving details of
9006 what the compiler does with generic declarations.
9007 </para>
9008
9009 </sect2>
9010
9011 <sect2> <title> Another example </title>
9012 <para>
9013 Just to finish with, here's another example I rather like:
9014 <programlisting>
9015   class Tag a where
9016     nCons :: a -> Int
9017     nCons {| Unit |}    _ = 1
9018     nCons {| a :*: b |} _ = 1
9019     nCons {| a :+: b |} _ = nCons (bot::a) + nCons (bot::b)
9020
9021     tag :: a -> Int
9022     tag {| Unit |}    _       = 1
9023     tag {| a :*: b |} _       = 1
9024     tag {| a :+: b |} (Inl x) = tag x
9025     tag {| a :+: b |} (Inr y) = nCons (bot::a) + tag y
9026 </programlisting>
9027 </para>
9028 </sect2>
9029 </sect1>
9030
9031 <sect1 id="monomorphism">
9032 <title>Control over monomorphism</title>
9033
9034 <para>GHC supports two flags that control the way in which generalisation is
9035 carried out at let and where bindings.
9036 </para>
9037
9038 <sect2>
9039 <title>Switching off the dreaded Monomorphism Restriction</title>
9040           <indexterm><primary><option>-XNoMonomorphismRestriction</option></primary></indexterm>
9041
9042 <para>Haskell's monomorphism restriction (see
9043 <ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.5">Section
9044 4.5.5</ulink>
9045 of the Haskell Report)
9046 can be completely switched off by
9047 <option>-XNoMonomorphismRestriction</option>.
9048 </para>
9049 </sect2>
9050
9051 <sect2>
9052 <title>Monomorphic pattern bindings</title>
9053           <indexterm><primary><option>-XNoMonoPatBinds</option></primary></indexterm>
9054           <indexterm><primary><option>-XMonoPatBinds</option></primary></indexterm>
9055
9056           <para> As an experimental change, we are exploring the possibility of
9057           making pattern bindings monomorphic; that is, not generalised at all.
9058             A pattern binding is a binding whose LHS has no function arguments,
9059             and is not a simple variable.  For example:
9060 <programlisting>
9061   f x = x                    -- Not a pattern binding
9062   f = \x -> x                -- Not a pattern binding
9063   f :: Int -> Int = \x -> x  -- Not a pattern binding
9064
9065   (g,h) = e                  -- A pattern binding
9066   (f) = e                    -- A pattern binding
9067   [x] = e                    -- A pattern binding
9068 </programlisting>
9069 Experimentally, GHC now makes pattern bindings monomorphic <emphasis>by
9070 default</emphasis>.  Use <option>-XNoMonoPatBinds</option> to recover the
9071 standard behaviour.
9072 </para>
9073 </sect2>
9074 </sect1>
9075
9076
9077
9078 <!-- Emacs stuff:
9079      ;;; Local Variables: ***
9080      ;;; mode: xml ***
9081      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
9082      ;;; ispell-local-dictionary: "british" ***
9083      ;;; End: ***
9084  -->
9085