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