| blob | 3c523472f39bd018e5516b43f7acc0dcabedc2bc |
1 <!--===- docs/Preprocessing.md
3 Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 See https://llvm.org/LICENSE.txt for license information.
5 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 -->
9 # Fortran Preprocessing
11 ```{contents}
12 ---
13 local:
14 ---
15 ```
17 ## Behavior common to (nearly) all compilers:
19 * Macro and argument names are sensitive to case.
20 * Fixed form right margin clipping after column 72 (or 132)
21 has precedence over macro name recognition, and also over
22 recognition of function-like parentheses and arguments.
23 * Fixed form right margin clipping does not apply to directive lines.
24 * Macro names are not recognized as such when spaces are inserted
25 into their invocations in fixed form.
26 This includes spaces at the ends of lines that have been clipped
27 at column 72 (or whatever).
28 * Text is rescanned after expansion of macros and arguments.
29 * Macros are not expanded within quoted character literals or
30 quoted FORMAT edit descriptors.
31 * Macro expansion occurs before any effective token pasting via fixed form
32 space removal.
33 * C-like line continuations with backslash-newline are allowed in
34 directives, including the definitions of macro bodies.
35 * `/* Old style C comments */` are ignored in directives and
36 removed from the bodies of macro definitions.
37 * `// New style C comments` are not removed, since Fortran has OPERATOR(//).
38 * C-like line continuations with backslash-newline can appear in
39 old-style C comments in directives.
40 * After `#define FALSE TRUE`, `.FALSE.` is replaced by `.TRUE.`;
41 i.e., tokenization does not hide the names of operators or logical constants.
42 * `#define KWM c` allows the use of `KWM` in column 1 as a fixed form comment
43 line indicator.
44 * A `#define` directive intermixed with continuation lines can't
45 define a macro that's invoked earlier in the same continued statement.
47 ## Behavior that is not consistent over all extant compilers but which probably should be uncontroversial:
49 * Invoked macro names can straddle a Fortran line continuation.
50 * ... unless implicit fixed form card padding intervenes; i.e.,
51 in fixed form, a continued macro name has to be split at column
52 72 (or 132).
53 * Comment lines may appear with continuations in a split macro names.
54 * Function-like macro invocations can straddle a Fortran fixed form line
55 continuation between the name and the left parenthesis, and comment and
56 directive lines can be there too.
57 * Function-like macro invocations can straddle a Fortran fixed form line
58 continuation between the parentheses, and comment lines can be there too.
59 * Macros are not expanded within Hollerith constants or Hollerith
60 FORMAT edit descriptors.
61 * Token pasting with `##` works in function-like macros.
62 * Argument stringization with `#` works in function-like macros.
63 * Directives can be capitalized (e.g., `#DEFINE`) in fixed form.
64 * Fixed form clipping after column 72 or 132 is done before macro expansion,
65 not after.
66 * C-like line continuation with backslash-newline can appear in the name of
67 a keyword-like macro definition.
68 * If `#` is in column 6 in fixed form, it's a continuation marker, not a
69 directive indicator.
70 * `#define KWM !` allows KWM to signal a comment.
72 ## Judgement calls, where precedents are unclear:
74 * Expressions in `#if` and `#elif` should support both Fortran and C
75 operators; e.g., `#if 2 .LT. 3` should work.
76 * If a function-like macro does not close its parentheses, line
77 continuation should be assumed.
78 This includes the case of a keyword-like macro that expands to
79 the name of a function-like macro.
80 * ... However, the leading parenthesis has to be on the same line as
81 the name of the function-like macro, or on a continuation line thereof.
82 * And no macro definition prior to that point can be allowed to have
83 unbalanced parentheses in its replacement text.
84 When that happens, it's possible to have false positive cases
85 causing implicit line continuations that break real code.
86 * If macros expand to text containing `&`, it doesn't work as a free form
87 line continuation marker.
88 * `#define c 1` does not allow a `c` in column 1 to be used as a label
89 in fixed form, rather than as a comment line indicator.
90 * IBM claims to be ISO C compliant and therefore recognizes trigraph sequences.
91 * Fortran comments in macro actual arguments should be respected, on
92 the principle that a macro call should work like a function reference.
93 * If a `#define` or `#undef` directive appears among continuation
94 lines, it may or may not affect text in the continued statement that
95 appeared before the directive.
97 ## Behavior that few compilers properly support (or none), but should:
99 * A macro invocation can straddle free form continuation lines in all of their
100 forms, with continuation allowed in the name, before the arguments, and
101 within the arguments.
102 * Directives can be capitalized in free form, too.
103 * `__VA_ARGS__` and `__VA_OPT__` work in variadic function-like macros.
105 ## In short, a Fortran preprocessor should work as if:
107 1. Fixed form lines are padded up to column 72 (or 132) and clipped thereafter.
108 2. Fortran comments are removed.
109 3. C-style line continuations are processed in preprocessing directives.
110 4. C old-style comments are removed from directives.
111 5. Fortran line continuations are processed (outside preprocessing directives).
112 Line continuation rules depend on source form.
113 Comment lines that are enabled compiler directives have their line
114 continuations processed.
115 Conditional compilation preprocessing directives (e.g., `#if`) may be
116 appear among continuation lines, and have their usual effects upon them.
117 6. Other preprocessing directives are processed and macros expanded.
118 Along the way, Fortran `INCLUDE` lines and preprocessor `#include` directives
119 are expanded, and all these steps applied recursively to the introduced text.
120 7. Any Fortran comments created by macro replacement are removed.
122 Steps 5 and 6 are interleaved with respect to the preprocessing state.
123 Conditional compilation preprocessing directives always reflect only the macro
124 definition state produced by the active `#define` and `#undef` preprocessing directives
125 that precede them.
127 If the source form is changed by means of a compiler directive (i.e.,
128 `!DIR$ FIXED` or `FREE`) in an included source file, its effects cease
129 at the end of that file.
131 Last, if the preprocessor is not integrated into the Fortran compiler,
132 new Fortran continuation line markers should be introduced into the final
133 text.
135 OpenMP-style directives that look like comments are not addressed by
136 this scheme but are obvious extensions.
138 ## Appendix
139 `N` in the table below means "not supported"; this doesn't
140 mean a bug, it just means that a particular behavior was
141 not observed.
142 `E` signifies "error reported".
144 The abbreviation `KWM` stands for "keyword macro" and `FLM` means
145 "function-like macro".
147 The first block of tests (`pp0*.F`) are all fixed-form source files;
148 the second block (`pp1*.F90`) are free-form source files.
150 ```
151 f18
152 | pgfortran
153 | | ifort
154 | | | gfortran
155 | | | | xlf
156 | | | | | nagfor
157 | | | | | |
158 . . . . . . pp001.F keyword macros
159 . . . . . . pp002.F #undef
160 . . . . . . pp003.F function-like macros
161 . . . . . . pp004.F KWMs case-sensitive
162 . N . N N . pp005.F KWM split across continuation, implicit padding
163 . N . N N . pp006.F ditto, but with intervening *comment line
164 N N N N N N pp007.F KWM split across continuation, clipped after column 72
165 . . . . . . pp008.F KWM with spaces in name at invocation NOT replaced
166 . N . N N . pp009.F FLM call split across continuation, implicit padding
167 . N . N N . pp010.F ditto, but with intervening *comment line
168 N N N N N N pp011.F FLM call name split across continuation, clipped
169 . N . N N . pp012.F FLM call name split across continuation
170 . E . N N . pp013.F FLM call split between name and (
171 . N . N N . pp014.F FLM call split between name and (, with intervening *comment
172 . E . N N . pp015.F FLM call split between name and (, clipped
173 . E . N N . pp016.F FLM call split between name and ( and in argument
174 . . . . . . pp017.F KLM rescan
175 . . . . . . pp018.F KLM rescan with #undef (so rescan is after expansion)
176 . . . . . . pp019.F FLM rescan
177 . . . . . . pp020.F FLM expansion of argument
178 . . . . . . pp021.F KWM NOT expanded in 'literal'
179 . . . . . . pp022.F KWM NOT expanded in "literal"
180 . . E E . E pp023.F KWM NOT expanded in 9HHOLLERITH literal
181 . . . E . . pp024.F KWM NOT expanded in Hollerith in FORMAT
182 . . . . . . pp025.F KWM expansion is before token pasting due to fixed-form space removal
183 . . . E . E pp026.F ## token pasting works in FLM
184 E . . E E . pp027.F #DEFINE works in fixed form
185 . N . N N . pp028.F fixed-form clipping done before KWM expansion on source line
186 . . . . . . pp029.F \ newline allowed in #define
187 . . . . . . pp030.F /* C comment */ erased from #define
188 E E E E E E pp031.F // C++ comment NOT erased from #define
189 . . . . . . pp032.F /* C comment */ \ newline erased from #define
190 . . . . . . pp033.F /* C comment \ newline */ erased from #define
191 . . . . . N pp034.F \ newline allowed in name on KWM definition
192 . E . E E . pp035.F #if 2 .LT. 3 works
193 . . . . . . pp036.F #define FALSE TRUE ... .FALSE. -> .TRUE.
194 N N N N N N pp037.F fixed-form clipping NOT applied to #define
195 . . E . E E pp038.F FLM call with closing ')' on next line (not a continuation)
196 E . E . E E pp039.F FLM call with '(' on next line (not a continuation)
197 . . . . . . pp040.F #define KWM c, then KWM works as comment line initiator
198 E . E . . E pp041.F use KWM expansion as continuation indicators
199 N N N . . N pp042.F #define c 1, then use c as label in fixed-form
200 . . . . N . pp043.F #define with # in column 6 is a continuation line in fixed-form
201 E . . . . . pp044.F #define directive amid continuations
202 . . . . . . pp101.F90 keyword macros
203 . . . . . . pp102.F90 #undef
204 . . . . . . pp103.F90 function-like macros
205 . . . . . . pp104.F90 KWMs case-sensitive
206 . N N N N N pp105.F90 KWM call name split across continuation, with leading &
207 . N N N N N pp106.F90 ditto, with & ! comment
208 N N E E N . pp107.F90 KWM call name split across continuation, no leading &, with & ! comment
209 N N E E N . pp108.F90 ditto, but without & ! comment
210 . N N N N N pp109.F90 FLM call name split with leading &
211 . N N N N N pp110.F90 ditto, with & ! comment
212 N N E E N . pp111.F90 FLM call name split across continuation, no leading &, with & ! comment
213 N N E E N . pp112.F90 ditto, but without & ! comment
214 . N N N N E pp113.F90 FLM call split across continuation between name and (, leading &
215 . N N N N E pp114.F90 ditto, with & ! comment, leading &
216 N N N N N . pp115.F90 ditto, with & ! comment, no leading &
217 N N N N N . pp116.F90 FLM call split between name and (, no leading &
218 . . . . . . pp117.F90 KWM rescan
219 . . . . . . pp118.F90 KWM rescan with #undef, proving rescan after expansion
220 . . . . . . pp119.F90 FLM rescan
221 . . . . . . pp120.F90 FLM expansion of argument
222 . . . . . . pp121.F90 KWM NOT expanded in 'literal'
223 . . . . . . pp122.F90 KWM NOT expanded in "literal"
224 . . E E . E pp123.F90 KWM NOT expanded in Hollerith literal
225 . . E E . E pp124.F90 KWM NOT expanded in Hollerith in FORMAT
226 E . . E E . pp125.F90 #DEFINE works in free form
227 . . . . . . pp126.F90 \ newline works in #define
228 . . E . E E pp127.F90 FLM call with closing ')' on next line (not a continuation)
229 E . E . E E pp128.F90 FLM call with '(' on next line (not a continuation)
230 . . N . . N pp129.F90 #define KWM !, then KWM works as comment line initiator
231 . . E . . E pp130.F90 #define KWM &, use for continuation w/o pasting (ifort and nag seem to continue #define)
232 ```