</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-XQuasiQuotes</option></term>
+ <listitem>
+ <para>Enables quasiquotation (see <xref
+ linkend="th-quasiquotation"/>).</para>
+
+ <para>Syntax stolen:
+ <literal>[:<replaceable>varid</replaceable>|</literal>.</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect1>
<para> Indeed,
the result of such processing is part of the description of the
<ulink
- url="http://haskell.cs.yale.edu/ghc/docs/papers/core.ps.gz">External
+ url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">External
Core language</ulink>.
So that document is a good place to look for a type-set version.
We would be very happy if someone wanted to volunteer to produce an SGML
</para>
</sect2>
+ <!-- ===================== View patterns =================== -->
+
+<sect2 id="view-patterns">
+<title>View patterns
+</title>
+
+<para>
+View patterns are enabled by the flag <literal>-XViewPatterns</literal>.
+More information and examples of view patterns can be found on the
+<ulink url="http://hackage.haskell.org/trac/ghc/wiki/ViewPatterns">Wiki
+page</ulink>.
+</para>
+
+<para>
+View patterns are somewhat like pattern guards that can be nested inside
+of other patterns. They are a convenient way of pattern-matching
+against values of abstract types. For example, in a programming language
+implementation, we might represent the syntax of the types of the
+language as follows:
+
+<programlisting>
+type Typ
+
+data TypView = Unit
+ | Arrow Typ Typ
+
+view :: Type -> TypeView
+
+-- additional operations for constructing Typ's ...
+</programlisting>
+
+The representation of Typ is held abstract, permitting implementations
+to use a fancy representation (e.g., hash-consing to managage sharing).
+
+Without view patterns, using this signature a little inconvenient:
+<programlisting>
+size :: Typ -> Integer
+size t = case view t of
+ Unit -> 1
+ Arrow t1 t2 -> size t1 + size t2
+</programlisting>
+
+It is necessary to iterate the case, rather than using an equational
+function definition. And the situation is even worse when the matching
+against <literal>t</literal> is buried deep inside another pattern.
+</para>
+
+<para>
+View patterns permit calling the view function inside the pattern and
+matching against the result:
+<programlisting>
+size (view -> Unit) = 1
+size (view -> Arrow t1 t2) = size t1 + size t2
+</programlisting>
+
+That is, we add a new form of pattern, written
+<replaceable>expression</replaceable> <literal>-></literal>
+<replaceable>pattern</replaceable> that means "apply the expression to
+whatever we're trying to match against, and then match the result of
+that application against the pattern". The expression can be any Haskell
+expression of function type, and view patterns can be used wherever
+patterns are used.
+</para>
+
+<para>
+The semantics of a pattern <literal>(</literal>
+<replaceable>exp</replaceable> <literal>-></literal>
+<replaceable>pat</replaceable> <literal>)</literal> are as follows:
+
+<itemizedlist>
+
+<listitem> Scoping:
+
+<para>The variables bound by the view pattern are the variables bound by
+<replaceable>pat</replaceable>.
+</para>
+
+<para>
+Any variables in <replaceable>exp</replaceable> are bound occurrences,
+but variables bound "to the left" in a pattern are in scope. This
+feature permits, for example, one argument to a function to be used in
+the view of another argument. For example, the function
+<literal>clunky</literal> from <xref linkend="pattern-guards" /> can be
+written using view patterns as follows:
+
+<programlisting>
+clunky env (lookup env -> Just val1) (lookup env -> Just val2) = val1 + val2
+...other equations for clunky...
+</programlisting>
+</para>
+
+<para>
+More precisely, the scoping rules are:
+<itemizedlist>
+<listitem>
+<para>
+In a single pattern, variables bound by patterns to the left of a view
+pattern expression are in scope. For example:
+<programlisting>
+example :: Maybe ((String -> Integer,Integer), String) -> Bool
+example Just ((f,_), f -> 4) = True
+</programlisting>
+
+Additionally, in function definitions, variables bound by matching earlier curried
+arguments may be used in view pattern expressions in later arguments:
+<programlisting>
+example :: (String -> Integer) -> String -> Bool
+example f (f -> 4) = True
+</programlisting>
+That is, the scoping is the same as it would be if the curried arguments
+were collected into a tuple.
+</para>
+</listitem>
+
+<listitem>
+<para>
+In mutually recursive bindings, such as <literal>let</literal>,
+<literal>where</literal>, or the top level, view patterns in one
+declaration may not mention variables bound by other declarations. That
+is, each declaration must be self-contained. For example, the following
+program is not allowed:
+<programlisting>
+let {(x -> y) = e1 ;
+ (y -> x) = e2 } in x
+</programlisting>
+
+(We may lift this
+restriction in the future; the only cost is that type checking patterns
+would get a little more complicated.)
+
+
+</para>
+</listitem>
+</itemizedlist>
+
+</para>
+</listitem>
+
+<listitem><para> Typing: If <replaceable>exp</replaceable> has type
+<replaceable>T1</replaceable> <literal>-></literal>
+<replaceable>T2</replaceable> and <replaceable>pat</replaceable> matches
+a <replaceable>T2</replaceable>, then the whole view pattern matches a
+<replaceable>T1</replaceable>.
+</para></listitem>
+
+<listitem><para> Matching: To the equations in Section 3.17.3 of the
+<ulink url="http://www.haskell.org/onlinereport/">Haskell 98
+Report</ulink>, add the following:
+<programlisting>
+case v of { (e -> p) -> e1 ; _ -> e2 }
+ =
+case (e v) of { p -> e1 ; _ -> e2 }
+</programlisting>
+That is, to match a variable <replaceable>v</replaceable> against a pattern
+<literal>(</literal> <replaceable>exp</replaceable>
+<literal>-></literal> <replaceable>pat</replaceable>
+<literal>)</literal>, evaluate <literal>(</literal>
+<replaceable>exp</replaceable> <replaceable> v</replaceable>
+<literal>)</literal> and match the result against
+<replaceable>pat</replaceable>.
+</para></listitem>
+
+<listitem><para> Efficiency: When the same view function is applied in
+multiple branches of a function definition or a case expression (e.g.,
+in <literal>size</literal> above), GHC makes an attempt to collect these
+applications into a single nested case expression, so that the view
+function is only applied once. Pattern compilation in GHC follows the
+matrix algorithm described in Chapter 4 of <ulink
+url="http://research.microsoft.com/~simonpj/Papers/slpj-book-1987/">The
+Implementation of Functional Programming Languages</ulink>. When the
+top rows of the first column of a matrix are all view patterns with the
+"same" expression, these patterns are transformed into a single nested
+case. This includes, for example, adjacent view patterns that line up
+in a tuple, as in
+<programlisting>
+f ((view -> A, p1), p2) = e1
+f ((view -> B, p3), p4) = e2
+</programlisting>
+</para>
+
+<para> The current notion of when two view pattern expressions are "the
+same" is very restricted: it is not even full syntactic equality.
+However, it does include variables, literals, applications, and tuples;
+e.g., two instances of <literal>view ("hi", "there")</literal> will be
+collected. However, the current implementation does not compare up to
+alpha-equivalence, so two instances of <literal>(x, view x ->
+y)</literal> will not be coalesced.
+</para>
+
+</listitem>
+
+</itemizedlist>
+</para>
+
+</sect2>
+
<!-- ===================== Recursive do-notation =================== -->
<sect2 id="mdo-notation">
</para>
<para>
-The web page: <ulink url="http://www.cse.ogi.edu/PacSoft/projects/rmb">http://www.cse.ogi.edu/PacSoft/projects/rmb</ulink>
+The web page: <ulink url="http://www.cse.ogi.edu/PacSoft/projects/rmb/">http://www.cse.ogi.edu/PacSoft/projects/rmb/</ulink>
contains up to date information on recursive monadic bindings.
</para>
branches.</para>
</sect2>
+
+ <!-- ===================== TRANSFORM LIST COMPREHENSIONS =================== -->
+
+ <sect2 id="generalised-list-comprehensions">
+ <title>Generalised (SQL-Like) List Comprehensions</title>
+ <indexterm><primary>list comprehensions</primary><secondary>generalised</secondary>
+ </indexterm>
+ <indexterm><primary>extended list comprehensions</primary>
+ </indexterm>
+ <indexterm><primary>group</primary></indexterm>
+ <indexterm><primary>sql</primary></indexterm>
+
+
+ <para>Generalised list comprehensions are a further enhancement to the
+ list comprehension syntatic 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>Here is an example:
+<programlisting>
+employees = [ ("Simon", "MS", 80)
+, ("Erik", "MS", 100)
+, ("Phil", "Ed", 40)
+, ("Gordon", "Ed", 45)
+, ("Paul", "Yale", 60)]
+
+output = [ (the dept, sum salary)
+| (name, dept, salary) <- employees
+, then group by dept
+, then sortWith by (sum salary)
+, then take 5 ]
+</programlisting>
+In this example, the list <literal>output</literal> would take on
+ the value:
+
+<programlisting>
+[("Yale", 60), ("Ed", 85), ("MS", 180)]
+</programlisting>
+</para>
+<para>There are three new keywords: <literal>group</literal>, <literal>by</literal>, and <literal>using</literal>.
+(The function <literal>sortWith</literal> is not a keyword; it is an ordinary
+function that is exported by <literal>GHC.Exts</literal>.)</para>
+
+<para>There are five new forms of compehension qualifier,
+all introduced by the (existing) keyword <literal>then</literal>:
+ <itemizedlist>
+ <listitem>
+
+<programlisting>
+then f
+</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
+ motivating example, as this form is used to apply <literal>take 5</literal>.
+
+ </listitem>
+
+
+ <listitem>
+<para>
+<programlisting>
+then f by e
+</programlisting>
+
+ This form is similar to the previous one, but allows you to create a function
+ which will be passed as the first argument to f. As a consequence f must have
+ the type <literal>forall a. (a -> t) -> [a] -> [a]</literal>. As you can see
+ from the type, this function lets f "project out" some information
+ from the elements of the list it is transforming.</para>
+
+ <para>An example is shown in the opening example, where <literal>sortWith</literal>
+ is supplied with a function that lets it find out the <literal>sum salary</literal>
+ for any item in the list comprehension it transforms.</para>
+
+ </listitem>
+
+
+ <listitem>
+
+<programlisting>
+then group by e using f
+</programlisting>
+
+ <para>This is the most general of the grouping-type statements. In this form,
+ f is required to have type <literal>forall a. (a -> t) -> [a] -> [[a]]</literal>.
+ As with the <literal>then f by e</literal> case above, the first argument
+ is a function supplied to f by the compiler which lets it compute e on every
+ element of the list being transformed. However, unlike the non-grouping case,
+ f additionally partitions the list into a number of sublists: this means that
+ at every point after this statement, binders occuring before it in the comprehension
+ refer to <emphasis>lists</emphasis> of possible values, not single values. To help understand
+ this, let's look at an example:</para>
+
+<programlisting>
+-- This works similarly to groupWith in GHC.Exts, but doesn't sort its input first
+groupRuns :: Eq b => (a -> b) -> [a] -> [[a]]
+groupRuns f = groupBy (\x y -> f x == f y)
+
+output = [ (the x, y)
+| x <- ([1..3] ++ [1..2])
+, y <- [4..6]
+, then group by x using groupRuns ]
+</programlisting>
+
+ <para>This results in the variable <literal>output</literal> taking on the value below:</para>
+
+<programlisting>
+[(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])]
+</programlisting>
+
+ <para>Note that we have used the <literal>the</literal> function to change the type
+ of x from a list to its original numeric type. The variable y, in contrast, is left
+ unchanged from the list form introduced by the grouping.</para>
+
+ </listitem>
+
+ <listitem>
+
+<programlisting>
+then group by e
+</programlisting>
+
+ <para>This form of grouping is essentially the same as the one described above. However,
+ since no function to use for the grouping has been supplied it will fall back on the
+ <literal>groupWith</literal> function defined in
+ <ulink url="../libraries/base/GHC-Exts.html"><literal>GHC.Exts</literal></ulink>. This
+ is the form of the group statement that we made use of in the opening example.</para>
+
+ </listitem>
+
+
+ <listitem>
+
+<programlisting>
+then group using f
+</programlisting>
+
+ <para>With this form of the group statement, f is required to simply have the type
+ <literal>forall a. [a] -> [[a]]</literal>, which will be used to group up the
+ comprehension so far directly. An example of this form is as follows:</para>
+
+<programlisting>
+output = [ x
+| y <- [1..5]
+, x <- "hello"
+, then group using inits]
+</programlisting>
+
+ <para>This will yield a list containing every prefix of the word "hello" written out 5 times:</para>
+
+<programlisting>
+["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...]
+</programlisting>
+
+ </listitem>
+</itemizedlist>
+</para>
+ </sect2>
+
+ <!-- ===================== REBINDABLE SYNTAX =================== -->
<sect2 id="rebindable-syntax">
<title>Rebindable syntax</title>
-
<para>GHC allows most kinds of built-in syntax to be rebound by
the user, to facilitate replacing the <literal>Prelude</literal>
with a home-grown version, for example.</para>
allows you to define postfix operators. The extension is this: the left section
<programlisting>
(e !)
-</programlisting>
+</programlisting>
is equivalent (from the point of view of both type checking and execution) to the expression
<programlisting>
((!) e)
-</programlisting>
+</programlisting>
(for any expression <literal>e</literal> and operator <literal>(!)</literal>.
The strict Haskell 98 interpretation is that the section is equivalent to
<programlisting>
(\y -> (!) e y)
-</programlisting>
+</programlisting>
That is, the operator must be a function of two arguments. GHC allows it to
take only one argument, and that in turn allows you to write the function
postfix.
records from different modules that use the same field name.
</para>
</sect2>
+
+ <!-- ===================== Record puns =================== -->
+
+<sect2 id="record-puns">
+<title>Record puns
+</title>
+
+<para>
+Record puns are enabled by the flag <literal>-XRecordPuns</literal>.
+</para>
+
+<para>
+When using records, it is common to write a pattern that binds a
+variable with the same name as a record field, such as:
+
+<programlisting>
+data C = C {a :: Int}
+f (C {a = a}) = a
+</programlisting>
+</para>
+
+<para>
+Record punning permits the variable name to be elided, so one can simply
+write
+
+<programlisting>
+f (C {a}) = a
+</programlisting>
+
+to mean the same pattern as above. That is, in a record pattern, the
+pattern <literal>a</literal> expands into the pattern <literal>a =
+a</literal> for the same name <literal>a</literal>.
+</para>
+
+<para>
+Note that puns and other patterns can be mixed in the same record:
+<programlisting>
+data C = C {a :: Int, b :: Int}
+f (C {a, b = 4}) = a
+</programlisting>
+and that puns can be used wherever record patterns occur (e.g. in
+<literal>let</literal> bindings or at the top-level).
+</para>
+
+<para>
+Record punning can also be used in an expression, writing, for example,
+<programlisting>
+let a = 1 in C {a}
+</programlisting>
+instead of
+<programlisting>
+let a = 1 in C {a = a}
+</programlisting>
+
+Note that this expansion is purely syntactic, so the record pun
+expression refers to the nearest enclosing variable that is spelled the
+same as the field name.
+</para>
+
+</sect2>
+
+ <!-- ===================== Record wildcards =================== -->
+
+<sect2 id="record-wildcards">
+<title>Record wildcards
+</title>
+
+<para>
+Record wildcards are enabled by the flag <literal>-XRecordWildCards</literal>.
+</para>
+
+<para>
+For records with many fields, it can be tiresome to write out each field
+individually in a record pattern, as in
+<programlisting>
+data C = C {a :: Int, b :: Int, c :: Int, d :: Int}
+f (C {a = 1, b = b, c = c, d = d}) = b + c + d
+</programlisting>
+</para>
+
+<para>
+Record wildcard syntax permits a (<literal>..</literal>) in a record
+pattern, where each elided field <literal>f</literal> is replaced by the
+pattern <literal>f = f</literal>. For example, the above pattern can be
+written as
+<programlisting>
+f (C {a = 1, ..}) = b + c + d
+</programlisting>
+</para>
+
+<para>
+Note that wildcards can be mixed with other patterns, including puns
+(<xref linkend="record-puns"/>); for example, in a pattern <literal>C {a
+= 1, b, ..})</literal>. Additionally, record wildcards can be used
+wherever record patterns occur, including in <literal>let</literal>
+bindings and at the top-level. For example, the top-level binding
+<programlisting>
+C {a = 1, ..} = e
+</programlisting>
+defines <literal>b</literal>, <literal>c</literal>, and
+<literal>d</literal>.
+</para>
+
+<para>
+Record wildcards can also be used in expressions, writing, for example,
+
+<programlisting>
+let {a = 1; b = 2; c = 3; d = 4} in C {..}
+</programlisting>
+
+in place of
+
+<programlisting>
+let {a = 1; b = 2; c = 3; d = 4} in C {a=a, b=b, c=c, d=d}
+</programlisting>
+
+Note that this expansion is purely syntactic, so the record wildcard
+expression refers to the nearest enclosing variables that are spelled
+the same as the omitted field names.
+</para>
+
+</sect2>
+
+ <!-- ===================== Local fixity declarations =================== -->
+
+<sect2 id="local-fixity-declarations">
+<title>Local Fixity Declarations
+</title>
+
+<para>A careful reading of the Haskell 98 Report reveals that fixity
+declarations (<literal>infix</literal>, <literal>infixl</literal>, and
+<literal>infixr</literal>) are permitted to appear inside local bindings
+such those introduced by <literal>let</literal> and
+<literal>where</literal>. However, the Haskell Report does not specify
+the semantics of such bindings very precisely.
+</para>
+
+<para>In GHC, a fixity declaration may accompany a local binding:
+<programlisting>
+let f = ...
+ infixr 3 `f`
+in
+ ...
+</programlisting>
+and the fixity declaration applies wherever the binding is in scope.
+For example, in a <literal>let</literal>, it applies in the right-hand
+sides of other <literal>let</literal>-bindings and the body of the
+<literal>let</literal>C. Or, in recursive <literal>do</literal>
+expressions (<xref linkend="mdo-notation"/>), the local fixity
+declarations of aA <literal>let</literal> statement scope over other
+statements in the group, just as the bound name does.
+</para>
+
+Moreover, a local fixity declatation *must* accompany a local binding of
+that name: it is not possible to revise the fixity of name bound
+elsewhere, as in
+<programlisting>
+let infixr 9 $ in ...
+</programlisting>
+
+Because local fixity declarations are technically Haskell 98, no flag is
+necessary to enable them.
+</sect2>
+
</sect1>
</sect3>
-<sect3>
-<title>Type classes</title>
+<sect3 id="existential-with-context">
+<title>Existentials and type classes</title>
<para>
An easy extension is to allow
extract it on pattern matching.
</para>
-<para>
-Notice the way that the syntax fits smoothly with that used for
-universal quantification earlier.
-</para>
-
</sect3>
<sect3 id="existential-records">
generated by the call to <literal>elem</literal>, so that the type of
<literal>insert</literal> itself has no <literal>Eq</literal> constraint.
</para>
-<para>This behaviour contrasts with Haskell 98's peculiar treament of
-contexts on a data type declaration (Section 4.2.1 of the Haskell 98 Report).
-In Haskell 98 the defintion
-<programlisting>
- data Eq a => Set' a = MkSet' [a]
-</programlisting>
-gives <literal>MkSet'</literal> the same type as <literal>MkSet</literal> above. But instead of
-<emphasis>making available</emphasis> an <literal>(Eq a)</literal> constraint, pattern-matching
-on <literal>MkSet'</literal> <emphasis>requires</emphasis> an <literal>(Eq a)</literal> constraint!
-GHC faithfully implements this behaviour, odd though it is. But for GADT-style declarations,
-GHC's behaviour is much more useful, as well as much more intuitive.</para>
<para>
-For example, a possible application of GHC's behaviour is to reify dictionaries:
+For example, one possible application is to reify dictionaries:
<programlisting>
data NumInst a where
MkNumInst :: Num a => NumInst a
Here, a value of type <literal>NumInst a</literal> is equivalent
to an explicit <literal>(Num a)</literal> dictionary.
</para>
+<para>
+All this applies to constructors declared using the syntax of <xref linkend="existential-with-context"/>.
+For example, the <literal>NumInst</literal> data type above could equivalently be declared
+like this:
+<programlisting>
+ data NumInst a
+ = Num a => MkNumInst (NumInst a)
+</programlisting>
+Notice that, unlike the situation when declaring an existental, there is
+no <literal>forall</literal>, because the <literal>Num</literal> constrains the
+data type's univerally quantified type variable <literal>a</literal>.
+A constructor may have both universal and existential type variables: for example,
+the following two declarations are equivalent:
+<programlisting>
+ data T1 a
+ = forall b. (Num a, Eq b) => MkT1 a b
+ data T2 a where
+ MkT2 :: (Num a, Eq b) => a -> b -> T2 a
+</programlisting>
+</para>
+<para>All this behaviour contrasts with Haskell 98's peculiar treatment of
+contexts on a data type declaration (Section 4.2.1 of the Haskell 98 Report).
+In Haskell 98 the definition
+<programlisting>
+ data Eq a => Set' a = MkSet' [a]
+</programlisting>
+gives <literal>MkSet'</literal> the same type as <literal>MkSet</literal> above. But instead of
+<emphasis>making available</emphasis> an <literal>(Eq a)</literal> constraint, pattern-matching
+on <literal>MkSet'</literal> <emphasis>requires</emphasis> an <literal>(Eq a)</literal> constraint!
+GHC faithfully implements this behaviour, odd though it is. But for GADT-style declarations,
+GHC's behaviour is much more useful, as well as much more intuitive.
+</para>
<para>
The rest of this section gives further details about GADT-style data
<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 exmaple
+For example
<programlisting>
aPerson = Adult { name = "Fred", children = [] }
A precise specification of the type rules is beyond what this user manual aspires to,
but the design closely follows that described in
the paper <ulink
-url="http://research.microsoft.com/%7Esimonpj/papers/gadt/index.htm">Simple
+url="http://research.microsoft.com/%7Esimonpj/papers/gadt/">Simple
unification-based type inference for GADTs</ulink>,
(ICFP 2006).
The general principle is this: <emphasis>type refinement is only carried out
<para>
These and many other examples are given in papers by Hongwei Xi, and
Tim Sheard. There is a longer introduction
-<ulink url="http://haskell.org/haskellwiki/GADT">on the wiki</ulink>,
+<ulink url="http://www.haskell.org/haskellwiki/GADT">on the wiki</ulink>,
and Ralf Hinze's
<ulink url="http://www.informatik.uni-bonn.de/~ralf/publications/With.pdf">Fun with phantom types</ulink> also has a number of examples. Note that papers
may use different notation to that implemented in GHC.
</para>
<para>
The rest of this section outlines the extensions to GHC that support GADTs. The extension is enabled with
-<option>-XGADTs</option>.
+<option>-XGADTs</option>. The <option>-XGADTs</option> flag also sets <option>-XRelaxedPolyRec</option>.
<itemizedlist>
<listitem><para>
A GADT can only be declared using GADT-style syntax (<xref linkend="gadt-style"/>);
<listitem><para>
You cannot use a <literal>deriving</literal> clause for a GADT; only for
-an ordianary data type.
+an ordinary data type.
</para></listitem>
<listitem><para>
<para>
GHC takes a conservative position: it accepts the first two, but not the third. The rule is this:
each constraint in the inferred instance context must consist only of type variables,
-with no repititions.
+with no repetitions.
</para>
<para>
This rule is applied regardless of flags. If you want a more exotic context, you can write
deriving instance MonadState Int Foo
</programlisting>
GHC always treats the <emphasis>last</emphasis> parameter of the instance
-(<literal>Foo</literal> in this exmample) as the type whose instance is being derived.
+(<literal>Foo</literal> in this example) as the type whose instance is being derived.
</para>
</sect2>
other classes you have to write an explicit instance declaration. For
example, if you define
-<programlisting>
+<programlisting>
newtype Dollars = Dollars Int
-</programlisting>
+</programlisting>
and you want to use arithmetic on <literal>Dollars</literal>, you have to
explicitly define an instance of <literal>Num</literal>:
-<programlisting>
+<programlisting>
instance Num Dollars where
Dollars a + Dollars b = Dollars (a+b)
...
GHC now permits such instances to be derived instead,
using the flag <option>-XGeneralizedNewtypeDeriving</option>,
so one can write
-<programlisting>
+<programlisting>
newtype Dollars = Dollars Int deriving (Eq,Show,Num)
-</programlisting>
+</programlisting>
and the implementation uses the <emphasis>same</emphasis> <literal>Num</literal> dictionary
for <literal>Dollars</literal> as for <literal>Int</literal>. Notionally, the compiler
derives an instance declaration of the form
-<programlisting>
+<programlisting>
instance Num Int => Num Dollars
-</programlisting>
+</programlisting>
which just adds or removes the <literal>newtype</literal> constructor according to the type.
</para>
way. For example, suppose we have implemented state and failure monad
transformers, such that
-<programlisting>
+<programlisting>
instance Monad m => Monad (State s m)
instance Monad m => Monad (Failure m)
-</programlisting>
+</programlisting>
In Haskell 98, we can define a parsing monad by
-<programlisting>
+<programlisting>
type Parser tok m a = State [tok] (Failure m) a
-</programlisting>
+</programlisting>
which is automatically a monad thanks to the instance declarations
above. With the extension, we can make the parser type abstract,
without needing to write an instance of class <literal>Monad</literal>, via
-<programlisting>
+<programlisting>
newtype Parser tok m a = Parser (State [tok] (Failure m) a)
deriving Monad
</programlisting>
In this case the derived instance declaration is of the form
-<programlisting>
+<programlisting>
instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)
-</programlisting>
+</programlisting>
Notice that, since <literal>Monad</literal> is a constructor class, the
instance is a <emphasis>partial application</emphasis> of the new type, not the
application'' of the class appears in the <literal>deriving</literal>
clause. For example, given the class
-<programlisting>
+<programlisting>
class StateMonad s m | m -> s where ...
instance Monad m => StateMonad s (State s m) where ...
-</programlisting>
+</programlisting>
then we can derive an instance of <literal>StateMonad</literal> for <literal>Parser</literal>s by
-<programlisting>
+<programlisting>
newtype Parser tok m a = Parser (State [tok] (Failure m) a)
deriving (Monad, StateMonad [tok])
</programlisting>
The derived instance is obtained by completing the application of the
class to the new type:
-<programlisting>
+<programlisting>
instance StateMonad [tok] (State [tok] (Failure m)) =>
StateMonad [tok] (Parser tok m)
</programlisting>
Derived instance declarations are constructed as follows. Consider the
declaration (after expansion of any type synonyms)
-<programlisting>
+<programlisting>
newtype T v1...vn = T' (t vk+1...vn) deriving (c1...cm)
-</programlisting>
+</programlisting>
where
<itemizedlist>
</itemizedlist>
Then, for each <literal>ci</literal>, the derived instance
declaration is:
-<programlisting>
+<programlisting>
instance ci t => ci (T v1...vk)
</programlisting>
As an example which does <emphasis>not</emphasis> work, consider
-<programlisting>
+<programlisting>
newtype NonMonad m s = NonMonad (State s m s) deriving Monad
-</programlisting>
+</programlisting>
Here we cannot derive the instance
-<programlisting>
+<programlisting>
instance Monad (State s m) => Monad (NonMonad m)
-</programlisting>
+</programlisting>
because the type variable <literal>s</literal> occurs in <literal>State s m</literal>,
and so cannot be "eta-converted" away. It is a good thing that this
important, since we can only derive instances for the last one. If the
<literal>StateMonad</literal> class above were instead defined as
-<programlisting>
+<programlisting>
class StateMonad m s | m -> s where ...
</programlisting>
<para>
This section, and the next one, documents GHC's type-class extensions.
There's lots of background in the paper <ulink
-url="http://research.microsoft.com/~simonpj/Papers/type-class-design-space" >Type
-classes: exploring the design space</ulink > (Simon Peyton Jones, Mark
+url="http://research.microsoft.com/~simonpj/Papers/type-class-design-space/">Type
+classes: exploring the design space</ulink> (Simon Peyton Jones, Mark
Jones, Erik Meijer).
</para>
<para>
The type of <literal>elem</literal> is illegal in Haskell 98, because it
contains the constraint <literal>Eq a</literal>, constrains only the
class type variable (in this case <literal>a</literal>).
-GHC lifts this restriction.
+GHC lifts this restriction (flag <option>-XConstrainedClassMethods</option>).
</para>
</title>
<para> Functional dependencies are implemented as described by Mark Jones
-in “<ulink url="http://www.cse.ogi.edu/~mpj/pubs/fundeps.html">Type Classes with Functional Dependencies</ulink>”, Mark P. Jones,
+in “<ulink url="http://citeseer.ist.psu.edu/jones00type.html">Type Classes with Functional Dependencies</ulink>”, Mark P. Jones,
In Proceedings of the 9th European Symposium on Programming,
ESOP 2000, Berlin, Germany, March 2000, Springer-Verlag LNCS 1782,
.
is a type variable that occurs in the head.
</para>
<para>
-The <option>-fglasgow-exts</option> flag loosens these restrictions
+The <option>-XFlexibleInstances</option> flag loosens these restrictions
considerably. Firstly, multi-parameter type classes are permitted. Secondly,
the context and head of the instance declaration can each consist of arbitrary
(well-kinded) assertions <literal>(C t1 ... tn)</literal> subject only to the
class F a b | a->b
instance F [a] [[a]]
instance (D c, F a c) => D [a] -- 'c' is not mentioned in the head
-</programlisting>
+</programlisting>
Similarly, it can be tempting to lift the coverage condition:
<programlisting>
class Mul a b c | a b -> c where
The willingness to be overlapped or incoherent is a property of
the <emphasis>instance declaration</emphasis> itself, controlled by the
presence or otherwise of the <option>-XOverlappingInstances</option>
-and <option>-XIncoherentInstances</option> flags when that mdodule is
+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:
<itemizedlist>
fromString cs = cs
</programlisting>
The class <literal>IsString</literal> is not in scope by default. If you want to mention
-it explicitly (for exmaple, to give an instance declaration for it), you can import it
+it explicitly (for example, to give an instance declaration for it), you can import it
from module <literal>GHC.Exts</literal>.
</para>
<para>
</para></listitem>
<listitem><para>
-The standard defaulting rule (<ulink url="http://haskell.org/onlinereport/decls.html#sect4.3.4">Haskell Report, Section 4.3.4</ulink>)
+The standard defaulting rule (<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.3.4">Haskell Report, Section 4.3.4</ulink>)
is extended thus: defaulting applies when all the unresolved constraints involve standard classes
<emphasis>or</emphasis> <literal>IsString</literal>; and at least one is a numeric class
<emphasis>or</emphasis> <literal>IsString</literal>.
<sect2 id="type-restrictions">
<title>Type signatures</title>
-<sect3><title>The context of a type signature</title>
+<sect3 id="flexible-contexts"><title>The context of a type signature</title>
<para>
Unlike Haskell 98, constraints in types do <emphasis>not</emphasis> have to be of
the form <emphasis>(class type-variable)</emphasis> or
Boston, Jan 2000.
</para>
-<para>(Most of the following, stil rather incomplete, documentation is
+<para>(Most of the following, still rather incomplete, documentation is
due to Jeff Lewis.)</para>
<para>Implicit parameter support is enabled with the option
right-hand side, so the implicit parameter <literal>?acc</literal> is not
passed to the recursive call. In the latter case, because <literal>len_acc2</literal>
has a type signature, the recursive call is made to the
-<emphasis>polymoprhic</emphasis> version, which takes <literal>?acc</literal>
+<emphasis>polymorphic</emphasis> version, which takes <literal>?acc</literal>
as an implicit parameter. So we get the following results in GHCi:
<programlisting>
Prog> len1 "hello"
<itemizedlist>
<listitem> <para> '<literal>?x</literal>' and '<literal>%x</literal>'
are entirely distinct implicit parameters: you
- can use them together and they won't intefere with each other. </para>
+ can use them together and they won't interfere with each other. </para>
</listitem>
<listitem> <para> You can bind linear implicit parameters in 'with' clauses. </para> </listitem>
</para>
<para>
GHC now instead allows you to specify the kind of a type variable directly, wherever
-a type variable is explicitly bound. Namely:
+a type variable is explicitly bound, with the flag <option>-XKindSignatures</option>.
+</para>
+<para>
+This flag enables kind signatures in the following places:
<itemizedlist>
<listitem><para><literal>data</literal> declarations:
<screen>
it has rank-2 types on the left of a function arrow.
</para>
<para>
-GHC allows types of arbitrary rank; you can nest <literal>forall</literal>s
-arbitrarily deep in function arrows. (GHC used to be restricted to rank 2, but
-that restriction has now been lifted.)
+GHC has three flags to control higher-rank types:
+<itemizedlist>
+<listitem><para>
+ <option>-XPolymorphicComponents</option>: data constructors (only) can have polymorphic argment types.
+</para></listitem>
+<listitem><para>
+ <option>-XRank2Types</option>: any function (including data constructors) can have a rank-2 type.
+</para></listitem>
+<listitem><para>
+ <option>-XRankNTypes</option>: any function (including data constructors) can have an arbitrary-rank type.
+That is, you can nest <literal>forall</literal>s
+arbitrarily deep in function arrows.
In particular, a forall-type (also called a "type scheme"),
including an operational type class context, is legal:
<itemizedlist>
<listitem> <para> As the type of an implicit parameter </para> </listitem>
<listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables"/>) </para> </listitem>
</itemizedlist>
+</para></listitem>
+</itemizedlist>
Of course <literal>forall</literal> becomes a keyword; you can't use <literal>forall</literal> as
a type variable any more!
</para>
<sect2 id="impredicative-polymorphism">
<title>Impredicative polymorphism
</title>
-<para>GHC supports <emphasis>impredicative polymorphism</emphasis>. This means
+<para>GHC supports <emphasis>impredicative polymorphism</emphasis>,
+enabled with <option>-XImpredicativeTypes</option>.
+This means
that you can call a polymorphic function at a polymorphic type, and
parameterise data structures over polymorphic types. For example:
<programlisting>
[a])</literal>.
</para>
<para>The technical details of this extension are described in the paper
-<ulink url="http://research.microsoft.com/%7Esimonpj/papers/boxy">Boxy types:
+<ulink url="http://research.microsoft.com/%7Esimonpj/papers/boxy/">Boxy types:
type inference for higher-rank types and impredicativity</ulink>,
which appeared at ICFP 2006.
</para>
it becomes possible to do so.
</para>
<para>Lexically-scoped type variables are enabled by
-<option>-fglasgow-exts</option>.
+<option>-XScopedTypeVariables</option>. This flag implies <option>-XRelaxedPolyRec</option>.
</para>
<para>Note: GHC 6.6 contains substantial changes to the way that scoped type
variables work, compared to earlier releases. Read this section
design.)</para></listitem>
<listitem><para>Furthermore, distinct lexical type variables stand for distinct
type variables. This means that every programmer-written type signature
-(includin one that contains free scoped type variables) denotes a
+(including one that contains free scoped type variables) denotes a
<emphasis>rigid</emphasis> type; that is, the type is fully known to the type
checker, and no inference is involved.</para></listitem>
<listitem><para>Lexical type variables may be alpha-renamed freely, without
</itemizedlist>
</para>
<para>
-In Haskell, a programmer-written type signature is implicitly quantifed over
+In Haskell, a programmer-written type signature is implicitly quantified over
its free type variables (<ulink
-url="http://haskell.org/onlinereport/decls.html#sect4.1.2">Section
+url="http://www.haskell.org/onlinereport/decls.html#sect4.1.2">Section
4.1.2</ulink>
of the Haskel Report).
Lexically scoped type variables affect this implicit quantification rules
<para>A declaration type signature that has <emphasis>explicit</emphasis>
quantification (using <literal>forall</literal>) brings into scope the
explicitly-quantified
-type variables, in the definition of the named function(s). For example:
+type variables, in the definition of the named function. For example:
<programlisting>
f :: forall a. [a] -> [a]
f (x:xs) = xs ++ [ x :: a ]
The "<literal>forall a</literal>" brings "<literal>a</literal>" into scope in
the definition of "<literal>f</literal>".
</para>
-<para>This only happens if the quantification in <literal>f</literal>'s type
+<para>This only happens if:
+<itemizedlist>
+<listitem><para> The quantification in <literal>f</literal>'s type
signature is explicit. For example:
<programlisting>
g :: [a] -> [a]
over the definition of "<literal>f</literal>", so "<literal>x::a</literal>"
means "<literal>x::forall a. a</literal>" by Haskell's usual implicit
quantification rules.
+</para></listitem>
+<listitem><para> The signature gives a type for a function binding or a bare variable binding,
+not a pattern binding.
+For example:
+<programlisting>
+ f1 :: forall a. [a] -> [a]
+ f1 (x:xs) = xs ++ [ x :: a ] -- OK
+
+ f2 :: forall a. [a] -> [a]
+ f2 = \(x:xs) -> xs ++ [ x :: a ] -- OK
+
+ f3 :: forall a. [a] -> [a]
+ Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ]) -- Not OK!
+</programlisting>
+The binding for <literal>f3</literal> is a pattern binding, and so its type signature
+does not bring <literal>a</literal> into scope. However <literal>f1</literal> is a
+function binding, and <literal>f2</literal> binds a bare variable; in both cases
+the type signature brings <literal>a</literal> into scope.
+</para></listitem>
+</itemizedlist>
</para>
</sect3>
<title>Pattern type signatures</title>
<para>
A type signature may occur in any pattern; this is a <emphasis>pattern type
-signature</emphasis>.
+signature</emphasis>.
For example:
<programlisting>
-- f and g assume that 'a' is already in scope
g (x::a) = x
h ((x,y) :: (Int,Bool)) = (y,x)
</programlisting>
-In the case where all the type variables in the pattern type sigature are
+In the case where all the type variables in the pattern type signature are
already in scope (i.e. bound by the enclosing context), matters are simple: the
signature simply constrains the type of the pattern in the obvious way.
</para>
<para>
-There is only one situation in which you can write a pattern type signature that
-mentions a type variable that is not already in scope, namely in pattern match
-of an existential data constructor. For example:
+Unlike expression and declaration type signatures, pattern type signatures are not implictly generalised.
+The pattern in a <emphasis>patterm binding</emphasis> may only mention type variables
+that are already in scope. For example:
+<programlisting>
+ f :: forall a. [a] -> (Int, [a])
+ f xs = (n, zs)
+ where
+ (ys::[a], n) = (reverse xs, length xs) -- OK
+ zs::[a] = xs ++ ys -- OK
+
+ Just (v::b) = ... -- Not OK; b is not in scope
+</programlisting>
+Here, the pattern signatures for <literal>ys</literal> and <literal>zs</literal>
+are fine, but the one for <literal>v</literal> is not because <literal>b</literal> is
+not in scope.
+</para>
+<para>
+However, in all patterns <emphasis>other</emphasis> than pattern bindings, a pattern
+type signature may mention a type variable that is not in scope; in this case,
+<emphasis>the signature brings that type variable into scope</emphasis>.
+This is particularly important for existential data constructors. For example:
<programlisting>
data T = forall a. MkT [a]
t3::[a] = [t,t,t]
</programlisting>
Here, the pattern type signature <literal>(t::a)</literal> mentions a lexical type
-variable that is not already in scope. Indeed, it cannot already be in scope,
+variable that is not already in scope. Indeed, it <emphasis>cannot</emphasis> already be in scope,
because it is bound by the pattern match. GHC's rule is that in this situation
(and only then), a pattern type signature can mention a type variable that is
not already in scope; the effect is to bring it into scope, standing for the
existentially-bound type variable.
</para>
<para>
-If this seems a little odd, we think so too. But we must have
+When a pattern type signature binds a type variable in this way, GHC insists that the
+type variable is bound to a <emphasis>rigid</emphasis>, or fully-known, type variable.
+This means that any user-written type signature always stands for a completely known type.
+</para>
+<para>
+If all this seems a little odd, we think so too. But we must have
<emphasis>some</emphasis> way to bring such type variables into scope, else we
-could not name existentially-bound type variables in subequent type signatures.
+could not name existentially-bound type variables in subsequent type signatures.
</para>
<para>
This is (now) the <emphasis>only</emphasis> situation in which a pattern type
The Haskell Report specifies that a group of bindings (at top level, or in a
<literal>let</literal> or <literal>where</literal>) should be sorted into
strongly-connected components, and then type-checked in dependency order
-(<ulink url="http://haskell.org/onlinereport/decls.html#sect4.5.1">Haskell
+(<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.1">Haskell
Report, Section 4.5.1</ulink>).
As each group is type-checked, any binders of the group that
have
an explicit type signature are put in the type environment with the specified
polymorphic type,
and all others are monomorphic until the group is generalised
-(<ulink url="http://haskell.org/onlinereport/decls.html#sect4.5.2">Haskell Report, Section 4.5.2</ulink>).
+(<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.2">Haskell Report, Section 4.5.2</ulink>).
</para>
<para>Following a suggestion of Mark Jones, in his paper
-<ulink url="http://www.cse.ogi.edu/~mpj/thih/">Typing Haskell in
+<ulink url="http://citeseer.ist.psu.edu/424440.html">Typing Haskell in
Haskell</ulink>,
GHC implements a more general scheme. If <option>-XRelaxedPolyRec</option> is
specified:
<literal>g</literal> is typechecked first, separately from that for
<literal>f</literal>,
because the reference to <literal>f</literal> in <literal>g</literal>'s right
-hand side is ingored by the dependency analysis. Then <literal>g</literal>'s
+hand side is ignored by the dependency analysis. Then <literal>g</literal>'s
type is generalised, to get
<programlisting>
g :: Ord a => a -> Bool
</programlisting>
-Now, the defintion for <literal>f</literal> is typechecked, with this type for
+Now, the definition for <literal>f</literal> is typechecked, with this type for
<literal>g</literal> in the type environment.
</para>
on the latter. As a result, the specification of the language extension is
also still to some degree in flux. Hence, a more detailed description of
the language extension and its use is currently available
-from <ulink url="http://haskell.org/haskellwiki/GHC/Indexed_types">the Haskell
+from <ulink url="http://www.haskell.org/haskellwiki/GHC/Indexed_types">the Haskell
wiki page on type families</ulink>. The material will be moved to this user's
guide when it has stabilised.
</para>
Haskell.
The background to
the main technical innovations is discussed in "<ulink
-url="http://research.microsoft.com/~simonpj/papers/meta-haskell">
+url="http://research.microsoft.com/~simonpj/papers/meta-haskell/">
Template Meta-programming for Haskell</ulink>" (Proc Haskell Workshop 2002).
</para>
<para>
There is a Wiki page about
-Template Haskell at <ulink url="http://haskell.org/haskellwiki/Template_Haskell">
+Template Haskell at <ulink url="http://www.haskell.org/haskellwiki/Template_Haskell">
http://www.haskell.org/haskellwiki/Template_Haskell</ulink>, and that is the best place to look for
further details.
You may also
</itemizedlist></para></listitem>
<listitem><para>
+ A quasi-quotation can appear in either a pattern context or an
+ expression context and is also written in Oxford brackets:
+ <itemizedlist>
+ <listitem><para> <literal>[:<replaceable>varid</replaceable>| ... |]</literal>,
+ where the "..." is an arbitrary string; a full description of the
+ quasi-quotation facility is given in <xref linkend="th-quasiquotation"/>.</para></listitem>
+ </itemizedlist></para></listitem>
+
+ <listitem><para>
A name can be quoted with either one or two prefix single quotes:
<itemizedlist>
<listitem><para> <literal>'f</literal> has type <literal>Name</literal>, and names the function <literal>f</literal>.
</para></listitem>
<listitem><para>
- Furthermore, you can only run a function at compile time if it is imported
+ You can only run a function at compile time if it is imported
from another module <emphasis>that is not part of a mutually-recursive group of modules
- that includes the module currently being compiled</emphasis>. For example, when compiling module A,
+ that includes the module currently being compiled</emphasis>. Furthermore, all of the modules of
+ the mutually-recursive group must be reachable by non-SOURCE imports from the module where the
+ splice is to be run.</para>
+ <para>
+ For example, when compiling module A,
you can only run Template Haskell functions imported from B if B does not import A (directly or indirectly).
The reason should be clear: to run B we must compile and run A, but we are currently type-checking A.
</para></listitem>
<para>Then compile it again with <option>-prof</option>, and
additionally use <option>-osuf
p_o</option><indexterm><primary><option>-osuf</option></primary></indexterm>
- to name the object files differentliy (you can choose any suffix
+ to name the object files differently (you can choose any suffix
that isn't the normal object suffix here). GHC will automatically
load the object files built in the first step when executing splice
expressions. If you omit the <option>-osuf</option> flag when
</orderedlist>
</sect2>
+<sect2 id="th-quasiquotation"> <title> Template Haskell Quasi-quotation </title>
+<para>Quasi-quotation allows patterns and expressions to be written using
+programmer-defined concrete syntax; the motivation behind the extension and
+several examples are documented in
+"<ulink url="http://www.eecs.harvard.edu/~mainland/ghc-quasiquoting/">Why It's
+Nice to be Quoted: Quasiquoting for Haskell</ulink>" (Proc Haskell Workshop
+2007). The example below shows how to write a quasiquoter for a simple
+expression language.</para>
+
+<para>
+In the example, the quasiquoter <literal>expr</literal> is bound to a value of
+type <literal>Language.Haskell.TH.Quote.QuasiQuoter</literal> which contains two
+functions for quoting expressions and patterns, respectively. The first argument
+to each quoter is the (arbitrary) string enclosed in the Oxford brackets. The
+context of the quasi-quotation statement determines which of the two parsers is
+called: if the quasi-quotation occurs in an expression context, the expression
+parser is called, and if it occurs in a pattern context, the pattern parser is
+called.</para>
+
+<para>
+Note that in the example we make use of an antiquoted
+variable <literal>n</literal>, indicated by the syntax <literal>'int:n</literal>
+(this syntax for anti-quotation was defined by the parser's
+author, <emphasis>not</emphasis> by GHC). This binds <literal>n</literal> to the
+integer value argument of the constructor <literal>IntExpr</literal> when
+pattern matching. Please see the referenced paper for further details regarding
+anti-quotation as well as the description of a technique that uses SYB to
+leverage a single parser of type <literal>String -> a</literal> to generate both
+an expression parser that returns a value of type <literal>Q Exp</literal> and a
+pattern parser that returns a value of type <literal>Q Pat</literal>.
+</para>
+
+<para>In general, a quasi-quote has the form
+<literal>[$<replaceable>quoter</replaceable>| <replaceable>string</replaceable> |]</literal>.
+The <replaceable>quoter</replaceable> must be the name of an imported quoter; it
+cannot be an arbitrary expression. The quoted <replaceable>string</replaceable>
+can be arbitrary, and may contain newlines.
+</para>
+<para>
+Quasiquoters must obey the same stage restrictions as Template Haskell, e.g., in
+the example, <literal>expr</literal> cannot be defined
+in <literal>Main.hs</literal> where it is used, but must be imported.
+</para>
+
+<programlisting>
+
+{- Main.hs -}
+module Main where
+
+import Expr
+
+main :: IO ()
+main = do { print $ eval [$expr|1 + 2|]
+ ; case IntExpr 1 of
+ { [$expr|'int:n|] -> print n
+ ; _ -> return ()
+ }
+ }
+
+
+{- Expr.hs -}
+module Expr where
+
+import qualified Language.Haskell.TH as TH
+import Language.Haskell.TH.Quasi
+
+data Expr = IntExpr Integer
+ | AntiIntExpr String
+ | BinopExpr BinOp Expr Expr
+ | AntiExpr String
+ deriving(Show, Typeable, Data)
+
+data BinOp = AddOp
+ | SubOp
+ | MulOp
+ | DivOp
+ deriving(Show, Typeable, Data)
+
+eval :: Expr -> Integer
+eval (IntExpr n) = n
+eval (BinopExpr op x y) = (opToFun op) (eval x) (eval y)
+ where
+ opToFun AddOp = (+)
+ opToFun SubOp = (-)
+ opToFun MulOp = (*)
+ opToFun DivOp = div
+
+expr = QuasiQuoter parseExprExp parseExprPat
+
+-- Parse an Expr, returning its representation as
+-- either a Q Exp or a Q Pat. See the referenced paper
+-- for how to use SYB to do this by writing a single
+-- parser of type String -> Expr instead of two
+-- separate parsers.
+
+parseExprExp :: String -> Q Exp
+parseExprExp ...
+
+parseExprPat :: String -> Q Pat
+parseExprPat ...
+</programlisting>
+
+<para>Now run the compiler:
+</para>
+<programlisting>
+$ ghc --make -XQuasiQuotes Main.hs -o main
+</programlisting>
+
+<para>Run "main" and here is your output:</para>
+
+<programlisting>
+$ ./main
+3
+1
+</programlisting>
+
+</sect2>
+
</sect1>
<!-- ===================== Arrow notation =================== -->
g7 x = case f x of { !y -> body }
</programlisting>
The functions <literal>g5</literal> and <literal>g6</literal> mean exactly the same thing.
-But <literal>g7</literal> evalutes <literal>(f x)</literal>, binds <literal>y</literal> to the
+But <literal>g7</literal> evaluates <literal>(f x)</literal>, binds <literal>y</literal> to the
result, and then evaluates <literal>body</literal>.
</para><para>
Bang patterns work in <literal>let</literal> and <literal>where</literal>
(!) f x = 3
</programlisting>
The semantics of Haskell pattern matching is described in <ulink
-url="http://haskell.org/onlinereport/exps.html#sect3.17.2">
+url="http://www.haskell.org/onlinereport/exps.html#sect3.17.2">
Section 3.17.2</ulink> of the Haskell Report. To this description add
one extra item 10, saying:
<itemizedlist><listitem><para>Matching
<literal>v</literal></para></listitem>
</itemizedlist>
</para></listitem></itemizedlist>
-Similarly, in Figure 4 of <ulink url="http://haskell.org/onlinereport/exps.html#sect3.17.3">
+Similarly, in Figure 4 of <ulink url="http://www.haskell.org/onlinereport/exps.html#sect3.17.3">
Section 3.17.3</ulink>, add a new case (t):
<programlisting>
case v of { !pat -> e; _ -> e' }
</programlisting>
</para><para>
That leaves let expressions, whose translation is given in
-<ulink url="http://haskell.org/onlinereport/exps.html#sect3.12">Section
+<ulink url="http://www.haskell.org/onlinereport/exps.html#sect3.12">Section
3.12</ulink>
of the Haskell Report.
In the translation box, first apply
unrecognised <replaceable>word</replaceable> is (silently)
ignored.</para>
+ <para>Certain pragmas are <emphasis>file-header pragmas</emphasis>. A file-header
+ pragma must precede the <literal>module</literal> keyword in the file.
+ There can be as many file-header pragmas as you please, and they can be
+ preceded or followed by comments.</para>
+
+ <sect2 id="language-pragma">
+ <title>LANGUAGE pragma</title>
+
+ <indexterm><primary>LANGUAGE</primary><secondary>pragma</secondary></indexterm>
+ <indexterm><primary>pragma</primary><secondary>LANGUAGE</secondary></indexterm>
+
+ <para>The <literal>LANGUAGE</literal> pragma allows language extensions to be enabled
+ in a portable way.
+ It is the intention that all Haskell compilers support the
+ <literal>LANGUAGE</literal> pragma with the same syntax, although not
+ all extensions are supported by all compilers, of
+ course. The <literal>LANGUAGE</literal> pragma should be used instead
+ of <literal>OPTIONS_GHC</literal>, if possible.</para>
+
+ <para>For example, to enable the FFI and preprocessing with CPP:</para>
+
+<programlisting>{-# LANGUAGE ForeignFunctionInterface, CPP #-}</programlisting>
+
+ <para><literal>LANGUAGE</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
+
+ <para>Every language extension can also be turned into a command-line flag
+ by prefixing it with "<literal>-X</literal>"; for example <option>-XForeignFunctionInterface</option>.
+ (Similarly, all "<literal>-X</literal>" flags can be written as <literal>LANGUAGE</literal> pragmas.
+ </para>
+
+ <para>A list of all supported language extensions can be obtained by invoking
+ <literal>ghc --supported-languages</literal> (see <xref linkend="modes"/>).</para>
+
+ <para>Any extension from the <literal>Extension</literal> type defined in
+ <ulink
+ url="../libraries/Cabal/Language-Haskell-Extension.html"><literal>Language.Haskell.Extension</literal></ulink>
+ may be used. GHC will report an error if any of the requested extensions are not supported.</para>
+ </sect2>
+
+
+ <sect2 id="options-pragma">
+ <title>OPTIONS_GHC pragma</title>
+ <indexterm><primary>OPTIONS_GHC</primary>
+ </indexterm>
+ <indexterm><primary>pragma</primary><secondary>OPTIONS_GHC</secondary>
+ </indexterm>
+
+ <para>The <literal>OPTIONS_GHC</literal> pragma is used to specify
+ additional options that are given to the compiler when compiling
+ this source file. See <xref linkend="source-file-options"/> for
+ details.</para>
+
+ <para>Previous versions of GHC accepted <literal>OPTIONS</literal> rather
+ than <literal>OPTIONS_GHC</literal>, but that is now deprecated.</para>
+ </sect2>
+
+ <para><literal>OPTIONS_GHC</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
+
+ <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>
+ </sect2>
+
<sect2 id="deprecated-pragma">
<title>DEPRECATED pragma</title>
<indexterm><primary>DEPRECATED</primary>
<para>When you compile any module that imports and uses any
of the specified entities, GHC will print the specified
message.</para>
- <para> You can only depecate entities declared at top level in the module
+ <para> You can only deprecate entities declared at top level in the module
being compiled, and you can only use unqualified names in the list of
entities being deprecated. A capitalised name, such as <literal>T</literal>
refers to <emphasis>either</emphasis> the type constructor <literal>T</literal>
<option>-fno-warn-deprecations</option>.</para>
</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>The <literal>INCLUDE</literal> pragma(s) must appear at the top of
- your source file with any <literal>OPTIONS_GHC</literal>
- pragma(s).</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>
- </sect2>
-
<sect2 id="inline-noinline-pragma">
<title>INLINE and NOINLINE pragmas</title>
<para>The major effect of an <literal>INLINE</literal> pragma
is to declare a function's “cost” to be very low.
The normal unfolding machinery will then be very keen to
- inline it.</para>
-
+ inline it. However, an <literal>INLINE</literal> pragma for a
+ function "<literal>f</literal>" has a number of other effects:
+<itemizedlist>
+<listitem><para>
+No funtions are inlined into <literal>f</literal>. Otherwise
+GHC might inline a big function into <literal>f</literal>'s right hand side,
+making <literal>f</literal> big; and then inline <literal>f</literal> blindly.
+</para></listitem>
+<listitem><para>
+The float-in, float-out, and common-sub-expression transformations are not
+applied to the body of <literal>f</literal>.
+</para></listitem>
+<listitem><para>
+An INLINE function is not worker/wrappered by strictness analysis.
+It's going to be inlined wholesale instead.
+</para></listitem>
+</itemizedlist>
+All of these effects are aimed at ensuring that what gets inlined is
+exactly what you asked for, no more and no less.
+</para>
<para>Syntactically, an <literal>INLINE</literal> pragma for a
function can be put anywhere its type signature could be
put.</para>
there was no pragma).
</para></listitem>
<listitem>
- <para>"<literal>INLINE[~k] f</literal>" means: be willing to inline
+ <para>"<literal>NOINLINE[~k] f</literal>" means: be willing to inline
<literal>f</literal>
until phase <literal>k</literal>, but from phase
<literal>k</literal> onwards do not inline it.
</sect3>
</sect2>
- <sect2 id="language-pragma">
- <title>LANGUAGE pragma</title>
-
- <indexterm><primary>LANGUAGE</primary><secondary>pragma</secondary></indexterm>
- <indexterm><primary>pragma</primary><secondary>LANGUAGE</secondary></indexterm>
-
- <para>This allows language extensions to be enabled in a portable way.
- It is the intention that all Haskell compilers support the
- <literal>LANGUAGE</literal> pragma with the same syntax, although not
- all extensions are supported by all compilers, of
- course. The <literal>LANGUAGE</literal> pragma should be used instead
- of <literal>OPTIONS_GHC</literal>, if possible.</para>
-
- <para>For example, to enable the FFI and preprocessing with CPP:</para>
-
-<programlisting>{-# LANGUAGE ForeignFunctionInterface, CPP #-}</programlisting>
-
- <para>Any extension from the <literal>Extension</literal> type defined in
- <ulink
- url="../libraries/Cabal/Language-Haskell-Extension.html"><literal>Language.Haskell.Extension</literal></ulink> may be used. GHC will report an error if any of the requested extensions are not supported.</para>
- </sect2>
-
-
<sect2 id="line-pragma">
<title>LINE pragma</title>
pragma.</para>
</sect2>
- <sect2 id="options-pragma">
- <title>OPTIONS_GHC pragma</title>
- <indexterm><primary>OPTIONS_GHC</primary>
- </indexterm>
- <indexterm><primary>pragma</primary><secondary>OPTIONS_GHC</secondary>
- </indexterm>
-
- <para>The <literal>OPTIONS_GHC</literal> pragma is used to specify
- additional options that are given to the compiler when compiling
- this source file. See <xref linkend="source-file-options"/> for
- details.</para>
-
- <para>Previous versions of GHC accepted <literal>OPTIONS</literal> rather
- than <literal>OPTIONS_GHC</literal>, but that is now deprecated.</para>
- </sect2>
-
<sect2 id="rules">
<title>RULES pragma</title>
<programlisting>
{-# SPECIALIZE f :: <type> #-}
</programlisting>
- is valid if and only if the defintion
+ is valid if and only if the definition
<programlisting>
f_spec :: <type>
f_spec = f
h :: Eq a => a -> a -> a
{-# SPECIALISE h :: (Eq a) => [a] -> [a] -> [a] #-}
-</programlisting>
+</programlisting>
The last of these examples will generate a
RULE with a somewhat-complex left-hand side (try it yourself), so it might not fire very
well. If you use this kind of specialisation, let us know how well it works.
<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"/>.
-The <literal>INLINE</literal> pragma affects the specialised verison of the
+The <literal>INLINE</literal> pragma affects the specialised version of the
function (only), and applies even if the function is recursive. The motivating
example is this:
<programlisting>
<para>will store the two <literal>Int</literal>s directly in the
<function>T</function> constructor, by flattening the pair.
- Multi-level unpacking is also supported:</para>
+ Multi-level unpacking is also supported:
<programlisting>
data T = T {-# UNPACK #-} !S
data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
</programlisting>
- <para>will store two unboxed <literal>Int#</literal>s
+ will store two unboxed <literal>Int#</literal>s
directly in the <function>T</function> constructor. The
unpacker can see through newtypes, too.</para>
constructor field.</para>
</sect2>
+ <sect2 id="source-pragma">
+ <title>SOURCE pragma</title>
+
+ <indexterm><primary>SOURCE</primary></indexterm>
+ <para>The <literal>{-# SOURCE #-}</literal> pragma is used only in <literal>import</literal> declarations,
+ to break a module loop. It is described in detail in <xref linkend="mutual-recursion"/>.
+ </para>
+</sect2>
+
</sect1>
<!-- ======================= REWRITE RULES ======================== -->
The programmer can specify rewrite rules as part of the source program
(in a pragma). GHC applies these rewrite rules wherever it can, provided (a)
the <option>-O</option> flag (<xref linkend="options-optimise"/>) is on,
-and (b) the <option>-frules-off</option> flag
+and (b) the <option>-fno-rewrite-rules</option> flag
(<xref linkend="options-f"/>) is not specified, and (c) the
<option>-fglasgow-exts</option> (<xref linkend="options-language"/>)
flag is active.
<listitem>
<para>
- The definition of (say) <function>build</function> in <filename>GHC/Base.lhs</filename> looks llike this:
+ The definition of (say) <function>build</function> in <filename>GHC/Base.lhs</filename> looks like this:
<programlisting>
build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
<sect1 id="special-ids">
<title>Special built-in functions</title>
-<para>GHC has a few built-in funcions with special behaviour. These
+<para>GHC has a few built-in functions with special behaviour. These
are now described in the module <ulink
url="../libraries/base/GHC-Prim.html"><literal>GHC.Prim</literal></ulink>
in the library documentation.</para>
op2 :: a -> Bool
op2 {| p :*: q |} (x :*: y) = False
</programlisting>
-(The reason for this restriction is that we gather all the equations for a particular type consructor
+(The reason for this restriction is that we gather all the equations for a particular type constructor
into a single generic instance declaration.)
</para>
</listitem>
inside a list.
</para>
<para>
-This restriction is an implementation restriction: we just havn't got around to
+This restriction is an implementation restriction: we just haven't got around to
implementing the necessary bidirectional maps over arbitrary type constructors.
It would be relatively easy to add specific type constructors, such as Maybe and list,
to the ones that are allowed.</para>
<indexterm><primary><option>-XNoMonomorphismRestriction</option></primary></indexterm>
<para>Haskell's monomorphism restriction (see
-<ulink url="http://haskell.org/onlinereport/decls.html#sect4.5.5">Section
+<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.5">Section
4.5.5</ulink>
of the Haskell Report)
can be completely switched off by
[x] = e -- A pattern binding
</programlisting>
Experimentally, GHC now makes pattern bindings monomorphic <emphasis>by
-default</emphasis>. Use <option>-XMonoPatBinds</option> to recover the
+default</emphasis>. Use <option>-XNoMonoPatBinds</option> to recover the
standard behaviour.
</para>
</sect2>