<para>This section describes other program(s) which we distribute,
that help with the Great Haskell Programming Task.</para>
+<!-- comment: hasktags documentation losely 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 guranteed 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">
corresponding type constructor instead.</para>
<para>Actually, GHC also comes with <command>etags</command>
- [for C], and <Command>perltags</Command> [for You
+ [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,
+ Denis Howe's <command>fptags</command> [for Haskell,
etc.] in the <Filename>ghc/CONTRIB</Filename>
section…)</para>
<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
+ <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
+ <para>You can get <command>happy</command> from <ulink
url="http://www.haskell.org/happy/">the Happy
Homepage</ulink>.</para>
<!-- we don't distribute this anymore
<sect1 id="pphs">
- <title>Pretty-printing Haskell: <Command>pphs</Command></title>
+ <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
+ <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
header file.</para>
<sect2>
- <title>Command line syntax</title>
+ <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>
+ <literal>––template=FILE</literal></term>
<listitem>
<para>The template file (see below).</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>--cc=PROG</literal></term>
+ <term><literal>-c PROG</literal> or
+ <literal>––cc=PROG</literal></term>
<listitem>
<para>The C compiler to use (default:
<command>ghc</command>)</para>
</varlistentry>
<varlistentry>
- <term><literal>--ld=PROG</literal></term>
+ <term><literal>-l PROG</literal> or
+ <literal>––ld=PROG</literal></term>
<listitem>
<para>The linker to use (default:
<command>gcc</command>).</para>
</varlistentry>
<varlistentry>
- <term><literal>--cflag=FLAG</literal></term>
+ <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>--lflag=FLAG</literal></term>
+ <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>--include=FILE</literal></term>
+ <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>
</varlistentry>
<varlistentry>
- <term><literal>--help</literal></term>
+ <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>Display a summary of the available flags.</para>
+ <para>Output version information and exit successfully.</para>
</listitem>
</varlistentry>
</variablelist>
- <para>The input file should end with .hsc. Output files get
- names with the <literal>.hsc</literal> suffix replaced:</para>
+ <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>
+ <tgroup cols="2">
<tbody>
<row>
<entry><literal>.hs</literal></entry>
<entry>Haskell file</entry>
</row>
<row>
- <entry><literal>.hs.h</literal></entry>
+ <entry><literal>_hsc.h</literal></entry>
<entry>C header</entry>
</row>
<row>
- <entry><literal>.hs.c</literal></entry>
+ <entry><literal>_hsc.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 placed outside Haskell comments
- and string literals. 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 separated by commas 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>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 keys:</para>
+ <para>Meanings of specific keywords:</para>
<variablelist>
<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>
<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>.
+ 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>
+ 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
+ <para>Similarly for poke. It will have the type
<literal>Storable b => Ptr a -> b -> IO ()</literal>.</para>
</listitem>
</varlistentry>
</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
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.
projects / ghc-hetmet.git / blobdiff