Commit d5b81cb3 authored by Simon Peyton Jones's avatar Simon Peyton Jones

Improve documentation for the 7.8 release

* Document ExplicitNamespaces
* Improve documentation of ambiguity, and AllowAmbiguousTypes
* Improve documentation of overlapping/incoherent instance rules
* List language extensions in alphabetical order
parent 8d7dd547
...@@ -699,23 +699,10 @@ ...@@ -699,23 +699,10 @@
<entry><option>-fno-glasgow-exts</option></entry> <entry><option>-fno-glasgow-exts</option></entry>
</row> </row>
<row> <row>
<entry><option>-XOverlappingInstances</option></entry> <entry><option>-firrefutable-tuples</option></entry>
<entry>Enable <link linkend="instance-overlap">overlapping instances</link></entry> <entry>Make tuple pattern matching irrefutable</entry>
<entry>dynamic</entry>
<entry><option>-XNoOverlappingInstances</option></entry>
</row>
<row>
<entry><option>-XIncoherentInstances</option></entry>
<entry>Enable <link linkend="instance-overlap">incoherent instances</link>.
Implies <option>-XOverlappingInstances</option> </entry>
<entry>dynamic</entry>
<entry><option>-XNoIncoherentInstances</option></entry>
</row>
<row>
<entry><option>-XUndecidableInstances</option></entry>
<entry>Enable <link linkend="undecidable-instances">undecidable instances</link></entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoUndecidableInstances</option></entry> <entry><option>-fno-irrefutable-tuples</option></entry>
</row> </row>
<row> <row>
<entry><option>-fcontext-stack=N</option><replaceable>n</replaceable></entry> <entry><option>-fcontext-stack=N</option><replaceable>n</replaceable></entry>
...@@ -723,6 +710,14 @@ ...@@ -723,6 +710,14 @@
<entry>dynamic</entry> <entry>dynamic</entry>
<entry></entry> <entry></entry>
</row> </row>
<row>
<entry><option>-XAllowAmbiguousTypes</option></entry>
<entry>Allow the user to write <link linkend="ambiguity">ambiguous types</link>,
and the type inference engine to infer them.
</entry>
<entry>dynamic</entry>
<entry><option>-XNoAllowAmbiguousTypes</option></entry>
</row>
<row> <row>
<entry><option>-XArrows</option></entry> <entry><option>-XArrows</option></entry>
<entry>Enable <link linkend="arrow-notation">arrow <entry>Enable <link linkend="arrow-notation">arrow
...@@ -730,6 +725,43 @@ ...@@ -730,6 +725,43 @@
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoArrows</option></entry> <entry><option>-XNoArrows</option></entry>
</row> </row>
<row>
<entry><option>-XAutoDeriveTypeable</option></entry>
<entry>Automatically <link linkend="auto-derive-typeable">derive Typeable instances for every datatype and type class declaration</link>.
Implies <option>-XDeriveDataTypeable</option>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoAutoDeriveTypeable</option></entry>
</row>
<row>
<entry><option>-XConstraintKinds</option></entry>
<entry>Enable a <link linkend="constraint-kind">kind of constraints</link>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoConstraintKinds</option></entry>
</row>
<row>
<entry><option>-XDataKinds</option></entry>
<entry>Enable <link linkend="promotion">datatype promotion</link>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoDataKinds</option></entry>
</row>
<row>
<entry><option>-XDeriveDataTypeable</option></entry>
<entry>Enable <link linkend="deriving-typeable">deriving for the Data and Typeable classes</link>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoDeriveDataTypeable</option></entry>
</row>
<row>
<entry><option>-XDeriveGeneric</option></entry>
<entry>Enable <link linkend="deriving-typeable">deriving for the Generic class</link>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoDeriveGeneric</option></entry>
</row>
<row>
<entry><option>-XGeneralizedNewtypeDeriving</option></entry>
<entry>Enable <link linkend="newtype-deriving">newtype deriving</link>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoGeneralizedNewtypeDeriving</option></entry>
</row>
<row> <row>
<entry><option>-XDisambiguateRecordFields</option></entry> <entry><option>-XDisambiguateRecordFields</option></entry>
<entry>Enable <link linkend="disambiguate-fields">record <entry>Enable <link linkend="disambiguate-fields">record
...@@ -737,6 +769,19 @@ ...@@ -737,6 +769,19 @@
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoDisambiguateRecordFields</option></entry> <entry><option>-XNoDisambiguateRecordFields</option></entry>
</row> </row>
<row>
<entry><option>-XEmptyCase</option></entry>
<entry>Allow <link linkend="empty-case">empty case alternatives</link>
</entry>
<entry>dynamic</entry>
<entry><option>-XNoEmptyCase</option></entry>
</row>
<row>
<entry><option>-XExtendedDefaultRules</option></entry>
<entry>Use GHCi's <link linkend="extended-default-rules">extended default rules</link> in a normal module</entry>
<entry>dynamic</entry>
<entry><option>-XNoExtendedDefaultRules</option></entry>
</row>
<row> <row>
<entry><option>-XForeignFunctionInterface</option></entry> <entry><option>-XForeignFunctionInterface</option></entry>
<entry>Enable <link linkend="ffi">foreign function interface</link> (implied by <entry>Enable <link linkend="ffi">foreign function interface</link> (implied by
...@@ -744,6 +789,20 @@ ...@@ -744,6 +789,20 @@
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoForeignFunctionInterface</option></entry> <entry><option>-XNoForeignFunctionInterface</option></entry>
</row> </row>
<row>
<entry><option>-XGADTs</option></entry>
<entry>Enable <link linkend="gadt">generalised algebraic data types</link>.
</entry>
<entry>dynamic</entry>
<entry><option>-XNoGADTs</option></entry>
</row>
<row>
<entry><option>-XGADTSyntax</option></entry>
<entry>Enable <link linkend="gadt-style">generalised algebraic data type syntax</link>.
</entry>
<entry>dynamic</entry>
<entry><option>-XNoGADTSyntax</option></entry>
</row>
<row> <row>
<entry><option>-XGenerics</option></entry> <entry><option>-XGenerics</option></entry>
<entry>Deprecated, does nothing. No longer enables <link linkend="generic-classes">generic classes</link>. <entry>Deprecated, does nothing. No longer enables <link linkend="generic-classes">generic classes</link>.
...@@ -759,12 +818,6 @@ ...@@ -759,12 +818,6 @@
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoImplicitParams</option></entry> <entry><option>-XNoImplicitParams</option></entry>
</row> </row>
<row>
<entry><option>-firrefutable-tuples</option></entry>
<entry>Make tuple pattern matching irrefutable</entry>
<entry>dynamic</entry>
<entry><option>-fno-irrefutable-tuples</option></entry>
</row>
<row> <row>
<entry><option>-XNoImplicitPrelude</option></entry> <entry><option>-XNoImplicitPrelude</option></entry>
<entry>Don't implicitly <literal>import Prelude</literal></entry> <entry>Don't implicitly <literal>import Prelude</literal></entry>
...@@ -772,10 +825,11 @@ ...@@ -772,10 +825,11 @@
<entry><option>-XImplicitPrelude</option></entry> <entry><option>-XImplicitPrelude</option></entry>
</row> </row>
<row> <row>
<entry><option>-XRebindableSyntax</option></entry> <entry><option>-XIncoherentInstances</option></entry>
<entry>Employ <link linkend="rebindable-syntax">rebindable syntax</link></entry> <entry>Enable <link linkend="instance-overlap">incoherent instances</link>.
Implies <option>-XOverlappingInstances</option> </entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoRebindableSyntax</option></entry> <entry><option>-XNoIncoherentInstances</option></entry>
</row> </row>
<row> <row>
<entry><option>-XNoMonomorphismRestriction</option></entry> <entry><option>-XNoMonomorphismRestriction</option></entry>
...@@ -784,16 +838,16 @@ ...@@ -784,16 +838,16 @@
<entry><option>-XMonomorphismRrestriction</option></entry> <entry><option>-XMonomorphismRrestriction</option></entry>
</row> </row>
<row> <row>
<entry><option>-XNoNPlusKPatterns</option></entry> <entry><option>-XNegativeLiterals</option></entry>
<entry>Disable support for <literal>n+k</literal> patterns</entry> <entry>Enable support for <link linkend="negative-literals">negative literals</link></entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNPlusKPatterns</option></entry> <entry><option>-XNoNegativeLiterals</option></entry>
</row> </row>
<row> <row>
<entry><option>-XNegativeLiterals</option></entry> <entry><option>-XNoNPlusKPatterns</option></entry>
<entry>Enable support for negative literals</entry> <entry>Disable support for <literal>n+k</literal> patterns</entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoNegativeLiterals</option></entry> <entry><option>-XNPlusKPatterns</option></entry>
</row> </row>
<row> <row>
<entry><option>-XNumDecimals</option></entry> <entry><option>-XNumDecimals</option></entry>
...@@ -802,22 +856,17 @@ ...@@ -802,22 +856,17 @@
<entry><option>-XNoNumDecimals</option></entry> <entry><option>-XNoNumDecimals</option></entry>
</row> </row>
<row> <row>
<entry><option>-XNoTraditionalRecordSyntax</option></entry> <entry><option>-XOverlappingInstances</option></entry>
<entry>Disable support for traditional record syntax (as supported by Haskell 98) <literal>C {f = x}</literal></entry> <entry>Enable <link linkend="instance-overlap">overlapping instances</link></entry>
<entry>dynamic</entry>
<entry><option>-XTraditionalRecordSyntax</option></entry>
</row>
<row>
<entry><option>-XRelaxedPolyRec</option></entry>
<entry>Relaxed checking for <link linkend="typing-binds">mutually-recursive polymorphic functions</link></entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoRelaxedPolyRec</option></entry> <entry><option>-XNoOverlappingInstances</option></entry>
</row> </row>
<row> <row>
<entry><option>-XExtendedDefaultRules</option></entry> <entry><option>-XOverloadedLists</option></entry>
<entry>Use GHCi's <link linkend="extended-default-rules">extended default rules</link> in a normal module</entry> <entry>Enable <link linkend="overloaded-lists">overloaded lists</link>.
</entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoExtendedDefaultRules</option></entry> <entry><option>-XNoOverloadedLists</option></entry>
</row> </row>
<row> <row>
<entry><option>-XOverloadedStrings</option></entry> <entry><option>-XOverloadedStrings</option></entry>
...@@ -827,25 +876,22 @@ ...@@ -827,25 +876,22 @@
<entry><option>-XNoOverloadedStrings</option></entry> <entry><option>-XNoOverloadedStrings</option></entry>
</row> </row>
<row> <row>
<entry><option>-XOverloadedLists</option></entry> <entry><option>-XQuasiQuotes</option></entry>
<entry>Enable <link linkend="overloaded-lists">overloaded lists</link>. <entry>Enable <link linkend="th-quasiquotation">quasiquotation</link>.</entry>
</entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoOverloadedLists</option></entry> <entry><option>-XNoQuasiQuotes</option></entry>
</row> </row>
<row> <row>
<entry><option>-XGADTs</option></entry> <entry><option>-XRelaxedPolyRec</option></entry>
<entry>Enable <link linkend="gadt">generalised algebraic data types</link>. <entry>Relaxed checking for <link linkend="typing-binds">mutually-recursive polymorphic functions</link></entry>
</entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoGADTs</option></entry> <entry><option>-XNoRelaxedPolyRec</option></entry>
</row> </row>
<row> <row>
<entry><option>-XGADTSyntax</option></entry> <entry><option>-XNoTraditionalRecordSyntax</option></entry>
<entry>Enable <link linkend="gadt-style">generalised algebraic data type syntax</link>. <entry>Disable support for traditional record syntax (as supported by Haskell 98) <literal>C {f = x}</literal></entry>
</entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoGADTSyntax</option></entry> <entry><option>-XTraditionalRecordSyntax</option></entry>
</row> </row>
<row> <row>
<entry><option>-XTypeFamilies</option></entry> <entry><option>-XTypeFamilies</option></entry>
...@@ -854,16 +900,10 @@ ...@@ -854,16 +900,10 @@
<entry><option>-XNoTypeFamilies</option></entry> <entry><option>-XNoTypeFamilies</option></entry>
</row> </row>
<row> <row>
<entry><option>-XConstraintKinds</option></entry> <entry><option>-XUndecidableInstances</option></entry>
<entry>Enable a <link linkend="constraint-kind">kind of constraints</link>.</entry> <entry>Enable <link linkend="undecidable-instances">undecidable instances</link></entry>
<entry>dynamic</entry>
<entry><option>-XNoConstraintKinds</option></entry>
</row>
<row>
<entry><option>-XDataKinds</option></entry>
<entry>Enable <link linkend="promotion">datatype promotion</link>.</entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoDataKinds</option></entry> <entry><option>-XNoUndecidableInstances</option></entry>
</row> </row>
<row> <row>
<entry><option>-XPolyKinds</option></entry> <entry><option>-XPolyKinds</option></entry>
...@@ -872,13 +912,6 @@ ...@@ -872,13 +912,6 @@
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoPolyKinds</option></entry> <entry><option>-XNoPolyKinds</option></entry>
</row> </row>
<row>
<entry><option>-XScopedTypeVariables</option></entry>
<entry>Enable <link linkend="scoped-type-variables">lexically-scoped type variables</link>.
Implied by <option>-fglasgow-exts</option>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoScopedTypeVariables</option></entry>
</row>
<row> <row>
<entry><option>-XMonoLocalBinds</option></entry> <entry><option>-XMonoLocalBinds</option></entry>
<entry>Enable <link linkend="mono-local-binds">do not generalise local bindings</link>. <entry>Enable <link linkend="mono-local-binds">do not generalise local bindings</link>.
...@@ -887,6 +920,19 @@ ...@@ -887,6 +920,19 @@
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoMonoLocalBinds</option></entry> <entry><option>-XNoMonoLocalBinds</option></entry>
</row> </row>
<row>
<entry><option>-XRebindableSyntax</option></entry>
<entry>Employ <link linkend="rebindable-syntax">rebindable syntax</link></entry>
<entry>dynamic</entry>
<entry><option>-XNoRebindableSyntax</option></entry>
</row>
<row>
<entry><option>-XScopedTypeVariables</option></entry>
<entry>Enable <link linkend="scoped-type-variables">lexically-scoped type variables</link>.
Implied by <option>-fglasgow-exts</option>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoScopedTypeVariables</option></entry>
</row>
<row> <row>
<entry><option>-XTemplateHaskell</option></entry> <entry><option>-XTemplateHaskell</option></entry>
<entry>Enable <link linkend="template-haskell">Template Haskell</link>. <entry>Enable <link linkend="template-haskell">Template Haskell</link>.
...@@ -894,12 +940,6 @@ ...@@ -894,12 +940,6 @@
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoTemplateHaskell</option></entry> <entry><option>-XNoTemplateHaskell</option></entry>
</row> </row>
<row>
<entry><option>-XQuasiQuotes</option></entry>
<entry>Enable <link linkend="th-quasiquotation">quasiquotation</link>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoQuasiQuotes</option></entry>
</row>
<row> <row>
<entry><option>-XBangPatterns</option></entry> <entry><option>-XBangPatterns</option></entry>
<entry>Enable <link linkend="bang-patterns">bang patterns</link>.</entry> <entry>Enable <link linkend="bang-patterns">bang patterns</link>.</entry>
...@@ -1033,7 +1073,9 @@ ...@@ -1033,7 +1073,9 @@
</row> </row>
<row> <row>
<entry><option>-XExplicitNamespaces</option></entry> <entry><option>-XExplicitNamespaces</option></entry>
<entry>Enable using the keyword <literal>type</literal> to specify the namespace of entries in imports and exports.</entry> <entry>Enable using the keyword <literal>type</literal> to specify the namespace of
entries in imports and exports (<xref linkend="explicit-namespaces"/>).
Implied by <option>-XTypeOperators</option> and <option>-XTypeFamilies</option>.</entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoExplicitNamespaces</option></entry> <entry><option>-XNoExplicitNamespaces</option></entry>
</row> </row>
...@@ -1079,31 +1121,6 @@ ...@@ -1079,31 +1121,6 @@
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-XNoStandaloneDeriving</option></entry> <entry><option>-XNoStandaloneDeriving</option></entry>
</row> </row>
<row>
<entry><option>-XDeriveDataTypeable</option></entry>
<entry>Enable <link linkend="deriving-typeable">deriving for the Data and Typeable classes</link>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoDeriveDataTypeable</option></entry>
</row>
<row>
<entry><option>-XAutoDeriveTypeable</option></entry>
<entry>Automatically <link linkend="auto-derive-typeable">derive Typeable instances for every datatype and type class declaration</link>.
Implies <option>-XDeriveDataTypeable</option>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoAutoDeriveTypeable</option></entry>
</row>
<row>
<entry><option>-XDeriveGeneric</option></entry>
<entry>Enable <link linkend="deriving-typeable">deriving for the Generic class</link>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoDeriveGeneric</option></entry>
</row>
<row>
<entry><option>-XGeneralizedNewtypeDeriving</option></entry>
<entry>Enable <link linkend="newtype-deriving">newtype deriving</link>.</entry>
<entry>dynamic</entry>
<entry><option>-XNoGeneralizedNewtypeDeriving</option></entry>
</row>
<row> <row>
<entry><option>-XTypeSynonymInstances</option></entry> <entry><option>-XTypeSynonymInstances</option></entry>
<entry>Enable <link linkend="flexible-instance-head">type synonyms in instance heads</link>.</entry> <entry>Enable <link linkend="flexible-instance-head">type synonyms in instance heads</link>.</entry>
...@@ -1190,14 +1207,14 @@ ...@@ -1190,14 +1207,14 @@
<entry><option>-</option></entry> <entry><option>-</option></entry>
</row> </row>
<row> <row>
<entry><option>-fpackage-trust</option></entry> <entry><option>-XTypeHoles</option></entry>
<entry>Enable <link linkend="safe-haskell">Safe Haskell</link> trusted package requirement for trustworty modules.</entry> <entry>Enable <link linkend="type-holes">holes</link> in expressions.</entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-</option></entry> <entry><option>--XNoTypeHoles</option></entry>
</row> </row>
<row> <row>
<entry><option>-XTypeHoles</option></entry> <entry><option>-fpackage-trust</option></entry>
<entry>Enable <link linkend="type-holes">holes</link> in expressions.</entry> <entry>Enable <link linkend="safe-haskell">Safe Haskell</link> trusted package requirement for trustworty modules.</entry>
<entry>dynamic</entry> <entry>dynamic</entry>
<entry><option>-</option></entry> <entry><option>-</option></entry>
</row> </row>
......
...@@ -2112,6 +2112,36 @@ import safe qualified Network.Socket as NS ...@@ -2112,6 +2112,36 @@ import safe qualified Network.Socket as NS
</sect2> </sect2>
<sect2 id="explicit-namespaces">
<title>Explicit namespaces in import/export</title>
<para> In an import or export list, such as
<programlisting>
module M( f, (++) ) where ...
import N( f, (++) )
...
</programlisting>
the entities <literal>f</literal> and <literal>(++)</literal> are <emphasis>values</emphasis>.
However, with type operators (<xref linkend="type-operators"/>) it becomes possible
to declare <literal>(++)</literal> as a <emphasis>type constructor</emphasis>. In that
case, how would you export or import it?
</para>
<para>
The <option>-XExplicitNamespaces</option> extension allows you to prefix the name of
a type constructor in an import or export list with "<literal>type</literal>" to
disambiguate this case, thus:
<programlisting>
module M( f, type (++) ) where ...
import N( f, type (++) )
...
module N( f, type (++) ) where
data family a ++ b = L a | R b
</programlisting>
The extension <option>-XExplicitNamespaces</option>
is implied by <option>-XTypeOperators</option> and (for some reason) by <option>-XTypeFamilies</option>.
</para>
</sect2>
<sect2 id="syntax-stolen"> <sect2 id="syntax-stolen">
<title>Summary of stolen syntax</title> <title>Summary of stolen syntax</title>
...@@ -2385,11 +2415,13 @@ There is now some potential ambiguity in import and export lists; for example ...@@ -2385,11 +2415,13 @@ There is now some potential ambiguity in import and export lists; for example
if you write <literal>import M( (+) )</literal> do you mean the if you write <literal>import M( (+) )</literal> do you mean the
<emphasis>function</emphasis> <literal>(+)</literal> or the <emphasis>function</emphasis> <literal>(+)</literal> or the
<emphasis>type constructor</emphasis> <literal>(+)</literal>? <emphasis>type constructor</emphasis> <literal>(+)</literal>?
The default is the former, but GHC allows you to specify the latter The default is the former, but with <option>-XExplicitNamespaces</option> (which is implied
by <option>-XExplicitTypeOperators</option>) GHC allows you to specify the latter
by preceding it with the keyword <literal>type</literal>, thus: by preceding it with the keyword <literal>type</literal>, thus:
<programlisting> <programlisting>
import M( type (+) ) import M( type (+) )
</programlisting> </programlisting>
See <xref linkend="explicit-namespaces"/>.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
The fixity of a type operator may be set using the usual fixity declarations The fixity of a type operator may be set using the usual fixity declarations
...@@ -4642,30 +4674,44 @@ The willingness to be overlapped or incoherent is a property of ...@@ -4642,30 +4674,44 @@ The willingness to be overlapped or incoherent is a property of
the <emphasis>instance declaration</emphasis> itself, controlled by the the <emphasis>instance declaration</emphasis> itself, controlled by the
presence or otherwise of the <option>-XOverlappingInstances</option> presence or otherwise of the <option>-XOverlappingInstances</option>
and <option>-XIncoherentInstances</option> flags when that module is and <option>-XIncoherentInstances</option> flags when that module is
being defined. Specifically, during the lookup process: being defined. Suppose we are searching for an instance of the
<emphasis>target constraint</emphasis> <literal>(C ty1 .. tyn)</literal>.
The search works like this.
<itemizedlist> <itemizedlist>
<listitem><para> <listitem><para>
If the constraint being looked up matches two instance declarations IA and IB, Find all instances I that <emphasis>match</emphasis> the target constraint;
and that is, the target constraint is a substitution instance of I. These
<itemizedlist> instance declarations are the <emphasis>candidates</emphasis>.
<listitem><para>IB is a substitution instance of IA (but not vice versa);
that is, IB is strictly more specific than IA</para></listitem>
<listitem><para>either IA or IB was compiled with <option>-XOverlappingInstances</option></para></listitem>
</itemizedlist>
then the less-specific instance IA is ignored.
</para></listitem> </para></listitem>
<listitem><para>
Find all <emphasis>non-candidate</emphasis> instances
that <emphasis>unify</emphasis> with the target constraint.
Such non-candidates instances might match when the target constraint is further
instantiated. If all of them were compiled with
<option>-XIncoherentInstances</option>, proceed; if not, the search fails.
</para></listitem>
<listitem><para> <listitem><para>
Suppose an instance declaration does not match the constraint being looked up, but Eliminate any candidate IX for which both of the following hold:
does <emphasis>unify</emphasis> 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 <itemizedlist>
some other constraint. But if the instance declaration was compiled with <listitem><para>There is another candidate IY that is strictly more specific;
<option>-XIncoherentInstances</option>, GHC will skip the "does-it-unify?" that is, IY is a substitution instance of IX but not vice versa.
check for that declaration. </para></listitem>
<listitem><para>Either IX or IY was compiled with
<option>-XOverlappingInstances</option>.
</para></listitem> </para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para> <listitem><para>
If two instance declarations are matched and either is compiled with If only one candidate remains, pick it.
<option>-XIncoherentInstances</option>, then that declaration is ignored. Otherwise if all remaining candidates were compiled with
<option>-XInccoherentInstances</option>, pick an arbitrary candidate.
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
These rules make it possible for a library author to design a library that relies on These rules make it possible for a library author to design a library that relies on
overlapping instances without the library client having to know. overlapping instances without the library client having to know.
...@@ -6386,106 +6432,91 @@ The flag <option>-XFlexibleContexts</option> also lifts the corresponding ...@@ -6386,106 +6432,91 @@ The flag <option>-XFlexibleContexts</option> also lifts the corresponding
restriction on class declarations (<xref linkend="superclass-rules"/>) and instance declarations restriction on class declarations (<xref linkend="superclass-rules"/>) and instance declarations
(<xref linkend="instance-rules"/>). (<xref linkend="instance-rules"/>).
</para> </para>
</sect2>
<para> <sect2 id="ambiguity"><title>Ambiguous types and the ambiguity check</title>
GHC imposes the following restrictions on the constraints in a type signature.
Consider the type:
<para>
Each user-written type signature is subjected to an
<emphasis>ambiguity check</emphasis>.
The ambiguity check rejects functions that can never be called; for example:
<programlisting> <programlisting>
forall tv1..tvn (c1, ...,cn) => type f :: C a => Int
</programlisting> </programlisting>
The idea is there can be no legal calls to <literal>f</literal> because every call will
(Here, we write the "foralls" explicitly, although the Haskell source give rise to an ambiguous constraint.
language omits them; in Haskell 98, all the free type variables of an
explicit source-language type signature are universally quantified,
except for the class type variables in a class declaration. However,
in GHC, you can give the foralls if you want. See <xref linkend="explicit-foralls"/>).
</para> </para>
<para> <para>