<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>
in a <emphasis>recursive</emphasis> binding.
</para></listitem>
<listitem><para> You may bind unboxed variables in a (non-recursive,
-non-top-level) pattern binding, but any such variable causes the entire
-pattern-match
-to become strict. For example:
+non-top-level) pattern binding, but you must make any such pattern-match
+strict. For example, rather than:
<programlisting>
data Foo = Foo Int Int#
f x = let (Foo a b, w) = ..rhs.. in ..body..
</programlisting>
-Since <literal>b</literal> has type <literal>Int#</literal>, the entire pattern
-match
-is strict, and the program behaves as if you had written
+you must write:
<programlisting>
data Foo = Foo Int Int#
- f x = case ..rhs.. of { (Foo a b, w) -> ..body.. }
+ f x = let !(Foo a b, w) = ..rhs.. in ..body..
</programlisting>
+since <literal>b</literal> has type <literal>Int#</literal>.
</para>
</listitem>
</itemizedlist>
</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>,
except that the syntax we use differs slightly from the paper.</para>
+<para>The extension is enabled with the flag <option>-XTransformListComp</option>.</para>
<para>Here is an example:
<programlisting>
employees = [ ("Simon", "MS", 80)
</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>
<listitem><para>
The type signature of
each constructor is independent, and is implicitly universally quantified as usual.
-Different constructors may have different universally-quantified type variables
-and different type-class constraints.
-For example, this is fine:
+In particular, the type variable(s) in the "<literal>data T a where</literal>" header
+have no scope, and different constructors may have different universally-quantified type variables:
+<programlisting>
+ data T a where -- The 'a' has no scope
+ T1,T2 :: b -> T b -- Means forall b. b -> T b
+ T3 :: T a -- Means forall a. T a
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+A constructor signature may mention type class constraints, which can differ for
+different constructors. For example, this is fine:
<programlisting>
data T a where
- T1 :: Eq b => b -> T b
+ T1 :: Eq b => b -> b -> T b
T2 :: (Show c, Ix c) => c -> [c] -> T c
</programlisting>
+When patten matching, these constraints are made available to discharge constraints
+in the body of the match. For example:
+<programlisting>
+ f :: T a -> String
+ f (T1 x y) | x==y = "yes"
+ | otherwise = "no"
+ f (T2 a b) = show a
+</programlisting>
+Note that <literal>f</literal> is not overloaded; the <literal>Eq</literal> constraint arising
+from the use of <literal>==</literal> is discharged by the pattern match on <literal>T1</literal>
+and similarly the <literal>Show</literal> constraint arising from the use of <literal>show</literal>.
</para></listitem>
<listitem><para>
</programlisting>
or even a mixture of the two:
<programlisting>
- data Foo a :: (* -> *) -> * where ...
+ data Bar a :: (* -> *) -> * where ...
</programlisting>
The type variables (if given) may be explicitly kinded, so we could also write the header for <literal>Foo</literal>
like this:
<programlisting>
- data Foo a (b :: * -> *) where ...
+ data Bar a (b :: * -> *) where ...
</programlisting>
</para></listitem>
</para></listitem>
<listitem><para>
+The type signature may have quantified type variables that do not appear
+in the result type:
+<programlisting>
+ data Foo where
+ MkFoo :: a -> (a->Bool) -> Foo
+ Nil :: Foo
+</programlisting>
+Here the type variable <literal>a</literal> does not appear in the result type
+of either constructor.
+Although it is universally quantified in the type of the constructor, such
+a type variable is often called "existential".
+Indeed, the above declaration declares precisely the same type as
+the <literal>data Foo</literal> in <xref linkend="existential-quantification"/>.
+</para><para>
+The type may contain a class context too, of course:
+<programlisting>
+ data Showable where
+ MkShowable :: Show a => a -> Showable
+</programlisting>
+</para></listitem>
+
+<listitem><para>
You can use record syntax on a GADT-style data type declaration:
<programlisting>
data Person where
- Adult { name :: String, children :: [Person] } :: Person
- Child { name :: String } :: Person
+ Adult :: { name :: String, children :: [Person] } -> Person
+ Child :: Show a => { name :: !String, funny :: a } -> Person
</programlisting>
As usual, for every constructor that has a field <literal>f</literal>, the type of
field <literal>f</literal> must be the same (modulo alpha conversion).
-</para>
-<para>
-At the moment, record updates are not yet possible with GADT-style declarations,
-so support is limited to record construction, selection and pattern matching.
-For example
-<programlisting>
- aPerson = Adult { name = "Fred", children = [] }
+The <literal>Child</literal> constructor above shows that the signature
+may have a context, existentially-quantified variables, and strictness annotations,
+just as in the non-record case. (NB: the "type" that follows the double-colon
+is not really a type, because of the record syntax and strictness annotations.
+A "type" of this form can appear only in a constructor signature.)
+</para></listitem>
- shortName :: Person -> Bool
- hasChildren (Adult { children = kids }) = not (null kids)
- hasChildren (Child {}) = False
-</programlisting>
+<listitem><para>
+Record updates are allowed with GADT-style declarations,
+only fields that have the following property: the type of the field
+mentions no existential type variables.
</para></listitem>
<listitem><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:
<itemizedlist>
<listitem><para> an expression; the spliced expression must
have type <literal>Q Exp</literal></para></listitem>
+ <listitem><para> an type; the spliced expression must
+ have type <literal>Q Typ</literal></para></listitem>
<listitem><para> a list of top-level declarations; the spliced expression must have type <literal>Q [Dec]</literal></para></listitem>
</itemizedlist>
</para>
(Compared to the original paper, there are many differences of detail.
The syntax for a declaration splice uses "<literal>$</literal>" not "<literal>splice</literal>".
The type of the enclosed expression must be <literal>Q [Dec]</literal>, not <literal>[Q Dec]</literal>.
-Type splices are not implemented, and neither are pattern splices or quotations.
+Pattern splices and quotations are not implemented.)
</sect2>
<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">