← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/config/preprocessor.txt

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

Lines of Context:
mozilla/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
An #else section can be followed by an #else section, as in:
 
50
 
 
51
   #if 1
 
52
      used
 
53
   #else
 
54
      not used
 
55
   #else
 
56
      used again
 
57
   #endif
 
58
 
 
59
Whether this is wise or not is left up to the reader to decide.
 
60
 
 
61
The #elifdef, #elifndef, and #elif instructions are equivalent to
 
62
#else instructions combined with the relevant conditional. For
 
63
example,
 
64
 
 
65
   #ifdef foo
 
66
      block 1
 
67
   #elifdef bar
 
68
      block 2
 
69
   #endif
 
70
 
 
71
...could be written as:
 
72
 
 
73
   #ifdef foo
 
74
      block 1
 
75
   #else
 
76
   #ifdef bar
 
77
      block 2
 
78
   #endif
 
79
   #endif
 
80
 
 
81
#else blocks need not come last, which can lead to some odd
 
82
constructs.
 
83
 
 
84
   #ifdef foo
 
85
      included if foo is defined
 
86
   #else
 
87
      included if foo is not defined
 
88
   #elifdef bar
 
89
      included if foo is defined and bar is defined
 
90
   #else
 
91
      included if either foo or bar are not defined
 
92
   #endif
 
93
 
 
94
Note in particular the following holds:
 
95
 
 
96
   #if 1
 
97
      always included
 
98
   #elif 1
 
99
      never included
 
100
   #else
 
101
      always included
 
102
   #endif
 
103
 
 
104
That is to say, #else is relative to whether the previous conditional
 
105
was included _only_. It isn't an "and" relationship with previous
 
106
conditionals. This is arguably a bug.
 
107
 
 
108
The #error instruction stops execution at this point with a fatal
 
109
error. The error message will include the given STRING.
 
110
 
 
111
The #include instruction causes the specified file FILENAME to be
 
112
recursively processed, as if it was inserted at the current position
 
113
in the file. This means conditionals can be started in one file and
 
114
ended in another, although this practice is strongly discouraged.
 
115
There is no predefined limit to the depth of #includes, and there is
 
116
no restriction on self-inclusion, so care should be taken to avoid
 
117
infinite loops.
 
118
 
 
119
The #includesubst instruction behaves like #include, except that any
 
120
variables in @ATSIGNS@ are expanded, like the substitution filter.
 
121
 
 
122
The #expand instruction will print the given STRING with variable
 
123
substitutions. See the substitution section below.
 
124
 
 
125
The #literal instruction will print the given STRING with a newline,
 
126
with absolutely no other fixups, guaranteed. This can be used to
 
127
output lines starting with a #, which would otherwise be stripped out
 
128
as comments.
 
129
 
 
130
The #filter instruction enables the specified filters. You can turn
 
131
off filters using #unfilter. See the Filters section below.
 
132
 
 
133
 
 
134
Variables
 
135
---------
 
136
 
 
137
Variables consist of any alphanumeric string. They are defined using
 
138
the -D command line argument and the #define instruction.
 
139
 
 
140
To define all environment variables, so that you can use __HOME__,
 
141
etc, with #expand, use the -E argument. Note that arguments that use
 
142
non-word characters (like "!") are not included. (In particular,
 
143
cygwin is known to include all kinds of weird characters in its
 
144
environment variables.)
 
145
 
 
146
Two special variables are predefined, FILE and LINE. They can be
 
147
passed to #define and #undef, but FILE is automatically redefined at
 
148
the top of each file, and LINE is increased by one at the start of
 
149
each line.
 
150
 
 
151
The variable '1' is predefined with value 1. The variable '0' is not
 
152
defined. This allows constructs such as
 
153
 
 
154
   #if 0
 
155
   ...
 
156
   #endif
 
157
 
 
158
...to be used to quickly comment out large sections. Note, however,
 
159
that these are simply variables, and can be redefined. This is
 
160
strongly discouraged.
 
161
 
 
162
 
 
163
Substitution
 
164
------------
 
165
 
 
166
In any line starting with the instruction #expand, variable names
 
167
contained between double underscores, like __THIS__, are expanded to
 
168
their string values, or the empty string if they are not defined.
 
169
 
 
170
For example to print the current filename:
 
171
 
 
172
   #expand <!-- This file is automatically generated from __FILE__ -->
 
173
 
 
174
Normal lines are not affected.
 
175
 
 
176
See also the substitution filter below.
 
177
 
 
178
 
 
179
Filters
 
180
-------
 
181
 
 
182
The following filters are supported:
 
183
 
 
184
   emptyLines
 
185
     Strips blank lines from the output.
 
186
 
 
187
   slashslash
 
188
     Strips everything from the first two consecutive slash (/)
 
189
     characters until the end of the line.
 
190
 
 
191
   spaces
 
192
     Collapses sequences of spaces into a single space.
 
193
 
 
194
   substitution
 
195
     Replaces occurances of "@foo@" by the value of the variable
 
196
     "foo". If @foo@ is not defined, the preprocessor will terminate
 
197
     with a fatal error.
 
198
 
 
199
   attemptSubstitution
 
200
     Replaces occurances of "@foo@" by the value of the variable
 
201
     "foo". If @foo@ is not defined, the empty string is used instead.
 
202
 
 
203
Filters are run in alphabetical order, on a per-line basis.
 
204
 
 
205
 
 
206
Command Line Arguments
 
207
----------------------
 
208
 
 
209
Syntax:
 
210
   preprocessor.pl [-Dvariable[=value]] [-E] [-Ffilter]
 
211
                   [-Ifilename] [-d] [--] filenames...
 
212
 
 
213
-Dvariable
 
214
   Set variable to 1 before processing the files.
 
215
 
 
216
-Dvariable=value
 
217
   Set variable to value before processing the files.
 
218
 
 
219
-E
 
220
   Define all environment variables.
 
221
 
 
222
-Ffilter
 
223
   Enables the specified filter.
 
224
 
 
225
-Ifilename
 
226
   Include filename before any other files.
 
227
 
 
228
-d
 
229
   Run through the files on the command line, listing the files they
 
230
   depend on given the specified environment variables and filters.
 
231
   Doesn't recurse into those files. The output is given as one
 
232
   dependency per line, and filenames are given relative to the
 
233
   current directory.
 
234
 
 
235
--line-endings=type
 
236
   Set the type of line endings to use. "type" can be either "cr",
 
237
   "lf", or "crlf". The default is whatever your platform uses for
 
238
   perl's "\n" character.
 
239
 
 
240
--
 
241
   Indicates the end of non-filename arguments.
 
242
 
 
243
-
 
244
   Indicates that input should come from standard input.
 
245
 
 
246
If no filenames are provided, standard input is used instead. If many
 
247
files are provided, they are processed sequentially, as if they were
 
248
one big file. -I files are handled before the other files, in the
 
249
order specified, but after handling any -D, -E, -F, and -d arguments.
 
250
 
 
251
 
 
252
Contact Details
 
253
---------------
 
254
 
 
255
Feel free to e-mail me if you have any questions:
 
256
Ian Hickson <preprocessor@software.hixie.ch>