Add an extension to disable n+k patterns

[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 43cfa48..ea31390 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -840,6 +840,19 @@ y)</literal> will not be coalesced.
 
 </sect2>
 
+    <!-- ===================== n+k patterns ===================  -->
+
+<sect2 id="n-k-patterns">
+<title>n+k patterns</title>
+<indexterm><primary><option>-XNoNPlusKPatterns</option></primary></indexterm>
+
+<para>
+<literal>n+k</literal> pattern support is enabled by default. To disable
+it, you can use the <option>-XNoNPlusKPatterns</option> flag.
+</para>
+
+</sect2>
+
     <!-- ===================== Recursive do-notation ===================  -->
 
 <sect2 id="mdo-notation">
@@ -1269,6 +1282,44 @@ definitions; you must define such a function in prefix form.</para>
 
 </sect2>
 
+<sect2 id="tuple-sections">
+<title>Tuple sections</title>
+
+<para>
+  The <option>-XTupleSections</option> flag enables Python-style partially applied
+  tuple constructors. For example, the following program
+<programlisting>
+  (, True)
+</programlisting>
+  is considered to be an alternative notation for the more unwieldy alternative
+<programlisting>
+  \x -> (x, True)
+</programlisting>
+You can omit any combination of arguments to the tuple, as in the following
+<programlisting>
+  (, "I", , , "Love", , 1337)
+</programlisting>
+which translates to
+<programlisting>
+  \a b c d -> (a, "I", b, c, "Love", d, 1337)
+</programlisting>
+</para>
+
+<para>
+  If you have <link linkend="unboxed-tuples">unboxed tuples</link> enabled, tuple sections
+  will also be available for them, like so
+<programlisting>
+  (# , True #)
+</programlisting>
+Because there is no unboxed unit tuple, the following expression
+<programlisting>
+  (# #)
+</programlisting>
+continues to stand for the unboxed singleton tuple data constructor.
+</para>
+
+</sect2>
+
 <sect2 id="disambiguate-fields">
 <title>Record field disambiguation</title>
 <para>
@@ -2691,16 +2742,22 @@ GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by
 </programlisting>
 The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword
 <literal>deriving</literal>, and (b) the absence of the <literal>where</literal> part.
-You must supply a context (in the example the context is <literal>(Eq a)</literal>), 
+Note the following points:
+<itemizedlist>
+<listitem><para>
+You must supply an explicit 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.) 
+(In contrast, in a <literal>deriving</literal> clause 
+attached to a data type declaration, the context is inferred.) 
+</para></listitem>
 
+<listitem><para>
 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>
+</para></listitem>
+
+<listitem><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 
@@ -2714,8 +2771,31 @@ for example
 </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></listitem>
+
+<listitem><para>
+Unlike a <literal>deriving</literal>
+declaration attached to a <literal>data</literal> declaration, 
+GHC does not restrict the form of the data type.  Instead, GHC simply generates the appropriate
+boilerplate code for the specified class, and typechecks it. If there is a type error, it is
+your problem. (GHC will show you the offending code if it has a type error.) 
+The merit of this is that you can derive instances for GADTs and other exotic
+data types, providing only that the boilerplate code does indeed typecheck.  For example:
+<programlisting>
+  data T a where
+     T1 :: T Int
+     T2 :: T Bool
+
+  deriving instance Show (T a)
+</programlisting>
+In this example, you cannot say <literal>... deriving( Show )</literal> on the 
+data type declaration for <literal>T</literal>, 
+because <literal>T</literal> is a GADT, but you <emphasis>can</emphasis> generate
+the instance declaration using stand-alone deriving.
 </para>
+</listitem>
 
+<listitem>
 <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"/>).
 For example:
@@ -2726,7 +2806,8 @@ For example:
 </programlisting>
 GHC always treats the <emphasis>last</emphasis> parameter of the instance
 (<literal>Foo</literal> in this example) as the type whose instance is being derived.
-</para>
+</para></listitem>
+</itemizedlist></para>
 
 </sect2>