(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 <link linkend="instance-decls"/>. </para>
+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"/>).
</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>
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>
projects / ghc-hetmet.git / blobdiff