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: hasktags documentation losely based on that for hstags -->
   9
  10 <sect1  id ="hasktags">
  11         <title>Ctags and Etags for Haskell: <command>hasktags</command></title>
  12         <indexterm><primary><command>hasktags</command></primary></indexterm>
  13         <indexterm><primary>CTAGS for Haskell</primary></indexterm>
  14
  15         <para><command>hasktags</command> is a very simple Haskell program that produces ctags "tags" and etags "TAGS" files for Haskell programs.</para>
  16
  17         <para>When loaded into an editor such an NEdit, Vim, or Emacs, this allows one to easily navigate around a multi-file program, finding definitions of functions, types, and constructors.</para>
  18
  19         <para>Invocation Syntax:</para>
  20
  21 <screen>
  22 hasktags files
  23 </screen>
  24
  25 <para>This will read all the files listed in <option>files</option> and produce a ctags "tags" file and an etags "TAGS" file in the current directory.</para>
  26
  27         <para>Example usage</para>
  28
  29 <screen>
  30 find -name \*.\*hs | xargs hasktags
  31 </screen>
  32
  33 <para>This will find all haskell source files in the current directory and below, and create tags files indexing them in the current directory.</para>
  34
  35         <para><command>hasktags</command> is a simple program that uses simple
  36         parsing rules to find definitions of functions, constructors, and types. It isn't guranteed to find everything, and will sometimes create false index entries, but it usually gets the job done fairly well. In particular, at present, functions are only indexed if a type signature is given for them.</para>
  37
  38         <para>Before hasktags, there used to be <command>fptags</command> and <command>hstags</command>, which did essentially the same job, however neither of these seem to be maintained any more.</para>
  39
  40 <sect2>
  41 <title>Using tags with your editor</title>
  42
  43 <para>With NEdit, load the "tags" file using "File/Load Tags File". Use "Ctrl-D" to search for a tag.</para>
  44
  45 <para>With XEmacs, load the "TAGS" file using "visit-tags-table". Use "M-." to search for a tag.</para>
  46
  47
  48 </sect2>
  49
  50 </sect1>
  51
  52 <!-- comment: hstags doesn't work anymore
  53
  54   <sect1 id="hstags">
  55     <title>Emacs `TAGS' for Haskell: <command>hstags</command></title>
  56     <indexterm><primary><command>hstags</command></primary></indexterm>
  57     <indexterm><primary>TAGS for Haskell</primary></indexterm>
  58
  59     <para>`Tags' is a facility for indexing the definitions of
  60     programming-language things in a multi-file program, and then
  61     using that index to jump around among these definitions.</para>
  62
  63     <para>Rather than scratch your head, saying &ldquo;Now where did
  64     we define `foo'?&rdquo;, you just do (in Emacs) <Literal>M-. foo
  65     RET</Literal>, and You're There!  Some people go wild over this
  66     stuff&hellip;</para>
  67
  68     <para>GHC comes with a program <command>hstags</command>, which
  69     build Emacs-able TAGS files.  The invocation syntax is:</para>
  70
  71 <screen>
  72 hstags [GHC-options] file [files...]
  73 </screen>
  74
  75     <para>The best thing is just to feed it your GHC command-line
  76     flags.  A good Makefile entry might be:</para>
  77
  78 <programlisting>
  79 tags:
  80         $(RM) TAGS
  81         hstags $(GHC_FLAGS) *.lhs
  82 </programlisting>
  83
  84     <para>The only flags of its own are: <Option>-v</Option> to be
  85     verbose; <Option>-a</Option> to <Emphasis>APPEND</Emphasis> to the
  86     TAGS file, rather than write to it.</para>
  87
  88     <para>Shortcomings: (1)&nbsp;Instance declarations don't get into
  89     the TAGS file (but the definitions inside them do); as instances
  90     aren't named, this is probably just as well.
  91     (2)&nbsp;Data-constructor definitions don't get in.  Go for the
  92     corresponding type constructor instead.</para>
  93
  94     <para>Actually, GHC also comes with <command>etags</command>
  95     &lsqb;for C&rsqb;, and <Command>perltags</Command> &lsqb;for You
  96     Know What&rsqb;.  And&mdash;I cannot tell a lie&mdash;there is
  97     Denis Howe's <Command>fptags</Command> &lsqb;for Haskell,
  98     etc.&rsqb; in the <Filename>ghc/CONTRIB</Filename>
  99     section&hellip;)</para>
 100
 101   </sect1>
 102 -->
 103
 104   <sect1 id="happy">
 105     <title>&ldquo;Yacc for Haskell&rdquo;: <command>happy</command></title>
 106
 107     <indexterm><primary>Happy</primary></indexterm>
 108     <indexterm><primary>Yacc for Haskell</primary></indexterm>
 109     <indexterm><primary>parser generator for Haskell</primary></indexterm>
 110
 111     <para>Andy Gill and Simon Marlow have written a parser-generator
 112     for Haskell, called
 113     <Command>happy</Command>.<IndexTerm><Primary>happy parser
 114     generator</Primary></IndexTerm> <command>Happy</command> is to
 115     Haskell what <command>Yacc</command> is to C.</para>
 116
 117     <para>You can get <Command>happy</Command> from <ulink
 118     url="http://www.haskell.org/happy/">the Happy
 119     Homepage</ulink>.</para>
 120
 121     <para><command>Happy</command> is at its shining best when
 122     compiled by GHC.</para>
 123
 124   </sect1>
 125
 126 <!-- we don't distribute this anymore
 127   <sect1 id="pphs">
 128     <title>Pretty-printing Haskell: <Command>pphs</Command></title>
 129     <indexterm><primary>pphs</primary></indexterm>
 130     <indexterm><primary>pretty-printing Haskell code</primary></indexterm>
 131
 132     <para>Andrew Preece has written
 133     <Command>pphs</Command>,<IndexTerm><Primary>pphs</Primary></IndexTerm><IndexTerm><Primary>pretty-printing
 134     Haskell</Primary></IndexTerm> a utility to pretty-print Haskell
 135     code in LaTeX documents.  Keywords in bolds, variables in
 136     italics&mdash;that sort of thing.  It is good at lining up program
 137     clauses and equals signs, things that are very tiresome to do by
 138     hand.</para>
 139
 140     <para>The code is distributed with GHC in
 141     <Filename>ghc/CONTRIB/pphs</Filename>.</para>
 142   </sect1>
 143 -->
 144
 145   <sect1 id="hsc2hs">
 146     <title>Writing Haskell interfaces to C code:
 147     <command>hsc2hs</command></title>
 148     <indexterm><primary><command>hsc2hs</command></primary>
 149     </indexterm>
 150
 151     <para>The <command>hsc2hs</command> command can be used to automate
 152     some parts of the process of writing Haskell bindings to C code.
 153     It reads an almost-Haskell source with embedded special
 154     constructs, and outputs a real Haskell file with these constructs
 155     processed, based on information taken from some C headers. The
 156     extra constructs deal with accessing C data from Haskell.</para>
 157
 158     <para>It may also output a C file which contains additional C
 159     functions to be linked into the program, together with a C header
 160     that gets included into the C code to which the Haskell module
 161     will be compiled (when compiled via C) and into the C file. These
 162     two files are created when the <literal>#def</literal> construct
 163     is used (see below).</para>
 164
 165     <para>Actually <command>hsc2hs</command> does not output the Haskell
 166     file directly.  It creates a C program that includes the headers,
 167     gets automatically compiled and run. That program outputs the
 168     Haskell code.</para>
 169
 170     <para>In the following, &ldquo;Haskell file&rdquo; is the main
 171     output (usually a <literal>.hs</literal> file), &ldquo;compiled
 172     Haskell file&rdquo; is the Haskell file after
 173     <command>ghc</command> has compiled it to C (i.e. a
 174     <literal>.hc</literal> file), &ldquo;C program&rdquo; is the
 175     program that outputs the Haskell file, &ldquo;C file&rdquo; is the
 176     optionally generated C file, and &ldquo;C header&rdquo; is its
 177     header file.</para>
 178
 179     <sect2>
 180       <title>Command line syntax</title>
 181
 182       <para><command>hsc2hs</command> takes input files as arguments,
 183       and flags that modify its behavior:</para>
 184
 185       <variablelist>
 186         <varlistentry>
 187           <term><literal>-t FILE</literal> or
 188           <literal>--template=FILE</literal></term>
 189           <listitem>
 190             <para>The template file (see below).</para>
 191           </listitem>
 192         </varlistentry>
 193
 194         <varlistentry>
 195           <term><literal>-c PROG</literal> or
 196           <literal>--cc=PROG</literal></term>
 197           <listitem>
 198             <para>The C compiler to use (default:
 199             <command>ghc</command>)</para>
 200           </listitem>
 201         </varlistentry>
 202
 203         <varlistentry>
 204           <term><literal>-l PROG</literal> or
 205           <literal>--ld=PROG</literal></term>
 206           <listitem>
 207             <para>The linker to use (default:
 208             <command>gcc</command>).</para>
 209           </listitem>
 210         </varlistentry>
 211
 212         <varlistentry>
 213           <term><literal>-C FLAG</literal> or
 214           <literal>--cflag=FLAG</literal></term>
 215           <listitem>
 216             <para>An extra flag to pass to the C compiler.</para>
 217           </listitem>
 218         </varlistentry>
 219
 220         <varlistentry>
 221           <term><literal>-I DIR</literal></term>
 222           <listitem>
 223             <para>Passed to the C compiler.</para>
 224           </listitem>
 225         </varlistentry>
 226
 227         <varlistentry>
 228           <term><literal>-L FLAG</literal> or
 229           <literal>--lflag=FLAG</literal></term>
 230           <listitem>
 231             <para>An extra flag to pass to the linker.</para>
 232           </listitem>
 233         </varlistentry>
 234
 235         <varlistentry>
 236           <term><literal>-i FILE</literal> or
 237           <literal>--include=FILE</literal></term>
 238           <listitem>
 239             <para>As if the appropriate <literal>#include</literal>
 240             directive was placed in the source.</para>
 241           </listitem>
 242         </varlistentry>
 243
 244         <varlistentry>
 245           <term><literal>-D NAME[=VALUE]</literal> or
 246           <literal>--define=NAME[=VALUE]</literal></term>
 247           <listitem>
 248             <para>As if the appropriate <literal>#define</literal>
 249             directive was placed in the source.</para>
 250           </listitem>
 251         </varlistentry>
 252
 253         <varlistentry>
 254           <term><literal>-o FILE</literal> or
 255           <literal>--output=FILE</literal></term>
 256           <listitem>
 257             <para>Name of the Haskell file.</para>
 258           </listitem>
 259         </varlistentry>
 260
 261         <varlistentry>
 262           <term><literal>--help</literal></term>
 263           <listitem>
 264             <para>Display a summary of the available flags.</para>
 265           </listitem>
 266         </varlistentry>
 267
 268         <varlistentry>
 269           <term><literal>--version</literal></term>
 270           <listitem>
 271             <para>Output version information.</para>
 272           </listitem>
 273         </varlistentry>
 274
 275         <varlistentry>
 276           <term><literal>--no-compile</literal></term>
 277           <listitem>
 278             <para>Stop after writing out the intermediate C program to disk.
 279             The file name for the intermediate C program is the input file name
 280             with <literal>.hsc</literal> replaced with <literal>_hsc_make.c</literal>.</para>
 281           </listitem>
 282         </varlistentry>
 283       </variablelist>
 284
 285       <para>The input file should end with .hsc. Output files by
 286       default get names with the <literal>.hsc</literal> suffix
 287       replaced:</para>
 288
 289       <informaltable>
 290         <tgroup cols=2>
 291           <tbody>
 292             <row>
 293               <entry><literal>.hs</literal></entry>
 294               <entry>Haskell file</entry>
 295             </row>
 296             <row>
 297               <entry><literal>_hsc.h</literal></entry>
 298               <entry>C header</entry>
 299             </row>
 300             <row>
 301               <entry><literal>_hsc.c</literal></entry>
 302               <entry>C file</entry>
 303             </row>
 304           </tbody>
 305         </tgroup>
 306       </informaltable>
 307
 308       <para>The C program is compiled using the Haskell compiler. This
 309       provides the include path to <filename>HsFFI.h</filename> which
 310       is automatically included into the C program.</para>
 311
 312     </sect2>
 313     <sect2><title>Input syntax</title>
 314
 315       <para>All special processing is triggered by
 316       the <literal>#</literal> operator. To output
 317       a literal <literal>#</literal>, write it twice:
 318       <literal>##</literal>. Inside string literals and comments
 319       <literal>#</literal> characters are not processed.</para>
 320
 321       <para>A <literal>#</literal> is followed by optional
 322       spaces and tabs, an alphanumeric keyword that describes
 323       the kind of processing, and its arguments. Arguments look
 324       like C expressions separated by commas (they are not
 325       written inside parens).  They extend up to the nearest
 326       unmatched <literal>)</literal>, <literal>]</literal> or
 327       <literal>}</literal>, or to the end of line if it occurs outside
 328       any <literal>() [] {} '' "" /**/</literal> and is not preceded
 329       by a backslash. Backslash-newline pairs are stripped.</para>
 330
 331       <para>In addition <literal>#{stuff}</literal> is equivalent
 332       to <literal>#stuff</literal> except that it's self-delimited
 333       and thus needs not to be placed at the end of line or in some
 334       brackets.</para>
 335
 336       <para>Meanings of specific keywords:</para>
 337
 338       <variablelist>
 339
 340         <varlistentry>
 341           <term><literal>#include &lt;file.h&gt;</literal></term>
 342           <term><literal>#include "file.h"</literal></term>
 343           <listitem>
 344             <para>The specified file gets included into the C program,
 345             the compiled Haskell file, and the C header.
 346             <literal>&lt;HsFFI.h&gt;</literal> is included
 347             automatically.</para>
 348           </listitem>
 349         </varlistentry>
 350
 351         <varlistentry>
 352           <term><literal>#define name</literal></term>
 353           <term><literal>#define name value</literal></term>
 354           <term><literal>#undef name</literal></term>
 355           <listitem>
 356             <para>Similar to <literal>#include</literal>. Note that
 357             <literal>#includes</literal> and
 358             <literal>#defines</literal> may be put in the same file
 359             twice so they should not assume otherwise.</para>
 360           </listitem>
 361         </varlistentry>
 362
 363         <varlistentry>
 364           <term><literal>#let name parameters = "definition"</literal></term>
 365           <listitem>
 366             <para>Defines a macro to be applied to the Haskell
 367             source. Parameter names are comma-separated, not
 368             inside parens. Such macro is invoked as other
 369             <literal>#</literal>-constructs, starting with
 370             <literal>#name</literal>. The definition will be
 371             put in the C program inside parens as arguments of
 372             <literal>printf</literal>. To refer to a parameter,
 373             close the quote, put a parameter name and open the
 374             quote again, to let C string literals concatenate.
 375             Or use <literal>printf</literal>'s format directives.
 376             Values of arguments must be given as strings, unless the
 377             macro stringifies them itself using the C preprocessor's
 378             <literal>#parameter</literal> syntax.</para>
 379           </listitem>
 380         </varlistentry>
 381
 382         <varlistentry>
 383           <term><literal>#def C_definition</literal></term>
 384           <listitem>
 385             <para>The definition (of a function, variable, struct or
 386             typedef) is written to the C file, and its prototype or
 387             extern declaration to the C header. Inline functions are
 388             handled correctly.  struct definitions and typedefs are
 389             written to the C program too.  The
 390             <literal>inline</literal>, <literal>struct</literal> or
 391             <literal>typedef</literal> keyword must come just after
 392             <literal>def</literal>.</para>
 393           </listitem>
 394         </varlistentry>
 395
 396         <varlistentry>
 397           <term><literal>#if condition</literal></term>
 398           <term><literal>#ifdef name</literal></term>
 399           <term><literal>#ifndef name</literal></term>
 400           <term><literal>#elif condition</literal></term>
 401           <term><literal>#else</literal></term>
 402           <term><literal>#endif</literal></term>
 403           <term><literal>#error message</literal></term>
 404           <term><literal>#warning message</literal></term>
 405           <listitem>
 406             <para>Conditional compilation directives are passed
 407             unmodified to the C program, C file, and C header. Putting
 408             them in the C program means that appropriate parts of the
 409             Haskell file will be skipped.</para>
 410           </listitem>
 411         </varlistentry>
 412
 413         <varlistentry>
 414           <term><literal>#const C_expression</literal></term>
 415           <listitem>
 416             <para>The expression must be convertible to
 417             <literal>long</literal> or <literal>unsigned
 418             long</literal>.  Its value (literal or negated literal)
 419             will be output.</para>
 420           </listitem>
 421         </varlistentry>
 422
 423         <varlistentry>
 424           <term><literal>#const_str C_expression</literal></term>
 425           <listitem>
 426             <para>The expression must be convertible to const char
 427             pointer.  Its value (string literal) will be output.</para>
 428           </listitem>
 429         </varlistentry>
 430
 431         <varlistentry>
 432           <term><literal>#type C_type</literal></term>
 433           <listitem>
 434             <para>A Haskell equivalent of the C numeric type will be
 435             output.  It will be one of
 436             <literal>{Int,Word}{8,16,32,64}</literal>,
 437             <literal>Float</literal>, <literal>Double</literal>,
 438             <literal>LDouble</literal>.</para>
 439           </listitem>
 440         </varlistentry>
 441
 442         <varlistentry>
 443           <term><literal>#peek struct_type, field</literal></term>
 444           <listitem>
 445             <para>A function that peeks a field of a C struct will be
 446             output.  It will have the type
 447               <literal>Storable b => Ptr a -> IO b</literal>.
 448
 449             The intention is that <literal>#peek</literal> and
 450             <literal>#poke</literal> can be used for implementing the
 451             operations of class <literal>Storable</literal> for a
 452             given C struct (see <xref linkend="sec-Storable">).</para>
 453           </listitem>
 454         </varlistentry>
 455
 456         <varlistentry>
 457           <term><literal>#poke struct_type, field</literal></term>
 458           <listitem>
 459             <para>Similarly for poke. It will have the type
 460               <literal>Storable b => Ptr a -> b -> IO ()</literal>.</para>
 461           </listitem>
 462         </varlistentry>
 463
 464         <varlistentry>
 465           <term><literal>#ptr struct_type, field</literal></term>
 466           <listitem>
 467             <para>Makes a pointer to a field struct. It will have the type
 468             <literal>Ptr a -> Ptr b</literal>.</para>
 469           </listitem>
 470         </varlistentry>
 471
 472         <varlistentry>
 473           <term><literal>#enum type, constructor, value, value, ...</literal></term>
 474           <listitem>
 475             <para>A shortcut for multiple definitions which use
 476             <literal>#const</literal>. Each <literal>value</literal>
 477             is a name of a C integer constant, e.g. enumeration value.
 478             The name will be translated to Haskell by making each
 479             letter following an underscore uppercase, making all the rest
 480             lowercase, and removing underscores. You can supply a different
 481             translation by writing <literal>hs_name = c_value</literal>
 482             instead of a <literal>value</literal>, in which case
 483             <literal>c_value</literal> may be an arbitrary expression.
 484             The <literal>hs_name</literal> will be defined as having the
 485             specified <literal>type</literal>. Its definition is the specified
 486             <literal>constructor</literal> (which in fact may be an expression
 487             or be empty) applied to the appropriate integer value. You can
 488             have multiple <literal>#enum</literal> definitions with the same
 489             <literal>type</literal>; this construct does not emit the type
 490             definition itself.</para>
 491           </listitem>
 492         </varlistentry>
 493       </variablelist>
 494
 495     </sect2>
 496
 497     <sect2>
 498       <title>Custom constructs</title>
 499
 500       <para><literal>#const</literal>, <literal>#type</literal>,
 501       <literal>#peek</literal>, <literal>#poke</literal> and
 502       <literal>#ptr</literal> are not hardwired into the
 503       <command>hsc2hs</command>, but are defined in a C template that is
 504       included in the C program: <filename>template-hsc.h</filename>.
 505       Custom constructs and templates can be used too. Any
 506       <literal>#</literal>-construct with unknown key is expected to
 507       be handled by a C template.</para>
 508
 509       <para>A C template should define a macro or function with name
 510       prefixed by <literal>hsc_</literal> that handles the construct
 511       by emitting the expansion to stdout. See
 512       <filename>template-hsc.h</filename> for examples.</para>
 513
 514       <para>Such macros can also be defined directly in the
 515       source. They are useful for making a <literal>#let</literal>-like
 516       macro whose expansion uses other <literal>#let</literal> macros.
 517       Plain <literal>#let</literal> prepends <literal>hsc_</literal>
 518       to the macro name and wraps the defininition in a
 519       <literal>printf</literal> call.</para>
 520
 521     </sect2>
 522
 523   </sect1>
 524
 525 </chapter>
 526
 527 <!-- Emacs stuff:
 528      ;;; Local Variables: ***
 529      ;;; mode: sgml ***
 530      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 531      ;;; End: ***
 532  -->