cpp: The preprocessing language
1
1 1.4 The preprocessing language
1 ==============================
1
1 After tokenization, the stream of tokens may simply be passed straight
1 to the compiler's parser. However, if it contains any operations in the
1 "preprocessing language", it will be transformed first. This stage
1 corresponds roughly to the standard's "translation phase 4" and is what
1 most people think of as the preprocessor's job.
1
1 The preprocessing language consists of "directives" to be executed
1 and "macros" to be expanded. Its primary capabilities are:
1
1 * Inclusion of header files. These are files of declarations that
1 can be substituted into your program.
1
1 * Macro expansion. You can define "macros", which are abbreviations
1 for arbitrary fragments of C code. The preprocessor will replace
1 the macros with their definitions throughout the program. Some
1 macros are automatically defined for you.
1
1 * Conditional compilation. You can include or exclude parts of the
1 program according to various conditions.
1
1 * Line control. If you use a program to combine or rearrange source
1 files into an intermediate file which is then compiled, you can use
1 line control to inform the compiler where each source line
1 originally came from.
1
1 * Diagnostics. You can detect problems at compile time and issue
1 errors or warnings.
1
1 There are a few more, less useful, features.
1
1 Except for expansion of predefined macros, all these operations are
1 triggered with "preprocessing directives". Preprocessing directives are
1 lines in your program that start with '#'. Whitespace is allowed before
1 and after the '#'. The '#' is followed by an identifier, the "directive
1 name". It specifies the operation to perform. Directives are commonly
1 referred to as '#NAME' where NAME is the directive name. For example,
1 '#define' is the directive that defines a macro.
1
1 The '#' which begins a directive cannot come from a macro expansion.
1 Also, the directive name is not macro expanded. Thus, if 'foo' is
1 defined as a macro expanding to 'define', that does not make '#foo' a
1 valid preprocessing directive.
1
1 The set of valid directive names is fixed. Programs cannot define
1 new preprocessing directives.
1
1 Some directives require arguments; these make up the rest of the
1 directive line and must be separated from the directive name by
1 whitespace. For example, '#define' must be followed by a macro name and
1 the intended expansion of the macro.
1
1 A preprocessing directive cannot cover more than one line. The line
1 may, however, be continued with backslash-newline, or by a block comment
1 which extends past the end of the line. In either case, when the
1 directive is processed, the continuations have already been merged with
1 the first line to make one long line.
1