178 lines
8.8 KiB
Markdown
178 lines
8.8 KiB
Markdown
[cpp.import]
|
||
|
||
# 15 Preprocessing directives [[cpp]](./#cpp)
|
||
|
||
## 15.6 Header unit importation [cpp.import]
|
||
|
||
[pp-import:](#nt:pp-import "15.6 Header unit importation [cpp.import]")
|
||
exportopt import [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]") [*pp-tokens*](cpp.pre#nt:pp-tokens "15.1 Preamble [cpp.pre]")opt ; [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]")
|
||
exportopt import [*header-name-tokens*](cpp.cond#nt:header-name-tokens "15.2 Conditional inclusion [cpp.cond]") [*pp-tokens*](cpp.pre#nt:pp-tokens "15.1 Preamble [cpp.pre]")opt ; [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]")
|
||
exportopt import [*pp-tokens*](cpp.pre#nt:pp-tokens "15.1 Preamble [cpp.pre]") ; [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]")
|
||
|
||
[1](#1)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1278)
|
||
|
||
A [*pp-import*](#nt:pp-import "15.6 Header unit importation [cpp.import]") shall not
|
||
appear in a context where import or (if it is the first preprocessing token of the [*pp-import*](#nt:pp-import "15.6 Header unit importation [cpp.import]")) export is an identifier defined as an object-like macro[.](#1.sentence-1)
|
||
|
||
[2](#2)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1284)
|
||
|
||
The preprocessing tokens after the import preprocessing token
|
||
in the import [*control-line*](cpp.pre#nt:control-line "15.1 Preamble [cpp.pre]") are processed just as in normal text
|
||
(i.e., each identifier currently defined as a macro name
|
||
is replaced by its replacement list of preprocessing tokens)[.](#2.sentence-1)
|
||
|
||
[*Note [1](#note-1)*:
|
||
|
||
An import directive
|
||
matching the first two forms of a [*pp-import*](#nt:pp-import "15.6 Header unit importation [cpp.import]") instructs the preprocessor to import macros
|
||
from the header unit ([[module.import]](module.import "10.3 Import declaration"))
|
||
denoted by the [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]"),
|
||
as described below[.](#2.sentence-2)
|
||
|
||
â *end note*]
|
||
|
||
The [*point of macro import*](#def:macro,point_of_import "15.6 Header unit importation [cpp.import]") for the
|
||
first two forms of [*pp-import*](#nt:pp-import "15.6 Header unit importation [cpp.import]") is
|
||
immediately after the [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]") terminating
|
||
the [*pp-import*](#nt:pp-import "15.6 Header unit importation [cpp.import]")[.](#2.sentence-3)
|
||
|
||
The last form of [*pp-import*](#nt:pp-import "15.6 Header unit importation [cpp.import]") is only considered
|
||
if the first two forms did not match, and
|
||
does not have a point of macro import[.](#2.sentence-4)
|
||
|
||
[3](#3)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1307)
|
||
|
||
If a [*pp-import*](#nt:pp-import "15.6 Header unit importation [cpp.import]") is produced by source file inclusion
|
||
(including by the rewrite produced
|
||
when a #include directive names an importable header)
|
||
while processing the [*group*](cpp.pre#nt:group "15.1 Preamble [cpp.pre]") of a [*module-file*](cpp.pre#nt:module-file "15.1 Preamble [cpp.pre]"),
|
||
the program is ill-formed[.](#3.sentence-1)
|
||
|
||
[4](#4)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1314)
|
||
|
||
In all three forms of [*pp-import*](#nt:pp-import "15.6 Header unit importation [cpp.import]"),
|
||
the import and export (if it exists) preprocessing tokens
|
||
are replaced by the *import-keyword* and*export-keyword* preprocessing tokens respectively[.](#4.sentence-1)
|
||
|
||
[*Note [2](#note-2)*:
|
||
|
||
This makes the line no longer a directive
|
||
so it is not removed at the end of phase 4[.](#4.sentence-2)
|
||
|
||
â *end note*]
|
||
|
||
Additionally, in the second form of [*pp-import*](#nt:pp-import "15.6 Header unit importation [cpp.import]"),
|
||
a [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]") token is formed as if
|
||
the [*header-name-tokens*](cpp.cond#nt:header-name-tokens "15.2 Conditional inclusion [cpp.cond]") were the [*pp-tokens*](cpp.pre#nt:pp-tokens "15.1 Preamble [cpp.pre]") of a #include directive[.](#4.sentence-3)
|
||
|
||
The [*header-name-tokens*](cpp.cond#nt:header-name-tokens "15.2 Conditional inclusion [cpp.cond]") are replaced by
|
||
the [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]") token[.](#4.sentence-4)
|
||
|
||
[*Note [3](#note-3)*:
|
||
|
||
This ensures that imports are treated consistently by
|
||
the preprocessor and later phases of translation[.](#4.sentence-5)
|
||
|
||
â *end note*]
|
||
|
||
[5](#5)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1334)
|
||
|
||
Each #define directive encountered when preprocessing
|
||
each translation unit in a program results in a distinct[*macro definition*](#def:macro,definition "15.6 Header unit importation [cpp.import]")[.](#5.sentence-1)
|
||
|
||
[*Note [4](#note-4)*:
|
||
|
||
A predefined macro name ([[cpp.predefined]](cpp.predefined "15.12 Predefined macro names"))
|
||
is not introduced by a #define directive[.](#5.sentence-2)
|
||
|
||
Implementations providing mechanisms to predefine additional macros
|
||
are encouraged to not treat them
|
||
as being introduced by a #define directive[.](#5.sentence-3)
|
||
|
||
â *end note*]
|
||
|
||
Each macro definition has at most one point of definition in
|
||
each translation unit and at most one point of undefinition, as follows:
|
||
|
||
- [(5.1)](#5.1)
|
||
|
||
The [*point of definition*](#def:macro,point_of_definition "15.6 Header unit importation [cpp.import]") of a macro definition within a translation unit T is
|
||
* [(5.1.1)](#5.1.1)
|
||
|
||
if the #define directive of the macro definition occurs within T,
|
||
the point at which that directive occurs, or otherwise,
|
||
|
||
* [(5.1.2)](#5.1.2)
|
||
|
||
if the macro name is not lexically identical to a keyword ([[lex.key]](lex.key "5.12 Keywords"))
|
||
or to the [*identifier*](lex.name#nt:identifier "5.11 Identifiers [lex.name]")*s* module or import,
|
||
the first point of macro import in T of a header unit
|
||
containing a point of definition for the macro definition, if any[.](#5.1.sentence-1)
|
||
|
||
In the latter case, the macro is said
|
||
to be [*imported*](#def:macro,import "15.6 Header unit importation [cpp.import]") from the header unit[.](#5.1.sentence-2)
|
||
|
||
- [(5.2)](#5.2)
|
||
|
||
The [*point of undefinition*](#def:macro,point_of_undefinition "15.6 Header unit importation [cpp.import]") of a macro definition within a translation unit
|
||
is the first point at which a #undef directive naming the macro occurs
|
||
after its point of definition, or the first point
|
||
of macro import of a header unit containing a point of undefinition for the
|
||
macro definition, whichever (if any) occurs first[.](#5.2.sentence-1)
|
||
|
||
[6](#6)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1375)
|
||
|
||
A macro definition is [*active*](#def:macro,active "15.6 Header unit importation [cpp.import]") at a source location
|
||
if it has a point of definition in that translation unit preceding the location,
|
||
and does not have a point of undefinition in that translation unit preceding
|
||
the location[.](#6.sentence-1)
|
||
|
||
[7](#7)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1382)
|
||
|
||
If a macro would be replaced or redefined, and multiple macro definitions
|
||
are active for that macro name, the active macro definitions shall all be
|
||
valid redefinitions of the same macro ([[cpp.replace]](cpp.replace "15.7 Macro replacement"))[.](#7.sentence-1)
|
||
|
||
[*Note [5](#note-5)*:
|
||
|
||
The relative order of [*pp-import*](#nt:pp-import "15.6 Header unit importation [cpp.import]")*s* has no bearing on whether a
|
||
particular macro definition is active[.](#7.sentence-2)
|
||
|
||
â *end note*]
|
||
|
||
[8](#8)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1391)
|
||
|
||
[*Example [1](#example-1)*:
|
||
|
||
Importable header "a.h":#define X 123 // #1#define Y 45 // #2#define Z a // #3#undef X // point of undefinition of #1 in "a.h"
|
||
|
||
Importable header "b.h":import "a.h"; // point of definition of #1, #2, and #3, point of undefinition of #1 in "b.h"#define X 456 // OK, #1 is not active#define Y 6 // error: #2 is active
|
||
|
||
Importable header "c.h":#define Y 45 // #4#define Z c // #5
|
||
|
||
Importable header "d.h":import "c.h"; // point of definition of #4 and #5 in "d.h"
|
||
|
||
Importable header "e.h":import "a.h"; // point of definition of #1, #2, and #3, point of undefinition of #1 in "e.h"import "d.h"; // point of definition of #4 and #5 in "e.h"int a = Y; // OK, active macro definitions #2 and #4 are valid redefinitionsint c = Z; // error: active macro definitions #3 and #5 are not valid redefinitions of Z
|
||
|
||
Module unit f:export module f;export import "a.h";
|
||
|
||
int a = Y; // OK
|
||
|
||
Translation unit #1:import f;int x = Y; // error: Y is neither a defined macro nor a declared name â *end example*]
|