docs/users_guide/utils.xml

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