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