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