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