mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-08 20:47:44 +00:00
261 lines
7.0 KiB
Plaintext
261 lines
7.0 KiB
Plaintext
Preprocessor
|
|
============
|
|
|
|
This is a very primitive line based preprocessor, for times when using
|
|
a C preprocessor isn't an option.
|
|
|
|
|
|
Instructions
|
|
------------
|
|
|
|
Any line starting with a hash # and a letter is considered to be a
|
|
preprocessor instruction. Other lines starting with a hash are ignored
|
|
as comments.
|
|
|
|
The following preprocessor instructions are recognised.
|
|
|
|
#define VARIABLE
|
|
#define VARIABLE STRING
|
|
#undef VARIABLE
|
|
#ifdef VARIABLE
|
|
#ifndef VARIABLE
|
|
#if VARIABLE
|
|
#if !VARIABLE
|
|
#if VARIABLE==STRING
|
|
#if VARIABLE!=STRING
|
|
#else
|
|
#elifdef VARIABLE
|
|
#elifndef VARIABLE
|
|
#elif VARIABLE
|
|
#elif !VARIABLE
|
|
#elif VARIABLE==STRING
|
|
#elif VARIABLE!=STRING
|
|
#endif
|
|
#error STRING
|
|
#include FILENAME
|
|
#includesubst @VAR@FILENAME
|
|
#expand STRING
|
|
#literal STRING
|
|
#filter FILTER1 FILTER2 ... FILTERn
|
|
#unfilter FILTER1 FILTER2 ... FILTERn
|
|
|
|
Whitespace is significant -- for instance, '#define TEST foo' is not
|
|
the same as '#define TEST foo '. The first defines TEST to be a three
|
|
character string, the second defines it to be four characters long.
|
|
|
|
The conditionals (#ifdef, #ifndef, #if, #else, #elifdef, #elifndef,
|
|
#elif, #endif) can be nested to arbitrary depth.
|
|
|
|
An #else section can be followed by an #else section, as in:
|
|
|
|
#if 1
|
|
used
|
|
#else
|
|
not used
|
|
#else
|
|
used again
|
|
#endif
|
|
|
|
Whether this is wise or not is left up to the reader to decide.
|
|
|
|
The #elifdef, #elifndef, and #elif instructions are equivalent to
|
|
#else instructions combined with the relevant conditional. For
|
|
example,
|
|
|
|
#ifdef foo
|
|
block 1
|
|
#elifdef bar
|
|
block 2
|
|
#endif
|
|
|
|
...could be written as:
|
|
|
|
#ifdef foo
|
|
block 1
|
|
#else
|
|
#ifdef bar
|
|
block 2
|
|
#endif
|
|
#endif
|
|
|
|
#else blocks need not come last, which can lead to some odd
|
|
constructs.
|
|
|
|
#ifdef foo
|
|
included if foo is defined
|
|
#else
|
|
included if foo is not defined
|
|
#elifdef bar
|
|
included if foo is defined and bar is defined
|
|
#else
|
|
included if either foo or bar are not defined
|
|
#endif
|
|
|
|
Note in particular the following holds:
|
|
|
|
#if 1
|
|
always included
|
|
#elif 1
|
|
never included
|
|
#else
|
|
always included
|
|
#endif
|
|
|
|
That is to say, #else is relative to whether the previous conditional
|
|
was included _only_. It isn't an "and" relationship with previous
|
|
conditionals. This is arguably a bug.
|
|
|
|
The #error instruction stops execution at this point with a fatal
|
|
error. The error message will include the given STRING.
|
|
|
|
The #include instruction causes the specified file FILENAME to be
|
|
recursively processed, as if it was inserted at the current position
|
|
in the file. This means conditionals can be started in one file and
|
|
ended in another, although this practice is strongly discouraged.
|
|
There is no predefined limit to the depth of #includes, and there is
|
|
no restriction on self-inclusion, so care should be taken to avoid
|
|
infinite loops.
|
|
|
|
The #includesubst instruction behaves like #include, except that any
|
|
variables in @ATSIGNS@ are expanded, like the substitution filter.
|
|
|
|
The #expand instruction will print the given STRING with variable
|
|
substitutions. See the substitution section below.
|
|
|
|
The #literal instruction will print the given STRING with a newline,
|
|
with absolutely no other fixups, guaranteed. This can be used to
|
|
output lines starting with a #, which would otherwise be stripped out
|
|
as comments.
|
|
|
|
The #filter instruction enables the specified filters. You can turn
|
|
off filters using #unfilter. See the Filters section below.
|
|
|
|
|
|
Variables
|
|
---------
|
|
|
|
Variables consist of any alphanumeric string. They are defined using
|
|
the -D command line argument and the #define instruction.
|
|
|
|
To define all environment variables, so that you can use __HOME__,
|
|
etc, with #expand, use the -E argument. Note that arguments that use
|
|
non-word characters (like "!") are not included. (In particular,
|
|
cygwin is known to include all kinds of weird characters in its
|
|
environment variables.)
|
|
|
|
Two special variables are predefined, FILE and LINE. They can be
|
|
passed to #define and #undef, but FILE is automatically redefined at
|
|
the top of each file, and LINE is increased by one at the start of
|
|
each line.
|
|
|
|
The variable '1' is predefined with value 1. The variable '0' is not
|
|
defined. This allows constructs such as
|
|
|
|
#if 0
|
|
...
|
|
#endif
|
|
|
|
...to be used to quickly comment out large sections. Note, however,
|
|
that these are simply variables, and can be redefined. This is
|
|
strongly discouraged.
|
|
|
|
|
|
Substitution
|
|
------------
|
|
|
|
In any line starting with the instruction #expand, variable names
|
|
contained between double underscores, like __THIS__, are expanded to
|
|
their string values, or the empty string if they are not defined.
|
|
|
|
For example to print the current filename:
|
|
|
|
#expand <!-- This file is automatically generated from __FILE__ -->
|
|
|
|
Normal lines are not affected.
|
|
|
|
See also the substitution filter below.
|
|
|
|
|
|
Filters
|
|
-------
|
|
|
|
The following filters are supported:
|
|
|
|
emptyLines
|
|
Strips blank lines from the output.
|
|
|
|
slashslash
|
|
Strips everything from the first two consecutive slash (/)
|
|
characters until the end of the line.
|
|
|
|
spaces
|
|
Collapses sequences of spaces into a single space.
|
|
|
|
substitution
|
|
Replaces occurrences of "@foo@" by the value of the variable
|
|
"foo". If @foo@ is not defined, the preprocessor will terminate
|
|
with a fatal error.
|
|
|
|
attemptSubstitution
|
|
Replaces occurrences of "@foo@" by the value of the variable
|
|
"foo". If @foo@ is not defined, the empty string is used instead.
|
|
|
|
Filters are run in alphabetical order, on a per-line basis.
|
|
|
|
|
|
Command Line Arguments
|
|
----------------------
|
|
|
|
Syntax:
|
|
preprocessor.pl [-Dvariable[=value]] [-E] [-Ffilter]
|
|
[-Ifilename] [-d] [--marker=<c>] [--] filenames...
|
|
|
|
-Dvariable
|
|
Set variable to 1 before processing the files.
|
|
|
|
-Dvariable=value
|
|
Set variable to value before processing the files.
|
|
|
|
-E
|
|
Define all environment variables.
|
|
|
|
-Ffilter
|
|
Enables the specified filter.
|
|
|
|
-Ifilename
|
|
Include filename before any other files.
|
|
|
|
-d
|
|
Run through the files on the command line, listing the files they
|
|
depend on given the specified environment variables and filters.
|
|
Doesn't recurse into those files. The output is given as one
|
|
dependency per line, and filenames are given relative to the
|
|
current directory.
|
|
|
|
--line-endings=type
|
|
Set the type of line endings to use. "type" can be either "cr",
|
|
"lf", or "crlf". The default is whatever your platform uses for
|
|
perl's "\n" character.
|
|
|
|
--marker=<c>
|
|
Use the character <c> instead of '#' as the marker for preprocessor
|
|
instructions.
|
|
|
|
--
|
|
Indicates the end of non-filename arguments.
|
|
|
|
-
|
|
Indicates that input should come from standard input.
|
|
|
|
If no filenames are provided, standard input is used instead. If many
|
|
files are provided, they are processed sequentially, as if they were
|
|
one big file. -I files are handled before the other files, in the
|
|
order specified, but after handling any -D, -E, -F, and -d arguments.
|
|
|
|
|
|
Contact Details
|
|
---------------
|
|
|
|
Feel free to e-mail me if you have any questions:
|
|
Ian Hickson <preprocessor@software.hixie.ch>
|