<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>.
+<ulink url="../libraries/ghc-prim/GHC-Prim.html">detailed online documentation</ulink>.
(This documentation is generated from the file <filename>compiler/prelude/primops.txt.pp</filename>.)
</para>
<para>
</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">
</para>
<para>
-The Control.Monad.Fix library introduces the <literal>MonadFix</literal> class. It's definition is:
+The Control.Monad.Fix library introduces the <literal>MonadFix</literal> class. Its definition is:
</para>
<programlisting>
class Monad m => MonadFix m where
<para>Generalised list comprehensions are a further enhancement to the
- list comprehension syntatic sugar to allow operations such as sorting
+ list comprehension syntactic sugar to allow operations such as sorting
and grouping which are familiar from SQL. They are fully described in the
paper <ulink url="http://research.microsoft.com/~simonpj/papers/list-comp">
Comprehensive comprehensions: comprehensions with "order by" and "group by"</ulink>,
</programlisting>
This statement requires that <literal>f</literal> have the type <literal>
- forall a. [a] -> [a]</literal>. You can see an example of it's use in the
+ forall a. [a] -> [a]</literal>. You can see an example of its use in the
motivating example, as this form is used to apply <literal>take 5</literal>.
</listitem>
</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>
</para></listitem>
<listitem><para>
-It's is permitted to declare an ordinary algebraic data type using GADT-style syntax.
+It 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>
</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
</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:
</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>
example, consider the following declaration:
<programlisting>
type family F a b :: * -> * -- F's arity is 2,
- -- although it's overall kind is * -> * -> * -> *
+ -- although its overall kind is * -> * -> * -> *
</programlisting>
Given this declaration the following are examples of well-formed and
malformed types:
<sect2 id="include-pragma">
<title>INCLUDE pragma</title>
- <para>The <literal>INCLUDE</literal> pragma is for specifying the names
- of C header files that should be <literal>#include</literal>'d into
- the C source code generated by the compiler for the current module (if
- compiling via C). For example:</para>
-
-<programlisting>
-{-# INCLUDE "foo.h" #-}
-{-# INCLUDE <stdio.h> #-}</programlisting>
-
- <para><literal>INCLUDE</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
-
- <para>An <literal>INCLUDE</literal> pragma is the preferred alternative
- to the <option>-#include</option> option (<xref
- linkend="options-C-compiler" />), because the
- <literal>INCLUDE</literal> pragma is understood by other
- compilers. Yet another alternative is to add the include file to each
- <literal>foreign import</literal> declaration in your code, but we
- don't recommend using this approach with GHC.</para>
+ <para>The <literal>INCLUDE</literal> used to be necessary for
+ specifying header files to be included when using the FFI and
+ compiling via C. It is no longer required for GHC, but is
+ accepted (and ignored) for compatibility with other
+ compilers.</para>
</sect2>
<sect2 id="warning-deprecated-pragma">