MERGED: Give PrimOps a NOINLINE pragma, to suppress silly warnings from dsRule
[ghc.git] / docs / ndp / haskell.sty
1 %%% This is a LaTeX2e style file.
2 %%%
3 %%% It supports setting functional languages, such as Haskell.
4 %%%
5 %%% Manuel M. T. Chakravarty <chak@cse.unsw.edu.au> [1998..2002]
6 %%%
7 %%% $Id: haskell.sty,v 1.2 2004/04/02 08:47:53 simonmar Exp $
8 %%%
9 %%% This file is free software; you can redistribute it and/or modify
10 %%% it under the terms of the GNU General Public License as published by
11 %%% the Free Software Foundation; either version 2 of the License, or
12 %%% (at your option) any later version.
13 %%%
14 %%% This file is distributed in the hope that it will be useful,
15 %%% but WITHOUT ANY WARRANTY; without even the implied warranty of
16 %%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 %%% GNU General Public License for more details.
18 %%%
19 %%% Acknowledegments ==========================================================
20 %%%
21 %%% Thanks to Gabriele Keller <keller@it.uts.edu.au> for beta testing and
22 %%% code contributions.  Thanks to the LaTeX3 project for improving the LaTeX
23 %%% sources (which helped me writing this code).  Furthermore, I am grateful
24 %%% to Martin Erwig <Martin.Erwig@FernUni-Hagen.de> and Bernard J. Pope
25 %%% <bjpop@cs.mu.OZ.AU> for feedback and suggestions, and to Conal Elliott
26 %%% <conal@MICROSOFT.com> and Marc van Dongen <dongen@cs.ucc.ie> for pointing
27 %%% out a tricky bug.
28 %%%
29 %%% TODO ======================================================================
30 %%%
31 %%% B ~ bug; F ~ feature
32 %%%
33 %%% * B: Consider to use the following alternative definition for \<..\>:
34 %%%
35 %%%        \def\<{\bgroup\@hsSpaceToApp\endhs}
36 %%%        \def\endhs#1\>{\(\mathit{#1}\)\egroup}
37 %%%
38 %%%      It completely avoids the problem that \mathit\bgroup..\egroup isn't
39 %%%      guaranteed to work and seems more elegant, anyway.
40 %%%
41 %%% * F: Along the lines of the discussion with Martin Erwig add support for
42 %%%      keywords etc (see the emails)
43 %%%
44 %%% * B: If we have as input 
45 %%%
46 %%%        \<map
47 %%%        g\>
48 %%%
49 %%%      there won't be a `\hsap' inserted!!  (Can this be solved by using
50 %%%      \obeylines in \<...\>?)
51 %%%
52 %%% * B: A \relax is needed after a & if it immediately followed by a \hsbody{}
53 %%%   (See TeXbook, S.240)
54 %%%
55 %%% * F: Implement a \hstext{...} as \(\text{...}\).
56 %%%
57 %%% * F: Star-form of \hscom that uses "---" instead of "-\hskip0pt-"
58 %%%
59 %%% * We would like hswhere* etc that are like haskell* (\hsalign already
60 %%%   supports this, ie, there is a \hsalign*).
61 %%%
62 %%% * Star-Versions of if, let etc that use a single line layout (maybe not
63 %%%   with star, because of the above).
64 %%%
65 %%% * Support for enforcing and prohibiting breaks in `haskell' displays.
66 %%%
67 %%% * Comments in a let-in should be aligned in the same way for the bindings
68 %%%   and the body.
69 %%%
70 %%% * It would be nice to have different styles (indentation after in of
71 %%%   let-in or not) etc; either to be set with a package option or in the
72 %%%   preamble (the latter probably makes more sense). 
73 %%%
74 %%% * Literate programming facility: Variant of the `haskell' env (maybe
75 %%%   `hschunk', which is named and can be used in other chunks).  But maybe
76 %%%   it is not necessary to provide a chunk-based reordering mechanism,
77 %%%   because most of the Haskell stuff can be in any order anyway...
78 %%%   Important is to provide a way to define visually pleasing layout
79 %%%   together with the raw Haskell form for program output. (Maybe `haskell*' 
80 %%%   as Haskell env that outputs its contents?)
81 %%%
82
83 %% Initialization
84 %% ==============
85
86 \NeedsTeXFormat{LaTeX2e} 
87 \ProvidesPackage{haskell}[2002/02/08 v1.1a Chilli's Haskell Style]
88
89 % NOTE: The sole purpose of the following is to work around what I believe is
90 %       a bug in LaTeX.  If the first occurence of \mathit in a document uses
91 %       \bgroup and \egroup to enclose the argument (instead of { and }),
92 %       \mathit does *not* apply to the argument.  (I guess, some font
93 %       initialisation stuff is getting in the way of parsing the argument.)
94 %
95 %       The following forces a \mathit right after \begin{document}.
96 %
97 %       UPDATE: The LaTeX project people say that it isn't really a bug; more
98 %               like a not supported form.  See alternative definition in the
99 %               bug list above.
100 %
101 \AtBeginDocument{\setbox0=\hbox{\(\mathit\relax\)}}
102
103
104 %% Parameters
105 %% ==========
106
107 \newskip\hsmargin
108 \hsmargin\leftmargini
109
110
111 %% Main macros and environments
112 %% ============================
113
114 % applications
115 %
116 \newcommand{\hsap}{%                    % application by juxtaposition
117   \unskip\mskip 4mu plus 1mu}           %   only the last \hsap counts
118
119 % commands to start and stop setting spaces as \hsap
120 %
121 {\obeyspaces\gdef\@hsSpaceToApp{\obeyspaces\let =\hsap}}  % spaces matter!!!
122 {\obeyspaces\gdef\@hsNormalSpace{\let =\space}}
123
124 % commands to start and stop treating numbers specially, ie, we don't want
125 % them to be affected by font changing commands in Haskell contexts as this
126 % would give italic numerals; the trick is to redefine their math code such
127 % that they go into math class 0 and thus don't change families (cf. `The
128 % TeXbook', Chapter 17, pp152)
129 %
130 \newcommand{\@hsRmNumbers}{%
131   \mathcode`0="0030
132   \mathcode`1="0031
133   \mathcode`2="0032
134   \mathcode`3="0033
135   \mathcode`4="0034
136   \mathcode`5="0035
137   \mathcode`6="0036
138   \mathcode`7="0037
139   \mathcode`8="0038
140   \mathcode`9="0039
141   }
142 \newcommand{\@hsNormalNumbers}{%
143   \mathcode`0="7030
144   \mathcode`1="7031
145   \mathcode`2="7032
146   \mathcode`3="7033
147   \mathcode`4="7034
148   \mathcode`5="7035
149   \mathcode`6="7036
150   \mathcode`7="7037
151   \mathcode`8="7038
152   \mathcode`9="7039
153   }
154
155 % Save the bindings of the standard math commands
156 %
157 % This is somewhat subtle as we want to able to enter the original math mode
158 % within Haskell mode and we have to ensure that the different opening
159 % commands are matched by the correct versions of the closing commands.
160 %
161 \let\@hsmathorg=\(
162 \let\@hsmathendorg=\)
163 \let\hs@crorg=\\
164 \newcommand{\@hsmath}{%
165   \relax\hbox\bgroup
166   \@hsNormalSpace
167   \@hsNormalNumbers
168   \let\(=\@hsmathorgx
169   \let\)=\@hsmathend
170   \def\\{\hs@crorg}%
171   \@hsmathorg
172   }
173 \newcommand{\@hsmathend}{%
174   \@hsmathendorg
175   \egroup
176   }
177 \newcommand{\@hsmathorgx}{%
178   \relax\@hsmathorg
179   \let\)=\@hsmathendorg
180   }
181
182 %% Typesetting of Haskell
183 %% ======================
184
185 % Inline Haskell phrases are delimited by `\<' and `\>'.
186 %
187 % Note: `\>' is only locally redefined.
188
189 \newcommand{\<}{%
190   \@hsmathorg
191   \mathit\bgroup
192   \@hsSpaceToApp
193   \@hsRmNumbers
194   \let\>=\@endhs
195   \let\(=\@hsmath  
196   \def\\{\cr}           % for Haskell alignments
197   }
198 \newcommand{\@endhs}{%
199   \egroup
200   \@hsmathendorg
201   }
202
203 % Displayed Haskell (environment `haskell' and `haskell*')
204 %
205 % There are two kind of preambles for \halign: \hs@preambleNorm is for 
206 % `amsmath' style alignments and \hs@preambleStar for `equation' style
207 % alignments (but with an unbound number of columns to its right)
208 %
209 % We need #### to get a ## in the \edef building the \halign command.
210 %
211 % first the preambles (also used in \hs@align below):
212 %
213 \def\hs@preambleNorm{%
214   \noexpand\<####\unskip\noexpand\>\hfil&&\noexpand%
215   \<{}####\unskip\noexpand\>\hfil}
216 \def\hs@preambleStar{%
217   \noexpand\<####\unskip\noexpand\>\hfil&\hfil\noexpand%
218   \<{}####\unskip{}\noexpand\>\hfil&&\noexpand\<{}####\noexpand\>\hfil}
219 %
220 % the environments:
221 %
222 \newenvironment{haskell}{%
223   \@haskell\hs@preambleNorm}{%
224   \@endhaskell
225   }
226 \newenvironment{haskell*}{%
227   \@haskell\hs@preambleStar}{%
228   \@endhaskell
229   }
230 %
231 % auxiliary definition getting the preamble as its first argument and starting 
232 % the environment:
233 %
234 \def\@haskell#1{%
235   \bgroup
236   \vspace\abovedisplayskip
237   \let\(=\@hsmath               % Important when `\(' occurs after `&'!  
238   \edef\@preamble{%
239     \halign\bgroup\hskip\hsmargin#1\cr}
240   \@preamble
241   }
242 %
243 % Auxiliary definition ending environment:
244 %
245 \def\@endhaskell{%
246   \crcr\egroup
247 %  \vspace\belowdisplayskip
248   \egroup\noindent\ignorespaces\global\@ignoretrue%
249   }
250
251 % single line comment and keyword style
252 %
253 \newcommand{\hscom}[1]{%
254   \relax\(\quad\textnormal{-\hskip0pt- #1}\)}
255 %  \relax\(\quad\textnormal{--- #1}\)}
256 \newcommand{\hskwd}[1]{%
257   \mathbf{#1}}
258
259 % informal description
260 %
261 \newcommand{\hsinf}[1]{%
262   \(\langle\textnormal{#1}\rangle\)}
263
264 % literals and some special symbols
265 %
266 \newcommand{\hschar}[1]{\textrm{'#1'}}                % character literals
267 \newcommand{\hsstr}[1]{\textrm{``#1''}}               % strings literals
268 \newcommand{\hsfrom}{\leftarrow}                      % <-
269
270 % aligned subphrases
271 %
272 % check for an optional star and combine prefix (in #1) with one of the two
273 % preambles (with star means to center the material between the first and
274 % second &) 
275 %
276 \def\hs@align#1{%
277   \@ifstar
278     {\hs@align@pre{#1\hs@preambleStar}}%
279     {\hs@align@pre{#1\hs@preambleNorm}}%
280   }
281 %
282 % test for optional argument; #1: preamble
283 %
284 \def\hs@align@pre#1{%
285   \@testopt{\hs@align@prealign#1}t}
286 %
287 % got all arguments, now for the real code; #1: preamble; #2: alignment; 
288 % #3: body (the material set by the \halign)
289 %
290 \def\hs@align@prealign#1[#2]#3{%
291   \relax\(
292   \edef\@preamble{%
293     \halign\bgroup#1\cr}
294   \if #2t\vtop \else \if#2b\vbox \else \vcenter \fi\fi
295   \bgroup%
296     \@preamble
297         #3%
298     \crcr\egroup%
299   \egroup\)
300   }
301 %
302 % user-level command: alignment without a prefix
303 %
304 \newcommand{\hsalign}{%
305   \relax
306   \hs@align\relax%
307   }
308
309 % subphrase breaking the surrounding alignment being flushed left
310 %
311 \newcommand{\hsnoalign}[1]{%
312   \noalign{%
313     \hs@align{\hskip\hsmargin}{#1}%
314     }%
315   }
316
317 % body expression breaking the surrounding alignment
318 %
319 % * setting \hsmargin to 0pt within the preamble (and _after_ it is used in
320 %   the preamble) is crucial, as we want \hsmargin only to be applied in
321 %   _outermost_ alignments
322 %
323 \newcommand{\hsbody}[1]{%
324   {}\\
325   \noalign{%
326     \hs@align{\hskip\hsmargin\quad\hsmargin0pt}{#1}%
327     }%
328   }
329
330
331 %% Defining commands for use in the Haskell mode
332 %% =============================================
333 %%
334 %% We use some of the low-level machinery defined in LaTeX's source file
335 %% `ltdefns.dtx'.
336 %%
337 %% \hscommand is similar to \newcommand, but there is no *-version.
338 %%
339 %% We use our own definitions here to insert a strategic `\relax' (see below)
340 %% and to obey spaces within the bodies of Haskell definitions.
341
342 \newcommand{\hscommand}[1]{\@testopt{\hs@newcommand#1}0}
343 \def\hs@newcommand#1[#2]{%
344   \obeyspaces                           % spaces count in Haskell macros
345   \@ifnextchar [{\hs@xargdef#1[#2]}%
346                 {\hs@argdef#1[#2]}}
347
348 % All this trouble only to be able to add the `\relax' into the expansion
349 % process.  If we don't that, commands without optional arguments when
350 % invoked after an alignment character & don't work properly (actually, the
351 % \obeyspaces doesn't work).  I am sure that has to do with the scanning for
352 % \omit etc in \halign (TeXbook, p240), but I don't understand yet why it
353 % is problematic in this case.
354 %
355 % Furthermore, we switch off \obeyspaces in the end.
356 %
357 \long\def\hs@argdef#1[#2]#3{%
358    \@ifdefinable#1{%
359      \expandafter\def\expandafter#1\expandafter{%
360        \relax                % in order to stop token expansion after &
361        \csname\string#1\expandafter\endcsname}%
362      \expandafter\@yargdef
363      \csname\string#1\endcsname
364      \@ne
365      {#2}%
366      {#3}}%
367    \catcode`\ =10%           % stop obeying spaces now
368    }
369
370 % Switch off \obeyspaces in the end.
371 %
372 \long\def\hs@xargdef#1[#2][#3]#4{%
373   \@ifdefinable#1{%
374     \expandafter\def\expandafter#1\expandafter{%
375       \expandafter
376       \@protected@testopt
377       \expandafter
378       #1%
379       \csname\string#1\expandafter\endcsname
380       {#3}}%
381     \expandafter\@yargdef
382     \csname\string#1\endcsname
383     \tw@
384     {#2}%
385     {#4}}%
386   \catcode`\ =10%           % stop obeying spaces now
387   }
388
389
390 %% Abbreviations
391 %% =============
392
393 % infix operators
394 %
395 \newcommand{\hsapp}{\mathbin{+\mkern-7mu+}}
396 \newcommand{\hsifix}[1]{\mathbin{\string`#1\string`}}
397
398 % let expression
399 %
400 \hscommand{\hslet}[3][t]{%
401   \hsalign[#1]{%
402     \hskwd{let}\\
403     \quad\hsalign{#2}\\
404     \hskwd{in}\\
405     #3
406     }%
407   }
408   
409 % if expression
410 %
411 \hscommand{\hsif}[4][t]{%
412   \hsalign[#1]{%
413     \hskwd{if} #2 \hskwd{then}\\
414     \quad\hsalign{#3}\\
415     \hskwd{else}\\
416     \quad\hsalign{#4}% 
417     }%
418   }
419
420 % case expression
421 %
422 \hscommand{\hscase}[3][t]{%
423   \hsalign[#1]{%
424     \hskwd{case} #2 \hskwd{of}\\
425     \quad\hsalign{#3}%
426     }%
427   }
428   
429 % where clause
430 %
431 % * it is important to take the \quad into the preamble, so that nested
432 %   \noaligns can break it
433 %
434 \hscommand{\hswhere}[1]{%
435   \hsbody{%
436     \hskwd{where}\\
437     \hs@align{\quad}{#1}%
438     }%
439   }
440
441 % do expression
442 %
443 \hscommand{\hsdo}[2][t]{%
444   \hsalign[#1]{%
445     \hskwd{do}\\
446     \quad\hsalign{#2}\\
447   }%
448 }
449
450 % class declaration
451 %
452 \hscommand{\hsclass}[2]{%
453   \hskwd{class} #1 \hskwd{where}
454   \hsbody{%
455     #2
456   }%
457 }
458
459 % instance declaration
460 %
461 \hscommand{\hsinstance}[2]{%
462   \hskwd{instance} #1 \hskwd{where}
463   \hsbody{%
464     #2
465   }%
466 }
467
468
469 %% Extensions for Distributed Haskell (Goffin)
470 %% ===========================================
471 %%
472 %% These definitions may change in the future.
473
474 \hscommand{\hsunif}{\mathbin{:=:}}
475 \hscommand{\hsalias}{\mathrel{\sim}}
476 \hscommand{\hsoutof}{\twoheadleftarrow}
477 \hscommand{\hsinto}{\twoheadrightarrow}
478 \hscommand{\hsparc}{\binampersand}
479 \hscommand{\hsseq}{\Longrightarrow}
480 \hscommand{\hsex}[2]{{\hskwd{ex} #1 \hskwd{in} #2}}
481
482 \hscommand{\hsexin}[3][t]{%
483   \hsalign[#1]{%
484     \hskwd{ex} #2 \hskwd{in}\\
485     \quad\hsalign{#3}\\
486     }%
487   }
488
489 \hscommand{\hschoice}[2][t]{%
490   \hsalign[#1]{%
491     \hskwd{choice}\\
492     \quad\hsalign{#2}\\
493     }%
494   }
495
496