[[cpphs @ 2004-05-17 18:02:02 by malcolm]
malcolm**20040517180202
Add a rationale for cpphs, and document some differences between cpphs
and the original cpp.
] {
hunk ./docs/index.html 18
-Recent news
+Differences to cpp
hunk ./docs/index.html 26
-cpphs is a simplified implementation of cpp,
+cpphs is a simplified re-implementation of cpp,
hunk ./docs/index.html 30
-This cut-down version of the C pre-processor is pretty-much complete.
+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:
+
+ - For some Haskell systems, notably Hugs on Windows, a true cpp
+ is not available by default.
+
- 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.
+
+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.
+
+
+This version of the C pre-processor is pretty-much feature-complete.
hunk ./docs/index.html 72
-
#define in-line definitions (symbols only, not macros)
+#define in-line definitions (symbols and macros)
hunk ./docs/index.html 77
+## /**/ token catenation within a macro definition
hunk ./docs/index.html 81
+Macro expansion is recursive. Redefinition of a macro or symbol does
+not generate a warning. Macros can be defined on the command-line
+with -D just like symbols. Macro/symbol names are permitted to be
+Haskell identifiers e.g. with the ' character, which is slightly
+looser than in C, but they still may not include operators.
+
+
hunk ./docs/index.html 125
-There are NO symbols defined by default. Could easily be changed in
-the source code though. The search path is searched in order of the -I
-options, except that the current directory is always searched first.
-Again, there is no default search path (and again, could easily
-be changed).
+There are NO symbols defined by default. (This could easily be
+changed in the source code though.) The search path is searched in
+order of the -I options, except that the current directory is always
+searched first. Again, there is no default search path (and again,
+could easily be changed).
hunk ./docs/index.html 133
-
+
hunk ./docs/index.html 136
-cpphs-0.2, release date 2004.05.14
+
+cpphs-0.3, release date 2004.05.xx
hunk ./docs/index.html 139
+.tar.gz,
+.zip.
+
+Fix recursive macro expansion bug.
+
+
+Older versions:
+
+cpphs-0.2, release date 2004.05.15
+By HTTP:
hunk ./docs/index.html 152
-Older versions:
+Implements textual replacement and macro expansion.
+
hunk ./docs/index.html 158
+
+Initial release: implements conditional compilation and file inclusion only.
hunk ./docs/index.html 164
-
- hmake cpphs [-package base]
+ hmake cpphs [-package base]
hunk ./docs/index.html 167
-
- ghc --make cpphs
+ ghc --make cpphs
hunk ./docs/index.html 170
-
- runhugs cpphs
+ runhugs cpphs
hunk ./docs/index.html 175
+
+
+In general, cpphs is based on the -traditional behaviour, not
+ANSI C, and has the following main differences from the standard cpp.
+
+
+General
+
+- The # that introduces any cpp directive must be in the first column.
+ (ANSI permits whitespace before the #.)
+
- Generates the #line n "filename" syntax, not the # n
+ "filename" variant.
+
- 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: /*
+ */ */*
+
+
+Macro language
+
+- Accepts both ## and /**/ for token-pasting in
+ a macro definition. (Cpp accepts the former only in ANSI mode,
+ the latter only in -traditional mode.) However, /* */
+ (with any text between the open/close comment) inserts whitespace.
+
- Replaces a macro formal parameter with the actual, even inside a
+ string (double or single quoted). This is -traditional behaviour,
+ not supported in ANSI.
+
- Does not understand the # stringisation operator in a macro definition.
+ (It is an ANSI addition, only needed because quoted stringisation
+ (above) is prohibited.)
+
- Preserves whitespace within a textual replacement definition exactly, but
+ leading and trailing space is eliminated.
+
- Preserves whitespace within a macro definition (and trailing it) exactly,
+ but leading space is eliminated.
+
- Preserves whitespace within a macro call exactly, but
+ leading and trailing space is eliminated.
+
- Line continuations in a macro definition are preserved as
+ line-breaks in the macro call. (Useful for layout-sensitive
+ code in Haskell.)
+
- In a macro definition, whitespace is permitted between any of the
+ initial name/argument/bracket/comma tokens. (In cpp, there can be
+ no space between the name and the opening bracket.)
+
+
+
hunk ./docs/index.html 223
-especially welcome, since it is so new. You can send Feature requests
-too, but I won't guarantee to attend to them, especially if they
-depart from ordinary cpp's behaviour. Please mail
+especially welcome, since it is so new. 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
}