</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">
</title>
<para> The recursive do-notation (also known as mdo-notation) is implemented as described in
-"A recursive do for Haskell",
-Levent Erkok, John Launchbury",
+<ulink url="http://citeseer.ist.psu.edu/erk02recursive.html">A recursive do for Haskell</ulink>,
+by Levent Erkok, John Launchbury,
Haskell Workshop 2002, pages: 29-37. Pittsburgh, Pennsylvania.
+This paper is essential reading for anyone making non-trivial use of mdo-notation,
+and we do not repeat it here.
</para>
<para>
The do-notation of Haskell does not allow <emphasis>recursive bindings</emphasis>,
</programlisting>
<para>
The function <literal>mfix</literal>
-dictates how the required recursion operation should be performed. If recursive bindings are required for a monad,
-then that monad must be declared an instance of the <literal>MonadFix</literal> class.
-For details, see the above mentioned reference.
+dictates how the required recursion operation should be performed. For example,
+<literal>justOnes</literal> desugars as follows:
+<programlisting>
+justOnes = mfix (\xs' -> do { xs <- Just (1:xs'); return xs }
+</programlisting>
+For full details of the way in which mdo is typechecked and desugared, see
+the paper <ulink url="http://citeseer.ist.psu.edu/erk02recursive.html">A recursive do for Haskell</ulink>.
+In particular, GHC implements the segmentation technique described in Section 3.2 of the paper.
</para>
<para>
+If recursive bindings are required for a monad,
+then that monad must be declared an instance of the <literal>MonadFix</literal> class.
The following instances of <literal>MonadFix</literal> are automatically provided: List, Maybe, IO.
Furthermore, the Control.Monad.ST and Control.Monad.ST.Lazy modules provide the instances of the MonadFix class
for Haskell's internal state monad (strict and lazy, respectively).
</para>
<para>
-There are three important points in using the recursive-do notation:
+Here are some important points in using the recursive-do notation:
<itemizedlist>
<listitem><para>
The recursive version of the do-notation uses the keyword <literal>mdo</literal> (rather
</para></listitem>
<listitem><para>
-As with other extensions, ghc should be given the flag <literal>-fglasgow-exts</literal>
+It is enabled with the flag <literal>-XRecursiveDo</literal>, which is in turn implied by
+<literal>-fglasgow-exts</literal>.
+</para></listitem>
+
+<listitem><para>
+Unlike ordinary do-notation, but like <literal>let</literal> and <literal>where</literal> bindings,
+name shadowing is not allowed; that is, all the names bound in a single <literal>mdo</literal> must
+be distinct (Section 3.3 of the paper).
+</para></listitem>
+
+<listitem><para>
+Variables bound by a <literal>let</literal> statement in an <literal>mdo</literal>
+are monomorphic in the <literal>mdo</literal> (Section 3.1 of the paper). However
+GHC breaks the <literal>mdo</literal> into segments to enhance polymorphism,
+and improve termination (Section 3.2 of the paper).
</para></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>
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>
</para>
</sect2>
+</sect1>
<!-- ====================== End of Generalised algebraic data types ======================= -->
+<sect1 id="deriving">
+<title>Extensions to the "deriving" mechanism</title>
+
+<sect2 id="deriving-inferred">
+<title>Inferred context for deriving clauses</title>
+
+<para>
+The Haskell Report is vague about exactly when a <literal>deriving</literal> clause is
+legal. For example:
+<programlisting>
+ data T0 f a = MkT0 a deriving( Eq )
+ data T1 f a = MkT1 (f a) deriving( Eq )
+ data T2 f a = MkT2 (f (f a)) deriving( Eq )
+</programlisting>
+The natural generated <literal>Eq</literal> code would result in these instance declarations:
+<programlisting>
+ instance Eq a => Eq (T0 f a) where ...
+ instance Eq (f a) => Eq (T1 f a) where ...
+ instance Eq (f (f a)) => Eq (T2 f a) where ...
+</programlisting>
+The first of these is obviously fine. The second is still fine, although less obviously.
+The third is not Haskell 98, and risks losing termination of instances.
+</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.
+</para>
+<para>
+This rule is applied regardless of flags. If you want a more exotic context, you can write
+it yourself, using the <link linkend="stand-alone-deriving">standalone deriving mechanism</link>.
+</para>
+</sect2>
+
+<sect2 id="stand-alone-deriving">
+<title>Stand-alone deriving declarations</title>
+
+<para>
+GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by <literal>-XStandaloneDeriving</literal>:
+<programlisting>
+ data Foo a = Bar a | Baz String
+
+ deriving instance Eq a => Eq (Foo a)
+</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>),
+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.) These <literal>deriving instance</literal>
+rules obey the same rules concerning form and termination as ordinary instance declarations,
+controlled by the same flags; see <xref linkend="instance-decls"/>. </para>
+
+<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>
+ newtype Foo a = MkFoo (State Int a)
+
+ 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.
+</para>
+
+</sect2>
+
<sect2 id="deriving-typeable">
<title>Deriving clause for classes <literal>Typeable</literal> and <literal>Data</literal></title>
</para>
<para>
GHC extends this list with two more classes that may be automatically derived
-(provided the <option>-fglasgow-exts</option> flag is specified):
+(provided the <option>-XDeriveDataTypeable</option> flag is specified):
<literal>Typeable</literal>, and <literal>Data</literal>. These classes are defined in the library
modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> respectively, and the
appropriate class must be in scope before it can be mentioned in the <literal>deriving</literal> clause.
<sect3> <title> Generalising the deriving clause </title>
<para>
-GHC now permits such instances to be derived instead, so one can write
+GHC now permits such instances to be derived instead,
+using the flag <option>-XGeneralizedNewtypeDeriving</option>,
+so one can write
<programlisting>
newtype Dollars = Dollars Int deriving (Eq,Show,Num)
</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
entire left hand side. We can imagine that the type declaration is
-``eta-converted'' to generate the context of the instance
+"eta-converted" to generate the context of the instance
declaration.
</para>
<para>
the standard method is used or the one described here.)
</para>
</sect3>
-
-</sect2>
-
-<sect2 id="stand-alone-deriving">
-<title>Stand-alone deriving declarations</title>
-
-<para>
-GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by <literal>-fglasgow-exts</literal>:
-<programlisting>
- data Foo a = Bar a | Baz String
-
- derive instance Eq (Foo a)
-</programlisting>
-The token "<literal>derive</literal>" is a keyword only when followed by "<literal>instance</literal>";
-you can use it as a variable name elsewhere.</para>
-<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>
- newtype Foo a = MkFoo (State Int a)
-
- derive 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.
-</para>
-
</sect2>
-
</sect1>
<!-- TYPE SYSTEM EXTENSIONS -->
-<sect1 id="other-type-extensions">
-<title>Other type system extensions</title>
+<sect1 id="type-class-extensions">
+<title>Class and instances declarations</title>
<sect2 id="multi-param-type-classes">
<title>Class declarations</title>
GHC does not commit to instance (C), because in a particular
call of <literal>f</literal>, <literal>b</literal> might be instantiate
to <literal>Int</literal>, in which case instance (D) would be more specific still.
-So GHC rejects the program. If you add the flag <option>-XIncoherentInstances</option>,
+So GHC rejects the program.
+(If you add the flag <option>-XIncoherentInstances</option>,
GHC will instead pick (C), without complaining about
-the problem of subsequent instantiations.
+the problem of subsequent instantiations.)
+</para>
+<para>
+Notice that we gave a type signature to <literal>f</literal>, so GHC had to
+<emphasis>check</emphasis> that <literal>f</literal> has the specified type.
+Suppose instead we do not give a type signature, asking GHC to <emphasis>infer</emphasis>
+it instead. In this case, GHC will refrain from
+simplifying the constraint <literal>C Int [Int]</literal> (for the same reason
+as before) but, rather than rejecting the program, it will infer the type
+<programlisting>
+ f :: C Int b => [b] -> [b]
+</programlisting>
+That postpones the question of which instance to pick to the
+call site for <literal>f</literal>
+by which time more is known about the type <literal>b</literal>.
</para>
<para>
The willingness to be overlapped or incoherent is a property of
reversed, but it makes sense to me.
</para>
-</sect3>
+</sect3>
+
+
+</sect2>
+
+<sect2 id="overloaded-strings">
+<title>Overloaded string literals
+</title>
+
+<para>
+GHC supports <emphasis>overloaded string literals</emphasis>. Normally a
+string literal has type <literal>String</literal>, but with overloaded string
+literals enabled (with <literal>-XOverloadedStrings</literal>)
+ a string literal has type <literal>(IsString a) => a</literal>.
+</para>
+<para>
+This means that the usual string syntax can be used, e.g., for packed strings
+and other variations of string like types. String literals behave very much
+like integer literals, i.e., they can be used in both expressions and patterns.
+If used in a pattern the literal with be replaced by an equality test, in the same
+way as an integer literal is.
+</para>
+<para>
+The class <literal>IsString</literal> is defined as:
+<programlisting>
+class IsString a where
+ fromString :: String -> a
+</programlisting>
+The only predefined instance is the obvious one to make strings work as usual:
+<programlisting>
+instance IsString [Char] where
+ 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
+from module <literal>GHC.Exts</literal>.
+</para>
+<para>
+Haskell's defaulting mechanism is extended to cover string literals, when <option>-XOverloadedStrings</option> is specified.
+Specifically:
+<itemizedlist>
+<listitem><para>
+Each type in a default declaration must be an
+instance of <literal>Num</literal> <emphasis>or</emphasis> of <literal>IsString</literal>.
+</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>)
+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>.
+</para></listitem>
+</itemizedlist>
+</para>
+<para>
+A small example:
+<programlisting>
+module Main where
+
+import GHC.Exts( IsString(..) )
+
+newtype MyString = MyString String deriving (Eq, Show)
+instance IsString MyString where
+ fromString = MyString
+
+greet :: MyString -> MyString
+greet "hello" = "world"
+greet other = other
+
+main = do
+ print $ greet "hello"
+ print $ greet "fool"
+</programlisting>
+</para>
+<para>
+Note that deriving <literal>Eq</literal> is necessary for the pattern matching
+to work since it gets translated into an equality comparison.
+</para>
+</sect2>
+</sect1>
-</sect2>
+<sect1 id="other-type-extensions">
+<title>Other type system extensions</title>
<sect2 id="type-restrictions">
<title>Type signatures</title>
</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>
</para>
</sect2>
-<sect2 id="overloaded-strings">
-<title>Overloaded string literals
-</title>
-
-<para>
-GHC supports <emphasis>overloaded string literals</emphasis>. Normally a
-string literal has type <literal>String</literal>, but with overloaded string
-literals enabled (with <literal>-XOverloadedStrings</literal>)
- a string literal has type <literal>(IsString a) => a</literal>.
-</para>
-<para>
-This means that the usual string syntax can be used, e.g., for packed strings
-and other variations of string like types. String literals behave very much
-like integer literals, i.e., they can be used in both expressions and patterns.
-If used in a pattern the literal with be replaced by an equality test, in the same
-way as an integer literal is.
-</para>
-<para>
-The class <literal>IsString</literal> is defined as:
-<programlisting>
-class IsString a where
- fromString :: String -> a
-</programlisting>
-The only predefined instance is the obvious one to make strings work as usual:
-<programlisting>
-instance IsString [Char] where
- 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
-from module <literal>GHC.Exts</literal>.
-</para>
-<para>
-Haskell's defaulting mechanism is extended to cover string literals, when <option>-XOverloadedStrings</option> is specified.
-Specifically:
-<itemizedlist>
-<listitem><para>
-Each type in a default declaration must be an
-instance of <literal>Num</literal> <emphasis>or</emphasis> of <literal>IsString</literal>.
-</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>)
-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>.
-</para></listitem>
-</itemizedlist>
-</para>
-<para>
-A small example:
-<programlisting>
-module Main where
-
-import GHC.Exts( IsString(..) )
-
-newtype MyString = MyString String deriving (Eq, Show)
-instance IsString MyString where
- fromString = MyString
-
-greet :: MyString -> MyString
-greet "hello" = "world"
-greet other = other
-
-main = do
- print $ greet "hello"
- print $ greet "fool"
-</programlisting>
-</para>
-<para>
-Note that deriving <literal>Eq</literal> is necessary for the pattern matching
-to work since it gets translated into an equality comparison.
-</para>
-</sect2>
-
<sect2 id="type-families">
<title>Type families
</title>
<para>
There is a Wiki page about
Template Haskell at <ulink url="http://haskell.org/haskellwiki/Template_Haskell">
-http://www.haskell.org/th/</ulink>, and that is the best place to look for
+http://www.haskell.org/haskellwiki/Template_Haskell</ulink>, and that is the best place to look for
further details.
You may also
consult the <ulink
url="http://www.haskell.org/ghc/docs/latest/html/libraries/index.html">online
Haskell library reference material</ulink>
-(search for the type ExpQ).
-[Temporary: many changes to the original design are described in
- <ulink url="http://research.microsoft.com/~simonpj/tmp/notes2.ps">"http://research.microsoft.com/~simonpj/tmp/notes2.ps"</ulink>.
-Not all of these changes are in GHC 6.6.]
+(look for module <literal>Language.Haskell.TH</literal>).
+Many changes to the original design are described in
+ <ulink url="http://research.microsoft.com/~simonpj/papers/meta-haskell/notes2.ps">
+Notes on Template Haskell version 2</ulink>.
+Not all of these changes are in GHC, however.
</para>
-<para> The first example from that paper is set out below as a worked example to help get you started.
+<para> The first example from that paper is set out below (<xref linkend="th-example"/>)
+as a worked example to help get you started.
</para>
<para>
-The documentation here describes the realisation in GHC. (It's rather sketchy just now;
-Tim Sheard is going to expand it.)
+The documentation here describes the realisation of Template Haskell in GHC. It is not detailed enough to
+understand Template Haskell; see the <ulink url="http://haskell.org/haskellwiki/Template_Haskell">
+Wiki page</ulink>.
</para>
<sect2>
<itemizedlist>
<listitem><para> an expression; the spliced expression must
have type <literal>Q Exp</literal></para></listitem>
- <listitem><para> a list of top-level declarations; ; the spliced expression must have type <literal>Q [Dec]</literal></para></listitem>
- <listitem><para> [Planned, but not implemented yet.] a
- 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>
- (Note that the syntax for a declaration splice uses "<literal>$</literal>" not "<literal>splice</literal>" as in
- the paper. Also the type of the enclosed expression must be <literal>Q [Dec]</literal>, not <literal>[Q Dec]</literal>
- as in the paper.)
- </para></listitem>
+ </para>
+ Inside a splice you can can only call functions defined in imported modules,
+ not functions defined elsewhere in the same module.</listitem>
<listitem><para>
A expression quotation is written in Oxford brackets, thus:
<itemizedlist>
<listitem><para> <literal>[| ... |]</literal>, where the "..." is an expression;
- the quotation has type <literal>Expr</literal>.</para></listitem>
+ the quotation has type <literal>Q Exp</literal>.</para></listitem>
<listitem><para> <literal>[d| ... |]</literal>, where the "..." is a list of top-level declarations;
the quotation has type <literal>Q [Dec]</literal>.</para></listitem>
<listitem><para> <literal>[t| ... |]</literal>, where the "..." is a type;
- the quotation has type <literal>Type</literal>.</para></listitem>
+ the quotation has type <literal>Q Typ</literal>.</para></listitem>
</itemizedlist></para></listitem>
<listitem><para>
- Reification is written thus:
+ A name can be quoted with either one or two prefix single quotes:
<itemizedlist>
- <listitem><para> <literal>reifyDecl T</literal>, where <literal>T</literal> is a type constructor; this expression
- has type <literal>Dec</literal>. </para></listitem>
- <listitem><para> <literal>reifyDecl C</literal>, where <literal>C</literal> is a class; has type <literal>Dec</literal>.</para></listitem>
- <listitem><para> <literal>reifyType f</literal>, where <literal>f</literal> is an identifier; has type <literal>Typ</literal>.</para></listitem>
- <listitem><para> Still to come: fixities </para></listitem>
-
- </itemizedlist></para>
+ <listitem><para> <literal>'f</literal> has type <literal>Name</literal>, and names the function <literal>f</literal>.
+ Similarly <literal>'C</literal> has type <literal>Name</literal> and names the data constructor <literal>C</literal>.
+ In general <literal>'</literal><replaceable>thing</replaceable> interprets <replaceable>thing</replaceable> in an expression context.
+ </para></listitem>
+ <listitem><para> <literal>''T</literal> has type <literal>Name</literal>, and names the type constructor <literal>T</literal>.
+ That is, <literal>''</literal><replaceable>thing</replaceable> interprets <replaceable>thing</replaceable> in a type context.
+ </para></listitem>
+ </itemizedlist>
+ These <literal>Names</literal> can be used to construct Template Haskell expressions, patterns, delarations etc. They
+ may also be given as an argument to the <literal>reify</literal> function.
+ </para>
</listitem>
</itemizedlist>
+(Compared to the original paper, there are many differnces 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.
+
</sect2>
<sect2> <title> Using Template Haskell </title>
</para>
</sect2>
-<sect2> <title> A Template Haskell Worked Example </title>
+<sect2 id="th-example"> <title> A Template Haskell Worked Example </title>
<para>To help you get over the confidence barrier, try out this skeletal worked example.
First cut and paste the two modules below into "Main.hs" and "Printf.hs":</para>
-- Generate Haskell source code from a parsed representation
-- of the format string. This code will be spliced into
-- the module which calls "pr", at compile time.
-gen :: [Format] -> ExpQ
+gen :: [Format] -> Q Exp
gen [D] = [| \n -> show n |]
gen [S] = [| \s -> s |]
gen [L s] = stringE s
-- Here we generate the Haskell code for the splice
-- from an input format string.
-pr :: String -> ExpQ
-pr s = gen (parse s)
+pr :: String -> Q Exp
+pr s = gen (parse s)
</programlisting>
<para>Now run the compiler (here we are a Cygwin prompt on Windows):
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>
<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>
</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>
<sect1 id="special-ids">
<title>Special built-in functions</title>
-<para>GHC has a few built-in funcions with special behaviour,
-described in this section. All are exported by
-<literal>GHC.Exts</literal>.</para>
-
-<sect2> <title>The <literal>seq</literal> function </title>
-<para>
-The function <literal>seq</literal> is as described in the Haskell98 Report.
-<programlisting>
- seq :: a -> b -> b
-</programlisting>
-It evaluates its first argument to head normal form, and then returns its
-second argument as the result. The reason that it is documented here is
-that, despite <literal>seq</literal>'s polymorphism, its
-second argument can have an unboxed type, or
-can be an unboxed tuple; for example <literal>(seq x 4#)</literal>
-or <literal>(seq x (# p,q #))</literal>. This requires <literal>b</literal>
-to be instantiated to an unboxed type, which is not usually allowed.
-</para>
-</sect2>
-
-<sect2> <title>The <literal>inline</literal> function </title>
-<para>
-The <literal>inline</literal> function is somewhat experimental.
-<programlisting>
- inline :: a -> a
-</programlisting>
-The call <literal>(inline f)</literal> arranges that <literal>f</literal>
-is inlined, regardless of its size. More precisely, the call
-<literal>(inline f)</literal> rewrites to the right-hand side of <literal>f</literal>'s
-definition.
-This allows the programmer to control inlining from
-a particular <emphasis>call site</emphasis>
-rather than the <emphasis>definition site</emphasis> of the function
-(c.f. <literal>INLINE</literal> pragmas <xref linkend="inline-noinline-pragma"/>).
-</para>
-<para>
-This inlining occurs regardless of the argument to the call
-or the size of <literal>f</literal>'s definition; it is unconditional.
-The main caveat is that <literal>f</literal>'s definition must be
-visible to the compiler. That is, <literal>f</literal> must be
-let-bound in the current scope.
-If no inlining takes place, the <literal>inline</literal> function
-expands to the identity function in Phase zero; so its use imposes
-no overhead.</para>
-
-<para> If the function is defined in another
-module, GHC only exposes its inlining in the interface file if the
-function is sufficiently small that it <emphasis>might</emphasis> be
-inlined by the automatic mechanism. There is currently no way to tell
-GHC to expose arbitrarily-large functions in the interface file. (This
-shortcoming is something that could be fixed, with some kind of pragma.)
-</para>
-</sect2>
-
-<sect2> <title>The <literal>lazy</literal> function </title>
-<para>
-The <literal>lazy</literal> function restrains strictness analysis a little:
-<programlisting>
- lazy :: a -> a
-</programlisting>
-The call <literal>(lazy e)</literal> means the same as <literal>e</literal>,
-but <literal>lazy</literal> has a magical property so far as strictness
-analysis is concerned: it is lazy in its first argument,
-even though its semantics is strict. After strictness analysis has run,
-calls to <literal>lazy</literal> are inlined to be the identity function.
-</para>
-<para>
-This behaviour is occasionally useful when controlling evaluation order.
-Notably, <literal>lazy</literal> is used in the library definition of
-<literal>Control.Parallel.par</literal>:
-<programlisting>
- par :: a -> b -> b
- par x y = case (par# x) of { _ -> lazy y }
-</programlisting>
-If <literal>lazy</literal> were not lazy, <literal>par</literal> would
-look strict in <literal>y</literal> which would defeat the whole
-purpose of <literal>par</literal>.
-</para>
-<para>
-Like <literal>seq</literal>, the argument of <literal>lazy</literal> can have
-an unboxed type.
-</para>
-
-</sect2>
-
-<sect2> <title>The <literal>unsafeCoerce#</literal> function </title>
-<para>
-The function <literal>unsafeCoerce#</literal> allows you to side-step the
-typechecker entirely. It has type
-<programlisting>
- unsafeCoerce# :: a -> b
-</programlisting>
-That is, it allows you to coerce any type into any other type. If you use this
-function, you had better get it right, otherwise segmentation faults await.
-It is generally used when you want to write a program that you know is
-well-typed, but where Haskell's type system is not expressive enough to prove
-that it is well typed.
-</para>
-<para>
-The argument to <literal>unsafeCoerce#</literal> can have unboxed types,
-although extremely bad things will happen if you coerce a boxed type
-to an unboxed type.
-</para>
-
-</sect2>
-
+<para>GHC has a few built-in funcions 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>
</sect1>
projects / ghc-hetmet.git / blobdiff