path: root/ghc/docs/users_guide/utils.sgml

<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>`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 &ldquo;Now where did
    we define `foo'?&rdquo;, you just do (in Emacs) <Literal>M-. foo
    RET</Literal>, and You're There!  Some people go wild over this
    stuff&hellip;</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>

<programlisting>
tags:
        $(RM) TAGS
        hstags $(GHC_FLAGS) *.lhs
</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)&nbsp;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)&nbsp;Data-constructor definitions don't get in.  Go for the
    corresponding type constructor instead.</para>

    <para>Actually, GHC also comes with <command>etags</command>
    &lsqb;for C&rsqb;, and <Command>perltags</Command> &lsqb;for You
    Know What&rsqb;.  And&mdash;I cannot tell a lie&mdash;there is
    Denis Howe's <Command>fptags</Command> &lsqb;for Haskell,
    etc.&rsqb; in the <Filename>ghc/CONTRIB</Filename>
    section&hellip;)</para>

  </sect1>
-->

  <sect1 id="happy">
    <title>&ldquo;Yacc for Haskell&rdquo;: <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&mdash;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, &ldquo;Haskell file&rdquo; is the main
    output (usually a <literal>.hs</literal> file), &ldquo;compiled
    Haskell file&rdquo; is the Haskell file after
    <command>ghc</command> has compiled it to C (i.e. a
    <literal>.hc</literal> file), &ldquo;C program&rdquo; is the
    program that outputs the Haskell file, &ldquo;C file&rdquo; is the
    optionally generated C file, and &ldquo;C header&rdquo; 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> suffix 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 &lt;file.h&gt;</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>&lt;HsFFI.h&gt;</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: ***
     ;;; mode: sgml ***
     ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
     ;;; End: ***
 -->