</sect1>
-->
- <sect1 id="hs2c">
+ <sect1 id="hsc2hs">
<title>Writing Haskell interfaces to C code:
- <command>hs2c</command></title>
- <indexterm><primary><command>hs2c</command></primary>
+ <command>hsc2hs</command></title>
+ <indexterm><primary><command>hsc2hs</command></primary>
</indexterm>
- <para>The <command>hs2c</command> command can be used to automate
+ <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
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.</para>
+ is used (see below).</para>
- <para>Actually <command>hs2c</command> does not output the Haskell
+ <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>
<sect2>
<title>Command line syntax</title>
- <para>glue-hsc takes input files as arguments, and flags that
- modify its behavior:</para>
+ <para><command>hsc2hs</command> takes input files as arguments,
+ and flags that modify its behavior:</para>
<variablelist>
<varlistentry>
</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>
</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>
</variablelist>
<para>The input file should end with .hsc. Output files get
- names with the <literal>.hsc</literal> suffix replaced:</para>
+ names with the <literal>*.hsc</literal> pattern replaced:</para>
<informaltable>
<tgroup cols=2>
<tbody>
<row>
- <entry><literal>.hs</literal></entry>
+ <entry><literal>*.hs</literal></entry>
<entry>Haskell file</entry>
</row>
<row>
- <entry><literal>_hsc.h</literal></entry>
+ <entry><literal>Hs*.h</literal></entry>
<entry>C header</entry>
</row>
<row>
- <entry><literal>_hsc.c</literal></entry>
+ <entry><literal>Hs*.c</literal></entry>
<entry>C file</entry>
</row>
</tbody>
</sect2>
<sect2><title>Input syntax</title>
- <para>All special processing is triggered by the
- <literal>#</literal> character. To output a literal
- <literal>#</literal>, write it twice: <literal>##</literal>.</para>
-
- <para>Otherwise <literal>#</literal> is followed by optional
- spaces and tabs, an alphanumeric key that describes the kind of
- processing, and its arguments. Arguments look like C expressions
- and extend up to the nearest unmatched <literal>)</literal>,
- <literal>]</literal>, or <literal>}</literal>, or to the end of
- line outside any <literal>() [] {} '' "" /* */</literal>. Any
- character may be preceded by a backslash and will not be treated
- specially.</para>
-
- <para>Meanings of specific keys:</para>
+ <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>
<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
+ 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
</varlistentry>
<varlistentry>
- <term><literal>#option opt</literal></term>
+ <term><literal>#let name parameters = "definition"</literal></term>
<listitem>
- <para>The specified Haskell compiler command-line option
- is placed in the <literal>{-# OPTIONS #-}</literal> pragma
- at the top of the Haskell file (see <xref
- linkend="source-file-options">). This is needed because
- glue-hsc emits its own <literal>OPTIONS</literal> pragma,
- and only one such pragma is interpreted by GHC.</para>
+ <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>
<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
<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>
<para><literal>#const</literal>, <literal>#type</literal>,
<literal>#peek</literal>, <literal>#poke</literal> and
<literal>#ptr</literal> are not hardwired into the
- <command>hs2c</command>, but are defined in a C template that is
+ <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
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>
projects / ghc-hetmet.git / blobdiff