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