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>-c PROG</literal> or
 152           <literal>--cc=PROG</literal></term>
 153           <listitem>
 154             <para>The C compiler to use (default:
 155             <command>ghc</command>)</para>
 156           </listitem>
 157         </varlistentry>
 158
 159         <varlistentry>
 160           <term><literal>-l PROG</literal> or
 161           <literal>--ld=PROG</literal></term>
 162           <listitem>
 163             <para>The linker to use (default:
 164             <command>gcc</command>).</para>
 165           </listitem>
 166         </varlistentry>
 167
 168         <varlistentry>
 169           <term><literal>-C FLAG</literal> or
 170           <literal>--cflag=FLAG</literal></term>
 171           <listitem>
 172             <para>An extra flag to pass to the C compiler.</para>
 173           </listitem>
 174         </varlistentry>
 175
 176         <varlistentry>
 177           <term><literal>-I DIR</literal></term>
 178           <listitem>
 179             <para>Passed to the C compiler.</para>
 180           </listitem>
 181         </varlistentry>
 182
 183         <varlistentry>
 184           <term><literal>-L FLAG</literal> or
 185           <literal>--lflag=FLAG</literal></term>
 186           <listitem>
 187             <para>An extra flag to pass to the linker.</para>
 188           </listitem>
 189         </varlistentry>
 190
 191         <varlistentry>
 192           <term><literal>-i FILE</literal> or
 193           <literal>--include=FILE</literal></term>
 194           <listitem>
 195             <para>As if the appropriate <literal>#include</literal>
 196             directive was placed in the source.</para>
 197           </listitem>
 198         </varlistentry>
 199
 200         <varlistentry>
 201           <term><literal>-D NAME[=VALUE]</literal> or
 202           <literal>--define=NAME[=VALUE]</literal></term>
 203           <listitem>
 204             <para>As if the appropriate <literal>#define</literal>
 205             directive was placed in the source.</para>
 206           </listitem>
 207         </varlistentry>
 208
 209         <varlistentry>
 210           <term><literal>-o FILE</literal> or
 211           <literal>--output=FILE</literal></term>
 212           <listitem>
 213             <para>Name of the Haskell file.</para>
 214           </listitem>
 215         </varlistentry>
 216
 217         <varlistentry>
 218           <term><literal>-s FILE</literal> or
 219           <literal>--support=FILE</literal></term>
 220           <listitem>
 221             <para>Basename of the C file and C header
 222             (with <literal>.c</literal>, <literal>.h</literal>
 223             suffixes removed).</para>
 224           </listitem>
 225         </varlistentry>
 226
 227         <varlistentry>
 228           <term><literal>--help</literal></term>
 229           <listitem>
 230             <para>Display a summary of the available flags.</para>
 231           </listitem>
 232         </varlistentry>
 233
 234         <varlistentry>
 235           <term><literal>--version</literal></term>
 236           <listitem>
 237             <para>Output version information.</para>
 238           </listitem>
 239         </varlistentry>
 240       </variablelist>
 241
 242       <para>The input file should end with .hsc. Output files by
 243       default get names with the <literal>*.hsc</literal> pattern
 244       replaced:</para>
 245
 246       <informaltable>
 247         <tgroup cols=2>
 248           <tbody>
 249             <row>
 250               <entry><literal>*.hs</literal></entry>
 251               <entry>Haskell file</entry>
 252             </row>
 253             <row>
 254               <entry><literal>Hs*.h</literal></entry>
 255               <entry>C header</entry>
 256             </row>
 257             <row>
 258               <entry><literal>Hs*.c</literal></entry>
 259               <entry>C file</entry>
 260             </row>
 261           </tbody>
 262         </tgroup>
 263       </informaltable>
 264
 265       <para>The C program is compiled using the Haskell compiler. This
 266       provides the include path to <filename>HsFFI.h</filename> which
 267       is automatically included into the C program.</para>
 268
 269     </sect2>
 270     <sect2><title>Input syntax</title>
 271
 272       <para>All special processing is triggered by
 273       the <literal>#</literal> operator. To output
 274       a literal <literal>#</literal>, write it twice:
 275       <literal>##</literal>. Inside string literals and comments
 276       <literal>#</literal> characters are not processed.</para>
 277
 278       <para>A <literal>#</literal> is followed by optional
 279       spaces and tabs, an alphanumeric keyword that describes
 280       the kind of processing, and its arguments. Arguments look
 281       like C expressions separated by commas (they are not
 282       written inside parens).  They extend up to the nearest
 283       unmatched <literal>)</literal>, <literal>]</literal> or
 284       <literal>}</literal>, or to the end of line if it occurs outside
 285       any <literal>() [] {} '' "" /**/</literal> and is not preceded
 286       by a backslash. Backslash-newline pairs are stripped.</para>
 287
 288       <para>In addition <literal>#{stuff}</literal> is equivalent
 289       to <literal>#stuff</literal> except that it's self-delimited
 290       and thus needs not to be placed at the end of line or in some
 291       brackets.</para>
 292
 293       <para>Meanings of specific keywords:</para>
 294
 295       <variablelist>
 296
 297         <varlistentry>
 298           <term><literal>#include &lt;file.h&gt;</literal></term>
 299           <term><literal>#include "file.h"</literal></term>
 300           <listitem>
 301             <para>The specified file gets included into the C program,
 302             the compiled Haskell file, and the C header.
 303             <literal>&lt;HsFFI.h&gt;</literal> is included
 304             automatically.</para>
 305           </listitem>
 306         </varlistentry>
 307
 308         <varlistentry>
 309           <term><literal>#define name</literal></term>
 310           <term><literal>#define name value</literal></term>
 311           <term><literal>#undef name</literal></term>
 312           <listitem>
 313             <para>Similar to <literal>#include</literal>. Note that
 314             <literal>#includes</literal> and
 315             <literal>#defines</literal> may be put in the same file
 316             twice so they should not assume otherwise.</para>
 317           </listitem>
 318         </varlistentry>
 319
 320         <varlistentry>
 321           <term><literal>#let name parameters = "definition"</literal></term>
 322           <listitem>
 323             <para>Defines a macro to be applied to the Haskell
 324             source. Parameter names are comma-separated, not
 325             inside parens. Such macro is invoked as other
 326             <literal>#</literal>-constructs, starting with
 327             <literal>#name</literal>. The definition will be
 328             put in the C program inside parens as arguments of
 329             <literal>printf</literal>. To refer to a parameter,
 330             close the quote, put a parameter name and open the
 331             quote again, to let C string literals concatenate.
 332             Or use <literal>printf</literal>'s format directives.
 333             Values of arguments must be given as strings, unless the
 334             macro stringifies them itself using the C preprocessor's
 335             <literal>#parameter</literal> syntax.</para>
 336           </listitem>
 337         </varlistentry>
 338
 339         <varlistentry>
 340           <term><literal>#def C_definition</literal></term>
 341           <listitem>
 342             <para>The definition (of a function, variable, struct or
 343             typedef) is written to the C file, and its prototype or
 344             extern declaration to the C header. Inline functions are
 345             handled correctly.  struct definitions and typedefs are
 346             written to the C program too.  The
 347             <literal>inline</literal>, <literal>struct</literal> or
 348             <literal>typedef</literal> keyword must come just after
 349             <literal>def</literal>.</para>
 350           </listitem>
 351         </varlistentry>
 352
 353         <varlistentry>
 354           <term><literal>#if condition</literal></term>
 355           <term><literal>#ifdef name</literal></term>
 356           <term><literal>#ifndef name</literal></term>
 357           <term><literal>#elif condition</literal></term>
 358           <term><literal>#else</literal></term>
 359           <term><literal>#endif</literal></term>
 360           <term><literal>#error message</literal></term>
 361           <term><literal>#warning message</literal></term>
 362           <listitem>
 363             <para>Conditional compilation directives are passed
 364             unmodified to the C program, C file, and C header. Putting
 365             them in the C program means that appropriate parts of the
 366             Haskell file will be skipped.</para>
 367           </listitem>
 368         </varlistentry>
 369
 370         <varlistentry>
 371           <term><literal>#const C_expression</literal></term>
 372           <listitem>
 373             <para>The expression must be convertible to
 374             <literal>long</literal> or <literal>unsigned
 375             long</literal>.  Its value (literal or negated literal)
 376             will be output.</para>
 377           </listitem>
 378         </varlistentry>
 379
 380         <varlistentry>
 381           <term><literal>#const_str C_expression</literal></term>
 382           <listitem>
 383             <para>The expression must be convertible to const char
 384             pointer.  Its value (string literal) will be output.</para>
 385           </listitem>
 386         </varlistentry>
 387
 388         <varlistentry>
 389           <term><literal>#type C_type</literal></term>
 390           <listitem>
 391             <para>A Haskell equivalent of the C numeric type will be
 392             output.  It will be one of
 393             <literal>{Int,Word}{8,16,32,64}</literal>,
 394             <literal>Float</literal>, <literal>Double</literal>,
 395             <literal>LDouble</literal>.</para>
 396           </listitem>
 397         </varlistentry>
 398
 399         <varlistentry>
 400           <term><literal>#peek struct_type, field</literal></term>
 401           <listitem>
 402             <para>A function that peeks a field of a C struct will be
 403             output.  It will have the type
 404               <literal>Storable b => Ptr a -> IO b</literal>.
 405
 406             The intention is that <literal>#peek</literal> and
 407             <literal>#poke</literal> can be used for implementing the
 408             operations of class <literal>Storable</literal> for a
 409             given C struct (see <xref linkend="sec-Storable">).</para>
 410           </listitem>
 411         </varlistentry>
 412
 413         <varlistentry>
 414           <term><literal>#poke struct_type, field</literal></term>
 415           <listitem>
 416             <para>Similarly for poke. It will have the type
 417               <literal>Storable b => Ptr a -> b -> IO ()</literal>.</para>
 418           </listitem>
 419         </varlistentry>
 420
 421         <varlistentry>
 422           <term><literal>#ptr struct_type, field</literal></term>
 423           <listitem>
 424             <para>Makes a pointer to a field struct. It will have the type
 425             <literal>Ptr a -> Ptr b</literal>.</para>
 426           </listitem>
 427         </varlistentry>
 428
 429         <varlistentry>
 430           <term><literal>#enum type, constructor, value, value, ...</literal></term>
 431           <listitem>
 432             <para>A shortcut for multiple definitions which use
 433             <literal>#const</literal>. Each <literal>value</literal>
 434             is a name of a C integer constant, e.g. enumeration value.
 435             The name will be translated to Haskell by making each
 436             letter following an underscore uppercase, making all the rest
 437             lowercase, and removing underscores. You can supply a different
 438             translation by writing <literal>hs_name = c_value</literal>
 439             instead of a <literal>value</literal>, in which case
 440             <literal>c_value</literal> may be an arbitrary expression.
 441             The <literal>hs_name</literal> will be defined as having the
 442             specified <literal>type</literal>. Its definition is the specified
 443             <literal>constructor</literal> (which in fact may be an expression
 444             or be empty) applied to the appropriate integer value. You can
 445             have multiple <literal>#enum</literal> definitions with the same
 446             <literal>type</literal>; this construct does not emit the type
 447             definition itself.</para>
 448           </listitem>
 449         </varlistentry>
 450       </variablelist>
 451
 452     </sect2>
 453
 454     <sect2>
 455       <title>Custom constructs</title>
 456
 457       <para><literal>#const</literal>, <literal>#type</literal>,
 458       <literal>#peek</literal>, <literal>#poke</literal> and
 459       <literal>#ptr</literal> are not hardwired into the
 460       <command>hsc2hs</command>, but are defined in a C template that is
 461       included in the C program: <filename>template-hsc.h</filename>.
 462       Custom constructs and templates can be used too. Any
 463       <literal>#</literal>-construct with unknown key is expected to
 464       be handled by a C template.</para>
 465
 466       <para>A C template should define a macro or function with name
 467       prefixed by <literal>hsc_</literal> that handles the construct
 468       by emitting the expansion to stdout. See
 469       <filename>template-hsc.h</filename> for examples.</para>
 470
 471       <para>Such macros can also be defined directly in the
 472       source. They are useful for making a <literal>#let</literal>-like
 473       macro whose expansion uses other <literal>#let</literal> macros.
 474       Plain <literal>#let</literal> prepends <literal>hsc_</literal>
 475       to the macro name and wraps the defininition in a
 476       <literal>printf</literal> call.</para>
 477
 478     </sect2>
 479
 480   </sect1>
 481
 482 </chapter>
 483
 484 <!-- Emacs stuff:
 485      ;;; Local Variables: ***
 486      ;;; mode: sgml ***
 487      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 488      ;;; End: ***
 489  -->