1CPPHS(1) User Manual CPPHS(1)
2
6 cpphs - liberalised cpp-a-like preprocessor for Haskell
7
10 cpphs [FILENAME|OPTION]...
11
14 cpphs is a liberalised re-implementation of cpp (1), the C pre-proces‐
15 sor, in and for Haskell.
16 Why re-implement cpp? Rightly or wrongly, the C pre-processor is
18 widely used in Haskell source code. It enables conditional compilation
19 for different compilers, different versions of the same compiler, and
20 different OS platforms. It is also occasionally used for its macro
21 language, which can enable certain forms of platform-specific detail-
22 filling, such as the tedious boilerplate generation of instance defini‐
23 tions and FFI declarations. However, there are two problems with cpp,
24 aside from the obvious aesthetic ones:
25 For some Haskell systems, notably Hugs on Windows, a true cpp is
27 not available by default.
28 Even for the other Haskell systems, the common cpp provided by
30 the gcc 3.x series is changing subtly in ways that are incompat‐
31 ible with Haskell's syntax. There have always been problems
32 with, for instance, string gaps, and prime characters in identi‐
33 fiers. These problems are only going to get worse.
34 So, it seemed right to attempt to provide an alternative to cpp, both
36 more compatible with Haskell, and itself written in Haskell so that it
37 can be distributed with compilers.
38 cpphs is pretty-much feature-complete, and compatible with the -tradi‐
40 tional style of cpp. It has two modes:
41 conditional compilation only (--nomacro),
43 and full macro-expansion (default).
45 In --nomacro mode, cpphs performs only conditional compilation actions,
47 i.e. #include's, #if's, and #ifdef's are processed according to text-
48 replacement definitions (both command-line and internal), but no param‐
49 eterised macro expansion is performed. In full compatibility mode (the
50 default), textual replacements and macro expansions are also processed
51 in the remaining body of non-cpp text.
52 Working Features:
54 #ifdef simple conditional compilation
56 #if the full boolean language of defined(), &&, ||, ==, etc.
58 #elif chained conditionals
60 #define
62 in-line definitions (text replacements and macros)
63 #undef in-line revocation of definitions
65 #include
67 file inclusion
68 #line line number directives
70 \n line continuations within all # directives
72 /**/ token catenation within a macro definition
74 ## ANSI-style token catenation
76 # ANSI-style token stringisation
78 __FILE__
80 special text replacement for DIY error messages
81 __LINE__
83 special text replacement for DIY error messages
84 __DATE__
86 special text replacement
87 __TIME__
89 special text replacement
90 Macro expansion is recursive. Redefinition of a macro name does not
92 generate a warning. Macros can be defined on the command-line with -D
93 just like textual replacements. Macro names are permitted to be
94 Haskell identifiers e.g. with the prime ` and backtick ´ characters,
95 which is slightly looser than in C, but they still may not include
96 operator symbols.
97 Numbering of lines in the output is preserved so that any later proces‐
99 sor can give meaningful error messages. When a file is #include'd,
100 cpphs inserts #line directives for the same reason. Numbering should be
101 correct even in the presence of line continuations. If you don't want
102 #line directives in the final output, use the --noline option.
103 Any syntax errors in cpp directives gives a message to stderr and halts
105 the program. Failure to find a #include'd file produces a warning to
106 stderr, but processing continues.
107 You can give any number of filenames on the command-line. The results
109 are catenated on standard output.
110 -Dsym define a textual replacement (default value is 1)
112 -Dsym=val
114 define a textual replacement with a specific value
115 -Ipath add a directory to the search path for #include's
117 -Ofile specify a file for output (default is stdout)
119 --nomacro
121 only process #ifdef's and #include's,
122 do not expand macros
123 --noline
125 remove #line droppings from the output
126 --strip
128 convert C-style comments to whitespace, even outside
129 cpp directives
130 --hashes
132 recognise the ANSI # stringise operator, and ## for
133 token catenation, within macros
134 --text treat the input as plain text, not Haskell code
136 --layout
138 preserve newlines within macro expansions
139 --unlit
141 remove literate-style comments
142 --version
144 report version number of cpphs and stop
145 There are NO textual replacements defined by default. (Normal cpp usu‐
147 ally has definitions for machine, OS, etc. These could easily be added
148 to the cpphs source code if you wish.) The search path is searched in
149 order of the -I options, except that the directory of the calling file,
150 then the current directory, are always searched first. Again, there is
151 no default search path (and again, this could easily be changed).
152
155 In general, cpphs is based on the -traditional behaviour, not ANSI C,
156 and has the following main differences from the standard cpp.
157 General
159 The # that introduces any cpp directive must be in the first column of
161 a line (whereas ANSI permits whitespace before the # ).
162 Generates the #line n "filename" syntax, not the # n "filename" vari‐
164 ant.
165 C comments are only removed from within cpp directives. They are not
167 stripped from other text. Consider for instance that in Haskell, all
168 of the following are valid operator symbols: /* */ */* However, you can
169 turn on C-comment removal with the --strip option.
170 Macro language
172 Accepts /**/ for token-pasting in a macro definition. However, /* */
174 (with any text between the open/close comment) inserts whitespace.
175 The ANSI ## token-pasting operator is available with the --hashes flag.
177 This is to avoid misinterpreting any valid Haskell operator of the same
178 name.
179 Replaces a macro formal parameter with the actual, even inside a string
181 (double or single quoted). This is -traditional behaviour, not sup‐
182 ported in ANSI.
183 Recognises the # stringisation operator in a macro definition only if
185 you use the --hashes option. (It is an ANSI addition, only needed
186 because quoted stringisation (above) is prohibited by ANSI.)
187 Preserves whitespace within a textual replacement definition exactly
189 (modulo newlines), but leading and trailing space is eliminated.
190 Preserves whitespace within a macro definition (and trailing it)
192 exactly (modulo newlines), but leading space is eliminated.
193 Preserves whitespace within macro call arguments exactly (including
195 newlines), but leading and trailing space is eliminated.
196 With the --layout option, line continuations in a textual replacement
198 or macro definition are preserved as line-breaks in the macro call.
199 (Useful for layout-sensitive code in Haskell.)
200
203 Bug reports, and any other feedback, should be sent to Malcolm Wallace
204 <Malcolm.Wallace@cs.york.ac.uk>
205
207 Copyright © 2004-2005 Malcolm Wallace, except for ParseLib (Copyright ©
208 1995 Graham Hutton and Erik Meijer).
209 The library modules in cpphs are distributed under the terms of the
211 LGPL. If that's a problem for you, contact me to make other arrange‐
212 ments. The application module Main.hs itself is GPL.
213
215 cpp(1)
216
219 This manual page was written, based on index.html, by Ian Lynagh
220 <igloo@debian.org> for the Debian system (but may be used by others).
221cpphs version 0.9 2004-10-01 CPPHS(1)