4
This is a very primitive line based preprocessor, for times when using
5
a C preprocessor isn't an option.
11
Any line starting with a hash # and a letter is considered to be a
12
preprocessor instruction. Other lines starting with a hash are ignored
15
The following preprocessor instructions are recognised.
18
#define VARIABLE STRING
31
#elif VARIABLE==STRING
32
#elif VARIABLE!=STRING
36
#includesubst @VAR@FILENAME
39
#filter FILTER1 FILTER2 ... FILTERn
40
#unfilter FILTER1 FILTER2 ... FILTERn
42
Whitespace is significant -- for instance, '#define TEST foo' is not
43
the same as '#define TEST foo '. The first defines TEST to be a three
44
character string, the second defines it to be four characters long.
46
The conditionals (#ifdef, #ifndef, #if, #else, #elifdef, #elifndef,
47
#elif, #endif) can be nested to arbitrary depth.
49
The #elifdef, #elifndef, and #elif instructions are equivalent to
50
#else instructions combined with the relevant conditional. For
59
...could be written as:
69
An #else block is included if all previous conditions were false, and
70
is equivalent to #elif 1, i.e.:
86
#else is not required to be the last condition in an if/el*/endif
87
series. In particular, along with #else's equivalence to #elif 1
88
this means that the following holds:
100
The #error instruction stops execution at this point with a fatal
101
error. The error message will include the given STRING.
103
The #include instruction causes the specified file FILENAME to be
104
recursively processed, as if it was inserted at the current position
105
in the file. This means conditionals can be started in one file and
106
ended in another, although this practice is strongly discouraged.
107
There is no predefined limit to the depth of #includes, and there is
108
no restriction on self-inclusion, so care should be taken to avoid
111
The #includesubst instruction behaves like #include, except that any
112
variables in @ATSIGNS@ are expanded, like the substitution filter.
114
The #expand instruction will print the given STRING with variable
115
substitutions. See the substitution section below.
117
The #literal instruction will print the given STRING with a newline,
118
with absolutely no other fixups, guaranteed. This can be used to
119
output lines starting with a #, which would otherwise be stripped out
122
The #filter instruction enables the specified filters. You can turn
123
off filters using #unfilter. See the Filters section below.
129
Variables consist of any alphanumeric string. They are defined using
130
the -D command line argument and the #define instruction.
132
To define all environment variables, so that you can use __HOME__,
133
etc, with #expand, use the -E argument. Note that arguments that use
134
non-word characters (like "!") are not included. (In particular,
135
cygwin is known to include all kinds of weird characters in its
136
environment variables.)
138
Two special variables are predefined, FILE and LINE. They can be
139
passed to #define and #undef, but FILE is automatically redefined at
140
the top of each file, and LINE is increased by one at the start of
143
The variable '1' is predefined with value 1. The variable '0' is not
144
defined. This allows constructs such as
150
...to be used to quickly comment out large sections. Note, however,
151
that these are simply variables, and can be redefined. This is
152
strongly discouraged.
158
In any line starting with the instruction #expand, variable names
159
contained between double underscores, like __THIS__, are expanded to
160
their string values, or the empty string if they are not defined.
162
For example to print the current filename:
164
#expand <!-- This file is automatically generated from __FILE__ -->
166
Normal lines are not affected.
168
See also the substitution filter below.
174
The following filters are supported:
177
Strips blank lines from the output.
180
Strips everything from the first two consecutive slash (/)
181
characters until the end of the line.
184
Collapses sequences of spaces into a single space.
187
Replaces occurrences of "@foo@" by the value of the variable
188
"foo". If @foo@ is not defined, the preprocessor will terminate
192
Replaces occurrences of "@foo@" by the value of the variable
193
"foo". If @foo@ is not defined, the empty string is used instead.
195
Filters are run in alphabetical order, on a per-line basis.
198
Command Line Arguments
199
----------------------
202
preprocessor.pl [-Dvariable[=value]] [-E] [-Ffilter]
203
[-Ifilename] [-d] [--marker=<c>] [--] filenames...
206
Set variable to 1 before processing the files.
209
Set variable to value before processing the files.
212
Define all environment variables.
215
Enables the specified filter.
218
Include filename before any other files.
221
Run through the files on the command line, listing the files they
222
depend on given the specified environment variables and filters.
223
Doesn't recurse into those files. The output is given as one
224
dependency per line, and filenames are given relative to the
228
Set the type of line endings to use. "type" can be either "cr",
229
"lf", or "crlf". The default is whatever your platform uses for
230
perl's "\n" character.
233
Use the character <c> instead of '#' as the marker for preprocessor
237
Indicates the end of non-filename arguments.
240
Indicates that input should come from standard input.
242
If no filenames are provided, standard input is used instead. If many
243
files are provided, they are processed sequentially, as if they were
244
one big file. -I files are handled before the other files, in the
245
order specified, but after handling any -D, -E, -F, and -d arguments.
251
Feel free to e-mail me if you have any questions:
252
Ian Hickson <preprocessor@software.hixie.ch>
added
removed
config/preprocessor.txt
