-<Chapter id="utils">
-<Title>Other Haskell utility programs
-</Title>
-
-<IndexTerm><Primary>utilities, Haskell</Primary></IndexTerm>
-
-<Para>
-This section describes other program(s) which we distribute, that help
-with the Great Haskell Programming Task.
-</Para>
-
-<Sect1 id="mkdependHS">
-<Title>Makefile dependencies in Haskell: using <Command>mkdependHS</Command>
-</Title>
-
-<Para>
-<IndexTerm><Primary>mkdependHS</Primary></IndexTerm>
-<IndexTerm><Primary>Makefile dependencies</Primary></IndexTerm>
-<IndexTerm><Primary>dependencies in Makefiles</Primary></IndexTerm>
-</Para>
-
-<Para>
-You run <Command>mkdependHS</Command> like this:
-
-<Screen>
-mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...]
-</Screen>
-
-or
-
-<Screen>
-ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...]
-</Screen>
-
-To see <Command>mkdependHS</Command>'s command-line flags, give it a duff flag,
-e.g., <Command>mkdependHS -help</Command>.
-</Para>
-
-<Para>
-In general, if module <Literal>A</Literal> contains the line
-
-<ProgramListing>
-import B ...blah...
-</ProgramListing>
-
-then <Command>mkdependHS</Command> will generate a dependency line of the form:
-
-<ProgramListing>
-A.o : B.hi
-</ProgramListing>
-
-If module <Literal>A</Literal> contains the line
-
-<ProgramListing>
-import {-# SOURCE #-} B ...blah...
-</ProgramListing>
-
-then <Command>mkdependHS</Command> will generate a dependency line of the form:
-
-<ProgramListing>
-A.o : B.hi-boot
-</ProgramListing>
-
-(See <XRef LinkEnd="hi-files"> for details of interface files.)
-If <Literal>A</Literal> imports multiple modules, then there will be multiple lines with <Filename>A.o</Filename> as the
-target.
-</Para>
-
-<Para>
-By default, <Command>mkdependHS</Command> generates all the dependencies, and then
-concatenates them onto the end of
-<Filename>makefile</Filename> (or <Filename>Makefile</Filename> if <Filename>makefile</Filename> doesn't exist) bracketed by
-the lines "<Literal># DO NOT DELETE: Beginning of Haskell dependencies</Literal>" and
-"<Literal># DO NOT DELETE: End of Haskell dependencies</Literal>". If these lines
-already exist in the <Filename>makefile</Filename>, <Command>mkdependHS</Command> deletes the old
-dependencies first.
-</Para>
-
-<Para>
-<Command>mkdependHS</Command> takes GHC options between <Literal>--</Literal> brackets.
-It understands the following ones. Any options between <Literal>--</Literal> brackets
-that it doesn't understand are simply ignored; this way you can feed your
-Makefile's standard GHC options to <Command>mkdependHS</Command> un-filtered.
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-cpp</Option></Term>
-<ListItem>
-<Para>
-Run the C pre-processor over the input files. The
-default is not to.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-D<blah></Option></Term>
-<ListItem>
-<Para>
-A cpp <Option>#define</Option>; usual meaning.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-i<dirs></Option></Term>
-<ListItem>
-<Para>
-Add <Filename><dirs></Filename> (colon-separated) to list of directories
-to search for "import"ed modules.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-I<dir></Option></Term>
-<ListItem>
-<Para>
-Add <Filename><dir></Filename> to list of directories to search for
-.h files (i.e., usual meaning).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-syslib <blah></Option></Term>
-<ListItem>
-<Para>
-This program uses this GHC system library; take
-appropriate action (e.g., recognise when they are
-"import"ing a module from that library).
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-Here are the <Command>mkdependHS</Command>-specific options (not between <Literal>--</Literal>'s):
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-v</Option></Term>
-<ListItem>
-<Para>
-Be verbose.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-v -v</Option></Term>
-<ListItem>
-<Para>
-Be very verbose.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-w</Option></Term>
-<ListItem>
-<Para>
-Turn off warnings about interface file shadowing.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-f blah</Option></Term>
-<ListItem>
-<Para>
-Use <Filename>blah</Filename> as the makefile, rather than <Filename>makefile</Filename>
-or <Filename>Makefile</Filename>. If <Filename>blah</Filename> doesn't exist, <Command>mkdependHS</Command> creates it.
-We often use <Option>-f .depend</Option> to put the dependencies in <Filename>.depend</Filename> and
-then <Command>include</Command> the file <Filename>.depend</Filename> into <Filename>Makefile</Filename>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-o <osuf></Option></Term>
-<ListItem>
-<Para>
-Use <Filename>.<osuf></Filename> as the "target file" suffix ( default: <Literal>o</Literal>).
-Multiple <Option>-o</Option> flags are permitted (GHC2.05 onwards). Thus "<Option>-o hc -o o</Option>"
-will generate dependencies for <Filename>.hc</Filename> and <Filename>.o</Filename> files.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-s <suf></Option></Term>
-<ListItem>
-<Para>
-Make extra dependencies that declare that files with
-suffix <Filename>.<suf>_<osuf></Filename> depend on interface files with suffix <Filename>.<suf>_hi</Filename>, or
-(for <Literal>{-# SOURCE #-}</Literal> imports) on <Filename>.hi-boot</Filename>.
-Multiple <Option>-s</Option> flags are permitted.
-For example, <Option>-o hc -s a -s b</Option> will
-make dependencies for <Filename>.hc</Filename> on <Filename>.hi</Filename>, <Filename>.a_hc</Filename> on <Filename>.a_hi</Filename>, and <Filename>.b_hc</Filename> on <Filename>.b_hi</Filename>.
-(Useful in conjunction with NoFib "ways".)
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>--exclude-module=<file></Option></Term>
-<ListItem>
-<Para>
-Regard <Filename><file></Filename> as "stable"; i.e., exclude it from having
-dependencies on it.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-x</Option></Term>
-<ListItem>
-<Para>
-same as <Option>--exclude-module</Option>
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>--exclude-directory=<dirs></Option></Term>
-<ListItem>
-<Para>
-Regard the colon-separated list of directories <Filename><dirs></Filename> as containing stable,
-don't generate any dependencies on modules therein.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-Xdirs</Option></Term>
-<ListItem>
-<Para>
-same as <Option>--exclude-directory</Option>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>--include-module=<file></Option></Term>
-<ListItem>
-<Para>
-Regard <Filename><file></Filename> as not "stable"; i.e., generate dependencies
-on it (if any). This option is normally used in conjunction
-with the <Option>--exclude-directory</Option> option.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>--include-prelude</Option></Term>
-<ListItem>
-<Para>
-Regard prelude libraries as unstable, i.e., generate dependencies
-on the prelude modules used (including <Literal>Prelude</Literal>).
-This option is normally only used by the various system libraries. If
-a <Option>-syslib</Option> option is used, dependencies will also be
-generated on the library's interfaces.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect1>
-
-<Sect1 id="hstags">
-<Title>Emacs `TAGS' for Haskell: <Command>hstags</Command>
-</Title>
-
-<Para>
-<IndexTerm><Primary>hstags</Primary></IndexTerm>
-<IndexTerm><Primary>TAGS for Haskell</Primary></IndexTerm>
-</Para>
-
-<Para>
-`Tags' is a facility for indexing the definitions of
-programming-language things in a multi-file program, and then using
-that index to jump around among these definitions.
-</Para>
-
-<Para>
-Rather than scratch your head, saying “Now where did we define
-`foo'?”, you just do (in Emacs) <Literal>M-. foo RET</Literal>, and You're There!
-Some people go wild over this stuff…
-</Para>
-
-<Para>
-GHC comes with a program <Command>hstags</Command>, which build Emacs-able TAGS files. The invocation syntax is:
-
-<Screen>
-hstags [GHC-options] file [files...]
-</Screen>
+<chapter id="utils">
+ <title>Other Haskell utility programs</title>
+ <indexterm><primary>utilities, Haskell</primary></indexterm>
+
+ <para>This section describes other program(s) which we distribute,
+ that help with the Great Haskell Programming Task.</para>
+
+<!-- comment: hstags doesn't work anymore
+
+ <sect1 id="hstags">
+ <title>Emacs `TAGS' for Haskell: <command>hstags</command></title>
+ <indexterm><primary><command>hstags</command></primary></indexterm>
+ <indexterm><primary>TAGS for Haskell</primary></indexterm>
-</Para>
+ <para>`Tags' is a facility for indexing the definitions of
+ programming-language things in a multi-file program, and then
+ using that index to jump around among these definitions.</para>
+
+ <para>Rather than scratch your head, saying “Now where did
+ we define `foo'?”, you just do (in Emacs) <Literal>M-. foo
+ RET</Literal>, and You're There! Some people go wild over this
+ stuff…</para>
+
+ <para>GHC comes with a program <command>hstags</command>, which
+ build Emacs-able TAGS files. The invocation syntax is:</para>
+
+<screen>
+hstags [GHC-options] file [files...]
+</screen>
-<Para>
-The best thing is just to feed it your GHC command-line flags.
-A good Makefile entry might be:
+ <para>The best thing is just to feed it your GHC command-line
+ flags. A good Makefile entry might be:</para>
-<ProgramListing>
+<programlisting>
tags:
$(RM) TAGS
hstags $(GHC_FLAGS) *.lhs
-</ProgramListing>
-
-</Para>
-
-<Para>
-The only flags of its own are: <Option>-v</Option> to be verbose; <Option>-a</Option> to
-<Emphasis>APPEND</Emphasis> to the TAGS file, rather than write to it.
-</Para>
-
-<Para>
-Shortcomings: (1) Instance declarations don't get into the TAGS file
-(but the definitions inside them do); as instances aren't named, this
-is probably just as well. (2) Data-constructor definitions don't get
-in. Go for the corresponding type constructor instead.
-</Para>
-
-<Para>
-(Actually, GHC also comes with <Command>etags</Command> [for C], and <Command>perltags</Command>
-[for You Know What]. And—I cannot tell a lie—there is Denis
-Howe's <Command>fptags</Command> [for Haskell, etc.] in the <Filename>ghc/CONTRIB</Filename>
-section…)
-</Para>
-
-</Sect1>
-
-<Sect1 id="happy">
-<Title>“Yacc for Haskell”: <Command>happy</Command>
-</Title>
-
-<Para>
-<IndexTerm><Primary>happy</Primary></IndexTerm>
-<IndexTerm><Primary>Yacc for Haskell</Primary></IndexTerm>
-<IndexTerm><Primary>parser generator for Haskell</Primary></IndexTerm>
-Andy Gill and Simon Marlow have written a parser-generator for
-Haskell, called <Command>happy</Command>.<IndexTerm><Primary>happy parser generator</Primary></IndexTerm> <Command>Happy</Command>
-is to Haskell what <Command>Yacc</Command> is to C.
-</Para>
-
-<Para>
-You can get <Command>happy</Command> by FTP from <Literal>ftp.dcs.gla.ac.uk</Literal> in
-<Filename>pub/haskell/happy</Filename>, the file <Filename>happy-1.5-src.tar.gz</Filename>.
-</Para>
-
-<Para>
-<Command>Happy</Command> is at its shining best when compiled by GHC.
-</Para>
-
-</Sect1>
-
-<Sect1 id="pphs">
-<Title>Pretty-printing Haskell: <Command>pphs</Command>
-</Title>
-
-<Para>
-<IndexTerm><Primary>pphs</Primary></IndexTerm>
-<IndexTerm><Primary>pretty-printing Haskell code</Primary></IndexTerm>
-</Para>
-
-<Para>
-Andrew Preece has written
-<Command>pphs</Command>,<IndexTerm><Primary>pphs</Primary></IndexTerm><IndexTerm><Primary>pretty-printing Haskell</Primary></IndexTerm>
-a utility to pretty-print Haskell code in LaTeX documents.
-Keywords in bolds, variables in italics—that sort of thing. It is
-good at lining up program clauses and equals signs, things that are
-very tiresome to do by hand.
-</Para>
-
-<Para>
-The code is distributed with GHC in <Filename>ghc/CONTRIB/pphs</Filename>.
-</Para>
-
-</Sect1>
-
-</Chapter>
+</programlisting>
+
+ <para>The only flags of its own are: <Option>-v</Option> to be
+ verbose; <Option>-a</Option> to <Emphasis>APPEND</Emphasis> to the
+ TAGS file, rather than write to it.</para>
+
+ <para>Shortcomings: (1) Instance declarations don't get into
+ the TAGS file (but the definitions inside them do); as instances
+ aren't named, this is probably just as well.
+ (2) Data-constructor definitions don't get in. Go for the
+ corresponding type constructor instead.</para>
+
+ <para>Actually, GHC also comes with <command>etags</command>
+ [for C], and <Command>perltags</Command> [for You
+ Know What]. And—I cannot tell a lie—there is
+ Denis Howe's <Command>fptags</Command> [for Haskell,
+ etc.] in the <Filename>ghc/CONTRIB</Filename>
+ section…)</para>
+
+ </sect1>
+-->
+
+ <sect1 id="happy">
+ <title>“Yacc for Haskell”: <command>happy</command></title>
+
+ <indexterm><primary>Happy</primary></indexterm>
+ <indexterm><primary>Yacc for Haskell</primary></indexterm>
+ <indexterm><primary>parser generator for Haskell</primary></indexterm>
+
+ <para>Andy Gill and Simon Marlow have written a parser-generator
+ for Haskell, called
+ <Command>happy</Command>.<IndexTerm><Primary>happy parser
+ generator</Primary></IndexTerm> <command>Happy</command> is to
+ Haskell what <command>Yacc</command> is to C.</para>
+
+ <para>You can get <Command>happy</Command> from <ulink
+ url="http://www.haskell.org/happy/">the Happy
+ Homepage</ulink>.</para>
+
+ <para><command>Happy</command> is at its shining best when
+ compiled by GHC.</para>
+
+ </sect1>
+
+<!-- we don't distribute this anymore
+ <sect1 id="pphs">
+ <title>Pretty-printing Haskell: <Command>pphs</Command></title>
+ <indexterm><primary>pphs</primary></indexterm>
+ <indexterm><primary>pretty-printing Haskell code</primary></indexterm>
+
+ <para>Andrew Preece has written
+ <Command>pphs</Command>,<IndexTerm><Primary>pphs</Primary></IndexTerm><IndexTerm><Primary>pretty-printing
+ Haskell</Primary></IndexTerm> a utility to pretty-print Haskell
+ code in LaTeX documents. Keywords in bolds, variables in
+ italics—that sort of thing. It is good at lining up program
+ clauses and equals signs, things that are very tiresome to do by
+ hand.</para>
+
+ <para>The code is distributed with GHC in
+ <Filename>ghc/CONTRIB/pphs</Filename>.</para>
+ </sect1>
+-->
+
+ <sect1 id="hsc2hs">
+ <title>Writing Haskell interfaces to C code:
+ <command>hsc2hs</command></title>
+ <indexterm><primary><command>hsc2hs</command></primary>
+ </indexterm>
+
+ <para>The <command>hsc2hs</command> command can be used to automate
+ some parts of the process of writing Haskell bindings to C code.
+ It reads an almost-Haskell source with embedded special
+ constructs, and outputs a real Haskell file with these constructs
+ processed, based on information taken from some C headers. The
+ extra constructs deal with accessing C data from Haskell.</para>
+
+ <para>It may also output a C file which contains additional C
+ functions to be linked into the program, together with a C header
+ that gets included into the C code to which the Haskell module
+ will be compiled (when compiled via C) and into the C file. These
+ two files are created when the <literal>#def</literal> construct
+ is used (see below).</para>
+
+ <para>Actually <command>hsc2hs</command> does not output the Haskell
+ file directly. It creates a C program that includes the headers,
+ gets automatically compiled and run. That program outputs the
+ Haskell code.</para>
+
+ <para>In the following, “Haskell file” is the main
+ output (usually a <literal>.hs</literal> file), “compiled
+ Haskell file” is the Haskell file after
+ <command>ghc</command> has compiled it to C (i.e. a
+ <literal>.hc</literal> file), “C program” is the
+ program that outputs the Haskell file, “C file” is the
+ optionally generated C file, and “C header” is its
+ header file.</para>
+
+ <sect2>
+ <title>Command line syntax</title>
+
+ <para><command>hsc2hs</command> takes input files as arguments,
+ and flags that modify its behavior:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>-t FILE</literal> or
+ <literal>--template=FILE</literal></term>
+ <listitem>
+ <para>The template file (see below).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>--cc=PROG</literal></term>
+ <listitem>
+ <para>The C compiler to use (default:
+ <command>ghc</command>)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>--ld=PROG</literal></term>
+ <listitem>
+ <para>The linker to use (default:
+ <command>gcc</command>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>--cflag=FLAG</literal></term>
+ <listitem>
+ <para>An extra flag to pass to the C compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>-I DIR</literal></term>
+ <listitem>
+ <para>Passed to the C compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>--lflag=FLAG</literal></term>
+ <listitem>
+ <para>An extra flag to pass to the linker.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>--include=FILE</literal></term>
+ <listitem>
+ <para>As if the appropriate <literal>#include</literal>
+ directive was placed in the source.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>--help</literal></term>
+ <listitem>
+ <para>Display a summary of the available flags.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The input file should end with .hsc. Output files get
+ names with the <literal>*.hsc</literal> pattern replaced:</para>
+
+ <informaltable>
+ <tgroup cols=2>
+ <tbody>
+ <row>
+ <entry><literal>*.hs</literal></entry>
+ <entry>Haskell file</entry>
+ </row>
+ <row>
+ <entry><literal>Hs*.h</literal></entry>
+ <entry>C header</entry>
+ </row>
+ <row>
+ <entry><literal>Hs*.c</literal></entry>
+ <entry>C file</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>The C program is compiled using the Haskell compiler. This
+ provides the include path to <filename>HsFFI.h</filename> which
+ is automatically included into the C program.</para>
+
+ </sect2>
+ <sect2><title>Input syntax</title>
+
+ <para>All special processing is triggered by
+ the <literal>#</literal> operator. To output
+ a literal <literal>#</literal>, write it twice:
+ <literal>##</literal>. Inside string literals and comments
+ <literal>#</literal> characters are not processed.</para>
+
+ <para>A <literal>#</literal> is followed by optional
+ spaces and tabs, an alphanumeric keyword that describes
+ the kind of processing, and its arguments. Arguments look
+ like C expressions separated by commas (they are not
+ written inside parens). They extend up to the nearest
+ unmatched <literal>)</literal>, <literal>]</literal> or
+ <literal>}</literal>, or to the end of line if it occurs outside
+ any <literal>() [] {} '' "" /**/</literal> and is not preceded
+ by a backslash. Backslash-newline pairs are stripped.</para>
+
+ <para>In addition <literal>#{stuff}</literal> is equivalent
+ to <literal>#stuff</literal> except that it's self-delimited
+ and thus needs not to be placed at the end of line or in some
+ brackets.</para>
+
+ <para>Meanings of specific keywords:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><literal>#include <file.h></literal></term>
+ <term><literal>#include "file.h"</literal></term>
+ <listitem>
+ <para>The specified file gets included into the C program,
+ the compiled Haskell file, and the C header.
+ <literal><HsFFI.h></literal> is included
+ automatically.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#define name</literal></term>
+ <term><literal>#define name value</literal></term>
+ <term><literal>#undef name</literal></term>
+ <listitem>
+ <para>Similar to <literal>#include</literal>. Note that
+ <literal>#includes</literal> and
+ <literal>#defines</literal> may be put in the same file
+ twice so they should not assume otherwise.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#let name parameters = "definition"</literal></term>
+ <listitem>
+ <para>Defines a macro to be applied to the Haskell
+ source. Parameter names are comma-separated, not
+ inside parens. Such macro is invoked as other
+ <literal>#</literal>-constructs, starting with
+ <literal>#name</literal>. The definition will be
+ put in the C program inside parens as arguments of
+ <literal>printf</literal>. To refer to a parameter,
+ close the quote, put a parameter name and open the
+ quote again, to let C string literals concatenate.
+ Or use <literal>printf</literal>'s format directives.
+ Values of arguments must be given as strings, unless the
+ macro stringifies them itself using the C preprocessor's
+ <literal>#parameter</literal> syntax.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#def C_definition</literal></term>
+ <listitem>
+ <para>The definition (of a function, variable, struct or
+ typedef) is written to the C file, and its prototype or
+ extern declaration to the C header. Inline functions are
+ handled correctly. struct definitions and typedefs are
+ written to the C program too. The
+ <literal>inline</literal>, <literal>struct</literal> or
+ <literal>typedef</literal> keyword must come just after
+ <literal>def</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#if condition</literal></term>
+ <term><literal>#ifdef name</literal></term>
+ <term><literal>#ifndef name</literal></term>
+ <term><literal>#elif condition</literal></term>
+ <term><literal>#else</literal></term>
+ <term><literal>#endif</literal></term>
+ <term><literal>#error message</literal></term>
+ <term><literal>#warning message</literal></term>
+ <listitem>
+ <para>Conditional compilation directives are passed
+ unmodified to the C program, C file, and C header. Putting
+ them in the C program means that appropriate parts of the
+ Haskell file will be skipped.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#const C_expression</literal></term>
+ <listitem>
+ <para>The expression must be convertible to
+ <literal>long</literal> or <literal>unsigned
+ long</literal>. Its value (literal or negated literal)
+ will be output.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#const_str C_expression</literal></term>
+ <listitem>
+ <para>The expression must be convertible to const char
+ pointer. Its value (string literal) will be output.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#type C_type</literal></term>
+ <listitem>
+ <para>A Haskell equivalent of the C numeric type will be
+ output. It will be one of
+ <literal>{Int,Word}{8,16,32,64}</literal>,
+ <literal>Float</literal>, <literal>Double</literal>,
+ <literal>LDouble</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#peek struct_type, field</literal></term>
+ <listitem>
+ <para>A function that peeks a field of a C struct will be
+ output. It will have the type
+ <literal>Storable b => Ptr a -> IO b</literal>.
+
+ The intention is that <literal>#peek</literal> and
+ <literal>#poke</literal> can be used for implementing the
+ operations of class <literal>Storable</literal> for a
+ given C struct (see <xref linkend="sec-Storable">).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#poke struct_type, field</literal></term>
+ <listitem>
+ <para>Similarly for poke. It will have the type
+ <literal>Storable b => Ptr a -> b -> IO ()</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#ptr struct_type, field</literal></term>
+ <listitem>
+ <para>Makes a pointer to a field struct. It will have the type
+ <literal>Ptr a -> Ptr b</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>#enum type, constructor, value, value, ...</literal></term>
+ <listitem>
+ <para>A shortcut for multiple definitions which use
+ <literal>#const</literal>. Each <literal>value</literal>
+ is a name of a C integer constant, e.g. enumeration value.
+ The name will be translated to Haskell by making each
+ letter following an underscore uppercase, making all the rest
+ lowercase, and removing underscores. You can supply a different
+ translation by writing <literal>hs_name = c_value</literal>
+ instead of a <literal>value</literal>, in which case
+ <literal>c_value</literal> may be an arbitrary expression.
+ The <literal>hs_name</literal> will be defined as having the
+ specified <literal>type</literal>. Its definition is the specified
+ <literal>constructor</literal> (which in fact may be an expression
+ or be empty) applied to the appropriate integer value. You can
+ have multiple <literal>#enum</literal> definitions with the same
+ <literal>type</literal>; this construct does not emit the type
+ definition itself.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2>
+ <title>Custom constructs</title>
+
+ <para><literal>#const</literal>, <literal>#type</literal>,
+ <literal>#peek</literal>, <literal>#poke</literal> and
+ <literal>#ptr</literal> are not hardwired into the
+ <command>hsc2hs</command>, but are defined in a C template that is
+ included in the C program: <filename>template-hsc.h</filename>.
+ Custom constructs and templates can be used too. Any
+ <literal>#</literal>-construct with unknown key is expected to
+ be handled by a C template.</para>
+
+ <para>A C template should define a macro or function with name
+ prefixed by <literal>hsc_</literal> that handles the construct
+ by emitting the expansion to stdout. See
+ <filename>template-hsc.h</filename> for examples.</para>
+
+ <para>Such macros can also be defined directly in the
+ source. They are useful for making a <literal>#let</literal>-like
+ macro whose expansion uses other <literal>#let</literal> macros.
+ Plain <literal>#let</literal> prepends <literal>hsc_</literal>
+ to the macro name and wraps the defininition in a
+ <literal>printf</literal> call.</para>
+
+ </sect2>
+
+ </sect1>
+
+</chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
projects / ghc-hetmet.git / blobdiff