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