Remove outdated link to OGI webpage

[ghc-hetmet.git] / docs / users_guide / glasgow_exts.xml

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 656d2db..42c3fb8 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -52,263 +52,53 @@ documentation</ulink> describes all the libraries that come with GHC.
    <para> Language options recognised by Cabal can also be enabled using the <literal>LANGUAGE</literal> pragma,
    thus <literal>{-# LANGUAGE TemplateHaskell #-}</literal> (see <xref linkend="language-pragma"/>>). </para>
 
    <para> Language options recognised by Cabal can also be enabled using the <literal>LANGUAGE</literal> pragma,
    thus <literal>{-# LANGUAGE TemplateHaskell #-}</literal> (see <xref linkend="language-pragma"/>>). </para>
 

-    <para>Turning on an option that enables special syntax
-    <emphasis>might</emphasis> cause working Haskell 98 code to fail
-    to compile, perhaps because it uses a variable name which has
-    become a reserved word.  So, together with each option below, we
-    list the special syntax which is enabled by this option.  We use
-    notation and nonterminal names from the Haskell 98 lexical syntax
-    (see the Haskell 98 Report).  There are two classes of special
-    syntax:</para>
-
-    <itemizedlist>
-      <listitem>
-       <para>New reserved words and symbols: character sequences
-        which are no longer available for use as identifiers in the
-        program.</para>
-      </listitem>
-      <listitem>
-       <para>Other special syntax: sequences of characters that have
-       a different meaning when this particular option is turned
-       on.</para>
-      </listitem>
-    </itemizedlist>
-
-    <para>We are only listing syntax changes here that might affect
-    existing working programs (i.e. "stolen" syntax).  Many of these
-    extensions will also enable new context-free syntax, but in all
-    cases programs written to use the new syntax would not be
-    compilable without the option enabled.</para>
-
-    <variablelist>
-
-      <varlistentry>
-       <term>
-          <option>-fglasgow-exts</option>:
+    <para>The flag <option>-fglasgow-exts</option>

           <indexterm><primary><option>-fglasgow-exts</option></primary></indexterm>
           <indexterm><primary><option>-fglasgow-exts</option></primary></indexterm>

-        </term>
-       <listitem>
-         <para>This simultaneously enables all of the extensions to
-          Haskell 98 described in <xref
-          linkend="ghc-language-features"/>, except where otherwise
-          noted. We are trying to move away from this portmanteau flag, 
+         is equivalent to enabling the following extensions: 
+          <option>-XPrintExplicitForalls</option>,
+          <option>-XForeignFunctionInterface</option>,
+          <option>-XUnliftedFFITypes</option>,
+          <option>-XGADTs</option>,
+          <option>-XImplicitParams</option>,
+          <option>-XScopedTypeVariables</option>,
+          <option>-XUnboxedTuples</option>,
+          <option>-XTypeSynonymInstances</option>,
+          <option>-XStandaloneDeriving</option>,
+          <option>-XDeriveDataTypeable</option>,
+          <option>-XFlexibleContexts</option>,
+          <option>-XFlexibleInstances</option>,
+          <option>-XConstrainedClassMethods</option>,
+          <option>-XMultiParamTypeClasses</option>,
+          <option>-XFunctionalDependencies</option>,
+          <option>-XMagicHash</option>,
+          <option>-XPolymorphicComponents</option>,
+          <option>-XExistentialQuantification</option>,
+          <option>-XUnicodeSyntax</option>,
+          <option>-XPostfixOperators</option>,
+          <option>-XPatternGuards</option>,
+          <option>-XLiberalTypeSynonyms</option>,
+          <option>-XRankNTypes</option>,
+          <option>-XImpredicativeTypes</option>,
+          <option>-XTypeOperators</option>,
+          <option>-XRecursiveDo</option>,
+          <option>-XParallelListComp</option>,
+          <option>-XEmptyDataDecls</option>,
+          <option>-XKindSignatures</option>,
+          <option>-XGeneralizedNewtypeDeriving</option>,
+          <option>-XTypeFamilies</option>.
+           Enabling these options is the <emphasis>only</emphasis> 
+           effect of <options>-fglasgow-exts</options>.
+          We are trying to move away from this portmanteau flag, 

          and towards enabling features individually.</para>
 
          and towards enabling features individually.</para>
 

-         <para>New reserved words: <literal>forall</literal> (only in
-         types), <literal>mdo</literal>.</para>
-
-         <para>Other syntax stolen:
-             <replaceable>varid</replaceable>{<literal>&num;</literal>},
-             <replaceable>char</replaceable><literal>&num;</literal>,      
-             <replaceable>string</replaceable><literal>&num;</literal>,    
-             <replaceable>integer</replaceable><literal>&num;</literal>,    
-             <replaceable>float</replaceable><literal>&num;</literal>,    
-             <replaceable>float</replaceable><literal>&num;&num;</literal>,    
-             <literal>(&num;</literal>, <literal>&num;)</literal>,         
-             <literal>|)</literal>, <literal>{|</literal>.</para>
-
-         <para>Implies these specific language options: 
-           <option>-XForeignFunctionInterface</option>,
-           <option>-XImplicitParams</option>,
-           <option>-XScopedTypeVariables</option>,
-           <option>-XGADTs</option>, 
-           <option>-XTypeFamilies</option>. </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-XForeignFunctionInterface</option>:
-          <indexterm><primary><option>-XForeignFunctionInterface</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>This option enables the language extension defined in the
-         Haskell 98 Foreign Function Interface Addendum.</para>
-
-         <para>New reserved words: <literal>foreign</literal>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-XMonomorphismRestriction</option>,<option>-XMonoPatBinds</option>:
-        </term>
-       <listitem>
-         <para> These two flags control how generalisation is done.
-           See <xref linkend="monomorphism"/>.
-          </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-XExtendedDefaultRules</option>:
-          <indexterm><primary><option>-XExtendedDefaultRules</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para> Use GHCi's extended default rules in a regular module (<xref linkend="extended-default-rules"/>).
-          Independent of the <option>-fglasgow-exts</option>
-          flag. </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-XOverlappingInstances</option>
-          <indexterm><primary><option>-XOverlappingInstances</option></primary></indexterm>
-        </term>
-       <term>
-          <option>-XUndecidableInstances</option>
-          <indexterm><primary><option>-XUndecidableInstances</option></primary></indexterm>
-        </term>
-       <term>
-          <option>-XIncoherentInstances</option>
-          <indexterm><primary><option>-XIncoherentInstances</option></primary></indexterm>
-        </term>
-       <term>
-          <option>-fcontext-stack=N</option>
-          <indexterm><primary><option>-fcontext-stack</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para> See <xref linkend="instance-decls"/>.  Only relevant
-          if you also use <option>-fglasgow-exts</option>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-finline-phase</option>
-          <indexterm><primary><option>-finline-phase</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>See <xref linkend="rewrite-rules"/>.  Only relevant if
-          you also use <option>-fglasgow-exts</option>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-XArrows</option>
-          <indexterm><primary><option>-XArrows</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>See <xref linkend="arrow-notation"/>.  Independent of
-          <option>-fglasgow-exts</option>.</para>
-
-         <para>New reserved words/symbols: <literal>rec</literal>,
-         <literal>proc</literal>, <literal>-&lt;</literal>,
-         <literal>&gt;-</literal>, <literal>-&lt;&lt;</literal>,
-         <literal>&gt;&gt;-</literal>.</para>
-
-         <para>Other syntax stolen: <literal>(|</literal>,
-         <literal>|)</literal>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-XGenerics</option>
-          <indexterm><primary><option>-XGenerics</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>See <xref linkend="generic-classes"/>.  Independent of
-          <option>-fglasgow-exts</option>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-XNoImplicitPrelude</option></term>
-       <listitem>
-         <para><indexterm><primary>-XNoImplicitPrelude
-          option</primary></indexterm> GHC normally imports
-          <filename>Prelude.hi</filename> files for you.  If you'd
-          rather it didn't, then give it a
-          <option>-XNoImplicitPrelude</option> option.  The idea is
-          that you can then import a Prelude of your own.  (But don't
-          call it <literal>Prelude</literal>; the Haskell module
-          namespace is flat, and you must not conflict with any
-          Prelude module.)</para>
-
-         <para>Even though you have not imported the Prelude, most of
-          the built-in syntax still refers to the built-in Haskell
-          Prelude types and values, as specified by the Haskell
-          Report.  For example, the type <literal>[Int]</literal>
-          still means <literal>Prelude.[] Int</literal>; tuples
-          continue to refer to the standard Prelude tuples; the
-          translation for list comprehensions continues to use
-          <literal>Prelude.map</literal> etc.</para>
-
-         <para>However, <option>-XNoImplicitPrelude</option> does
-         change the handling of certain built-in syntax: see <xref
-         linkend="rebindable-syntax"/>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-XImplicitParams</option></term>
-       <listitem>
-         <para>Enables implicit parameters (see <xref
-         linkend="implicit-parameters"/>).  Currently also implied by 
-         <option>-fglasgow-exts</option>.</para>
-
-         <para>Syntax stolen:
-         <literal>?<replaceable>varid</replaceable></literal>,
-         <literal>%<replaceable>varid</replaceable></literal>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-XOverloadedStrings</option></term>
-       <listitem>
-         <para>Enables overloaded string literals (see <xref
-         linkend="overloaded-strings"/>).</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-XScopedTypeVariables</option></term>
-       <listitem>
-         <para>Enables lexically-scoped type variables (see <xref
-         linkend="scoped-type-variables"/>).  Implied by
-         <option>-fglasgow-exts</option>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-XTemplateHaskell</option></term>
-       <listitem>
-         <para>Enables Template Haskell (see <xref
-         linkend="template-haskell"/>).  This flag must
-         be given explicitly; it is no longer implied by
-         <option>-fglasgow-exts</option>.</para>
-
-         <para>Syntax stolen: <literal>[|</literal>,
-         <literal>[e|</literal>, <literal>[p|</literal>,
-         <literal>[d|</literal>, <literal>[t|</literal>,
-         <literal>$(</literal>,
-         <literal>$<replaceable>varid</replaceable></literal>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-XQuasiQuotes</option></term>
-       <listitem>
-         <para>Enables quasiquotation (see <xref
-         linkend="th-quasiquotation"/>).</para>
-
-         <para>Syntax stolen:
-         <literal>[:<replaceable>varid</replaceable>|</literal>.</para>
-       </listitem>
-      </varlistentry>
-
-    </variablelist>

   </sect1>
 
 <!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS -->
 <sect1 id="primitives">
   <title>Unboxed types and primitive operations</title>
 
   </sect1>
 
 <!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS -->
 <sect1 id="primitives">
   <title>Unboxed types and primitive operations</title>
 

-<para>GHC is built on a raft of primitive data types and operations.
+<para>GHC is built on a raft of primitive data types and operations;
+"primitive" in the sense that they cannot be defined in Haskell itself.

 While you really can use this stuff to write fast code,
   we generally find it a lot less painful, and more satisfying in the
   long run, to use higher-level language features and libraries.  With
 While you really can use this stuff to write fast code,
   we generally find it a lot less painful, and more satisfying in the
   long run, to use higher-level language features and libraries.  With

@@ -316,28 +106,21 @@ While you really can use this stuff to write fast code,
   unboxed version in any case.  And if it isn't, we'd like to know
   about it.</para>
 
   unboxed version in any case.  And if it isn't, we'd like to know
   about it.</para>
 

-<para>We do not currently have good, up-to-date documentation about the
-primitives, perhaps because they are mainly intended for internal use.
-There used to be a long section about them here in the User Guide, but it
-became out of date, and wrong information is worse than none.</para>
-
-<para>The Real Truth about what primitive types there are, and what operations
-work over those types, is held in the file
-<filename>compiler/prelude/primops.txt.pp</filename>.
-This file is used directly to generate GHC's primitive-operation definitions, so
-it is always correct!  It is also intended for processing into text.</para>
-
-<para>Indeed,
-the result of such processing is part of the description of the 
- <ulink
-      url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">External
-        Core language</ulink>.
-So that document is a good place to look for a type-set version.
-We would be very happy if someone wanted to volunteer to produce an XML
-back end to the program that processes <filename>primops.txt</filename> so that
-we could include the results here in the User Guide.</para>
-
-<para>What follows here is a brief summary of some main points.</para>
+<para>All these primitive data types and operations are exported by the 
+library <literal>GHC.Prim</literal>, for which there is 
+<ulink url="../libraries/base/GHC.Prim.html">detailed online documentation</ulink>.
+(This documentation is generated from the file <filename>compiler/prelude/primops.txt.pp</filename>.)
+</para>
+<para>
+If you want to mention any of the primitive data types or operations in your
+program, you must first import <literal>GHC.Prim</literal> to bring them
+into scope.  Many of them have names ending in "&num;", and to mention such
+names you need the <option>-XMagicHash</option> extension (<xref linkend="magic-hash"/>).
+</para>
+
+<para>The primops make extensive use of <link linkend="glasgow-unboxed">unboxed types</link> 
+and <link linkend="unboxed-tuples">unboxed tuples</link>, which
+we briefly summarise here. </para>

   
 <sect2 id="glasgow-unboxed">
 <title>Unboxed types
   
 <sect2 id="glasgow-unboxed">
 <title>Unboxed types

@@ -366,26 +149,15 @@ would use in C: <literal>Int&num;</literal> (long int),
 know and love&mdash;usually one instruction.
 </para>
 
 know and love&mdash;usually one instruction.
 </para>
 

-<para> For some primitive types we have special syntax for literals.
-Anything that would be an integer lexeme followed by a
-<literal>&num;</literal> is an <literal>Int&num;</literal> literal, e.g.
-<literal>32&num;</literal> and <literal>-0x3A&num;</literal>. Likewise,
-any non-negative integer literal followed by
-<literal>&num;&num;</literal> is a <literal>Word&num;</literal> literal.
-Likewise, any floating point literal followed by a
-<literal>&num;</literal> is a <literal>Float&num;</literal> literal, and
-followed by <literal>&num;&num;</literal> is a
-<literal>Double&num;</literal>. Finally, a string literal followed by a
-<literal>&num;</literal>, e.g. <literal>&quot;foo&quot;&num;</literal>,
-is a <literal>Addr&num;</literal> literal.
-</para>
-

 <para>
 Primitive (unboxed) types cannot be defined in Haskell, and are
 therefore built into the language and compiler.  Primitive types are
 always unlifted; that is, a value of a primitive type cannot be
 <para>
 Primitive (unboxed) types cannot be defined in Haskell, and are
 therefore built into the language and compiler.  Primitive types are
 always unlifted; that is, a value of a primitive type cannot be

-bottom.  We use the convention that primitive types, values, and
-operations have a <literal>&num;</literal> suffix.
+bottom.  We use the convention (but it is only a convention) 
+that primitive types, values, and
+operations have a <literal>&num;</literal> suffix (see <xref linkend="magic-hash"/>).
+For some primitive types we have special syntax for literals, also
+described in the <link linkend="magic-hash">same section</link>.

 </para>
 
 <para>
 </para>
 
 <para>

@@ -562,8 +334,77 @@ Indeed, the bindings can even be recursive.
 <sect1 id="syntax-extns">
 <title>Syntactic extensions</title>
  
 <sect1 id="syntax-extns">
 <title>Syntactic extensions</title>
  

+    <sect2 id="magic-hash">
+      <title>The magic hash</title>
+      <para>The language extension <option>-XMagicHash</option> allows "&num;" as a
+       postfix modifier to identifiers.  Thus, "x&num;" is a valid variable, and "T&num;" is
+       a valid type constructor or data constructor.</para>
+
+      <para>The hash sign does not change sematics at all.  We tend to use variable
+       names ending in "&num;" for unboxed values or types (e.g. <literal>Int&num;</literal>), 
+       but there is no requirement to do so; they are just plain ordinary variables.
+       Nor does the <option>-XMagicHash</option> extension bring anything into scope.
+       For example, to bring <literal>Int&num;</literal> into scope you must 
+       import <literal>GHC.Prim</literal> (see <xref linkend="primitives"/>); 
+       the <option>-XMagicHash</option> extension
+       then allows you to <emphasis>refer</emphasis> to the <literal>Int&num;</literal>
+       that is now in scope.</para>
+      <para> The <option>-XMagicHash</option> also enables some new forms of literals (see <xref linkend="glasgow-unboxed"/>):
+       <itemizedlist> 
+         <listitem><para> <literal>'x'&num;</literal> has type <literal>Char&num;</literal></para> </listitem>
+         <listitem><para> <literal>&quot;foo&quot;&num;</literal> has type <literal>Addr&num;</literal></para> </listitem>
+         <listitem><para> <literal>3&num;</literal> has type <literal>Int&num;</literal>. In general,
+         any Haskell 98 integer lexeme followed by a <literal>&num;</literal> is an <literal>Int&num;</literal> literal, e.g.
+            <literal>-0x3A&num;</literal> as well as <literal>32&num;</literal></para>.</listitem>
+         <listitem><para> <literal>3&num;&num;</literal> has type <literal>Word&num;</literal>. In general,
+         any non-negative Haskell 98 integer lexeme followed by <literal>&num;&num;</literal> 
+             is a <literal>Word&num;</literal>. </para> </listitem>
+         <listitem><para> <literal>3.2&num;</literal> has type <literal>Float&num;</literal>.</para> </listitem>
+         <listitem><para> <literal>3.2&num;&num;</literal> has type <literal>Double&num;</literal></para> </listitem>
+         </itemizedlist>
+      </para>
+   </sect2>
+
+    <sect2>
+      <title>New qualified operator syntax</title>
+
+      <para>A new syntax for referencing qualified operators is
+        planned to be introduced by Haskell', and is enabled in GHC
+        with
+        the <option>-XNewQualifiedOperators</option><indexterm><primary><option>-XNewQualifiedOperators</option></primary></indexterm>
+        option.  In the new syntax, the prefix form of a qualified
+        operator is
+        written <literal><replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)</literal>
+        (in Haskell 98 this would
+        be <literal>(<replaceable>module</replaceable>.<replaceable>symbol</replaceable>)</literal>),
+        and the infix form is
+        written <literal>`<replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)`</literal>
+        (in Haskell 98 this would
+        be <literal>`<replaceable>module</replaceable>.<replaceable>symbol</replaceable>`</literal>.
+        For example:
+<programlisting>
+  add x y = Prelude.(+) x y
+  subtract y = (`Prelude.(-)` y)
+</programlisting>
+        The new form of qualified operators is intended to regularise
+        the syntax by eliminating odd cases
+        like <literal>Prelude..</literal>.  For example,
+        when <literal>NewQualifiedOperators</literal> is on, it is possible to
+        write the enerated sequence <literal>[Monday..]</literal>
+        without spaces, whereas in Haskell 98 this would be a
+        reference to the operator &lsquo;<literal>.</literal>&lsquo;
+        from module <literal>Monday</literal>.</para>
+
+      <para>When <option>-XNewQualifiedOperators</option> is on, the old Haskell
+        98 syntax for qualified operators is not accepted, so this
+        option may cause existing Haskell 98 code to break.</para>
+
+    </sect2>
+        
+

     <!-- ====================== HIERARCHICAL MODULES =======================  -->
 
     <!-- ====================== HIERARCHICAL MODULES =======================  -->
 

+

     <sect2 id="hierarchical-modules">
       <title>Hierarchical Modules</title>
 
     <sect2 id="hierarchical-modules">
       <title>Hierarchical Modules</title>
 

@@ -1018,11 +859,6 @@ and improve termination (Section 3.2 of the paper).
 </para>
 
 <para>
 </para>
 
 <para>

-The web page: <ulink url="http://www.cse.ogi.edu/PacSoft/projects/rmb/">http://www.cse.ogi.edu/PacSoft/projects/rmb/</ulink>
-contains up to date information on recursive monadic bindings.
-</para>
-
-<para>

 Historical note: The old implementation of the mdo-notation (and most
 of the existing documents) used the name
 <literal>MonadRec</literal> for the class and the corresponding library.
 Historical note: The old implementation of the mdo-notation (and most
 of the existing documents) used the name
 <literal>MonadRec</literal> for the class and the corresponding library.

@@ -1247,21 +1083,28 @@ output = [ x
    <!-- ===================== REBINDABLE SYNTAX ===================  -->
 
 <sect2 id="rebindable-syntax">
    <!-- ===================== REBINDABLE SYNTAX ===================  -->
 
 <sect2 id="rebindable-syntax">

-<title>Rebindable syntax</title>
-
-      <para>GHC allows most kinds of built-in syntax to be rebound by
-      the user, to facilitate replacing the <literal>Prelude</literal>
-      with a home-grown version, for example.</para>
-
-            <para>You may want to define your own numeric class
+<title>Rebindable syntax and the implicit Prelude import</title>
+
+ <para><indexterm><primary>-XNoImplicitPrelude
+ option</primary></indexterm> GHC normally imports
+ <filename>Prelude.hi</filename> files for you.  If you'd
+ rather it didn't, then give it a
+ <option>-XNoImplicitPrelude</option> option.  The idea is
+ that you can then import a Prelude of your own.  (But don't
+ call it <literal>Prelude</literal>; the Haskell module
+ namespace is flat, and you must not conflict with any
+ Prelude module.)</para>
+
+            <para>Suppose you are importing a Prelude of your own
+             in order to define your own numeric class

             hierarchy.  It completely defeats that purpose if the
             literal "1" means "<literal>Prelude.fromInteger
             1</literal>", which is what the Haskell Report specifies.
             hierarchy.  It completely defeats that purpose if the
             literal "1" means "<literal>Prelude.fromInteger
             1</literal>", which is what the Haskell Report specifies.

-            So the <option>-XNoImplicitPrelude</option> flag causes
+            So the <option>-XNoImplicitPrelude</option> 
+             flag <emphasis>also</emphasis> causes

             the following pieces of built-in syntax to refer to
             <emphasis>whatever is in scope</emphasis>, not the Prelude
             versions:
             the following pieces of built-in syntax to refer to
             <emphasis>whatever is in scope</emphasis>, not the Prelude
             versions:

-

            <itemizedlist>
              <listitem>
                <para>An integer literal <literal>368</literal> means
            <itemizedlist>
              <listitem>
                <para>An integer literal <literal>368</literal> means

@@ -1410,7 +1253,7 @@ records from different modules that use the same field name.
 </title>
 
 <para>
 </title>
 
 <para>

-Record puns are enabled by the flag <literal>-XRecordPuns</literal>.
+Record puns are enabled by the flag <literal>-XNamedFieldPuns</literal>.

 </para>
 
 <para>
 </para>
 
 <para>

@@ -1568,6 +1411,167 @@ necessary to enable them.
 </para>
 </sect2>
 
 </para>
 </sect2>
 

+<sect2 id="package-imports">
+  <title>Package-qualified imports</title>
+
+  <para>With the <option>-XPackageImports</option> flag, GHC allows
+  import declarations to be qualified by the package name that the
+    module is intended to be imported from.  For example:</para>
+
+<programlisting>
+import "network" Network.Socket
+</programlisting>
+  
+  <para>would import the module <literal>Network.Socket</literal> from
+    the package <literal>network</literal> (any version).  This may
+    be used to disambiguate an import when the same module is
+    available from multiple packages, or is present in both the
+    current package being built and an external package.</para>
+
+  <para>Note: you probably don't need to use this feature, it was
+    added mainly so that we can build backwards-compatible versions of
+    packages when APIs change.  It can lead to fragile dependencies in
+    the common case: modules occasionally move from one package to
+    another, rendering any package-qualified imports broken.</para>
+</sect2>
+
+<sect2 id="syntax-stolen">
+<title>Summary of stolen syntax</title>
+
+    <para>Turning on an option that enables special syntax
+    <emphasis>might</emphasis> cause working Haskell 98 code to fail
+    to compile, perhaps because it uses a variable name which has
+    become a reserved word.  This section lists the syntax that is
+    "stolen" by language extensions.
+     We use
+    notation and nonterminal names from the Haskell 98 lexical syntax
+    (see the Haskell 98 Report).  
+    We only list syntax changes here that might affect
+    existing working programs (i.e. "stolen" syntax).  Many of these
+    extensions will also enable new context-free syntax, but in all
+    cases programs written to use the new syntax would not be
+    compilable without the option enabled.</para>
+
+<para>There are two classes of special
+    syntax:
+
+    <itemizedlist>
+      <listitem>
+       <para>New reserved words and symbols: character sequences
+        which are no longer available for use as identifiers in the
+        program.</para>
+      </listitem>
+      <listitem>
+       <para>Other special syntax: sequences of characters that have
+       a different meaning when this particular option is turned
+       on.</para>
+      </listitem>
+    </itemizedlist>
+    
+The following syntax is stolen:
+
+    <variablelist>
+      <varlistentry>
+       <term>
+          <literal>forall</literal>
+          <indexterm><primary><literal>forall</literal></primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen (in types) by: <option>-XScopedTypeVariables</option>,
+           <option>-XLiberalTypeSynonyms</option>,
+           <option>-XRank2Types</option>,
+           <option>-XRankNTypes</option>,
+           <option>-XPolymorphicComponents</option>,
+           <option>-XExistentialQuantification</option>
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <literal>mdo</literal>
+          <indexterm><primary><literal>mdo</literal></primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XRecursiveDo</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <literal>foreign</literal>
+          <indexterm><primary><literal>foreign</literal></primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XForeignFunctionInterface</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <literal>rec</literal>,
+         <literal>proc</literal>, <literal>-&lt;</literal>,
+         <literal>&gt;-</literal>, <literal>-&lt;&lt;</literal>,
+         <literal>&gt;&gt;-</literal>, and <literal>(|</literal>,
+         <literal>|)</literal> brackets
+          <indexterm><primary><literal>proc</literal></primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XArrows</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+         <literal>?<replaceable>varid</replaceable></literal>,
+         <literal>%<replaceable>varid</replaceable></literal>
+          <indexterm><primary>implicit parameters</primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XImplicitParams</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+         <literal>[|</literal>,
+         <literal>[e|</literal>, <literal>[p|</literal>,
+         <literal>[d|</literal>, <literal>[t|</literal>,
+         <literal>$(</literal>,
+         <literal>$<replaceable>varid</replaceable></literal>
+          <indexterm><primary>Template Haskell</primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XTemplateHaskell</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+         <literal>[:<replaceable>varid</replaceable>|</literal>
+          <indexterm><primary>quasi-quotation</primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XQuasiQuotes</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+             <replaceable>varid</replaceable>{<literal>&num;</literal>},
+             <replaceable>char</replaceable><literal>&num;</literal>,      
+             <replaceable>string</replaceable><literal>&num;</literal>,    
+             <replaceable>integer</replaceable><literal>&num;</literal>,    
+             <replaceable>float</replaceable><literal>&num;</literal>,    
+             <replaceable>float</replaceable><literal>&num;&num;</literal>,    
+             <literal>(&num;</literal>, <literal>&num;)</literal>,         
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XMagicHash</option>,
+         </para></listitem>
+      </varlistentry>
+    </variablelist>
+</para>
+</sect2>

 </sect1>
 
 
 </sect1>
 
 

@@ -1668,9 +1672,12 @@ to be written infix, very much like expressions.  More specifically:
 <title>Liberalised type synonyms</title>
 
 <para>
 <title>Liberalised type synonyms</title>
 
 <para>

-Type synonyms are like macros at the type level, and
+Type synonyms are like macros at the type level, but Haskell 98 imposes many rules
+on individual synonym declarations.
+With the <option>-XLiberalTypeSynonyms</option> extension,

 GHC does validity checking on types <emphasis>only after expanding type synonyms</emphasis>.
 GHC does validity checking on types <emphasis>only after expanding type synonyms</emphasis>.

-That means that GHC can be very much more liberal about type synonyms than Haskell 98:
+That means that GHC can be very much more liberal about type synonyms than Haskell 98. 
+

 <itemizedlist>
 <listitem> <para>You can write a <literal>forall</literal> (including overloading)
 in a type synonym, thus:
 <itemizedlist>
 <listitem> <para>You can write a <literal>forall</literal> (including overloading)
 in a type synonym, thus:

@@ -1687,7 +1694,8 @@ in a type synonym, thus:
 </listitem>
 
 <listitem><para>
 </listitem>
 
 <listitem><para>

-You can write an unboxed tuple in a type synonym:
+If you also use <option>-XUnboxedTuples</option>, 
+you can write an unboxed tuple in a type synonym:

 <programlisting>
   type Pr = (# Int, Int #)
 
 <programlisting>
   type Pr = (# Int, Int #)
 

@@ -2436,11 +2444,17 @@ The result type of each constructor must begin with the type constructor being d
 but for a GADT the arguments to the type constructor can be arbitrary monotypes.  
 For example, in the <literal>Term</literal> data
 type above, the type of each constructor must end with <literal>Term ty</literal>, but
 but for a GADT the arguments to the type constructor can be arbitrary monotypes.  
 For example, in the <literal>Term</literal> data
 type above, the type of each constructor must end with <literal>Term ty</literal>, but

-the <literal>ty</literal> may not be a type variable (e.g. the <literal>Lit</literal>
+the <literal>ty</literal> need not be a type variable (e.g. the <literal>Lit</literal>

 constructor).
 </para></listitem>
 
 <listitem><para>
 constructor).
 </para></listitem>
 
 <listitem><para>

+It's is permitted to declare an ordinary algebraic data type using GADT-style syntax.
+What makes a GADT into a GADT is not the syntax, but rather the presence of data constructors
+whose result type is not just <literal>T a b</literal>.
+</para></listitem>
+
+<listitem><para>

 You cannot use a <literal>deriving</literal> clause for a GADT; only for
 an ordinary data type.
 </para></listitem>
 You cannot use a <literal>deriving</literal> clause for a GADT; only for
 an ordinary data type.
 </para></listitem>

@@ -2476,6 +2490,23 @@ their selector functions actually have different types:
 </programlisting>
 </para></listitem>
 
 </programlisting>
 </para></listitem>
 

+<listitem><para>
+When pattern-matching against data constructors drawn from a GADT, 
+for example in a <literal>case</literal> expression, the following rules apply:
+<itemizedlist>
+<listitem><para>The type of the scrutinee must be rigid.</para></listitem>
+<listitem><para>The type of the entire <literal>case</literal> expression must be rigid.</para></listitem>
+<listitem><para>The type of any free variable mentioned in any of
+the <literal>case</literal> alternatives must be rigid.</para></listitem>
+</itemizedlist>
+A type is "rigid" if it is completely known to the compiler at its binding site.  The easiest
+way to ensure that a variable a rigid type is to give it a type signature.
+For more precise details see <ulink url="http://research.microsoft.com/%7Esimonpj/papers/gadt">
+Simple unification-based type inference for GADTs
+</ulink>. The criteria implemented by GHC are given in the Appendix.
+
+</para></listitem>
+

 </itemizedlist>
 </para>
 
 </itemizedlist>
 </para>
 

@@ -2533,9 +2564,27 @@ The syntax is identical to that of an ordinary instance declaration apart from (
 You must supply a context (in the example the context is <literal>(Eq a)</literal>), 
 exactly as you would in an ordinary instance declaration.
 (In contrast the context is inferred in a <literal>deriving</literal> clause 
 You must supply a context (in the example the context is <literal>(Eq a)</literal>), 
 exactly as you would in an ordinary instance declaration.
 (In contrast the context is inferred in a <literal>deriving</literal> clause 

-attached to a data type declaration.) These <literal>deriving instance</literal>
-rules obey the same rules concerning form and termination as ordinary instance declarations,
-controlled by the same flags; see <xref linkend="instance-decls"/>. </para>
+attached to a data type declaration.) 
+
+A <literal>deriving instance</literal> declaration
+must obey the same rules concerning form and termination as ordinary instance declarations,
+controlled by the same flags; see <xref linkend="instance-decls"/>.
+</para>
+<para>
+Unlike a <literal>deriving</literal>
+declaration attached to a <literal>data</literal> declaration, the instance can be more specific
+than the data type (assuming you also use 
+<literal>-XFlexibleInstances</literal>, <xref linkend="instance-rules"/>).  Consider
+for example
+<programlisting>
+  data Foo a = Bar a | Baz String
+
+  deriving instance Eq a => Eq (Foo [a])
+  deriving instance Eq a => Eq (Foo (Maybe a))
+</programlisting>
+This will generate a derived instance for <literal>(Foo [a])</literal> and <literal>(Foo (Maybe a))</literal>,
+but other types such as <literal>(Foo (Int,Bool))</literal> will not be an instance of <literal>Eq</literal>.
+</para>

 
 <para>The stand-alone syntax is generalised for newtypes in exactly the same
 way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>).
 
 <para>The stand-alone syntax is generalised for newtypes in exactly the same
 way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>).

@@ -3251,7 +3300,7 @@ corresponding type in the instance declaration.
 These restrictions ensure that context reduction terminates: each reduction
 step makes the problem smaller by at least one
 constructor.  Both the Paterson Conditions and the Coverage Condition are lifted 
 These restrictions ensure that context reduction terminates: each reduction
 step makes the problem smaller by at least one
 constructor.  Both the Paterson Conditions and the Coverage Condition are lifted 

-if you give the <option>-fallow-undecidable-instances</option> 
+if you give the <option>-XUndecidableInstances</option> 

 flag (<xref linkend="undecidable-instances"/>).
 You can find lots of background material about the reason for these
 restrictions in the paper <ulink
 flag (<xref linkend="undecidable-instances"/>).
 You can find lots of background material about the reason for these
 restrictions in the paper <ulink

@@ -3449,14 +3498,36 @@ Notice that we gave a type signature to <literal>f</literal>, so GHC had to
 <emphasis>check</emphasis> that <literal>f</literal> has the specified type.  
 Suppose instead we do not give a type signature, asking GHC to <emphasis>infer</emphasis>
 it instead.  In this case, GHC will refrain from
 <emphasis>check</emphasis> that <literal>f</literal> has the specified type.  
 Suppose instead we do not give a type signature, asking GHC to <emphasis>infer</emphasis>
 it instead.  In this case, GHC will refrain from

-simplifying the constraint <literal>C Int [Int]</literal> (for the same reason
+simplifying the constraint <literal>C Int [b]</literal> (for the same reason

 as before) but, rather than rejecting the program, it will infer the type
 <programlisting>
 as before) but, rather than rejecting the program, it will infer the type
 <programlisting>

-  f :: C Int b => [b] -> [b]
+  f :: C Int [b] => [b] -> [b]

 </programlisting>
 That postpones the question of which instance to pick to the 
 call site for <literal>f</literal>
 by which time more is known about the type <literal>b</literal>.
 </programlisting>
 That postpones the question of which instance to pick to the 
 call site for <literal>f</literal>
 by which time more is known about the type <literal>b</literal>.

+You can write this type signature yourself if you use the 
+<link linkend="flexible-contexts"><option>-XFlexibleContexts</option></link>
+flag.
+</para>
+<para>
+Exactly the same situation can arise in instance declarations themselves.  Suppose we have
+<programlisting>
+  class Foo a where
+     f :: a -> a
+  instance Foo [b] where
+     f x = ...
+</programlisting>
+and, as before, the constraint <literal>C Int [b]</literal> arises from <literal>f</literal>'s
+right hand side.  GHC will reject the instance, complaining as before that it does not know how to resolve
+the constraint <literal>C Int [b]</literal>, because it matches more than one instance
+declaration.  The solution is to postpone the choice by adding the constraint to the context
+of the instance declaration, thus:
+<programlisting>
+  instance C Int [b] => Foo [b] where
+     f x = ...
+</programlisting>
+(You need <link linkend="instance-rules"><option>-XFlexibleInstances</option></link> to do this.)

 </para>
 <para>
 The willingness to be overlapped or incoherent is a property of 
 </para>
 <para>
 The willingness to be overlapped or incoherent is a property of 

@@ -3631,9 +3702,11 @@ to work since it gets translated into an equality comparison.
 
 <sect3 id="flexible-contexts"><title>The context of a type signature</title>
 <para>
 
 <sect3 id="flexible-contexts"><title>The context of a type signature</title>
 <para>

-Unlike Haskell 98, constraints in types do <emphasis>not</emphasis> have to be of
-the form <emphasis>(class type-variable)</emphasis> or
-<emphasis>(class (type-variable type-variable ...))</emphasis>.  Thus,
+The <option>-XFlexibleContexts</option> flag lifts the Haskell 98 restriction
+that the type-class constraints in a type signature must have the 
+form <emphasis>(class type-variable)</emphasis> or
+<emphasis>(class (type-variable type-variable ...))</emphasis>. 
+With <option>-XFlexibleContexts</option>

 these type signatures are perfectly OK
 <programlisting>
   g :: Eq [a] => ...
 these type signatures are perfectly OK
 <programlisting>
   g :: Eq [a] => ...

@@ -5329,6 +5402,8 @@ For more details, see
 &ldquo;Generalising Monads to Arrows&rdquo;,
 John Hughes, in <citetitle>Science of Computer Programming</citetitle> 37,
 pp67&ndash;111, May 2000.
 &ldquo;Generalising Monads to Arrows&rdquo;,
 John Hughes, in <citetitle>Science of Computer Programming</citetitle> 37,
 pp67&ndash;111, May 2000.

+The paper that introduced arrows: a friendly introduction, motivated with
+programming examples.

 </para>
 </listitem>
 
 </para>
 </listitem>
 

@@ -5336,6 +5411,7 @@ pp67&ndash;111, May 2000.
 <para>
 &ldquo;<ulink url="http://www.soi.city.ac.uk/~ross/papers/notation.html">A New Notation for Arrows</ulink>&rdquo;,
 Ross Paterson, in <citetitle>ICFP</citetitle>, Sep 2001.
 <para>
 &ldquo;<ulink url="http://www.soi.city.ac.uk/~ross/papers/notation.html">A New Notation for Arrows</ulink>&rdquo;,
 Ross Paterson, in <citetitle>ICFP</citetitle>, Sep 2001.

+Introduced the notation described here.

 </para>
 </listitem>
 
 </para>
 </listitem>
 

@@ -5347,17 +5423,42 @@ Palgrave, 2003.
 </para>
 </listitem>
 
 </para>
 </listitem>
 

-</itemizedlist>
-and the arrows web page at
+<listitem>
+<para>
+&ldquo;<ulink url="http://www.cs.chalmers.se/~rjmh/afp-arrows.pdf">Programming with Arrows</ulink>&rdquo;,
+John Hughes, in <citetitle>5th International Summer School on
+Advanced Functional Programming</citetitle>,
+<citetitle>Lecture Notes in Computer Science</citetitle> vol. 3622,
+Springer, 2004.
+This paper includes another introduction to the notation,
+with practical examples.
+</para>
+</listitem>
+
+<listitem>
+<para>
+&ldquo;<ulink url="http://www.haskell.org/ghc/docs/papers/arrow-rules.pdf">Type and Translation Rules for Arrow Notation in GHC</ulink>&rdquo;,
+Ross Paterson and Simon Peyton Jones, September 16, 2004.
+A terse enumeration of the formal rules used
+(extracted from comments in the source code).
+</para>
+</listitem>
+
+<listitem>
+<para>
+The arrows web page at

 <ulink url="http://www.haskell.org/arrows/"><literal>http://www.haskell.org/arrows/</literal></ulink>.
 <ulink url="http://www.haskell.org/arrows/"><literal>http://www.haskell.org/arrows/</literal></ulink>.

+</para>
+</listitem>
+
+</itemizedlist>

 With the <option>-XArrows</option> flag, GHC supports the arrow
 With the <option>-XArrows</option> flag, GHC supports the arrow

-notation described in the second of these papers.
-What follows is a brief introduction to the notation;
-it won't make much sense unless you've read Hughes's paper.
-This notation is translated to ordinary Haskell,
-using combinators from the
+notation described in the second of these papers,
+translating it using combinators from the

 <ulink url="../libraries/base/Control-Arrow.html"><literal>Control.Arrow</literal></ulink>
 module.
 <ulink url="../libraries/base/Control-Arrow.html"><literal>Control.Arrow</literal></ulink>
 module.

+What follows is a brief introduction to the notation;
+it won't make much sense unless you've read Hughes's paper.

 </para>
 
 <para>The extension adds a new kind of expression for defining arrows:
 </para>
 
 <para>The extension adds a new kind of expression for defining arrows:

@@ -5631,7 +5732,8 @@ We could define our own operator
 <programlisting>
 untilA :: ArrowChoice a => a e () -> a e Bool -> a e ()
 untilA body cond = proc x ->
 <programlisting>
 untilA :: ArrowChoice a => a e () -> a e Bool -> a e ()
 untilA body cond = proc x ->

-        if cond x then returnA -&lt; ()
+        b &lt;- cond -&lt; x
+        if b then returnA -&lt; ()

         else do
                 body -&lt; x
                 untilA body cond -&lt; x
         else do
                 body -&lt; x
                 untilA body cond -&lt; x

@@ -6144,56 +6246,63 @@ Assertion failures can be caught, see the documentation for the
        don't recommend using this approach with GHC.</para>
     </sect2>
 
        don't recommend using this approach with GHC.</para>
     </sect2>
 

-    <sect2 id="deprecated-pragma">
-      <title>DEPRECATED pragma</title>
-      <indexterm><primary>DEPRECATED</primary>
-      </indexterm>
+    <sect2 id="warning-deprecated-pragma">
+      <title>WARNING and DEPRECATED pragmas</title>
+      <indexterm><primary>WARNING</primary></indexterm>
+      <indexterm><primary>DEPRECATED</primary></indexterm>

 
 

-      <para>The DEPRECATED pragma lets you specify that a particular
-      function, class, or type, is deprecated.  There are two
-      forms.
+      <para>The WARNING pragma allows you to attach an arbitrary warning
+      to a particular function, class, or type.
+      A DEPRECATED pragma lets you specify that
+      a particular function, class, or type is deprecated.
+      There are two ways of using these pragmas.

 
       <itemizedlist>
        <listitem>
 
       <itemizedlist>
        <listitem>

-         <para>You can deprecate an entire module thus:</para>
+         <para>You can work on an entire module thus:</para>

 <programlisting>
    module Wibble {-# DEPRECATED "Use Wobble instead" #-} where
      ...
 </programlisting>
 <programlisting>
    module Wibble {-# DEPRECATED "Use Wobble instead" #-} where
      ...
 </programlisting>

+      <para>Or:</para>
+<programlisting>
+   module Wibble {-# WARNING "This is an unstable interface." #-} where
+     ...
+</programlisting>

          <para>When you compile any module that import
           <literal>Wibble</literal>, GHC will print the specified
           message.</para>
        </listitem>
 
        <listitem>
          <para>When you compile any module that import
           <literal>Wibble</literal>, GHC will print the specified
           message.</para>
        </listitem>
 
        <listitem>

-         <para>You can deprecate a function, class, type, or data constructor, with the
-         following top-level declaration:</para>
+         <para>You can attach a warning to a function, class, type, or data constructor, with the
+         following top-level declarations:</para>

 <programlisting>
    {-# DEPRECATED f, C, T "Don't use these" #-}
 <programlisting>
    {-# DEPRECATED f, C, T "Don't use these" #-}

+   {-# WARNING unsafePerformIO "This is unsafe; I hope you know what you're doing" #-}

 </programlisting>
          <para>When you compile any module that imports and uses any
           of the specified entities, GHC will print the specified
           message.</para>
 </programlisting>
          <para>When you compile any module that imports and uses any
           of the specified entities, GHC will print the specified
           message.</para>

-         <para> You can only deprecate entities declared at top level in the module
+         <para> You can only attach to entities declared at top level in the module

          being compiled, and you can only use unqualified names in the list of
          being compiled, and you can only use unqualified names in the list of

-         entities being deprecated.  A capitalised name, such as <literal>T</literal>
+         entities. A capitalised name, such as <literal>T</literal>

          refers to <emphasis>either</emphasis> the type constructor <literal>T</literal>
          <emphasis>or</emphasis> the data constructor <literal>T</literal>, or both if
          refers to <emphasis>either</emphasis> the type constructor <literal>T</literal>
          <emphasis>or</emphasis> the data constructor <literal>T</literal>, or both if

-         both are in scope.  If both are in scope, there is currently no way to deprecate 
-         one without the other (c.f. fixities <xref linkend="infix-tycons"/>).</para>
+         both are in scope.  If both are in scope, there is currently no way to
+      specify one without the other (c.f. fixities
+      <xref linkend="infix-tycons"/>).</para>

        </listitem>
       </itemizedlist>
        </listitem>
       </itemizedlist>

-      Any use of the deprecated item, or of anything from a deprecated
-      module, will be flagged with an appropriate message.  However,
-      deprecations are not reported for
-      (a) uses of a deprecated function within its defining module, and
-      (b) uses of a deprecated function in an export list.
+      Warnings and deprecations are not reported for
+      (a) uses within the defining module, and
+      (b) uses in an export list.

       The latter reduces spurious complaints within a library
       in which one module gathers together and re-exports 
       the exports of several others.
       </para>
       <para>You can suppress the warnings with the flag
       The latter reduces spurious complaints within a library
       in which one module gathers together and re-exports 
       the exports of several others.
       </para>
       <para>You can suppress the warnings with the flag

-      <option>-fno-warn-deprecations</option>.</para>
+      <option>-fno-warn-warnings-deprecations</option>.</para>

     </sect2>
 
     <sect2 id="inline-noinline-pragma">
     </sect2>
 
     <sect2 id="inline-noinline-pragma">

@@ -6220,16 +6329,9 @@ Assertion failures can be caught, see the documentation for the
 
 <programlisting>
 key_function :: Int -> String -> (Bool, Double)
 
 <programlisting>
 key_function :: Int -> String -> (Bool, Double)

-
-#ifdef __GLASGOW_HASKELL__

 {-# INLINE key_function #-}
 {-# INLINE key_function #-}

-#endif

 </programlisting>
 
 </programlisting>
 

-       <para>(You don't need to do the C pre-processor carry-on
-        unless you're going to stick the code through HBC&mdash;it
-        doesn't like <literal>INLINE</literal> pragmas.)</para>
-

         <para>The major effect of an <literal>INLINE</literal> pragma
         is to declare a function's &ldquo;cost&rdquo; to be very low.
         The normal unfolding machinery will then be very keen to
         <para>The major effect of an <literal>INLINE</literal> pragma
         is to declare a function's &ldquo;cost&rdquo; to be very low.
         The normal unfolding machinery will then be very keen to

@@ -6253,6 +6355,16 @@ It's going to be inlined wholesale instead.
 All of these effects are aimed at ensuring that what gets inlined is
 exactly what you asked for, no more and no less.
 </para>
 All of these effects are aimed at ensuring that what gets inlined is
 exactly what you asked for, no more and no less.
 </para>

+<para>GHC ensures that inlining cannot go on forever: every mutually-recursive
+group is cut by one or more <emphasis>loop breakers</emphasis> that is never inlined
+(see <ulink url="http://research.microsoft.com/%7Esimonpj/Papers/inlining/index.htm">
+Secrets of the GHC inliner, JFP 12(4) July 2002</ulink>).
+GHC tries not to select a function with an INLINE pragma as a loop breaker, but
+when there is no choice even an INLINE function can be selected, in which case
+the INLINE pragma is ignored.
+For example, for a self-recursive function, the loop breaker can only be the function
+itself, so an INLINE pragma is always ignored.</para>
+

        <para>Syntactically, an <literal>INLINE</literal> pragma for a
         function can be put anywhere its type signature could be
         put.</para>
        <para>Syntactically, an <literal>INLINE</literal> pragma for a
         function can be put anywhere its type signature could be
         put.</para>

@@ -6265,14 +6377,18 @@ exactly what you asked for, no more and no less.
         <literal>UniqueSupply</literal> monad code, we have:</para>
 
 <programlisting>
         <literal>UniqueSupply</literal> monad code, we have:</para>
 
 <programlisting>

-#ifdef __GLASGOW_HASKELL__

 {-# INLINE thenUs #-}
 {-# INLINE returnUs #-}
 {-# INLINE thenUs #-}
 {-# INLINE returnUs #-}

-#endif

 </programlisting>
 
        <para>See also the <literal>NOINLINE</literal> pragma (<xref
         linkend="noinline-pragma"/>).</para>
 </programlisting>
 
        <para>See also the <literal>NOINLINE</literal> pragma (<xref
         linkend="noinline-pragma"/>).</para>

+
+       <para>Note: the HBC compiler doesn't like <literal>INLINE</literal> pragmas,
+         so if you want your code to be HBC-compatible you'll have to surround
+         the pragma with C pre-processor directives 
+         <literal>#ifdef __GLASGOW_HASKELL__</literal>...<literal>#endif</literal>.</para>
+

       </sect3>
 
       <sect3 id="noinline-pragma">
       </sect3>
 
       <sect3 id="noinline-pragma">

@@ -6600,15 +6716,7 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
 
 <para>
 The programmer can specify rewrite rules as part of the source program
 
 <para>
 The programmer can specify rewrite rules as part of the source program

-(in a pragma).  GHC applies these rewrite rules wherever it can, provided (a) 
-the <option>-O</option> flag (<xref linkend="options-optimise"/>) is on, 
-and (b) the <option>-fno-rewrite-rules</option> flag
-(<xref linkend="options-f"/>) is not specified, and (c) the
-<option>-fglasgow-exts</option> (<xref linkend="options-language"/>)
-flag is active.
-</para>
-
-<para>
+(in a pragma).  

 Here is an example:
 
 <programlisting>
 Here is an example:
 
 <programlisting>

@@ -6617,6 +6725,11 @@ Here is an example:
     #-}
 </programlisting>
 </para>
     #-}
 </programlisting>
 </para>

+<para>
+Use the debug flag <option>-ddump-simpl-stats</option> to see what rules fired.
+If you need more information, then <option>-ddump-rule-firings</option> shows you
+each individual rule firing in detail.
+</para>

 
 <sect2>
 <title>Syntax</title>
 
 <sect2>
 <title>Syntax</title>

@@ -6723,17 +6836,40 @@ variables it mentions, though of course they need to be in scope.
 <listitem>
 
 <para>
 <listitem>
 
 <para>

- Rules are automatically exported from a module, just as instance declarations are.
+ All rules are implicitly exported from the module, and are therefore
+in force in any module that imports the module that defined the rule, directly
+or indirectly.  (That is, if A imports B, which imports C, then C's rules are
+in force when compiling A.)  The situation is very similar to that for instance
+declarations.
+</para>
+</listitem>
+
+<listitem>
+
+<para>
+Inside a RULE "<literal>forall</literal>" is treated as a keyword, regardless of
+any other flag settings.  Furthermore, inside a RULE, the language extension
+<option>-XScopedTypeVariables</option> is automatically enabled; see 
+<xref linkend="scoped-type-variables"/>.

 </para>
 </listitem>
 </para>
 </listitem>

+<listitem>

 
 

+<para>
+Like other pragmas, RULE pragmas are always checked for scope errors, and
+are typechecked. Typechecking means that the LHS and RHS of a rule are typechecked, 
+and must have the same type.  However, rules are only <emphasis>enabled</emphasis>
+if the <option>-fenable-rewrite-rules</option> flag is 
+on (see <xref linkend="rule-semantics"/>).
+</para>
+</listitem>

 </itemizedlist>
 
 </para>
 
 </sect2>
 
 </itemizedlist>
 
 </para>
 
 </sect2>
 

-<sect2>
+<sect2 id="rule-semantics">

 <title>Semantics</title>
 
 <para>
 <title>Semantics</title>
 
 <para>

@@ -6741,9 +6877,17 @@ From a semantic point of view:
 
 <itemizedlist>
 <listitem>
 
 <itemizedlist>
 <listitem>

-

 <para>
 <para>

-Rules are only applied if you use the <option>-O</option> flag.
+Rules are enabled (that is, used during optimisation)
+by the <option>-fenable-rewrite-rules</option> flag.
+This flag is implied by <option>-O</option>, and may be switched
+off (as usual) by <option>-fno-enable-rewrite-rules</option>.
+(NB: enabling <option>-fenable-rewrite-rules</option> without <option>-O</option> 
+may not do what you expect, though, because without <option>-O</option> GHC 
+ignores all optimisation information in interface files;
+see <option>-fignore-interface-pragmas</option>, <xref linkend="options-f"/>.)
+Note that <option>-fenable-rewrite-rules</option> is an <emphasis>optimisation</emphasis> flag, and
+has no effect on parsing or typechecking.

 </para>
 </listitem>
 
 </para>
 </listitem>
 

@@ -6760,14 +6904,6 @@ expression by substituting for the pattern variables.
 <listitem>
 
 <para>
 <listitem>
 
 <para>

- The LHS and RHS of a rule are typechecked, and must have the
-same type.
-
-</para>
-</listitem>
-<listitem>
-
-<para>

  GHC makes absolutely no attempt to verify that the LHS and RHS
 of a rule have the same meaning.  That is undecidable in general, and
 infeasible in most interesting cases.  The responsibility is entirely the programmer's!
  GHC makes absolutely no attempt to verify that the LHS and RHS
 of a rule have the same meaning.  That is undecidable in general, and
 infeasible in most interesting cases.  The responsibility is entirely the programmer's!

@@ -6834,48 +6970,32 @@ not be substituted, and the rule would not fire.
 <listitem>
 
 <para>
 <listitem>
 
 <para>

- In the earlier phases of compilation, GHC inlines <emphasis>nothing
-that appears on the LHS of a rule</emphasis>, because once you have substituted
-for something you can't match against it (given the simple minded
-matching).  So if you write the rule
-
+Ordinary inlining happens at the same time as rule rewriting, which may lead to unexpected
+results.  Consider this (artificial) example

 <programlisting>
 <programlisting>

-        "map/map"       forall f,g.  map f . map g = map (f.g)
-</programlisting>
+f x = x
+{-# RULES "f" f True = False #-}

 
 

-this <emphasis>won't</emphasis> match the expression <literal>map f (map g xs)</literal>.
-It will only match something written with explicit use of ".".
-Well, not quite.  It <emphasis>will</emphasis> match the expression
+g y = f y

 
 

-<programlisting>
-wibble f g xs
+h z = g True

 </programlisting>
 </programlisting>

-
-where <function>wibble</function> is defined:
-
+Since <literal>f</literal>'s right-hand side is small, it is inlined into <literal>g</literal>,
+to give

 <programlisting>
 <programlisting>

-wibble f g = map f . map g
+g y = y

 </programlisting>
 </programlisting>

-
-because <function>wibble</function> will be inlined (it's small).
-
-Later on in compilation, GHC starts inlining even things on the
-LHS of rules, but still leaves the rules enabled.  This inlining
-policy is controlled by the per-simplification-pass flag <option>-finline-phase</option><emphasis>n</emphasis>.
-
+Now <literal>g</literal> is inlined into <literal>h</literal>, but <literal>f</literal>'s RULE has
+no chance to fire.  
+If instead GHC had first inlined <literal>g</literal> into <literal>h</literal> then there
+would have been a better chance that <literal>f</literal>'s RULE might fire.  

 </para>
 </para>

-</listitem>
-<listitem>
-

 <para>
 <para>

- All rules are implicitly exported from the module, and are therefore
-in force in any module that imports the module that defined the rule, directly
-or indirectly.  (That is, if A imports B, which imports C, then C's rules are
-in force when compiling A.)  The situation is very similar to that for instance
-declarations.
+The way to get predictable behaviour is to use a NOINLINE 
+pragma on <literal>f</literal>, to ensure
+that it is not inlined until its RULEs have had a chance to fire.

 </para>
 </listitem>
 </para>
 </listitem>

-

 </itemizedlist>
 
 </para>
 </itemizedlist>
 
 </para>