Fix Trac #1525

[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 e7858ce..27d38ee 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -962,6 +962,48 @@ definitions; you must define such a function in prefix form.</para>
 
 </sect2>
 
+<sect2 id="disambiguate-fields">
+<title>Record field disambiguation</title>
+<para>
+In record construction and record pattern matching
+it is entirely unambiguous which field is referred to, even if there are two different
+data types in scope with a common field name.  For example:
+<programlisting>
+module M where
+  data S = MkS { x :: Int, y :: Bool }
+
+module Foo where
+  import M
+
+  data T = MkT { x :: Int }
+  
+  ok1 (MkS { x = n }) = n+1   -- Unambiguous
+
+  ok2 n = MkT { x = n+1 }     -- Unambiguous
+
+  bad1 k = k { x = 3 }  -- Ambiguous
+  bad2 k = x k          -- Ambiguous
+</programlisting>
+Even though there are two <literal>x</literal>'s in scope,
+it is clear that the <literal>x</literal> in the pattern in the
+definition of <literal>ok1</literal> can only mean the field
+<literal>x</literal> from type <literal>S</literal>. Similarly for
+the function <literal>ok2</literal>.  However, in the record update
+in <literal>bad1</literal> and the record selection in <literal>bad2</literal>
+it is not clear which of the two types is intended.
+</para>
+<para>
+Haskell 98 regards all four as ambiguous, but with the
+<option>-fdisambiguate-record-fields</option> flag, GHC will accept
+the former two.  The rules are precisely the same as those for instance
+declarations in Haskell 98, where the method names on the left-hand side 
+of the method bindings in an instance declaration refer unambiguously
+to the method of that class (provided they are in scope at all), even
+if there are other variables in scope with the same name.
+This reduces the clutter of qualified names when you import two
+records from different modules that use the same field name.
+</para>
+</sect2>
 </sect1>
 
 
@@ -2794,7 +2836,7 @@ match is found, and (b) the instance declaration was compiled with
 more-specific instance does not matter.
 </para></listitem>
 <listitem><para>
-Suppose an instance declaration does not matche the constraint being looked up, but
+Suppose an instance declaration does not match the constraint being looked up, but
 does unify with it, so that it might match when the constraint is further 
 instantiated.  Usually GHC will regard this as a reason for not committing to
 some other constraint.  But if the instance declaration was compiled with
@@ -4039,7 +4081,7 @@ and all others are monomorphic until the group is generalised
 <para>Following a suggestion of Mark Jones, in his paper
 <ulink url="http://www.cse.ogi.edu/~mpj/thih/">Typing Haskell in
 Haskell</ulink>,
-GHC implements a more general scheme.  If <option>-fglasgow-exts</option> is
+GHC implements a more general scheme.  If <option>-X=RelaxedPolyRec</option> is
 specified:
 <emphasis>the dependency analysis ignores references to variables that have an explicit
 type signature</emphasis>.
@@ -4068,7 +4110,7 @@ Now, the defintion for <literal>f</literal> is typechecked, with this type for
 The same refined dependency analysis also allows the type signatures of 
 mutually-recursive functions to have different contexts, something that is illegal in
 Haskell 98 (Section 4.5.2, last sentence).  With
-<option>-fglasgow-exts</option>
+<option>-X=RelaxedPolyRec</option>
 GHC only insists that the type signatures of a <emphasis>refined</emphasis> group have identical
 type signatures; in practice this means that only variables bound by the same
 pattern binding must have the same context.  For example, this is fine:
@@ -4262,7 +4304,7 @@ Tim Sheard is going to expand it.)
                              the quotation has type <literal>Expr</literal>.</para></listitem>
                    <listitem><para> <literal>[d| ... |]</literal>, where the "..." is a list of top-level declarations;
                              the quotation has type <literal>Q [Dec]</literal>.</para></listitem>
-                   <listitem><para>  [Planned, but not implemented yet.]  <literal>[t| ... |]</literal>, where the "..." is a type; 
+                   <listitem><para> <literal>[t| ... |]</literal>, where the "..." is a type;
                              the quotation has type <literal>Type</literal>.</para></listitem>
                  </itemizedlist></para></listitem>