+++ /dev/null
-<?xml version="1.0" encoding="iso-8859-1"?>
-<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: hasktags documentation loosely based on that for hstags -->
-
-<sect1 id ="hasktags">
- <title>Ctags and Etags for Haskell: <command>hasktags</command></title>
- <indexterm><primary><command>hasktags</command></primary></indexterm>
- <indexterm><primary>CTAGS for Haskell</primary></indexterm>
-
- <para><command>hasktags</command> is a very simple Haskell program that produces ctags "tags" and etags "TAGS" files for Haskell programs.</para>
-
- <para>When loaded into an editor such an NEdit, Vim, or Emacs, this allows one to easily navigate around a multi-file program, finding definitions of functions, types, and constructors.</para>
-
- <para>Invocation Syntax:</para>
-
-<screen>
-hasktags files
-</screen>
-
-<para>This will read all the files listed in <option>files</option> and produce a ctags "tags" file and an etags "TAGS" file in the current directory.</para>
-
- <para>Example usage</para>
-
-<screen>
-find -name \*.\*hs | xargs hasktags
-</screen>
-
-<para>This will find all haskell source files in the current directory and below, and create tags files indexing them in the current directory.</para>
-
- <para><command>hasktags</command> is a simple program that uses simple
- parsing rules to find definitions of functions, constructors, and types. It isn't guaranteed to find everything, and will sometimes create false index entries, but it usually gets the job done fairly well. In particular, at present, functions are only indexed if a type signature is given for them.</para>
-
- <para>Before hasktags, there used to be <command>fptags</command> and <command>hstags</command>, which did essentially the same job, however neither of these seem to be maintained any more.</para>
-
-<sect2>
-<title>Using tags with your editor</title>
-
-<para>With NEdit, load the "tags" file using "File/Load Tags File". Use "Ctrl-D" to search for a tag.</para>
-
-<para>With XEmacs, load the "TAGS" file using "visit-tags-table". Use "M-." to search for a tag.</para>
-
-
-</sect2>
-
-</sect1>
-
-<!-- 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 “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>
-
-<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) 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>-o FILE</literal> or
- <literal>––output=FILE</literal></term>
- <listitem>
- <para>Name of the Haskell file.</para>
- </listitem>
- </varlistentry>
-
- <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>-c PROG</literal> or
- <literal>––cc=PROG</literal></term>
- <listitem>
- <para>The C compiler to use (default:
- <command>ghc</command>)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>-l PROG</literal> or
- <literal>––ld=PROG</literal></term>
- <listitem>
- <para>The linker to use (default:
- <command>gcc</command>).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>-C FLAG</literal> or
- <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>-L FLAG</literal> or
- <literal>––lflag=FLAG</literal></term>
- <listitem>
- <para>An extra flag to pass to the linker.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>-i FILE</literal> or
- <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>-D NAME[=VALUE]</literal> or
- <literal>––define=NAME[=VALUE]</literal></term>
- <listitem>
- <para>As if the appropriate <literal>#define</literal>
- directive was placed in the source.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>––no-compile</literal></term>
- <listitem>
- <para>Stop after writing out the intermediate C program to disk.
- The file name for the intermediate C program is the input file name
- with <literal>.hsc</literal> replaced with <literal>_hsc_make.c</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>-?</literal> or <literal>––help</literal></term>
- <listitem>
- <para>Display a summary of the available flags and exit successfully.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>-V</literal> or <literal>––version</literal></term>
- <listitem>
- <para>Output version information and exit successfully.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>The input file should end with .hsc (it should be plain
- Haskell source only; literate Haskell is not supported at the
- moment). Output files by default 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>_hsc.h</literal></entry>
- <entry>C header</entry>
- </row>
- <row>
- <entry><literal>_hsc.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>
-
- <note><para>A <literal>foreign import</literal> of a
- C function may be inlined across a module boundary,
- in which case you must arrange for the importing
- module to <literal>#include</literal> the C header
- file generated by <command>hsc2hs</command> (see
- <xref linkend="glasgow-foreign-headers"/>).
- For this reason we avoid using <literal>#def</literal>
- in the libraries.</para></note>
- </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 the
- <literal>Foreign.Storable</literal> module in the library
- documentation).</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>#offset struct_type, field</literal></term>
- <listitem>
- <para>Computes the offset, in bytes, of
- <literal>field</literal> in
- <literal>struct_type</literal>. It will have type
- <literal>Int</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>#size struct_type</literal></term>
- <listitem>
- <para>Computes the size, in bytes, of
- <literal>struct_type</literal>. It will have type
- <literal>Int</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 definition in a
- <literal>printf</literal> call.</para>
-
- </sect2>
-
- </sect1>
-
-</chapter>
-
-<!-- Emacs stuff:
- ;;; Local Variables: ***
- ;;; mode: xml ***
- ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
- ;;; End: ***
- -->
projects / ghc-hetmet.git / blobdiff