flang/docs/Preprocessing.md

   1 <!--===- docs/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
   9 # Fortran Preprocessing
  10
  11 ```{contents}
  12 ---
  13 local:
  14 ---
  15 ```
  16
  17 ## Behavior common to (nearly) all compilers:
  18
  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.
  46
  47 ## Behavior that is not consistent over all extant compilers but which probably should be uncontroversial:
  48
  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.
  71
  72 ## Judgement calls, where precedents are unclear:
  73
  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.
  96 * A backslash at the end of a free form source line is a continuation
  97   marker, with no space skipping or special handling of a leading `&`
  98   on the next line.
  99
 100 ## Behavior that few compilers properly support (or none), but should:
 101
 102 * A macro invocation can straddle free form continuation lines in all of their
 103   forms, with continuation allowed in the name, before the arguments, and
 104   within the arguments.
 105 * Directives can be capitalized in free form, too.
 106 * `__VA_ARGS__` and `__VA_OPT__` work in variadic function-like macros.
 107
 108 ## In short, a Fortran preprocessor should work as if:
 109
 110 1. Fixed form lines are padded up to column 72 (or 132) and clipped thereafter.
 111 2. Fortran comments are removed.
 112 3. C-style line continuations are processed in preprocessing directives.
 113 4. C old-style comments are removed from directives.
 114 5. Fortran line continuations are processed (outside preprocessing directives).
 115    Line continuation rules depend on source form.
 116    Comment lines that are enabled compiler directives have their line
 117    continuations processed.
 118    Conditional compilation preprocessing directives (e.g., `#if`) may be
 119    appear among continuation lines, and have their usual effects upon them.
 120 6. Other preprocessing directives are processed and macros expanded.
 121    Along the way, Fortran `INCLUDE` lines and preprocessor `#include` directives
 122    are expanded, and all these steps applied recursively to the introduced text.
 123 7. Any Fortran comments created by macro replacement are removed.
 124
 125 Steps 5 and 6 are interleaved with respect to the preprocessing state.
 126 Conditional compilation preprocessing directives always reflect only the macro
 127 definition state produced by the active `#define` and `#undef` preprocessing directives
 128 that precede them.
 129
 130 If the source form is changed by means of a compiler directive (i.e.,
 131 `!DIR$ FIXED` or `FREE`) in an included source file, its effects cease
 132 at the end of that file.
 133
 134 Last, if the preprocessor is not integrated into the Fortran compiler,
 135 new Fortran continuation line markers should be introduced into the final
 136 text.
 137
 138 OpenMP-style directives that look like comments are not addressed by
 139 this scheme but are obvious extensions.
 140
 141 ## Appendix
 142 `N` in the table below means "not supported"; this doesn't
 143 mean a bug, it just means that a particular behavior was
 144 not observed.
 145 `E` signifies "error reported".
 146
 147 The abbreviation `KWM` stands for "keyword macro" and `FLM` means
 148 "function-like macro".
 149
 150 The first block of tests (`pp0*.F`) are all fixed-form source files;
 151 the second block (`pp1*.F90`) are free-form source files.
 152
 153 ```
 154 f18
 155 | pgfortran
 156 | | ifort
 157 | | | gfortran
 158 | | | | xlf
 159 | | | | | nagfor
 160 | | | | | |
 161 . . . . . .   pp001.F  keyword macros
 162 . . . . . .   pp002.F  #undef
 163 . . . . . .   pp003.F  function-like macros
 164 . . . . . .   pp004.F  KWMs case-sensitive
 165 . N . N N .   pp005.F  KWM split across continuation, implicit padding
 166 . N . N N .   pp006.F  ditto, but with intervening *comment line
 167 N N N N N N   pp007.F  KWM split across continuation, clipped after column 72
 168 . . . . . .   pp008.F  KWM with spaces in name at invocation NOT replaced
 169 . N . N N .   pp009.F  FLM call split across continuation, implicit padding
 170 . N . N N .   pp010.F  ditto, but with intervening *comment line
 171 N N N N N N   pp011.F  FLM call name split across continuation, clipped
 172 . N . N N .   pp012.F  FLM call name split across continuation
 173 . E . N N .   pp013.F  FLM call split between name and (
 174 . N . N N .   pp014.F  FLM call split between name and (, with intervening *comment
 175 . E . N N .   pp015.F  FLM call split between name and (, clipped
 176 . E . N N .   pp016.F  FLM call split between name and ( and in argument
 177 . . . . . .   pp017.F  KLM rescan
 178 . . . . . .   pp018.F  KLM rescan with #undef (so rescan is after expansion)
 179 . . . . . .   pp019.F  FLM rescan
 180 . . . . . .   pp020.F  FLM expansion of argument
 181 . . . . . .   pp021.F  KWM NOT expanded in 'literal'
 182 . . . . . .   pp022.F  KWM NOT expanded in "literal"
 183 . . E E . E   pp023.F  KWM NOT expanded in 9HHOLLERITH literal
 184 . . . E . .   pp024.F  KWM NOT expanded in Hollerith in FORMAT
 185 . . . . . .   pp025.F  KWM expansion is before token pasting due to fixed-form space removal
 186 . . . E . E   pp026.F  ## token pasting works in FLM
 187 E . . E E .   pp027.F  #DEFINE works in fixed form
 188 . N . N N .   pp028.F  fixed-form clipping done before KWM expansion on source line
 189 . . . . . .   pp029.F  \ newline allowed in #define
 190 . . . . . .   pp030.F  /* C comment */ erased from #define
 191 E E E E E E   pp031.F   // C++ comment NOT erased from #define
 192 . . . . . .   pp032.F  /* C comment */ \ newline erased from #define
 193 . . . . . .   pp033.F  /* C comment \ newline */ erased from #define
 194 . . . . . N   pp034.F  \ newline allowed in name on KWM definition
 195 . E . E E .   pp035.F  #if 2 .LT. 3 works
 196 . . . . . .   pp036.F  #define FALSE TRUE ...  .FALSE. -> .TRUE.
 197 N N N N N N   pp037.F  fixed-form clipping NOT applied to #define
 198 . . E . E E   pp038.F  FLM call with closing ')' on next line (not a continuation)
 199 E . E . E E   pp039.F  FLM call with '(' on next line (not a continuation)
 200 . . . . . .   pp040.F  #define KWM c, then KWM works as comment line initiator
 201 E . E . . E   pp041.F  use KWM expansion as continuation indicators
 202 N N N . . N   pp042.F  #define c 1, then use c as label in fixed-form
 203 . . . . N .   pp043.F  #define with # in column 6 is a continuation line in fixed-form
 204 E . . . . .   pp044.F  #define directive amid continuations
 205 . . . . . .   pp101.F90  keyword macros
 206 . . . . . .   pp102.F90  #undef
 207 . . . . . .   pp103.F90  function-like macros
 208 . . . . . .   pp104.F90  KWMs case-sensitive
 209 . N N N N N   pp105.F90  KWM call name split across continuation, with leading &
 210 . N N N N N   pp106.F90  ditto, with & ! comment
 211 N N E E N .   pp107.F90  KWM call name split across continuation, no leading &, with & ! comment
 212 N N E E N .   pp108.F90  ditto, but without & ! comment
 213 . N N N N N   pp109.F90  FLM call name split with leading &
 214 . N N N N N   pp110.F90  ditto, with & ! comment
 215 N N E E N .   pp111.F90  FLM call name split across continuation, no leading &, with & ! comment
 216 N N E E N .   pp112.F90  ditto, but without & ! comment
 217 . N N N N E   pp113.F90  FLM call split across continuation between name and (, leading &
 218 . N N N N E   pp114.F90  ditto, with & ! comment, leading &
 219 N N N N N .   pp115.F90  ditto, with & ! comment, no leading &
 220 N N N N N .   pp116.F90  FLM call split between name and (, no leading &
 221 . . . . . .   pp117.F90  KWM rescan
 222 . . . . . .   pp118.F90  KWM rescan with #undef, proving rescan after expansion
 223 . . . . . .   pp119.F90  FLM rescan
 224 . . . . . .   pp120.F90  FLM expansion of argument
 225 . . . . . .   pp121.F90  KWM NOT expanded in 'literal'
 226 . . . . . .   pp122.F90  KWM NOT expanded in "literal"
 227 . . E E . E   pp123.F90  KWM NOT expanded in Hollerith literal
 228 . . E E . E   pp124.F90  KWM NOT expanded in Hollerith in FORMAT
 229 E . . E E .   pp125.F90  #DEFINE works in free form
 230 . . . . . .   pp126.F90  \ newline works in #define
 231 . . E . E E   pp127.F90  FLM call with closing ')' on next line (not a continuation)
 232 E . E . E E   pp128.F90  FLM call with '(' on next line (not a continuation)
 233 . . N . . N   pp129.F90  #define KWM !, then KWM works as comment line initiator
 234 . . E . . E   pp130.F90  #define KWM &, use for continuation w/o pasting (ifort and nag seem to continue #define)
 235 ```