1 <?xml version="1.0" encoding="iso-8859-1"?>
3 <title>Other Haskell utility programs</title>
4 <indexterm><primary>utilities, Haskell</primary></indexterm>
6 <para>This section describes other program(s) which we distribute,
7 that help with the Great Haskell Programming Task.</para>
9 <!-- comment: hasktags was dropped in GHC 6.12
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>
16 <para><command>hasktags</command> is a very simple Haskell program that produces ctags "tags" and etags "TAGS" files for Haskell programs.</para>
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>
20 <para>Invocation Syntax:</para>
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>
28 <para>Example usage</para>
31 find -name \*.\*hs | xargs hasktags
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>
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>
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>
42 <title>Using tags with your editor</title>
44 <para>With NEdit, load the "tags" file using "File/Load Tags File". Use "Ctrl-D" to search for a tag.</para>
46 <para>With XEmacs, load the "TAGS" file using "visit-tags-table". Use "M-." to search for a tag.</para>
54 <!-- comment: hstags doesn't work anymore
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>
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>
65 <para>Rather than scratch your head, saying “Now where did
66 we define `foo'?”, you just do (in Emacs) <Literal>M-. foo
67 RET</Literal>, and You're There! Some people go wild over this
70 <para>GHC comes with a program <command>hstags</command>, which
71 build Emacs-able TAGS files. The invocation syntax is:</para>
74 hstags [GHC-options] file [files...]
77 <para>The best thing is just to feed it your GHC command-line
78 flags. A good Makefile entry might be:</para>
83 hstags $(GHC_FLAGS) *.lhs
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>
90 <para>Shortcomings: (1) 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) Data-constructor definitions don't get in. Go for the
94 corresponding type constructor instead.</para>
96 <para>Actually, GHC also comes with <command>etags</command>
97 [for C], and <command>perltags</command> [for You
98 Know What]. And—I cannot tell a lie—there is
99 Denis Howe's <command>fptags</command> [for Haskell,
100 etc.] in the <Filename>ghc/CONTRIB</Filename>
101 section…)</para>
107 <title>“Yacc for Haskell”: <command>happy</command></title>
109 <indexterm><primary>Happy</primary></indexterm>
110 <indexterm><primary>Yacc for Haskell</primary></indexterm>
111 <indexterm><primary>parser generator for Haskell</primary></indexterm>
113 <para>Andy Gill and Simon Marlow have written a parser-generator
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>
119 <para>You can get <command>happy</command> from <ulink
120 url="http://www.haskell.org/happy/">the Happy
121 Homepage</ulink>.</para>
123 <para><command>Happy</command> is at its shining best when
124 compiled by GHC.</para>
128 <!-- we don't distribute this anymore
130 <title>Pretty-printing Haskell: <command>pphs</command></title>
131 <indexterm><primary>pphs</primary></indexterm>
132 <indexterm><primary>pretty-printing Haskell code</primary></indexterm>
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—that sort of thing. It is good at lining up program
139 clauses and equals signs, things that are very tiresome to do by
142 <para>The code is distributed with GHC in
143 <Filename>ghc/CONTRIB/pphs</Filename>.</para>
148 <title>Writing Haskell interfaces to C code:
149 <command>hsc2hs</command></title>
150 <indexterm><primary><command>hsc2hs</command></primary>
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>
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>
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
172 <para>In the following, “Haskell file” is the main
173 output (usually a <literal>.hs</literal> file), “compiled
174 Haskell file” is the Haskell file after
175 <command>ghc</command> has compiled it to C (i.e. a
176 <literal>.hc</literal> file), “C program” is the
177 program that outputs the Haskell file, “C file” is the
178 optionally generated C file, and “C header” is its
182 <title>command line syntax</title>
184 <para><command>hsc2hs</command> takes input files as arguments,
185 and flags that modify its behavior:</para>
189 <term><literal>-o FILE</literal> or
190 <literal>––output=FILE</literal></term>
192 <para>Name of the Haskell file.</para>
197 <term><literal>-t FILE</literal> or
198 <literal>––template=FILE</literal></term>
200 <para>The template file (see below).</para>
205 <term><literal>-c PROG</literal> or
206 <literal>––cc=PROG</literal></term>
208 <para>The C compiler to use (default:
209 <command>gcc</command>)</para>
214 <term><literal>-l PROG</literal> or
215 <literal>––ld=PROG</literal></term>
217 <para>The linker to use (default:
218 <command>gcc</command>).</para>
223 <term><literal>-C FLAG</literal> or
224 <literal>––cflag=FLAG</literal></term>
226 <para>An extra flag to pass to the C compiler.</para>
231 <term><literal>-I DIR</literal></term>
233 <para>Passed to the C compiler.</para>
238 <term><literal>-L FLAG</literal> or
239 <literal>––lflag=FLAG</literal></term>
241 <para>An extra flag to pass to the linker.</para>
246 <term><literal>-i FILE</literal> or
247 <literal>––include=FILE</literal></term>
249 <para>As if the appropriate <literal>#include</literal>
250 directive was placed in the source.</para>
255 <term><literal>-D NAME[=VALUE]</literal> or
256 <literal>––define=NAME[=VALUE]</literal></term>
258 <para>As if the appropriate <literal>#define</literal>
259 directive was placed in the source.</para>
264 <term><literal>––no-compile</literal></term>
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>
273 <term><literal>-?</literal> or <literal>––help</literal></term>
275 <para>Display a summary of the available flags and exit successfully.</para>
280 <term><literal>-V</literal> or <literal>––version</literal></term>
282 <para>Output version information and exit successfully.</para>
287 <para>The input file should end with .hsc (it should be plain
288 Haskell source only; literate Haskell is not supported at the
289 moment). Output files by default get names with the
290 <literal>.hsc</literal> suffix replaced:</para>
296 <entry><literal>.hs</literal></entry>
297 <entry>Haskell file</entry>
300 <entry><literal>_hsc.h</literal></entry>
301 <entry>C header</entry>
304 <entry><literal>_hsc.c</literal></entry>
305 <entry>C file</entry>
311 <para>The C program is compiled using the Haskell compiler. This
312 provides the include path to <filename>HsFFI.h</filename> which
313 is automatically included into the C program.</para>
316 <sect2><title>Input syntax</title>
318 <para>All special processing is triggered by
319 the <literal>#</literal> operator. To output
320 a literal <literal>#</literal>, write it twice:
321 <literal>##</literal>. Inside string literals and comments
322 <literal>#</literal> characters are not processed.</para>
324 <para>A <literal>#</literal> is followed by optional
325 spaces and tabs, an alphanumeric keyword that describes
326 the kind of processing, and its arguments. Arguments look
327 like C expressions separated by commas (they are not
328 written inside parens). They extend up to the nearest
329 unmatched <literal>)</literal>, <literal>]</literal> or
330 <literal>}</literal>, or to the end of line if it occurs outside
331 any <literal>() [] {} '' "" /**/</literal> and is not preceded
332 by a backslash. Backslash-newline pairs are stripped.</para>
334 <para>In addition <literal>#{stuff}</literal> is equivalent
335 to <literal>#stuff</literal> except that it's self-delimited
336 and thus needs not to be placed at the end of line or in some
339 <para>Meanings of specific keywords:</para>
344 <term><literal>#include <file.h></literal></term>
345 <term><literal>#include "file.h"</literal></term>
347 <para>The specified file gets included into the C program,
348 the compiled Haskell file, and the C header.
349 <literal><HsFFI.h></literal> is included
350 automatically.</para>
355 <term><literal>#define name</literal></term>
356 <term><literal>#define name value</literal></term>
357 <term><literal>#undef name</literal></term>
359 <para>Similar to <literal>#include</literal>. Note that
360 <literal>#includes</literal> and
361 <literal>#defines</literal> may be put in the same file
362 twice so they should not assume otherwise.</para>
367 <term><literal>#let name parameters = "definition"</literal></term>
369 <para>Defines a macro to be applied to the Haskell
370 source. Parameter names are comma-separated, not
371 inside parens. Such macro is invoked as other
372 <literal>#</literal>-constructs, starting with
373 <literal>#name</literal>. The definition will be
374 put in the C program inside parens as arguments of
375 <literal>printf</literal>. To refer to a parameter,
376 close the quote, put a parameter name and open the
377 quote again, to let C string literals concatenate.
378 Or use <literal>printf</literal>'s format directives.
379 Values of arguments must be given as strings, unless the
380 macro stringifies them itself using the C preprocessor's
381 <literal>#parameter</literal> syntax.</para>
386 <term><literal>#def C_definition</literal></term>
388 <para>The definition (of a function, variable, struct or
389 typedef) is written to the C file, and its prototype or
390 extern declaration to the C header. Inline functions are
391 handled correctly. struct definitions and typedefs are
392 written to the C program too. The
393 <literal>inline</literal>, <literal>struct</literal> or
394 <literal>typedef</literal> keyword must come just after
395 <literal>def</literal>.</para>
400 <term><literal>#if condition</literal></term>
401 <term><literal>#ifdef name</literal></term>
402 <term><literal>#ifndef name</literal></term>
403 <term><literal>#elif condition</literal></term>
404 <term><literal>#else</literal></term>
405 <term><literal>#endif</literal></term>
406 <term><literal>#error message</literal></term>
407 <term><literal>#warning message</literal></term>
409 <para>Conditional compilation directives are passed
410 unmodified to the C program, C file, and C header. Putting
411 them in the C program means that appropriate parts of the
412 Haskell file will be skipped.</para>
417 <term><literal>#const C_expression</literal></term>
419 <para>The expression must be convertible to
420 <literal>long</literal> or <literal>unsigned
421 long</literal>. Its value (literal or negated literal)
422 will be output.</para>
427 <term><literal>#const_str C_expression</literal></term>
429 <para>The expression must be convertible to const char
430 pointer. Its value (string literal) will be output.</para>
435 <term><literal>#type C_type</literal></term>
437 <para>A Haskell equivalent of the C numeric type will be
438 output. It will be one of
439 <literal>{Int,Word}{8,16,32,64}</literal>,
440 <literal>Float</literal>, <literal>Double</literal>,
441 <literal>LDouble</literal>.</para>
446 <term><literal>#peek struct_type, field</literal></term>
448 <para>A function that peeks a field of a C struct will be
449 output. It will have the type
450 <literal>Storable b => Ptr a -> IO b</literal>.
452 The intention is that <literal>#peek</literal> and
453 <literal>#poke</literal> can be used for implementing the
454 operations of class <literal>Storable</literal> for a
455 given C struct (see the
456 <literal>Foreign.Storable</literal> module in the library
457 documentation).</para>
462 <term><literal>#poke struct_type, field</literal></term>
464 <para>Similarly for poke. It will have the type
465 <literal>Storable b => Ptr a -> b -> IO ()</literal>.</para>
470 <term><literal>#ptr struct_type, field</literal></term>
472 <para>Makes a pointer to a field struct. It will have the type
473 <literal>Ptr a -> Ptr b</literal>.</para>
478 <term><literal>#offset struct_type, field</literal></term>
480 <para>Computes the offset, in bytes, of
481 <literal>field</literal> in
482 <literal>struct_type</literal>. It will have type
483 <literal>Int</literal>.</para>
488 <term><literal>#size struct_type</literal></term>
490 <para>Computes the size, in bytes, of
491 <literal>struct_type</literal>. It will have type
492 <literal>Int</literal>.</para>
497 <term><literal>#enum type, constructor, value, value, ...</literal></term>
499 <para>A shortcut for multiple definitions which use
500 <literal>#const</literal>. Each <literal>value</literal>
501 is a name of a C integer constant, e.g. enumeration value.
502 The name will be translated to Haskell by making each
503 letter following an underscore uppercase, making all the rest
504 lowercase, and removing underscores. You can supply a different
505 translation by writing <literal>hs_name = c_value</literal>
506 instead of a <literal>value</literal>, in which case
507 <literal>c_value</literal> may be an arbitrary expression.
508 The <literal>hs_name</literal> will be defined as having the
509 specified <literal>type</literal>. Its definition is the specified
510 <literal>constructor</literal> (which in fact may be an expression
511 or be empty) applied to the appropriate integer value. You can
512 have multiple <literal>#enum</literal> definitions with the same
513 <literal>type</literal>; this construct does not emit the type
514 definition itself.</para>
522 <title>Custom constructs</title>
524 <para><literal>#const</literal>, <literal>#type</literal>,
525 <literal>#peek</literal>, <literal>#poke</literal> and
526 <literal>#ptr</literal> are not hardwired into the
527 <command>hsc2hs</command>, but are defined in a C template that is
528 included in the C program: <filename>template-hsc.h</filename>.
529 Custom constructs and templates can be used too. Any
530 <literal>#</literal>-construct with unknown key is expected to
531 be handled by a C template.</para>
533 <para>A C template should define a macro or function with name
534 prefixed by <literal>hsc_</literal> that handles the construct
535 by emitting the expansion to stdout. See
536 <filename>template-hsc.h</filename> for examples.</para>
538 <para>Such macros can also be defined directly in the
539 source. They are useful for making a <literal>#let</literal>-like
540 macro whose expansion uses other <literal>#let</literal> macros.
541 Plain <literal>#let</literal> prepends <literal>hsc_</literal>
542 to the macro name and wraps the definition in a
543 <literal>printf</literal> call.</para>
552 ;;; Local Variables: ***
553 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***