<indexterm><primary>language, GHC</primary></indexterm>
<indexterm><primary>extensions, GHC</primary></indexterm>
As with all known Haskell systems, GHC implements some extensions to
-the language. They are all enabled by options; by default GHC
-understands only plain Haskell 98.
+the language. They can all be enabled or disabled by commandline flags
+or language pragmas. By default GHC understands the most recent Haskell
+version it supports, plus a handful of extensions.
</para>
<para>
</indexterm>
<para>The language option flags control what variation of the language are
- permitted. Leaving out all of them gives you standard Haskell
- 98.</para>
+ permitted.</para>
<para>Language options can be controlled in two ways:
<itemizedlist>
<listitem><para> <literal>'x'#</literal> has type <literal>Char#</literal></para> </listitem>
<listitem><para> <literal>"foo"#</literal> has type <literal>Addr#</literal></para> </listitem>
<listitem><para> <literal>3#</literal> has type <literal>Int#</literal>. In general,
- any Haskell 98 integer lexeme followed by a <literal>#</literal> is an <literal>Int#</literal> literal, e.g.
+ any Haskell integer lexeme followed by a <literal>#</literal> is an <literal>Int#</literal> literal, e.g.
<literal>-0x3A#</literal> as well as <literal>32#</literal></para>.</listitem>
<listitem><para> <literal>3##</literal> has type <literal>Word#</literal>. In general,
- any non-negative Haskell 98 integer lexeme followed by <literal>##</literal>
+ any non-negative Haskell integer lexeme followed by <literal>##</literal>
is a <literal>Word#</literal>. </para> </listitem>
<listitem><para> <literal>3.2#</literal> has type <literal>Float#</literal>.</para> </listitem>
<listitem><para> <literal>3.2##</literal> has type <literal>Double#</literal></para> </listitem>
</para>
</sect2>
- <sect2 id="new-qualified-operators">
- <title>New qualified operator syntax</title>
-
- <para>A new syntax for referencing qualified operators is
- planned to be introduced by Haskell', and is enabled in GHC
- with
- the <option>-XNewQualifiedOperators</option><indexterm><primary><option>-XNewQualifiedOperators</option></primary></indexterm>
- option. In the new syntax, the prefix form of a qualified
- operator is
- written <literal><replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)</literal>
- (in Haskell 98 this would
- be <literal>(<replaceable>module</replaceable>.<replaceable>symbol</replaceable>)</literal>),
- and the infix form is
- written <literal>`<replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)`</literal>
- (in Haskell 98 this would
- be <literal>`<replaceable>module</replaceable>.<replaceable>symbol</replaceable>`</literal>.
- For example:
-<programlisting>
- add x y = Prelude.(+) x y
- subtract y = (`Prelude.(-)` y)
-</programlisting>
- The new form of qualified operators is intended to regularise
- the syntax by eliminating odd cases
- like <literal>Prelude..</literal>. For example,
- when <literal>NewQualifiedOperators</literal> is on, it is possible to
- write the enumerated sequence <literal>[Monday..]</literal>
- without spaces, whereas in Haskell 98 this would be a
- reference to the operator ‘<literal>.</literal>‘
- from module <literal>Monday</literal>.</para>
-
- <para>When <option>-XNewQualifiedOperators</option> is on, the old Haskell
- 98 syntax for qualified operators is not accepted, so this
- option may cause existing Haskell 98 code to break.</para>
-
- </sect2>
-
-
<!-- ====================== HIERARCHICAL MODULES ======================= -->
</para>
</sect2>
+ <!-- ===================== MONAD COMPREHENSIONS ===================== -->
+
+<sect2 id="monad-comprehensions">
+ <title>Monad comprehensions</title>
+ <indexterm><primary>monad comprehensions</primary></indexterm>
+
+ <para>
+ Monad comprehesions generalise the list comprehension notation to work
+ for any monad.
+ </para>
+
+ <para>Monad comprehensions support:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Bindings:
+ </para>
+
+<programlisting>
+[ x + y | x <- Just 1, y <- Just 2 ]
+</programlisting>
+
+ <para>
+ Bindings are translated with the <literal>(>>=)</literal> and
+ <literal>return</literal> functions to the usual do-notation:
+ </para>
+
+<programlisting>
+do x <- Just 1
+ y <- Just 2
+ return (x+y)
+</programlisting>
+
+ </listitem>
+ <listitem>
+ <para>
+ Guards:
+ </para>
+
+<programlisting>
+[ x | x <- [1..10], x <= 5 ]
+</programlisting>
+
+ <para>
+ Guards are translated with the <literal>guard</literal> function,
+ which requires a <literal>MonadPlus</literal> instance:
+ </para>
+
+<programlisting>
+do x <- [1..10]
+ guard (x <= 5)
+ return x
+</programlisting>
+
+ </listitem>
+ <listitem>
+ <para>
+ Transform statements (as with <literal>-XTransformListComp</literal>):
+ </para>
+
+<programlisting>
+[ x+y | x <- [1..10], y <- [1..x], then take 2 ]
+</programlisting>
+
+ <para>
+ This translates to:
+ </para>
+
+<programlisting>
+do (x,y) <- take 2 (do x <- [1..10]
+ y <- [1..x]
+ return (x,y))
+ return (x+y)
+</programlisting>
+
+ </listitem>
+ <listitem>
+ <para>
+ Group statements (as with <literal>-XTransformListComp</literal>):
+ </para>
+
+<programlisting>
+[ x | x <- [1,1,2,2,3], then group by x ]
+[ x | x <- [1,1,2,2,3], then group by x using GHC.Exts.groupWith ]
+[ x | x <- [1,1,2,2,3], then group using myGroup ]
+</programlisting>
+
+ <para>
+ The basic <literal>then group by e</literal> statement is
+ translated using the <literal>mgroupWith</literal> function, which
+ requires a <literal>MonadGroup</literal> instance, defined in
+ <ulink url="&libraryBaseLocation;/Control-Monad-Group.html"><literal>Control.Monad.Group</literal></ulink>:
+ </para>
+
+<programlisting>
+do x <- mgroupWith (do x <- [1,1,2,2,3]
+ return x)
+ return x
+</programlisting>
+
+ <para>
+ Note that the type of <literal>x</literal> is changed by the
+ grouping statement.
+ </para>
+
+ <para>
+ The grouping function can also be defined with the
+ <literal>using</literal> keyword.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Parallel statements (as with <literal>-XParallelListComp</literal>):
+ </para>
+
+<programlisting>
+[ (x+y) | x <- [1..10]
+ | y <- [11..20]
+ ]
+</programlisting>
+
+ <para>
+ Parallel statements are translated using the
+ <literal>mzip</literal> function, which requires a
+ <literal>MonadZip</literal> instance defined in
+ <ulink url="&libraryBaseLocation;/Control-Monad-Zip.html"><literal>Control.Monad.Zip</literal></ulink>:
+ </para>
+
+<programlisting>
+do (x,y) <- mzip (do x <- [1..10]
+ return x)
+ (do y <- [11..20]
+ return y)
+ return (x+y)
+</programlisting>
+
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ All these features are enabled by default if the
+ <literal>MonadComprehensions</literal> extension is enabled. The types
+ and more detailed examples on how to use comprehensions are explained
+ in the previous chapters <xref
+ linkend="generalised-list-comprehensions"/> and <xref
+ linkend="parallel-list-comprehensions"/>. In general you just have
+ to replace the type <literal>[a]</literal> with the type
+ <literal>Monad m => m a</literal> for monad comprehensions.
+ </para>
+
+ <para>
+ Note: Even though most of these examples are using the list monad,
+ monad comprehensions work for any monad.
+ The <literal>base</literal> package offers all necessary instances for
+ lists, which make <literal>MonadComprehensions</literal> backward
+ compatible to built-in, transform and parallel list comprehensions.
+ </para>
+
+</sect2>
+
<!-- ===================== REBINDABLE SYNTAX =================== -->
<sect2 id="rebindable-syntax">
hierarchy. It completely defeats that purpose if the
literal "1" means "<literal>Prelude.fromInteger
1</literal>", which is what the Haskell Report specifies.
- So the <option>-XNoImplicitPrelude</option>
- flag <emphasis>also</emphasis> causes
+ So the <option>-XRebindableSyntax</option>
+ flag causes
the following pieces of built-in syntax to refer to
<emphasis>whatever is in scope</emphasis>, not the Prelude
versions:
</para></listitem>
<listitem>
+ <para>Conditionals (e.g. "<literal>if</literal> e1 <literal>then</literal> e2 <literal>else</literal> e3")
+ means "<literal>ifThenElse</literal> e1 e2 e3". However <literal>case</literal> expressions are unaffected.
+ </para></listitem>
+
+ <listitem>
<para>"Do" notation is translated using whatever
functions <literal>(>>=)</literal>,
<literal>(>>)</literal>, and <literal>fail</literal>,
to use this, ask!
</para></listitem>
</itemizedlist>
+<option>-XRebindableSyntax</option> implies <option>-XNoImplicitPrelude</option>.
+</para>
+<para>
In all cases (apart from arrow notation), the static semantics should be that of the desugared form,
even if that is a little unexpected. For example, the
static semantics of the literal <literal>368</literal>
<sect2 id="gadt-style">
<title>Declaring data types with explicit constructor signatures</title>
-<para>GHC allows you to declare an algebraic data type by
+<para>When the <literal>GADTSyntax</literal> extension is enabled,
+GHC allows you to declare an algebraic data type by
giving the type signatures of constructors explicitly. For example:
<programlisting>
data Maybe a where
the <emphasis>instance declaration</emphasis> itself, controlled by the
presence or otherwise of the <option>-XOverlappingInstances</option>
and <option>-XIncoherentInstances</option> flags when that module is
-being defined. Neither flag is required in a module that imports and uses the
-instance declaration. Specifically, during the lookup process:
+being defined. Specifically, during the lookup process:
<itemizedlist>
<listitem><para>
-An instance declaration is ignored during the lookup process if (a) a more specific
-match is found, and (b) the instance declaration was compiled with
-<option>-XOverlappingInstances</option>. The flag setting for the
-more-specific instance does not matter.
+If the constraint being looked up matches two instance declarations IA and IB,
+and
+<itemizedlist>
+<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>
<listitem><para>
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
+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
some other constraint. But if the instance declaration was compiled with
<option>-XIncoherentInstances</option>, GHC will skip the "does-it-unify?"
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.
</para>
-<para>
-If an instance declaration is compiled without
-<option>-XOverlappingInstances</option>,
-then that instance can never be overlapped. This could perhaps be
-inconvenient. Perhaps the rule should instead say that the
-<emphasis>overlapping</emphasis> instance declaration should be compiled in
-this way, rather than the <emphasis>overlapped</emphasis> one. Perhaps overlap
-at a usage site should be permitted regardless of how the instance declarations
-are compiled, if the <option>-XOverlappingInstances</option> flag is
-used at the usage site. (Mind you, the exact usage site can occasionally be
-hard to pin down.) We are interested to receive feedback on these points.
-</para>
<para>The <option>-XIncoherentInstances</option> flag implies the
<option>-XOverlappingInstances</option> flag, but not vice versa.
</para>
<sect2 id="impredicative-polymorphism">
<title>Impredicative polymorphism
</title>
-<para><emphasis>NOTE: the impredicative-polymorphism feature is deprecated in GHC 6.12, and
-will be removed or replaced in GHC 6.14.</emphasis></para>
-
<para>GHC supports <emphasis>impredicative polymorphism</emphasis>,
enabled with <option>-XImpredicativeTypes</option>.
This means
g (x:xs) = xs ++ [ x :: a ]
</programlisting>
This program will be rejected, because "<literal>a</literal>" does not scope
-over the definition of "<literal>f</literal>", so "<literal>x::a</literal>"
+over the definition of "<literal>g</literal>", so "<literal>x::a</literal>"
means "<literal>x::forall a. a</literal>" by Haskell's usual implicit
quantification rules.
</para></listitem>
<programlisting>
f = runST ( (op >>= \(x :: STRef s Int) -> g x) :: forall s. ST s Bool )
</programlisting>
-Here, the type signature <literal>forall a. ST s Bool</literal> brings the
+Here, the type signature <literal>forall s. ST s Bool</literal> brings the
type variable <literal>s</literal> into scope, in the annotated expression
<literal>(op >>= \(x :: STRef s Int) -> g x)</literal>.
</para>
There is one (apparent) exception to this general rule that a bang only
makes a difference when it precedes a variable or wild-card: a bang at the
top level of a <literal>let</literal> or <literal>where</literal>
-binding makes the binding strict, regardless of the pattern. For example:
+binding makes the binding strict, regardless of the pattern.
+(We say "apparent" exception because the Right Way to think of it is that the bang
+at the top of a binding is not part of the <emphasis>pattern</emphasis>; rather it
+is part of the syntax of the <emphasis>binding</emphasis>,
+creating a "bang-pattern binding".)
+For example:
<programlisting>
let ![x,y] = e in b
</programlisting>
-is a strict binding: operationally, it evaluates <literal>e</literal>, matches
-it against the pattern <literal>[x,y]</literal>, and then evaluates <literal>b</literal>.
-(We say "apparent" exception because the Right Way to think of it is that the bang
-at the top of a binding is not part of the <emphasis>pattern</emphasis>; rather it
-is part of the syntax of the <emphasis>binding</emphasis>.)
-Nested bangs in a pattern binding behave uniformly with all other forms of
+is a bang-pattern binding. Operationally, it behaves just like a case expression:
+<programlisting>
+case e of [x,y] -> b
+</programlisting>
+Like a case expression, a bang-pattern binding must be non-recursive, and
+is monomorphic.
+
+However, <emphasis>nested</emphasis> bangs in a pattern binding behave uniformly with all other forms of
pattern matching. For example
<programlisting>
let (!x,[y]) = e in b
<sect3 id="inlinable-pragma">
<title>INLINABLE pragma</title>
-<para>An INLINABLE pragma works very like an INLINE pragma, except that:
+<para>An <literal>{-# INLINABLE f #-}</literal> pragma on a
+function <literal>f</literal> has the following behaviour:
<itemizedlist>
<listitem><para>
-INLINE says "please inline me", but INLINABLE says "feel free to inline me; use your
+While <literal>INLINE</literal> says "please inline me", the <literal>INLINABLE</literal>
+says "feel free to inline me; use your
discretion". In other words the choice is left to GHC, which uses the same
-rules as for pragma-free functions. Unlike INLINE, That decision is made at
+rules as for pragma-free functions. Unlike <literal>INLINE</literal>, that decision is made at
the <emphasis>call site</emphasis>, and
will therefore be affected by the inlining threshold, optimisation level etc.
</para></listitem>
<listitem><para>
-Like INLINE, the INLINABLE pragma retains a copy of the original RHS for
+Like <literal>INLINE</literal>, the <literal>INLINABLE</literal> pragma retains a
+copy of the original RHS for
inlining purposes, and persists it in the interface file, regardless of
the size of the RHS.
</para></listitem>
+
<listitem><para>
-If you use the special function <literal>inline</literal> (<xref linkend="special-ids"/>)
-to force inlining at a
-call site, you will get a copy of the the original RHS.
-Indeed, if you intend to use <literal>inline f</literal> it
-is a good idea to mark the definition of <literal>f</literal> INLINABLE,
+One way to use <literal>INLINABLE</literal> is in conjunction with
+the special function <literal>inline</literal> (<xref linkend="special-ids"/>).
+The call <literal>inline f</literal> tries very hard to inline <literal>f</literal>.
+To make sure that <literal>f</literal> can be inlined,
+it is a good idea to mark the definition
+of <literal>f</literal> as <literal>INLINABLE</literal>,
so that GHC guarantees to expose an unfolding regardless of how big it is.
+Moreover, by annotating <literal>f</literal> as <literal>INLINABLE</literal>,
+you ensure that <literal>f</literal>'s original RHS is inlined, rather than
+whatever random optimised version of <literal>f</literal> GHC's optimiser
+has produced.
+</para></listitem>
+
+<listitem><para>
+The <literal>INLINABLE</literal> pragma also works with <literal>SPECIALISE</literal>:
+if you mark function <literal>f</literal> as <literal>INLINABLE</literal>, then
+you can subsequently <literal>SPECIALISE</literal> in another module
+(see <xref linkend="specialize-pragma"/>).</para></listitem>
+
+<listitem><para>
+Unlike <literal>INLINE</literal>, it is OK to use
+an <literal>INLINABLE</literal> pragma on a recursive function.
+The principal reason do to so to allow later use of <literal>SPECIALISE</literal>
</para></listitem>
</itemizedlist>
</para>
well. If you use this kind of specialisation, let us know how well it works.
</para>
+ <sect3 id="specialize-inline">
+ <title>SPECIALIZE INLINE</title>
+
<para>A <literal>SPECIALIZE</literal> pragma can optionally be followed with a
<literal>INLINE</literal> or <literal>NOINLINE</literal> pragma, optionally
followed by a phase, as described in <xref linkend="inline-noinline-pragma"/>.
unrolling of the indexing function.</para>
<para>Warning: you can make GHC diverge by using <literal>SPECIALISE INLINE</literal>
on an ordinarily-recursive function.</para>
+</sect3>
+
+<sect3><title>SPECIALIZE for imported functions</title>
+
+<para>
+Generally, you can only give a <literal>SPECIALIZE</literal> pragma
+for a function defined in the same module.
+However if a function <literal>f</literal> is given an <literal>INLINABLE</literal>
+pragma at its definition site, then it can subequently be specialised by
+importing modules (see <xref linkend="inlinable-pragma"/>).
+For example
+<programlisting>
+module Map( lookup, blah blah ) where
+ lookup :: Ord key => [(key,a)] -> key -> Maybe a
+ lookup = ...
+ {-# INLINABLE lookup #-}
+
+module Client where
+ import Map( lookup )
+
+ data T = T1 | T2 deriving( Eq, Ord )
+ {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a
+</programlisting>
+Here, <literal>lookup</literal> is declared <literal>INLINABLE</literal>, but
+it cannot be specialised for type <literal>T</literal> at its definition site,
+because that type does not exist yet. Instead a client module can define <literal>T</literal>
+and then specialise <literal>lookup</literal> at that type.
+</para>
+<para>
+Moreover, every module that imports <literal>Client</literal> (or imports a module
+that imports <literal>Client</literal>, transitively) will "see", and make use of,
+the specialised version of <literal>lookup</literal>. You don't need to put
+a <literal>SPECIALIZE</literal> pragma in every module.
+</para>
+<para>
+Moreover you often don't even need the <literal>SPECIALIZE</literal> pragma in the
+first place. When compiling a module M,
+GHC's optimiser (with -O) automatically considers each top-level
+overloaded function declared in M, and specialises it
+for the different types at which it is called in M. The optimiser
+<emphasis>also</emphasis> considers each <emphasis>imported</emphasis>
+<literal>INLINABLE</literal> overloaded function, and specialises it
+for the different types at which it is called in M.
+So in our example, it would be enough for <literal>lookup</literal> to
+be called at type <literal>T</literal>:
+<programlisting>
+module Client where
+ import Map( lookup )
+
+ data T = T1 | T2 deriving( Eq, Ord )
+
+ findT1 :: [(T,a)] -> Maybe a
+ findT1 m = lookup m T1 -- A call of lookup at type T
+</programlisting>
+However, sometimes there are no such calls, in which case the
+pragma can be useful.
+</para>
+</sect3>
+
+<sect3><title>Obselete SPECIALIZE syntax</title>
<para>Note: In earlier versions of GHC, it was possible to provide your own
specialised function for a given type:
This feature has been removed, as it is now subsumed by the
<literal>RULES</literal> pragma (see <xref linkend="rule-spec"/>).</para>
+</sect3>
</sect2>
directly in the <function>T</function> constructor. The
unpacker can see through newtypes, too.</para>
- <para>If a field cannot be unpacked, you will not get a warning,
- so it might be an idea to check the generated code with
- <option>-ddump-simpl</option>.</para>
-
<para>See also the <option>-funbox-strict-fields</option> flag,
which essentially has the effect of adding
<literal>{-# UNPACK #-}</literal> to every strict
<para>
Use the debug flag <option>-ddump-simpl-stats</option> to see what rules fired.
If you need more information, then <option>-ddump-rule-firings</option> shows you
-each individual rule firing in detail.
+each individual rule firing and <option>-ddump-rule-rewrites</option> also shows what the code looks like before and after the rewrite.
</para>
<sect2>
<listitem>
<para>
- Use <option>-ddump-rule-firings</option> to see in great detail what rules are being fired.
+ Use <option>-ddump-rule-firings</option> or <option>-ddump-rule-rewrites</option>
+to see in great detail what rules are being fired.
If you add <option>-dppr-debug</option> you get a still more detailed listing.
</para>
</listitem>
</para>
<programlisting>
- import Generics
+ import Data.Generics
class Bin a where
toBin :: a -> [Int]
<para>
This class declaration explains how <literal>toBin</literal> and <literal>fromBin</literal>
work for arbitrary data types. They do so by giving cases for unit, product, and sum,
-which are defined thus in the library module <literal>Generics</literal>:
+which are defined thus in the library module <literal>Data.Generics</literal>:
</para>
<programlisting>
data Unit = Unit
<para>To use generics you need to</para>
<itemizedlist>
<listitem>
- <para>Use the flags <option>-fglasgow-exts</option> (to enable the extra syntax),
- <option>-XGenerics</option> (to generate extra per-data-type code),
- and <option>-package lang</option> (to make the <literal>Generics</literal> library
- available. </para>
+ <para>
+ Use the flags <option>-XGenerics</option> (to enable the
+ extra syntax and generate extra per-data-type code),
+ and <option>-package syb</option> (to make the
+ <literal>Data.Generics</literal> module available.
+ </para>
</listitem>
<listitem>
- <para>Import the module <literal>Generics</literal> from the
- <literal>lang</literal> package. This import brings into
+ <para>Import the module <literal>Data.Generics</literal> from the
+ <literal>syb</literal> package. This import brings into
scope the data types <literal>Unit</literal>,
<literal>:*:</literal>, and <literal>:+:</literal>. (You
don't need this import if you don't mention these types
projects / ghc-hetmet.git / blobdiff