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>hsc2hs</command> does not output the Haskell
file directly. It creates a C program that includes the headers,
<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>
</varlistentry>
<varlistentry>
- <term><literal>#option opt</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>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><literal>#def C_definition</literal></term>
<listitem>
<para>The definition (of a function, variable, struct or
<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>
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