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>gcc</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           </listitem>
 396         </varlistentry>
 397
 398         <varlistentry>
 399           <term><literal>#if condition</literal></term>
 400           <term><literal>#ifdef name</literal></term>
 401           <term><literal>#ifndef name</literal></term>
 402           <term><literal>#elif condition</literal></term>
 403           <term><literal>#else</literal></term>
 404           <term><literal>#endif</literal></term>
 405           <term><literal>#error message</literal></term>
 406           <term><literal>#warning message</literal></term>
 407           <listitem>
 408             <para>Conditional compilation directives are passed
 409             unmodified to the C program, C file, and C header. Putting
 410             them in the C program means that appropriate parts of the
 411             Haskell file will be skipped.</para>
 412           </listitem>
 413         </varlistentry>
 414
 415         <varlistentry>
 416           <term><literal>#const C_expression</literal></term>
 417           <listitem>
 418             <para>The expression must be convertible to
 419             <literal>long</literal> or <literal>unsigned
 420             long</literal>.  Its value (literal or negated literal)
 421             will be output.</para>
 422           </listitem>
 423         </varlistentry>
 424
 425         <varlistentry>
 426           <term><literal>#const_str C_expression</literal></term>
 427           <listitem>
 428             <para>The expression must be convertible to const char
 429             pointer.  Its value (string literal) will be output.</para>
 430           </listitem>
 431         </varlistentry>
 432
 433         <varlistentry>
 434           <term><literal>#type C_type</literal></term>
 435           <listitem>
 436             <para>A Haskell equivalent of the C numeric type will be
 437             output.  It will be one of
 438             <literal>{Int,Word}{8,16,32,64}</literal>,
 439             <literal>Float</literal>, <literal>Double</literal>,
 440             <literal>LDouble</literal>.</para>
 441           </listitem>
 442         </varlistentry>
 443
 444         <varlistentry>
 445           <term><literal>#peek struct_type, field</literal></term>
 446           <listitem>
 447             <para>A function that peeks a field of a C struct will be
 448             output.  It will have the type
 449               <literal>Storable b => Ptr a -> IO b</literal>.
 450
 451             The intention is that <literal>#peek</literal> and
 452             <literal>#poke</literal> can be used for implementing the
 453             operations of class <literal>Storable</literal> for a
 454             given C struct (see the
 455             <literal>Foreign.Storable</literal> module in the library
 456             documentation).</para>
 457           </listitem>
 458         </varlistentry>
 459
 460         <varlistentry>
 461           <term><literal>#poke struct_type, field</literal></term>
 462           <listitem>
 463             <para>Similarly for poke. It will have the type
 464               <literal>Storable b => Ptr a -> b -> IO ()</literal>.</para>
 465           </listitem>
 466         </varlistentry>
 467
 468         <varlistentry>
 469           <term><literal>#ptr struct_type, field</literal></term>
 470           <listitem>
 471             <para>Makes a pointer to a field struct. It will have the type
 472             <literal>Ptr a -> Ptr b</literal>.</para>
 473           </listitem>
 474         </varlistentry>
 475
 476         <varlistentry>
 477           <term><literal>#offset struct_type, field</literal></term>
 478           <listitem>
 479             <para>Computes the offset, in bytes, of
 480             <literal>field</literal> in
 481             <literal>struct_type</literal>. It will have type
 482             <literal>Int</literal>.</para>
 483           </listitem>
 484         </varlistentry>
 485
 486         <varlistentry>
 487           <term><literal>#size struct_type</literal></term>
 488           <listitem>
 489                 <para>Computes the size, in bytes, of
 490                 <literal>struct_type</literal>. It will have type
 491                 <literal>Int</literal>.</para>
 492           </listitem>
 493         </varlistentry>
 494
 495         <varlistentry>
 496           <term><literal>#enum type, constructor, value, value, ...</literal></term>
 497           <listitem>
 498             <para>A shortcut for multiple definitions which use
 499             <literal>#const</literal>. Each <literal>value</literal>
 500             is a name of a C integer constant, e.g. enumeration value.
 501             The name will be translated to Haskell by making each
 502             letter following an underscore uppercase, making all the rest
 503             lowercase, and removing underscores. You can supply a different
 504             translation by writing <literal>hs_name = c_value</literal>
 505             instead of a <literal>value</literal>, in which case
 506             <literal>c_value</literal> may be an arbitrary expression.
 507             The <literal>hs_name</literal> will be defined as having the
 508             specified <literal>type</literal>. Its definition is the specified
 509             <literal>constructor</literal> (which in fact may be an expression
 510             or be empty) applied to the appropriate integer value. You can
 511             have multiple <literal>#enum</literal> definitions with the same
 512             <literal>type</literal>; this construct does not emit the type
 513             definition itself.</para>
 514           </listitem>
 515         </varlistentry>
 516       </variablelist>
 517
 518     </sect2>
 519
 520     <sect2>
 521       <title>Custom constructs</title>
 522
 523       <para><literal>#const</literal>, <literal>#type</literal>,
 524       <literal>#peek</literal>, <literal>#poke</literal> and
 525       <literal>#ptr</literal> are not hardwired into the
 526       <command>hsc2hs</command>, but are defined in a C template that is
 527       included in the C program: <filename>template-hsc.h</filename>.
 528       Custom constructs and templates can be used too. Any
 529       <literal>#</literal>-construct with unknown key is expected to
 530       be handled by a C template.</para>
 531
 532       <para>A C template should define a macro or function with name
 533       prefixed by <literal>hsc_</literal> that handles the construct
 534       by emitting the expansion to stdout. See
 535       <filename>template-hsc.h</filename> for examples.</para>
 536
 537       <para>Such macros can also be defined directly in the
 538       source. They are useful for making a <literal>#let</literal>-like
 539       macro whose expansion uses other <literal>#let</literal> macros.
 540       Plain <literal>#let</literal> prepends <literal>hsc_</literal>
 541       to the macro name and wraps the definition in a
 542       <literal>printf</literal> call.</para>
 543
 544     </sect2>
 545
 546   </sect1>
 547
 548 </chapter>
 549
 550 <!-- Emacs stuff:
 551      ;;; Local Variables: ***
 552      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 553      ;;; End: ***
 554  -->