.TH PREPROCESS 1 \" -*- nroff -*-
.SH NAME
preprocess \- Preprocess a file.
.SH SYNOPSIS
\fBpreprocess\fR [\fIoptions\fR...] \fIinfile\fR
.SH DESCRIPTION
Preprocess is like a typical C preprocessor, but it extends to multiple
languages. Languages for which it works include: C++, Python, Perl,
Tcl, XML, JavaScript, CSS, IDL, TeX, Fortran, PHP, Java, Shell scripts
(Bash, CSH, etc.) and C#. Preprocess is usable both as a command line
app and as a Python module.
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
Print help text and exit.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print the version info and exit.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Give verbose output for errors.
.TP
\fB\-o\fR \fIoutfile\fR
Write output to the given file instead of to stdout.
.TP
\fB\-f\fR, \fB\-\-force\fR
Overwrite given output file. Otherwise an IOError will be raised if
\fIoutfile\fR already exists.
.TP
\fB\-D\fR \fIdefine\fR
Define a variable for preprocessing. \fIdefine\fR can simply be a
variable name (in which case it will be true) or it can be of the form
\fIvar\fR=\fIval\fR. An attempt will be made to convert \fIval\fR to an
integer so "\fB\-D FOO=0\fR" will create a false value.
.TP
\fB\-I\fR \fIdir\fR
Add a directory to the include path for #include directives.
.TP
\fB\-k\fR, \fB\-\-keep-lines\fR
Emit empty lines for preprocessor statement lines and skipped output
lines. This allows line numbers to stay constant.
.TP
\fB\-s\fR, \fB\-\-substitute\fR
Substitute defines into emitted lines. By default substitution is NOT
done because it currently will substitute into program strings.
.SH MODULE USAGE
.LP
.IP
 from preprocess import preprocess
 preprocess(infile, outfile=sys.stdout, defines={}, force=0,
            keepLines=0, includePath=[], substitute=0)
.LP
The <infile> can be marked up with special preprocessor statement lines
of the form:
.IP
 <comment-prefix> <preprocessor-statement> <comment-suffix>
.LP
where the <comment-prefix/suffix> are the native comment delimiters for
that file type.
.SH EXAMPLES
.LP
HTML (*.htm, *.html) or XML (*.xml, *.kpf, *.xul) files:
.IP
 <!-- #if FOO -->
 ...
 <!-- #endif -->
.LP
Python (*.py), Perl (*.pl), Tcl (*.tcl), Ruby (*.rb), Bash (*.sh), or
make ([Mm]akefile*) files:
.IP
 # #if defined('FAV_COLOR') and FAV_COLOR == "blue"
 ...
 # #elif FAV_COLOR == "red"
 ...
 # #else
 ...
 # #endif
.LP
C (*.c, *.h), C++ (*.cpp, *.cxx, *.cc, *.h, *.hpp, *.hxx, *.hh), Java
(*.java), PHP (*.php) or C# (*.cs) files:
.IP
 // #define FAV_COLOR 'blue'
 ...
 /* #ifndef FAV_COLOR */
 ...
 // #endif
.LP
Fortran 77 (*.f) or 90/95 (*.f90) files:
.IP
 C     #if COEFF == 'var'
       ...
 C     #endif
.SH PREPROCESSOR SYNTAX
.LP
Valid statements:
.IP
 #define <var> [<value>]
 #undef <var>
 #ifdef <var>
 #ifndef <var>
 #if <expr>
 #elif <expr>
 #else
 #endif
 #error <error string>
 #include "<file>"
.LP
where <expr> is any valid Python expression.
.LP
The expression after #if/elif may be a Python statement. It is an error
to refer to a variable that has not been defined by a \fB\-D\fR option
or by an in-content #define.
.LP
Special built-in methods for expressions:
.IP
 defined(varName)    Return true if given variable is defined.
.SH TIPS
.LP
A suggested file naming convention is to let input files to preprocess
be of the form <basename>.p.<ext> and direct the output of preprocess to
<basename>.<ext>, e.g.:
.IP
 \fBpreprocess\fR \-o foo.py foo.p.py
.LP
The advantage is that other tools (esp. editors) will still recognize
the unpreprocessed file as the original language.

.SH AUTHORS
Trent Mick <trentm@gmail.com>

This manual page was written by Johannes Ring <johannr@simula.no> for
the Debian GNU/Linux system (but may be used by others).