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