1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>
cpphs
</title>
</head>
<body bgcolor='#ffffff'>
<center>
<h1>cpphs</h1>
<table><tr><td width=200 align=center>
<a href="#what">What is cpphs?</a><br>
<a href="#how">How do I use it?</a><br>
<a href="#download">Downloads</a><br>
</td><td width=200 align=center>
<a href="#diff">Differences to cpp</a><br>
<a href="#who">Contacts</a><br>
</td></tr></table>
</center>
<hr>
<center><h3><a name="what">What is cpphs?</a></h3></center>
<p>
<b>cpphs</b> is a simplified re-implementation of
<a href="http://gcc.gnu.org/onlinedocs/gcc-2.95.3/cpp.html">cpp</a>,
the C pre-processor, in <a href="http://haskell.org/">Haskell</a>.
<p>
Why re-implement cpp? Rightly or wrongly, the C pre-processor is
widely used in Haskell source code. It enables conditional compilation
for different compilers, different versions of the same compiler,
and different OS platforms. It is also occasionally used for its
macro language, which can enable certain forms of platform-specific
detail-filling, such as the tedious boilerplate generation of instance
definitions and FFI declarations. However, there are two problems with
cpp, aside from the obvious aesthetic ones:
<ul>
<li> For some Haskell systems, notably Hugs on Windows, a true cpp
is not available by default.
<li> Even for the other Haskell systems, the common cpp provided by
the gcc 3.x series is changing subtly in ways that are
incompatible with Haskell's syntax. There have always been
problems with, for instance, string gaps, and prime characters
in identifiers. These problems are only going to get worse.
</ul>
So, it seemed right to attempt to provide an alternative to cpp,
both more compatible with Haskell, and itself written in Haskell so
that it can be distributed with compilers.
<p>
This version of the C pre-processor is pretty-much feature-complete,
and compatible with the <tt>-traditional</tt> style.
It has two modes:
<ul>
<li> conditional compilation only (--nomacro),
<li> and full macro-expansion (default).
</ul>
In <tt>--nomacro</tt> mode, cpphs performs only conditional
compilation actions, namely <tt>#include</tt>'s, <tt>#if</tt>'s,
and <tt>#ifdef</tt>'s are processed according to text-replacement
definitions (both command-line and internal), but no parameterised
macro expansion is performed. In full compatibility mode (the
default), textual replacements and macro expansions are also processed
in the remaining body of non-cpp text.
<p>
Working Features:
<dl>
<dt>#ifdef</dt> <dd>simple conditional compilation</dd>
<dt>#if</dt> <dd>the full boolean language of defined(),
&&, ||, ==, etc.</dd>
<dt>#elif</dt> <dd>chained conditionals</dd>
<dt>#define</dt> <dd>in-line definitions (text replacements and macros)</dd>
<dt>#undef</dt> <dd>in-line revocation of definitions</dd>
<dt>#include</dt><dd>file inclusion</dd>
<dt>#line</dt> <dd>line number directives</dd>
<dt>\\n</dt> <dd>line continuations within all # directives</dd>
<dt>/**/</dt> <dd>token catenation within a macro definition</dd>
<dt>##</dt> <dd>ANSI-style token catenation</dd>
<dt>#</dt> <dd>ANSI-style token stringisation</dd>
<dt>__FILE__</dt><dd>special text replacement for DIY error messages</dd>
<dt>__LINE__</dt><dd>special text replacement for DIY error messages</dd>
<dt>__DATE__</dt><dd>special text replacement</dd>
<dt>__TIME__</dt><dd>special text replacement</dd>
</dl>
<p>
Macro expansion is recursive. Redefinition of a macro name does not
generate a warning. Macros can be defined on the command-line with
-D just like textual replacements. Macro names are permitted to be
Haskell identifiers e.g. with the prime ' and backtick ` characters,
which is slightly looser than in C, but they still may not include
operator symbols.
<p>
Numbering of lines in the output is preserved so that any later
processor can give meaningful error messages. When a file is
<tt>#include</tt>'d, cpphs inserts <tt>#line</tt> directives for the
same reason. Numbering should be correct even in the presence of
line continuations. If you don't want <tt>#line</tt> directives in
the final output, use the <tt>--noline</tt> option.
<p>
Any syntax errors in cpp directives gives a message to stderr and
halts the program. Failure to find a #include'd file produces a
warning to stderr, but processing continues.
<hr>
<center><h3><a name="how">How do I use it?</a></h3></center>
<p>
<center><pre>
Usage: cpphs [ filename | -Dsym | -Dsym=val | -Ipath ]+ [-Ofile]
[--nomacro] [--noline] [--strip] [--hashes] [--layout]
cpphs --version
</pre></center>
<p>
You can give any number of filenames on the command-line. The
results are catenated on standard output.
<p>
Options:
<dl>
<dt>-Dsym</dt> <dd>define a textual replacement (default value is 1)</dd>
<dt>-Dsym=val</dt><dd>define a textual replacement with a specific value</dd>
<dt>-Ipath</dt> <dd>add a directory to the search path for #include's</dd>
<dt>-Ofile</dt> <dd>specify a file for output (default is stdout)</dd>
<dt>--nomacro</dt><dd>only process #ifdef's and #include's,
do not expand macros</dd>
<dt>--noline</dt> <dd>remove #line droppings from the output</dd>
<dt>--strip</dt> <dd>convert C-style comments to whitespace, even outside
cpp directives</dd>
<dt>--hashes</dt> <dd>recognise the ANSI # stringise operator, and ## for
token catenation, within macros</dd>
<dt>--layout</dt> <dd>preserve newlines within macro expansions</dd>
<dt>--version</dt><dd>report version number of cpphs and stop</dd>
</dl>
<p>
There are NO textual replacements defined by default. (Normal cpp
usually has definitions for machine, OS, etc. These could easily
be added to the cpphs source code if you wish.) The search path is
searched in order of the -I options, except that the directory of the
calling file, then the current directory, are always searched first.
Again, there is no default search path (and again, this could easily
be changed).
<hr>
<center><h3><a name="download">Downloads</a></h3></center>
<p>
<b>Current version:</b>
<p>
cpphs-0.7, release date 2004.09.01<br>
By HTTP:
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.7.tar.gz">.tar.gz</a>,
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.7.zip">.zip</a>,
<a href="http://www.freshports.org/devel/hs-cpphs/">FreeBSD port</a>.
<ul>
<li> Enable the <tt>__FILE__</tt>, <tt>__LINE__</tt>, <tt>__DATE__</tt>,
and <tt>__TIME__</tt> specials, which can be useful for creating
DIY error messages.
</ul>
<p>
<b>Older versions:</b>
<p>
cpphs-0.6, release date 2004.07.30<br>
By HTTP:
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.6.tar.gz">.tar.gz</a>,
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.6.zip">.zip</a>,
<a href="http://www.freshports.org/devel/hs-cpphs/">FreeBSD port</a>.
<ul>
<li> Recognise and ignore the <tt>#pragma</tt> cpp directive.
<li> Fix beginning-of-file bug, where in <tt>--noline</tt> mode, a
<tt>#line</tt> cpp directive appeared at the top of the output file.
<li> Fix chained parenthesised boolean exprs in <tt>#if</tt>, e.g.
<pre>#if ( foo ) && ( bar )</pre>
<li> Fix precedence in chained unparenthesised boolean exprs in
<tt>#if</tt>, e.g.
<pre>#if foo && bar || baz && frob</pre>
<li> For better compatibility with cpp, and because otherwise
there are certain constructs that cannot be expressed, we no
longer permit whitespace in a <tt>#define</tt> between the
symbolname and an opening parenthesis, e.g.
<pre>#define f (f' id)</pre>. Previously, this was interpreted
as a parametrised macro, with arguments in the parens, and
no expansion. Now, the space indicates that this is a textual
replacement, and the parenthesised expression is in fact the
replacement.
</ul>
<p>
cpphs-0.5, release date 2004.06.07<br>
By HTTP:
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.5.tar.gz">.tar.gz</a>,
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.5.zip">.zip</a>,
<a href="http://www.freshports.org/devel/hs-cpphs/">FreeBSD port</a>.
<ul>
<li> Added a --version flag to report the version number.
<li> Renamed --stringise to --hashes, and use it to turn on ## catenation
as well.
<li> Bugfix for <tt>#if 1</tt>, previously interpreted as false.
<li> Bugfix for --nolines: it no longer adds extra spurious newlines.
<li> File inclusion now looks in the directory of the calling file.
<li> Failure to find an include file is now merely a warning to stderr
rather than an error.
<li> Added a --layout flag. Previously, line continuations in a macro
definition were always preserved in the output, permitting use
of the Haskell layout rule even inside a macro. The default is now
to remove line continuations for conformance with cpp, but the option
of using --layout is still possible.
</ul>
<p>
cpphs-0.4, release date 2004.05.19<br>
By HTTP:
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.4.tar.gz">.tar.gz</a>,
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.4.zip">.zip</a>.
<ul>
<li> New flag -Ofile to redirect output
<li> Bugfix for precedence of ! in #if !False && False
<li> Bugfix for whitespace permitted between # and if
<li> Bugfix for <tt>#define F "blah"; #include F</tt>
</ul>
<p>
cpphs-0.3, release date 2004.05.18<br>
By HTTP:
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.3.tar.gz">.tar.gz</a>,
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.3.zip">.zip</a>.
<p>
Fix recursive macro expansion bug. Added option to strip C comments.
Added option to recognise the # stringise operator.
<p>
cpphs-0.2, release date 2004.05.15<br>
By HTTP:
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.2.tar.gz">.tar.gz</a>,
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.2.zip">.zip</a>.
<p>
Implements textual replacement and macro expansion.
<p>
cpphs-0.1, release date 2004.04.07<br>
By HTTP:
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.1.tar.gz">.tar.gz</a>,
<a href="http://www.cs.york.ac.uk/fp/cpphs/cpphs-0.1.zip">.zip</a>.
<p>
Initial release: implements conditional compilation and file inclusion only.
<p>
<b>Building instructions</b>
<p>
To build cpphs, use
<pre> hmake Main [-package base]; mv Main cpphs
</pre>
or
<pre> ghc --make Main; mv Main cpphs
</pre>
or
<pre> runhugs Main
</pre>
<hr>
<center><h3><a name="diff">Differences from cpp</a></h3></center>
<p>
In general, cpphs is based on the <tt>-traditional</tt> behaviour, not
ANSI C, and has the following main differences from the standard cpp.
<p>
<b>General</b>
<ul>
<li> The <tt>#</tt> that introduces any cpp directive must be in the first
column of a line (whereas ANSI permits whitespace before the <tt>#</tt>).
<li> Generates the <tt>#line n "filename"</tt> syntax, not the <tt># n
"filename"</tt> variant.
<li> C comments are only removed from within cpp directives. They are
not stripped from other text. Consider for instance that in
Haskell, all of the following are valid operator symbols: <tt>/*
*/ */*</tt> However, you can turn on C-comment removal with the
<tt>--strip</tt> option.
</ul>
<p>
<b>Macro language</b>
<ul>
<li> Accepts <tt>/**/</tt> for token-pasting in a macro definition.
However, <tt>/* */</tt> (with any text between the open/close
comment) inserts whitespace.
<li> The ANSI <tt>##</tt> token-pasting operator is available with
the <tt>--hashes</tt> flag. This is to avoid misinterpreting
any valid Haskell operator of the same name.
<li> Replaces a macro formal parameter with the actual, even inside a
string (double or single quoted). This is -traditional behaviour,
not supported in ANSI.
<li> Recognises the <tt>#</tt> stringisation operator in a macro
definition only if you use the <tt>--hashes</tt> option. (It is
an ANSI addition, only needed because quoted stringisation (above)
is prohibited by ANSI.)
<li> Preserves whitespace within a textual replacement definition
exactly (modulo newlines), but leading and trailing space is eliminated.
<li> Preserves whitespace within a macro definition (and trailing it)
exactly (modulo newlines), but leading space is eliminated.
<li> Preserves whitespace within macro call arguments exactly
(including newlines), but leading and trailing space is eliminated.
<li> With the <tt>--layout</tt> option, line continuations in a textual
replacement or macro definition are preserved as line-breaks in the
macro call. (Useful for layout-sensitive code in Haskell.)
</ul>
<hr>
<center><h3><a name="who">Contacts</a></h3></center>
<p>
I am interested in hearing your feedback on cpphs. Bug reports
especially welcome. You can send feature requests too, but I won't
guarantee to implement them if they depart much from the ordinary
cpp's behaviour. Please mail
<ul>
<li> <a href="mailto:Malcolm.Wallace@cs.york.ac.uk">
Malcolm.Wallace@cs.york.ac.uk</a>
</ul>
<p><b>Copyright:</b> © 2004 Malcolm Wallace,
except for ParseLib (Copyright © 1995 Graham Hutton and Erik Meijer)
<p><b>License:</b> The library modules in cpphs are distributed under
the terms of the LGPL (see file <a href="LICENCE-LGPL">LICENCE-LGPL</a>
for more details). If that's a problem for you, contact me to make
other arrangements. The application module 'Main.hs' itself is GPL
(see file <a href="LICENCE-GPL">LICENCE-GPL</a>).
<p>
This software comes with no warranty. Use at your own risk.
<hr>
</body>
</html>
|
