1CPPHS(1)                          User Manual                         CPPHS(1)
2
3
4

NAME

6       cpphs - liberalised cpp-a-like preprocessor for Haskell
7
8

SYNOPSIS

10       cpphs [FILENAME|OPTION]...
11
12

DESCRIPTION

14       cpphs  is a liberalised re-implementation of cpp (1), the C pre-proces‐
15       sor, in and for Haskell.
16
17       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
26              For some Haskell systems, notably Hugs on Windows, a true cpp is
27              not available by default.
28
29              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
35       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
39       cpphs is pretty-much feature-complete, and compatible with the  -tradi‐
40       tional style of cpp.  It has two modes:
41
42              conditional compilation only (--nomacro),
43
44              and full macro-expansion (default).
45
46       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
53       Working Features:
54
55       #ifdef simple conditional compilation
56
57       #if    the full boolean language of defined(), &&, ||, ==, etc.
58
59       #elif  chained conditionals
60
61       #define
62              in-line definitions (text replacements and macros)
63
64       #undef in-line revocation of definitions
65
66       #include
67              file inclusion
68
69       #line  line number directives
70
71       \n     line continuations within all # directives
72
73       /**/   token catenation within a macro definition
74
75       ##     ANSI-style token catenation
76
77       #      ANSI-style token stringisation
78
79       __FILE__
80              special text replacement for DIY error messages
81
82       __LINE__
83              special text replacement for DIY error messages
84
85       __DATE__
86              special text replacement
87
88       __TIME__
89              special text replacement
90
91       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
98       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
104       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
108       You  can give any number of filenames on the command-line.  The results
109       are catenated on standard output.
110
111       -Dsym  define a textual replacement (default value is 1)
112
113       -Dsym=val
114              define a textual replacement with a specific value
115
116       -Ipath add a directory to the search path for #include's
117
118       -Ofile specify a file for output (default is stdout)
119
120       --nomacro
121              only process #ifdef's and #include's,
122                                    do not expand macros
123
124       --noline
125              remove #line droppings from the output
126
127       --strip
128              convert C-style comments to whitespace, even outside
129                                    cpp directives
130
131       --hashes
132              recognise the ANSI # stringise operator, and ## for
133                                    token catenation, within macros
134
135       --text treat the input as plain text, not Haskell code
136
137       --layout
138              preserve newlines within macro expansions
139
140       --unlit
141              remove literate-style comments
142
143       --version
144              report version number of cpphs and stop
145
146       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
153

DIFFERENCES FROM CPP

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
158       General
159
160       The # that introduces any cpp directive must be in the first column  of
161       a line (whereas ANSI permits whitespace before the # ).
162
163       Generates  the  #line n "filename" syntax, not the # n "filename" vari‐
164       ant.
165
166       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
171       Macro language
172
173       Accepts  /**/  for token-pasting in a macro definition.  However, /* */
174       (with any text between the open/close comment) inserts whitespace.
175
176       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
180       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
184       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
188       Preserves whitespace within a textual  replacement  definition  exactly
189       (modulo newlines), but leading and trailing space is eliminated.
190
191       Preserves  whitespace  within  a  macro  definition  (and  trailing it)
192       exactly (modulo newlines), but leading space is eliminated.
193
194       Preserves whitespace within macro  call  arguments  exactly  (including
195       newlines), but leading and trailing space is eliminated.
196
197       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
201

BUGS

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
210       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

SEE ALSO

215       cpp(1)
216
217

AUTHOR

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).
221
222
223
224
225
226cpphs version 0.9                 2004-10-01                          CPPHS(1)
Impressum