cpphs

What is cpphs?
How do I use it?
Downloads

What is cpphs?

cpphs is a simplified re-implementation of cpp, the C pre-processor, in Haskell.

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. It has two modes:

conditional compilation only (--nomacro),
and full macro-expansion (default).

In --nomacro mode, cpphs performs only conditional compilation actions, namely #include's, #if's, and #ifdef's are processed according to symbol definitions (both command-line and internal), but no symbol replacement or parameterised macro expansion is performed. In full compatibility mode (the default), symbol replacements and macro expansions are also processed.

Working Features:

#ifdef: simple conditional compilation
#if: the full boolean language of defined(), &&, ||, ==, etc.
#elif: chained conditionals
#define: in-line definitions (symbols only, not macros)
#undef: in-line revocation of definitions
#include: file inclusion
#line: line number directives
\\n: line continuations within all # directives
## /**/: token catenation within a macro definition

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.

Numbering of lines in the output is preserved so that any later processor can give meaningful error messages. When a file is #include'd, cpphs inserts #line directives for the same reason. Numbering should be correct even in the presence of line continuations. If you don't want #line directives in the final output, use the --noline option.

Any syntax errors in cpp directives, and any failure to find a #include'd file, gives a message to standard error and halts the program.

How do I use it?

Usage: cpphs  [ filename | -Dsym | -Dsym=val | -Ipath ]+
              [ --nomacro ] [ --noline ]

You can give any number of filenames on the command-line. The results are catenated on standard output.

Options:

-Dsym: define a symbol
-Dsym=val: define a symbol with a specific value
-Ipath: add a directory to the search path for #include's
--nomacro: only process #ifdef's and #include's, do not expand macros
--noline: remove #line droppings from the output

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).

Downloads

Current version: cpphs-0.2, release date 2004.05.15
By HTTP: .tar.gz, .zip.

Older versions: cpphs-0.1, release date 2004.04.07
By HTTP: .tar.gz, .zip.

To build cpphs, use

    hmake cpphs [-package base]

    ghc --make cpphs

    runhugs cpphs

Contacts

I am interested in hearing your feedback on cpphs. Bug reports 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

Malcolm.Wallace@cs.york.ac.uk

License: The library modules in cpphs are distributed under the terms of the LGPL (see file LICENCE-LGPL for more details). If that's a problem for you, contact me to make other arrangements.

The application module 'cpphs.hs' itself is trivial (since all the functionality is inside the library) and so is placed into the public domain.

This software comes with no warranty. Use at your own risk.