ghc/docs/users_guide/utils.sgml

   1 <chapter id="utils">
   2   <title>Other Haskell utility programs</title>
   3   <indexterm><primary>utilities, Haskell</primary></indexterm>
   4
   5   <para>This section describes other program(s) which we distribute,
   6   that help with the Great Haskell Programming Task.</para>
   7
   8 <!-- comment: hstags doesn't work anymore
   9
  10   <sect1 id="hstags">
  11     <title>Emacs `TAGS' for Haskell: <command>hstags</command></title>
  12     <indexterm><primary><command>hstags</command></primary></indexterm>
  13     <indexterm><primary>TAGS for Haskell</primary></indexterm>
  14
  15     <para>`Tags' is a facility for indexing the definitions of
  16     programming-language things in a multi-file program, and then
  17     using that index to jump around among these definitions.</para>
  18
  19     <para>Rather than scratch your head, saying &ldquo;Now where did
  20     we define `foo'?&rdquo;, you just do (in Emacs) <Literal>M-. foo
  21     RET</Literal>, and You're There!  Some people go wild over this
  22     stuff&hellip;</para>
  23
  24     <para>GHC comes with a program <command>hstags</command>, which
  25     build Emacs-able TAGS files.  The invocation syntax is:</para>
  26
  27 <screen>
  28 hstags [GHC-options] file [files...]
  29 </screen>
  30
  31     <para>The best thing is just to feed it your GHC command-line
  32     flags.  A good Makefile entry might be:</para>
  33
  34 <programlisting>
  35 tags:
  36         $(RM) TAGS
  37         hstags $(GHC_FLAGS) *.lhs
  38 </programlisting>
  39
  40     <para>The only flags of its own are: <Option>-v</Option> to be
  41     verbose; <Option>-a</Option> to <Emphasis>APPEND</Emphasis> to the
  42     TAGS file, rather than write to it.</para>
  43
  44     <para>Shortcomings: (1)&nbsp;Instance declarations don't get into
  45     the TAGS file (but the definitions inside them do); as instances
  46     aren't named, this is probably just as well.
  47     (2)&nbsp;Data-constructor definitions don't get in.  Go for the
  48     corresponding type constructor instead.</para>
  49
  50     <para>Actually, GHC also comes with <command>etags</command>
  51     &lsqb;for C&rsqb;, and <Command>perltags</Command> &lsqb;for You
  52     Know What&rsqb;.  And&mdash;I cannot tell a lie&mdash;there is
  53     Denis Howe's <Command>fptags</Command> &lsqb;for Haskell,
  54     etc.&rsqb; in the <Filename>ghc/CONTRIB</Filename>
  55     section&hellip;)</para>
  56
  57   </sect1>
  58 -->
  59
  60   <sect1 id="happy">
  61     <title>&ldquo;Yacc for Haskell&rdquo;: <command>happy</command></title>
  62
  63     <indexterm><primary>Happy</primary></indexterm>
  64     <indexterm><primary>Yacc for Haskell</primary></indexterm>
  65     <indexterm><primary>parser generator for Haskell</primary></indexterm>
  66
  67     <para>Andy Gill and Simon Marlow have written a parser-generator
  68     for Haskell, called
  69     <Command>happy</Command>.<IndexTerm><Primary>happy parser
  70     generator</Primary></IndexTerm> <command>Happy</command> is to
  71     Haskell what <command>Yacc</command> is to C.</para>
  72
  73     <para>You can get <Command>happy</Command> from <ulink
  74     url="http://www.haskell.org/happy/">the Happy
  75     Homepage</ulink>.</para>
  76
  77     <para><command>Happy</command> is at its shining best when
  78     compiled by GHC.</para>
  79
  80   </sect1>
  81
  82 <!-- we don't distribute this anymore
  83   <sect1 id="pphs">
  84     <title>Pretty-printing Haskell: <Command>pphs</Command></title>
  85     <indexterm><primary>pphs</primary></indexterm>
  86     <indexterm><primary>pretty-printing Haskell code</primary></indexterm>
  87
  88     <para>Andrew Preece has written
  89     <Command>pphs</Command>,<IndexTerm><Primary>pphs</Primary></IndexTerm><IndexTerm><Primary>pretty-printing
  90     Haskell</Primary></IndexTerm> a utility to pretty-print Haskell
  91     code in LaTeX documents.  Keywords in bolds, variables in
  92     italics&mdash;that sort of thing.  It is good at lining up program
  93     clauses and equals signs, things that are very tiresome to do by
  94     hand.</para>
  95
  96     <para>The code is distributed with GHC in
  97     <Filename>ghc/CONTRIB/pphs</Filename>.</para>
  98   </sect1>
  99 -->
 100
 101   <sect1 id="hsc2hs">
 102     <title>Writing Haskell interfaces to C code:
 103     <command>hsc2hs</command></title>
 104     <indexterm><primary><command>hsc2hs</command></primary>
 105     </indexterm>
 106
 107     <para>The <command>hsc2hs</command> command can be used to automate
 108     some parts of the process of writing Haskell bindings to C code.
 109     It reads an almost-Haskell source with embedded special
 110     constructs, and outputs a real Haskell file with these constructs
 111     processed, based on information taken from some C headers. The
 112     extra constructs deal with accessing C data from Haskell.</para>
 113
 114     <para>It may also output a C file which contains additional C
 115     functions to be linked into the program, together with a C header
 116     that gets included into the C code to which the Haskell module
 117     will be compiled (when compiled via C) and into the C file. These
 118     two files are created when the <literal>#def</literal> construct
 119     is used (see below).</para>
 120
 121     <para>Actually <command>hsc2hs</command> does not output the Haskell
 122     file directly.  It creates a C program that includes the headers,
 123     gets automatically compiled and run. That program outputs the
 124     Haskell code.</para>
 125
 126     <para>In the following, &ldquo;Haskell file&rdquo; is the main
 127     output (usually a <literal>.hs</literal> file), &ldquo;compiled
 128     Haskell file&rdquo; is the Haskell file after
 129     <command>ghc</command> has compiled it to C (i.e. a
 130     <literal>.hc</literal> file), &ldquo;C program&rdquo; is the
 131     program that outputs the Haskell file, &ldquo;C file&rdquo; is the
 132     optionally generated C file, and &ldquo;C header&rdquo; is its
 133     header file.</para>
 134
 135     <sect2>
 136       <title>Command line syntax</title>
 137
 138       <para><command>hsc2hs</command> takes input files as arguments,
 139       and flags that modify its behavior:</para>
 140
 141       <variablelist>
 142         <varlistentry>
 143           <term><literal>-t FILE</literal> or
 144           <literal>--template=FILE</literal></term>
 145           <listitem>
 146             <para>The template file (see below).</para>
 147           </listitem>
 148         </varlistentry>
 149
 150         <varlistentry>
 151           <term><literal>--cc=PROG</literal></term>
 152           <listitem>
 153             <para>The C compiler to use (default:
 154             <command>ghc</command>)</para>
 155           </listitem>
 156         </varlistentry>
 157
 158         <varlistentry>
 159           <term><literal>--ld=PROG</literal></term>
 160           <listitem>
 161             <para>The linker to use (default:
 162             <command>gcc</command>).</para>
 163           </listitem>
 164         </varlistentry>
 165
 166         <varlistentry>
 167           <term><literal>--cflag=FLAG</literal></term>
 168           <listitem>
 169             <para>An extra flag to pass to the C compiler.</para>
 170           </listitem>
 171         </varlistentry>
 172
 173         <varlistentry>
 174           <term><literal>-I DIR</literal></term>
 175           <listitem>
 176             <para>Passed to the C compiler.</para>
 177           </listitem>
 178         </varlistentry>
 179
 180         <varlistentry>
 181           <term><literal>--lflag=FLAG</literal></term>
 182           <listitem>
 183             <para>An extra flag to pass to the linker.</para>
 184           </listitem>
 185         </varlistentry>
 186
 187         <varlistentry>
 188           <term><literal>--include=FILE</literal></term>
 189           <listitem>
 190             <para>As if the appropriate <literal>#include</literal>
 191             directive was placed in the source.</para>
 192           </listitem>
 193         </varlistentry>
 194
 195         <varlistentry>
 196           <term><literal>--help</literal></term>
 197           <listitem>
 198             <para>Display a summary of the available flags.</para>
 199           </listitem>
 200         </varlistentry>
 201       </variablelist>
 202
 203       <para>The input file should end with .hsc. Output files get
 204       names with the <literal>.hsc</literal> suffix replaced:</para>
 205
 206       <informaltable>
 207         <tgroup cols=2>
 208           <tbody>
 209             <row>
 210               <entry><literal>.hs</literal></entry>
 211               <entry>Haskell file</entry>
 212             </row>
 213             <row>
 214               <entry><literal>.hs.h</literal></entry>
 215               <entry>C header</entry>
 216             </row>
 217             <row>
 218               <entry><literal>.hs.c</literal></entry>
 219               <entry>C file</entry>
 220             </row>
 221           </tbody>
 222         </tgroup>
 223       </informaltable>
 224
 225       <para>The C program is compiled using the Haskell compiler. This
 226       provides the include path to <filename>HsFFI.h</filename> which
 227       is automatically included into the C program.</para>
 228
 229     </sect2>
 230     <sect2><title>Input syntax</title>
 231
 232       <para>All special processing is triggered by the
 233       <literal>#</literal> character placed outside Haskell comments
 234       and string literals. To output a literal <literal>#</literal>,
 235       write it twice: <literal>##</literal>.</para>
 236
 237       <para>Otherwise <literal>#</literal> is followed by optional
 238       spaces and tabs, an alphanumeric key that describes the
 239       kind of processing, and its arguments. Arguments look
 240       like C expressions separated by commas and extend up to the
 241       nearest unmatched <literal>)</literal>, <literal>]</literal>,
 242       or <literal>}</literal>, or to the end of line outside any
 243       <literal>() [] {} '' "" /* */</literal>. Any character may be
 244       preceded by a backslash and will not be treated specially.</para>
 245
 246       <para>Meanings of specific keys:</para>
 247
 248       <variablelist>
 249
 250         <varlistentry>
 251           <term><literal>#include &lt;file.h&gt;</literal></term>
 252           <term><literal>#include "file.h"</literal></term>
 253           <listitem>
 254             <para>The specified file gets included into the C program,
 255             the compiled Haskell file, and the C header.
 256             <literal>&lt;HsFFI.h&gt;</literal> is included
 257             automatically.</para>
 258           </listitem>
 259         </varlistentry>
 260
 261         <varlistentry>
 262           <term><literal>#define name</literal></term>
 263           <term><literal>#define name value</literal></term>
 264           <term><literal>#undef name</literal></term>
 265           <listitem>
 266             <para>Similar to <literal>#include</literal>. Note that
 267             <literal>#includes</literal> and
 268             <literal>#defines</literal> may be put in the same file
 269             twice so they should not assume otherwise.</para>
 270           </listitem>
 271         </varlistentry>
 272
 273         <varlistentry>
 274           <term><literal>#let name parameters = "definition"</literal></term>
 275           <listitem>
 276             <para>Defines a macro to be applied to the Haskell
 277             source. Parameter names are comma-separated, not
 278             inside parens. Such macro is invoked as other
 279             <literal>#</literal>-constructs, starting with
 280             <literal>#name</literal>. The definition will be
 281             put in the C program inside parens as arguments of
 282             <literal>printf</literal>. To refer to a parameter,
 283             close the quote, put a parameter name and open the
 284             quote again, to let C string literals concatenate.
 285             Or use <literal>printf</literal>'s format directives.
 286             Values of arguments must be given as strings, unless the
 287             macro stringifies them itself using the C preprocessor's
 288             <literal>#parameter</literal> syntax.</para>
 289           </listitem>
 290         </varlistentry>
 291
 292         <varlistentry>
 293           <term><literal>#option opt</literal></term>
 294           <listitem>
 295             <para>The specified Haskell compiler command-line option
 296             is placed in the <literal>{-# OPTIONS #-}</literal> pragma
 297             at the top of the Haskell file (see <xref
 298             linkend="source-file-options">). This is needed because
 299             <command>hsc2hs</command> emits its own <literal>OPTIONS</literal> pragma,
 300             and only one such pragma is interpreted by GHC.</para>
 301           </listitem>
 302         </varlistentry>
 303
 304         <varlistentry>
 305           <term><literal>#def C_definition</literal></term>
 306           <listitem>
 307             <para>The definition (of a function, variable, struct or
 308             typedef) is written to the C file, and its prototype or
 309             extern declaration to the C header. Inline functions are
 310             handled correctly.  struct definitions and typedefs are
 311             written to the C program too.  The
 312             <literal>inline</literal>, <literal>struct</literal> or
 313             <literal>typedef</literal> keyword must come just after
 314             <literal>def</literal>.</para>
 315           </listitem>
 316         </varlistentry>
 317
 318         <varlistentry>
 319           <term><literal>#if condition</literal></term>
 320           <term><literal>#ifdef name</literal></term>
 321           <term><literal>#ifndef name</literal></term>
 322           <term><literal>#elif condition</literal></term>
 323           <term><literal>#else</literal></term>
 324           <term><literal>#endif</literal></term>
 325           <term><literal>#error message</literal></term>
 326           <listitem>
 327             <para>Conditional compilation directives are passed
 328             unmodified to the C program, C file, and C header. Putting
 329             them in the C program means that appropriate parts of the
 330             Haskell file will be skipped.</para>
 331           </listitem>
 332         </varlistentry>
 333
 334         <varlistentry>
 335           <term><literal>#const C_expression</literal></term>
 336           <listitem>
 337             <para>The expression must be convertible to
 338             <literal>long</literal> or <literal>unsigned
 339             long</literal>.  Its value (literal or negated literal)
 340             will be output.</para>
 341           </listitem>
 342         </varlistentry>
 343
 344         <varlistentry>
 345           <term><literal>#const_str C_expression</literal></term>
 346           <listitem>
 347             <para>The expression must be convertible to const char
 348             pointer.  Its value (string literal) will be output.</para>
 349           </listitem>
 350         </varlistentry>
 351
 352         <varlistentry>
 353           <term><literal>#type C_type</literal></term>
 354           <listitem>
 355             <para>A Haskell equivalent of the C numeric type will be
 356             output.  It will be one of
 357             <literal>{Int,Word}{8,16,32,64}</literal>,
 358             <literal>Float</literal>, <literal>Double</literal>,
 359             <literal>LDouble</literal>.</para>
 360           </listitem>
 361         </varlistentry>
 362
 363         <varlistentry>
 364           <term><literal>#peek struct_type, field</literal></term>
 365           <listitem>
 366             <para>A function that peeks a field of a C struct will be
 367             output.  It will have the type
 368               <literal>Storable b => Ptr a -> IO b</literal>.
 369
 370             The intention is that <literal>#peek</literal> and
 371             <literal>#poke</literal> can be used for implementing the
 372             operations of class <literal>Storable</literal> for a
 373             given C struct (see <xref linkend="sec-Storable">).</para>
 374           </listitem>
 375         </varlistentry>
 376
 377         <varlistentry>
 378           <term><literal>#poke struct_type, field</literal></term>
 379           <listitem>
 380             <para>Similarly for poke. It will have the type
 381               <literal>Storable b => Ptr a -> b -> IO ()</literal>.</para>
 382           </listitem>
 383         </varlistentry>
 384
 385         <varlistentry>
 386           <term><literal>#ptr struct_type, field</literal></term>
 387           <listitem>
 388             <para>Makes a pointer to a field struct. It will have the type
 389             <literal>Ptr a -> Ptr b</literal>.</para>
 390           </listitem>
 391         </varlistentry>
 392       </variablelist>
 393
 394     </sect2>
 395
 396     <sect2>
 397       <title>Custom constructs</title>
 398
 399       <para><literal>#const</literal>, <literal>#type</literal>,
 400       <literal>#peek</literal>, <literal>#poke</literal> and
 401       <literal>#ptr</literal> are not hardwired into the
 402       <command>hsc2hs</command>, but are defined in a C template that is
 403       included in the C program: <filename>template-hsc.h</filename>.
 404       Custom constructs and templates can be used too. Any
 405       <literal>#</literal>-construct with unknown key is expected to
 406       be handled by a C template.</para>
 407
 408       <para>A C template should define a macro or function with name
 409       prefixed by <literal>hsc_</literal> that handles the construct
 410       by emitting the expansion to stdout. See
 411       <filename>template-hsc.h</filename> for examples.</para>
 412
 413       <para>Such macros can also be defined directly in the
 414       source. They are useful for making a <literal>#let</literal>-like
 415       macro whose expansion uses other <literal>#let</literal> macros.
 416       Plain <literal>#let</literal> prepends <literal>hsc_</literal>
 417       to the macro name and wraps the defininition in a
 418       <literal>printf</literal> call.
 419
 420     </sect2>
 421
 422   </sect1>
 423
 424 </chapter>
 425
 426 <!-- Emacs stuff:
 427      ;;; Local Variables: ***
 428      ;;; mode: sgml ***
 429      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 430      ;;; End: ***
 431  -->