config/preprocessor.txt

   1 Preprocessor
   2 ============
   3
   4 This is a very primitive line based preprocessor, for times when using
   5 a C preprocessor isn't an option.
   6
   7
   8 Instructions
   9 ------------
  10
  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
  13 as comments.
  14
  15 The following preprocessor instructions are recognised.
  16
  17    #define VARIABLE
  18    #define VARIABLE STRING
  19    #undef VARIABLE
  20    #ifdef VARIABLE
  21    #ifndef VARIABLE
  22    #if VARIABLE
  23    #if !VARIABLE
  24    #if VARIABLE==STRING
  25    #if VARIABLE!=STRING
  26    #else
  27    #elifdef VARIABLE
  28    #elifndef VARIABLE
  29    #elif VARIABLE
  30    #elif !VARIABLE
  31    #elif VARIABLE==STRING
  32    #elif VARIABLE!=STRING
  33    #endif
  34    #error STRING
  35    #include FILENAME
  36    #includesubst @VAR@FILENAME
  37    #expand STRING
  38    #literal STRING
  39    #filter FILTER1 FILTER2 ... FILTERn
  40    #unfilter FILTER1 FILTER2 ... FILTERn
  41
  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.
  45
  46 The conditionals (#ifdef, #ifndef, #if, #else, #elifdef, #elifndef,
  47 #elif, #endif) can be nested to arbitrary depth.
  48
  49 The #elifdef, #elifndef, and #elif instructions are equivalent to
  50 #else instructions combined with the relevant conditional.  For
  51 example,
  52
  53    #ifdef foo
  54       block 1
  55    #elifdef bar
  56       block 2
  57    #endif
  58
  59 ...could be written as:
  60
  61    #ifdef foo
  62       block 1
  63    #else
  64    #ifdef bar
  65       block 2
  66    #endif
  67    #endif
  68
  69 An #else block is included if all previous conditions were false, and
  70 is equivalent to #elif 1, i.e.:
  71
  72    #ifdef foo
  73       foo is defined
  74    #else
  75       foo is not defined
  76    #endif
  77
  78 ...is equivalent to:
  79
  80    #ifdef foo
  81       foo is defined
  82    #elif 1
  83       foo is not defined
  84    #endif
  85
  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:
  89
  90    #if 0
  91       never included
  92    #else
  93       always included
  94    #else
  95       never included
  96    #elif 1
  97       never included
  98    #endif
  99
 100 The #error instruction stops execution at this point with a fatal
 101 error. The error message will include the given STRING.
 102
 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
 109 infinite loops.
 110
 111 The #includesubst instruction behaves like #include, except that any
 112 variables in @ATSIGNS@ are expanded, like the substitution filter.
 113
 114 The #expand instruction will print the given STRING with variable
 115 substitutions. See the substitution section below.
 116
 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
 120 as comments.
 121
 122 The #filter instruction enables the specified filters. You can turn
 123 off filters using #unfilter. See the Filters section below.
 124
 125
 126 Variables
 127 ---------
 128
 129 Variables consist of any alphanumeric string. They are defined using
 130 the -D command line argument and the #define instruction.
 131
 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.)
 137
 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
 141 each line.
 142
 143 The variable '1' is predefined with value 1. The variable '0' is not
 144 defined. This allows constructs such as
 145
 146    #if 0
 147    ...
 148    #endif
 149
 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.
 153
 154
 155 Substitution
 156 ------------
 157
 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.
 161
 162 For example to print the current filename:
 163
 164    #expand <!-- This file is automatically generated from __FILE__ -->
 165
 166 Normal lines are not affected.
 167
 168 See also the substitution filter below.
 169
 170
 171 Filters
 172 -------
 173
 174 The following filters are supported:
 175
 176    emptyLines
 177      Strips blank lines from the output.
 178
 179    slashslash
 180      Strips everything from the first two consecutive slash (/)
 181      characters until the end of the line.
 182
 183    spaces
 184      Collapses sequences of spaces into a single space.
 185
 186    substitution
 187      Replaces occurrences of "@foo@" by the value of the variable
 188      "foo". If @foo@ is not defined, the preprocessor will terminate
 189      with a fatal error.
 190
 191    attemptSubstitution
 192      Replaces occurrences of "@foo@" by the value of the variable
 193      "foo". If @foo@ is not defined, the empty string is used instead.
 194
 195 Filters are run in alphabetical order, on a per-line basis.
 196
 197
 198 Command Line Arguments
 199 ----------------------
 200
 201 Syntax:
 202    preprocessor.pl [-Dvariable[=value]] [-E] [-Ffilter]
 203                    [-Ifilename] [-d] [--marker=<c>] [--] filenames...
 204
 205 -Dvariable
 206    Set variable to 1 before processing the files.
 207
 208 -Dvariable=value
 209    Set variable to value before processing the files.
 210
 211 -E
 212    Define all environment variables.
 213
 214 -Ffilter
 215    Enables the specified filter.
 216
 217 -Ifilename
 218    Include filename before any other files.
 219
 220 -d
 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
 225    current directory.
 226
 227 --line-endings=type
 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.
 231
 232 --marker=<c>
 233    Use the character <c> instead of '#' as the marker for preprocessor
 234    instructions.
 235
 236 --
 237    Indicates the end of non-filename arguments.
 238
 239 -
 240    Indicates that input should come from standard input.
 241
 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.
 246
 247
 248 Contact Details
 249 ---------------
 250
 251 Feel free to e-mail me if you have any questions:
 252 Ian Hickson <preprocessor@software.hixie.ch>