15 Preprocessing directives [cpp]

15.1 Preamble [cpp.pre]

preprocessing-file:
	group $_{o p t}$ 
	module-file

module-file:
	pp-global-module-fragment $_{o p t}$  pp-module group $_{o p t}$  pp-private-module-fragment $_{o p t}$

pp-global-module-fragment:
	module ; new-line group $_{o p t}$

pp-private-module-fragment:
	module : private ; new-line group $_{o p t}$

group:
	group-part
	group group-part

group-part:
	control-line
	if-section
	text-line
	# conditionally-supported-directive

control-line:
	# include pp-tokens new-line
	pp-import
	# define  identifier replacement-list new-line
	# define  identifier lparen identifier-list $_{o p t}$  ) replacement-list new-line
	# define  identifier lparen ... ) replacement-list new-line
	# define  identifier lparen identifier-list , ... ) replacement-list new-line
	# undef   identifier new-line
	# line    pp-tokens new-line
	# error   pp-tokens $_{o p t}$  new-line
	# pragma  pp-tokens $_{o p t}$  new-line
	# new-line

if-section:
	if-group elif-groups $_{o p t}$  else-group $_{o p t}$  endif-line

if-group:
	# if      constant-expression new-line group $_{o p t}$ 
	# ifdef   identifier new-line group $_{o p t}$ 
	# ifndef  identifier new-line group $_{o p t}$

elif-groups:
	elif-group
	elif-groups elif-group

elif-group:
	# elif    constant-expression new-line group $_{o p t}$

else-group:
	# else    new-line group $_{o p t}$

endif-line:
	# endif   new-line

text-line:
	pp-tokens $_{o p t}$  new-line

conditionally-supported-directive:
	pp-tokens new-line

lparen:
	a ( character not immediately preceded by white-space

identifier-list:
	identifier
	identifier-list , identifier

replacement-list:
	pp-tokens $_{o p t}$

pp-tokens:
	preprocessing-token
	pp-tokens preprocessing-token

new-line:
	the new-line character

A preprocessing directive consists of a sequence of preprocessing tokens that satisfies the following constraints: At the start of translation phase 4, the first token in the sequence, referred to as a directive-introducing token, begins with the first character in the source file (optionally after white space containing no new-line characters) or follows white space containing at least one new-line character, and is

(1.1)
a # preprocessing token, or
(1.2)
an import preprocessing token immediately followed on the same logical line by a header-name, <, identifier, string-literal, or : preprocessing token, or
(1.3)
a module preprocessing token immediately followed on the same logical line by an identifier, :, or ; preprocessing token, or
(1.4)
an export preprocessing token immediately followed on the same logical line by one of the two preceding forms.

The last token in the sequence is the first token within the sequence that is immediately followed by whitespace containing a new-line character.141

[ Note

A new-line character ends the preprocessing directive even if it occurs within what would otherwise be an invocation of a function-like macro.

— end note

]

[ Example

#                       // preprocessing directive
module ;                // preprocessing directive
export module leftpad;  // preprocessing directive
import <string>;        // preprocessing directive
export import "squee";  // preprocessing directive
import rightpad;        // preprocessing directive
import :part;           // preprocessing directive

module                  // not a preprocessing directive
;                       // not a preprocessing directive

export                  // not a preprocessing directive
import                  // not a preprocessing directive
foo;                    // not a preprocessing directive

export                  // not a preprocessing directive
import foo;             // preprocessing directive (ill-formed at phase 7)

import ::               // not a preprocessing directive
import ->               // not a preprocessing directive

— end example

]

A sequence of preprocessing tokens is only a text-line if it does not begin with a directive-introducing token.

A sequence of preprocessing tokens is only a conditionally-supported-directive if it does not begin with any of the directive names appearing after a # in the syntax.

A conditionally-supported-directive is conditionally-supported with implementation-defined semantics.

At the start of phase 4 of translation, the group of a pp-global-module-fragment shall contain neither a text-line nor a pp-import .

When in a group that is skipped ([cpp.cond]), the directive syntax is relaxed to allow any sequence of preprocessing tokens to occur between the directive name and the following new-line character.

The only white-space characters that shall appear between preprocessing tokens within a preprocessing directive (from just after the directive-introducing token through just before the terminating new-line character) are space and horizontal-tab (including spaces that have replaced comments or possibly other white-space characters in translation phase 3).

The implementation can process and skip sections of source files conditionally, include other source files, import macros from header units, and replace macros.

These capabilities are called preprocessing, because conceptually they occur before translation of the resulting translation unit.

The preprocessing tokens within a preprocessing directive are not subject to macro expansion unless otherwise stated.

[ Example

In:

#define EMPTY
EMPTY   #   include <file.h>

the sequence of preprocessing tokens on the second line is not a preprocessing directive, because it does not begin with a # at the start of translation phase 4, even though it will do so after the macro EMPTY has been replaced.

— end example

]

141)

Thus, preprocessing directives are commonly called “lines”.

These “lines” have no other syntactic significance, as all white space is equivalent except in certain situations during preprocessing (see the # character string literal creation operator in [cpp.stringize], for example).

⮥