</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>
<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"/>);
<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>
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
<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>
</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>
</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 =================== -->
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.
<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 ======================== -->