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>-o FILE</literal> or
 188           <literal>&ndash;&ndash;output=FILE</literal></term>
 189           <listitem>
 190             <para>Name of the Haskell file.</para>
 191           </listitem>
 192         </varlistentry>
 193
 194         <varlistentry>
 195           <term><literal>-t FILE</literal> or
 196           <literal>&ndash;&ndash;template=FILE</literal></term>
 197           <listitem>
 198             <para>The template file (see below).</para>
 199           </listitem>
 200         </varlistentry>
 201
 202         <varlistentry>
 203           <term><literal>-c PROG</literal> or
 204           <literal>&ndash;&ndash;cc=PROG</literal></term>
 205           <listitem>
 206             <para>The C compiler to use (default:
 207             <command>ghc</command>)</para>
 208           </listitem>
 209         </varlistentry>
 210
 211         <varlistentry>
 212           <term><literal>-l PROG</literal> or
 213           <literal>&ndash;&ndash;ld=PROG</literal></term>
 214           <listitem>
 215             <para>The linker to use (default:
 216             <command>gcc</command>).</para>
 217           </listitem>
 218         </varlistentry>
 219
 220         <varlistentry>
 221           <term><literal>-C FLAG</literal> or
 222           <literal>&ndash;&ndash;cflag=FLAG</literal></term>
 223           <listitem>
 224             <para>An extra flag to pass to the C compiler.</para>
 225           </listitem>
 226         </varlistentry>
 227
 228         <varlistentry>
 229           <term><literal>-I DIR</literal></term>
 230           <listitem>
 231             <para>Passed to the C compiler.</para>
 232           </listitem>
 233         </varlistentry>
 234
 235         <varlistentry>
 236           <term><literal>-L FLAG</literal> or
 237           <literal>&ndash;&ndash;lflag=FLAG</literal></term>
 238           <listitem>
 239             <para>An extra flag to pass to the linker.</para>
 240           </listitem>
 241         </varlistentry>
 242
 243         <varlistentry>
 244           <term><literal>-i FILE</literal> or
 245           <literal>&ndash;&ndash;include=FILE</literal></term>
 246           <listitem>
 247             <para>As if the appropriate <literal>#include</literal>
 248             directive was placed in the source.</para>
 249           </listitem>
 250         </varlistentry>
 251
 252         <varlistentry>
 253           <term><literal>-D NAME[=VALUE]</literal> or
 254           <literal>&ndash;&ndash;define=NAME[=VALUE]</literal></term>
 255           <listitem>
 256             <para>As if the appropriate <literal>#define</literal>
 257             directive was placed in the source.</para>
 258           </listitem>
 259         </varlistentry>
 260
 261         <varlistentry>
 262           <term><literal>&ndash;&ndash;no-compile</literal></term>
 263           <listitem>
 264             <para>Stop after writing out the intermediate C program to disk.
 265             The file name for the intermediate C program is the input file name
 266             with <literal>.hsc</literal> replaced with <literal>_hsc_make.c</literal>.</para>
 267           </listitem>
 268         </varlistentry>
 269
 270         <varlistentry>
 271           <term><literal>-?</literal> or <literal>&ndash;&ndash;help</literal></term>
 272           <listitem>
 273             <para>Display a summary of the available flags and exit successfully.</para>
 274           </listitem>
 275         </varlistentry>
 276
 277         <varlistentry>
 278           <term><literal>-V</literal> or <literal>&ndash;&ndash;version</literal></term>
 279           <listitem>
 280             <para>Output version information and exit successfully.</para>
 281           </listitem>
 282         </varlistentry>
 283       </variablelist>
 284
 285       <para>The input file should end with .hsc (it should be plain
 286       Haskell source only; literate Haskell is not supported at the
 287       moment). Output files by default get names with the
 288       <literal>.hsc</literal> suffix replaced:</para>
 289
 290       <informaltable>
 291         <tgroup cols=2>
 292           <tbody>
 293             <row>
 294               <entry><literal>.hs</literal></entry>
 295               <entry>Haskell file</entry>
 296             </row>
 297             <row>
 298               <entry><literal>_hsc.h</literal></entry>
 299               <entry>C header</entry>
 300             </row>
 301             <row>
 302               <entry><literal>_hsc.c</literal></entry>
 303               <entry>C file</entry>
 304             </row>
 305           </tbody>
 306         </tgroup>
 307       </informaltable>
 308
 309       <para>The C program is compiled using the Haskell compiler. This
 310       provides the include path to <filename>HsFFI.h</filename> which
 311       is automatically included into the C program.</para>
 312
 313     </sect2>
 314     <sect2><title>Input syntax</title>
 315
 316       <para>All special processing is triggered by
 317       the <literal>#</literal> operator. To output
 318       a literal <literal>#</literal>, write it twice:
 319       <literal>##</literal>. Inside string literals and comments
 320       <literal>#</literal> characters are not processed.</para>
 321
 322       <para>A <literal>#</literal> is followed by optional
 323       spaces and tabs, an alphanumeric keyword that describes
 324       the kind of processing, and its arguments. Arguments look
 325       like C expressions separated by commas (they are not
 326       written inside parens).  They extend up to the nearest
 327       unmatched <literal>)</literal>, <literal>]</literal> or
 328       <literal>}</literal>, or to the end of line if it occurs outside
 329       any <literal>() [] {} '' "" /**/</literal> and is not preceded
 330       by a backslash. Backslash-newline pairs are stripped.</para>
 331
 332       <para>In addition <literal>#{stuff}</literal> is equivalent
 333       to <literal>#stuff</literal> except that it's self-delimited
 334       and thus needs not to be placed at the end of line or in some
 335       brackets.</para>
 336
 337       <para>Meanings of specific keywords:</para>
 338
 339       <variablelist>
 340
 341         <varlistentry>
 342           <term><literal>#include &lt;file.h&gt;</literal></term>
 343           <term><literal>#include "file.h"</literal></term>
 344           <listitem>
 345             <para>The specified file gets included into the C program,
 346             the compiled Haskell file, and the C header.
 347             <literal>&lt;HsFFI.h&gt;</literal> is included
 348             automatically.</para>
 349           </listitem>
 350         </varlistentry>
 351
 352         <varlistentry>
 353           <term><literal>#define name</literal></term>
 354           <term><literal>#define name value</literal></term>
 355           <term><literal>#undef name</literal></term>
 356           <listitem>
 357             <para>Similar to <literal>#include</literal>. Note that
 358             <literal>#includes</literal> and
 359             <literal>#defines</literal> may be put in the same file
 360             twice so they should not assume otherwise.</para>
 361           </listitem>
 362         </varlistentry>
 363
 364         <varlistentry>
 365           <term><literal>#let name parameters = "definition"</literal></term>
 366           <listitem>
 367             <para>Defines a macro to be applied to the Haskell
 368             source. Parameter names are comma-separated, not
 369             inside parens. Such macro is invoked as other
 370             <literal>#</literal>-constructs, starting with
 371             <literal>#name</literal>. The definition will be
 372             put in the C program inside parens as arguments of
 373             <literal>printf</literal>. To refer to a parameter,
 374             close the quote, put a parameter name and open the
 375             quote again, to let C string literals concatenate.
 376             Or use <literal>printf</literal>'s format directives.
 377             Values of arguments must be given as strings, unless the
 378             macro stringifies them itself using the C preprocessor's
 379             <literal>#parameter</literal> syntax.</para>
 380           </listitem>
 381         </varlistentry>
 382
 383         <varlistentry>
 384           <term><literal>#def C_definition</literal></term>
 385           <listitem>
 386             <para>The definition (of a function, variable, struct or
 387             typedef) is written to the C file, and its prototype or
 388             extern declaration to the C header. Inline functions are
 389             handled correctly.  struct definitions and typedefs are
 390             written to the C program too.  The
 391             <literal>inline</literal>, <literal>struct</literal> or
 392             <literal>typedef</literal> keyword must come just after
 393             <literal>def</literal>.</para>
 394           </listitem>
 395         </varlistentry>
 396
 397         <varlistentry>
 398           <term><literal>#if condition</literal></term>
 399           <term><literal>#ifdef name</literal></term>
 400           <term><literal>#ifndef name</literal></term>
 401           <term><literal>#elif condition</literal></term>
 402           <term><literal>#else</literal></term>
 403           <term><literal>#endif</literal></term>
 404           <term><literal>#error message</literal></term>
 405           <term><literal>#warning message</literal></term>
 406           <listitem>
 407             <para>Conditional compilation directives are passed
 408             unmodified to the C program, C file, and C header. Putting
 409             them in the C program means that appropriate parts of the
 410             Haskell file will be skipped.</para>
 411           </listitem>
 412         </varlistentry>
 413
 414         <varlistentry>
 415           <term><literal>#const C_expression</literal></term>
 416           <listitem>
 417             <para>The expression must be convertible to
 418             <literal>long</literal> or <literal>unsigned
 419             long</literal>.  Its value (literal or negated literal)
 420             will be output.</para>
 421           </listitem>
 422         </varlistentry>
 423
 424         <varlistentry>
 425           <term><literal>#const_str C_expression</literal></term>
 426           <listitem>
 427             <para>The expression must be convertible to const char
 428             pointer.  Its value (string literal) will be output.</para>
 429           </listitem>
 430         </varlistentry>
 431
 432         <varlistentry>
 433           <term><literal>#type C_type</literal></term>
 434           <listitem>
 435             <para>A Haskell equivalent of the C numeric type will be
 436             output.  It will be one of
 437             <literal>{Int,Word}{8,16,32,64}</literal>,
 438             <literal>Float</literal>, <literal>Double</literal>,
 439             <literal>LDouble</literal>.</para>
 440           </listitem>
 441         </varlistentry>
 442
 443         <varlistentry>
 444           <term><literal>#peek struct_type, field</literal></term>
 445           <listitem>
 446             <para>A function that peeks a field of a C struct will be
 447             output.  It will have the type
 448               <literal>Storable b => Ptr a -> IO b</literal>.
 449
 450             The intention is that <literal>#peek</literal> and
 451             <literal>#poke</literal> can be used for implementing the
 452             operations of class <literal>Storable</literal> for a
 453             given C struct (see the
 454             <literal>Foreign.Storable</literal> module in the library
 455             documentation).</para>
 456           </listitem>
 457         </varlistentry>
 458
 459         <varlistentry>
 460           <term><literal>#poke struct_type, field</literal></term>
 461           <listitem>
 462             <para>Similarly for poke. It will have the type
 463               <literal>Storable b => Ptr a -> b -> IO ()</literal>.</para>
 464           </listitem>
 465         </varlistentry>
 466
 467         <varlistentry>
 468           <term><literal>#ptr struct_type, field</literal></term>
 469           <listitem>
 470             <para>Makes a pointer to a field struct. It will have the type
 471             <literal>Ptr a -> Ptr b</literal>.</para>
 472           </listitem>
 473         </varlistentry>
 474
 475         <varlistentry>
 476           <term><literal>#offset struct_type, field</literal></term>
 477           <listitem>
 478             <para>Computes the offset, in bytes, of
 479             <literal>field</literal> in
 480             <literal>struct_type</literal>. It will have type
 481             <literal>Int</literal>.</para>
 482           </listitem>
 483         </varlistentry>
 484
 485         <varlistentry>
 486           <term><literal>#size struct_type</literal></term>
 487           <listitem>
 488                 <para>Computes the size, in bytes, of
 489                 <literal>struct_type</literal>. It will have type
 490                 <literal>Int</literal>.</para>
 491           </listitem>
 492         </varlistentry>
 493
 494         <varlistentry>
 495           <term><literal>#enum type, constructor, value, value, ...</literal></term>
 496           <listitem>
 497             <para>A shortcut for multiple definitions which use
 498             <literal>#const</literal>. Each <literal>value</literal>
 499             is a name of a C integer constant, e.g. enumeration value.
 500             The name will be translated to Haskell by making each
 501             letter following an underscore uppercase, making all the rest
 502             lowercase, and removing underscores. You can supply a different
 503             translation by writing <literal>hs_name = c_value</literal>
 504             instead of a <literal>value</literal>, in which case
 505             <literal>c_value</literal> may be an arbitrary expression.
 506             The <literal>hs_name</literal> will be defined as having the
 507             specified <literal>type</literal>. Its definition is the specified
 508             <literal>constructor</literal> (which in fact may be an expression
 509             or be empty) applied to the appropriate integer value. You can
 510             have multiple <literal>#enum</literal> definitions with the same
 511             <literal>type</literal>; this construct does not emit the type
 512             definition itself.</para>
 513           </listitem>
 514         </varlistentry>
 515       </variablelist>
 516
 517     </sect2>
 518
 519     <sect2>
 520       <title>Custom constructs</title>
 521
 522       <para><literal>#const</literal>, <literal>#type</literal>,
 523       <literal>#peek</literal>, <literal>#poke</literal> and
 524       <literal>#ptr</literal> are not hardwired into the
 525       <command>hsc2hs</command>, but are defined in a C template that is
 526       included in the C program: <filename>template-hsc.h</filename>.
 527       Custom constructs and templates can be used too. Any
 528       <literal>#</literal>-construct with unknown key is expected to
 529       be handled by a C template.</para>
 530
 531       <para>A C template should define a macro or function with name
 532       prefixed by <literal>hsc_</literal> that handles the construct
 533       by emitting the expansion to stdout. See
 534       <filename>template-hsc.h</filename> for examples.</para>
 535
 536       <para>Such macros can also be defined directly in the
 537       source. They are useful for making a <literal>#let</literal>-like
 538       macro whose expansion uses other <literal>#let</literal> macros.
 539       Plain <literal>#let</literal> prepends <literal>hsc_</literal>
 540       to the macro name and wraps the defininition in a
 541       <literal>printf</literal> call.</para>
 542
 543     </sect2>
 544
 545   </sect1>
 546
 547 </chapter>
 548
 549 <!-- Emacs stuff:
 550      ;;; Local Variables: ***
 551      ;;; mode: sgml ***
 552      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 553      ;;; End: ***
 554  -->