Man Linux: Main Page and Category List

NAME

       cpphs - liberalised cpp-a-like preprocessor for Haskell

SYNOPSIS

       cpphs [FILENAME|OPTION]...

DESCRIPTION

       cpphs  is  a  liberalised  re-implementation  of  cpp  (1),  the C pre-
       processor, in and for 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.

       cpphs  is  pretty-much  feature-complete,  and  compatible   with   the
       -traditional style of cpp.  It has two modes:

              conditional compilation only (--nomacro),

              and full macro-expansion (default).

       In --nomacro mode, cpphs performs only conditional compilation actions,
       i.e.  #include’s, #if’s, and #ifdef’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.

       Working Features:

       #ifdef simple conditional compilation

       #if    the full boolean language of defined(), &&, ||, ==, etc.

       #elif  chained conditionals

       #define
              in-line definitions (text replacements and 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

       ##     ANSI-style token catenation

       #      ANSI-style token stringisation

       __FILE__
              special text replacement for DIY error messages

       __LINE__
              special text replacement for DIY error messages

       __DATE__
              special text replacement

       __TIME__
              special text replacement

       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.

       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 gives a message to stderr and halts
       the  program.   Failure to find a #include’d file produces a warning to
       stderr, but processing continues.

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

       -Dsym  define a textual replacement (default value is 1)

       -Dsym=val
              define a textual replacement with a specific value

       -Ipath add a directory to the search path for #include’s

       -Ofile specify a file for output (default is stdout)

       --nomacro
              only process #ifdef’s and #include’s,
                                    do not expand macros

       --noline
              remove #line droppings from the output

       --strip
              convert C-style comments to whitespace, even outside
                                    cpp directives

       --hashes
              recognise the ANSI # stringise operator, and ## for
                                    token catenation, within macros

       --text treat the input as plain text, not Haskell code

       --layout
              preserve newlines within macro expansions

       --unlit
              remove literate-style comments

       --version
              report version number of cpphs and stop

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

DIFFERENCES FROM CPP

       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  of
       a line (whereas 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: /* */ */* However, you can
       turn on C-comment removal with the --strip option.

       Macro language

       Accepts  /**/  for token-pasting in a macro definition.  However, /* */
       (with any text between the open/close comment) inserts whitespace.

       The ANSI ## token-pasting operator is available with the --hashes flag.
       This is to avoid misinterpreting any valid Haskell operator of the same
       name.

       Replaces a macro formal parameter with the actual, even inside a string
       (double  or  single  quoted).   This  is  -traditional  behaviour,  not
       supported in ANSI.

       Recognises the # stringisation operator in a macro definition  only  if
       you  use  the  --hashes  option.   (It is an ANSI addition, only needed
       because quoted stringisation (above) is prohibited by ANSI.)

       Preserves whitespace within a textual  replacement  definition  exactly
       (modulo newlines), but leading and trailing space is eliminated.

       Preserves  whitespace  within  a  macro  definition  (and  trailing it)
       exactly (modulo newlines), but leading space is eliminated.

       Preserves whitespace within macro  call  arguments  exactly  (including
       newlines), but leading and trailing space is eliminated.

       With  the  --layout 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.)

BUGS

       Bug  reports, and any other feedback, should be sent to Malcolm Wallace
       <Malcolm.Wallace@cs.york.ac.uk>

COPYRIGHT

       Copyright © 2004-2005 Malcolm Wallace, except for ParseLib (Copyright ©
       1995 Graham Hutton and Erik Meijer).

       The  library  modules  in  cpphs are distributed under the terms of the
       LGPL.  If  that’s  a  problem  for  you,  contact  me  to  make   other
       arrangements. The application module Main.hs itself is GPL.

SEE ALSO

       cpp(1)

AUTHOR

       This  manual  page  was  written,  based  on  index.html, by Ian Lynagh
       <igloo@debian.org> for the Debian system (but may be used by others).