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