1# Semantics: Resolving Labels and Construct Names
2
3## Overview
4
5After the Fortran input file(s) has been parsed into a syntax tree, the compiler must check that the program checks semantically.  Target labels must be checked and violations of legal semantics should be reported to the user.
6
7This is the detailed design document on how these labels will be semantically checked.  Legal semantics may result in rewrite operations on the syntax tree.  Semantics violations will be reported as errors to the user.
8
9## Requirements
10
11- Input: a parse tree that decomposes the Fortran program unit
12- Output:
13   * **Success** returns true
14     (Additionally, the parse tree may be rewritten on success to capture the nested DO loop structure explicitly from any _label-do-stmt_ type loops.)
15   * **Failure** returns false, instantiates (a container of) error message(s) to indicate the problem(s)
16
17
18### Label generalities (6.2.5)
19
20Enforcement of the general label constraints.  There are three sorts of label usage. Labels can serve
21   1. as a _label-do-stmt_ block range marker
22   1. as branching (control flow) targets
23   1. as specification annotations (`FORMAT` statements) for data transfer statements (I/O constructs)
24
25Labels are related to the standard definition of inclusive scope.  For example, control-flow arcs are not allowed to originate from one inclusive scope and target statements outside of that inclusive scope.
26
27Inclusive scope is defined as a tree structure of nested scoping constructs. A statement, _s_, is said to be *in* the same inclusive scope as another statement, _t_, if and only if _s_ and _t_ are in the same scope or _t_ is in one of the enclosing scopes of _s_, otherwise _s_ is *not in* the same inclusive scope as _t_. (Inclusive scope is unidirectional and is always from innermost scopes to outermost scopes.)
28
29#### Semantic Checks
30
31- labels range from 1 to 99999, inclusive (6.2.5 note 2)
32  * handled automatically by the parser, but add a range check
33- labels must be pairwise distinct within their program unit scope (6.2.5 para 2)
34  * if redundant labels appear → error redundant labels
35  * the total number of unique statement labels may have a limit
36
37
38### Labels Used for `DO` Loop Ranging
39
40#### _label-do-stmt_ (R1121)
41
42A _label-do-stmt_ is a control construct that results in the iterative execution of a number of statements.  A _label-do-stmt_ has a (possibly shared, _nonblock-do-construct_) _label_ that will be called the loop target label.  The statements to be executed will be the range from the _label-do-stmt_ to the statement identified by the loop target label, inclusive. This range of statements will be called the loop's body and logically forms a _do-block_.
43
44A _label-do-stmt_ is quite similar to a _block-do-construct_ in semantics, but the parse tree is different in that the parser does not impose a _do-block_ structure on the loop body.
45
46In F18, the nonblock `DO` construct has been removed.  For legacy support (through F08), we will need to handle nonblock `DO` constructs.  In F18, the following legacy code is an error.
47
48```fortran
49  DO 100 I = 1, 100
50    DO 100 J = 1, 100
51      ...
52 100 CONTINUE
53```
54
55##### Semantic Checks
56
57- the loop body target label must exist in the scope (F18:C1133; F08:C815, C817, C819)
58  * if the label does not appear, error of missing label
59- the loop body target label must be, lexically, after the _label-do-stmt_ (R1119)
60  * if the label appears lexically preceding the `DO`, error of malformed `DO`
61- control cannot transfer into the body from outside the _do-block_
62  * Exceptions (errors demoted to warnings)
63    - some implementations relax enforcement of this and allow `GOTO`s from the loop body to "extended ranges" and back again (PGI & gfortan appear to allow, NAG & Intel do not.)
64    - should some form of "extended ranges" for _do-constructs_ be supported, it should still be limited and not include parallel loops such as `DO CONCURRENT` or loops annotated with OpenACC or OpenMP directives.
65  * `GOTO`s into the `DO`s inclusive scope, error/warn of invalid transfer of control
66- requires that the loop terminating statement for a _label-do-stmt_ be either an `END DO` or a `CONTINUE`
67  * Exception
68    - earlier standards allowed other statements to be terminators
69
70Semantics for F08 and earlier that support sharing the loop terminating statement in a _nonblock-do-construct_ between multiple loops
71- some statements cannot be _do-term-action-stmt_ (F08:C816)
72  * a _do-term-action-stmt_ is an _action-stmt_ but does not include _arithmetic-if-stmt_, _continue-stmt_, _cycle-stmt_, _end-function-stmt_, _end-mp-subprogram-stmt_, _end-program-stmt_, _end-subroutine-stmt_, _error-stop-stmt_, _exit-stmt_, _goto-stmt_, _return-stmt_, or _stop-stmt_
73    - if the term action statement is forbidden, error invalid statement in `DO` loop term position
74- some statements cannot be _do-term-shared-stmt_ (F08:C818)
75  * this is the case as in our above example where two different nested loops share the same terminating statement (`100 continue`)
76  * a _do-term-shared-stmt_ is an _action-stmt_ with all the same exclusions as a _do-term-action-stmt_ except a _continue-stmt_ **is** allowed
77    - if the term shared action statement is forbidden, error invalid statement in term position
78
79If the `DO` loop is a `DO CONCURRENT` construct, there are additional constraints (11.1.7.5).
80- a _return-stmt_ is not allowed (C1136)
81- image control statements are not allowed (C1137)
82- branches must be from a statement and to a statement that both reside within the `DO CONCURRENT` (C1138)
83- impure procedures shall not be called (C1139)
84- deallocation of polymorphic objects is not allowed (C1140)
85- references to `IEEE_GET_FLAG`, `IEEE_SET_HALTING_MODE`, and `IEEE_GET_HALTING_MODE` cannot appear in the body of a `DO CONCURRENT` (C1141)
86- the use of the `ADVANCE=` specifier by an I/O statement in the body of a `DO CONCURRENT` is not allowed (11.1.7.5, para 5)
87
88### Labels Used in Branching
89
90#### _goto-stmt_ (11.2.2, R1157)
91
92A `GOTO` statement is a simple, direct transfer of control from the `GOTO` to the labelled statement.
93
94##### Semantic Checks
95
96- the labelled statement that is the target of a `GOTO` (11.2.1 constraints)
97  - must refer to a label that is in inclusive scope of the computed `GOTO` statement (C1169)
98    * if a label does not exist, error nonexistent label
99    * if a label is out of scope, error out of inclusive scope
100  - the branch target statement must be valid
101    * if the statement is not allowed as a branch target, error not a valid branch target
102- the labelled statement must be a branch target statement
103  * a branch target statement is any of _action-stmt_, _associate-stmt_, _end-associate-stmt_, _if-then-stmt_, _end-if-stmt_, _select-case-stmt_, _end-select-stmt_, _select-rank-stmt_, _end-select-rank-stmt_, _select-type-stmt_, _end-select-type-stmt_, _do-stmt_, _end-do-stmt_, _block-stmt_, _end-block-stmt_, _critical-stmt_, _end-critical-stmt_, _forall-construct-stmt_, _forall-stmt_, _where-construct-stmt_, _end-function-stmt_, _end-mp-subprogram-stmt_, _end-program-stmt_, or _end-subroutine-stmt_. (11.2.1)
104  * Some deleted features that were _action-stmt_ in older standards include _arithmetic-if-stmt_, _assign-stmt_, _assigned-goto-stmt_, and _pause-stmt_. For legacy mode support, these statements should be considered _action-stmt_.
105
106
107#### _computed-goto-stmt_ (11.2.3, R1158)
108
109The computed `GOTO` statement is analogous to a `switch` statement in C++.
110
111```fortran
112  GOTO ( label-list ) [,] scalar-int-expr
113```
114
115##### Semantics Checks
116
117- each label in _label-list_ (11.2.1 constraints, same as `GOTO`)
118  - must refer to a label that is in inclusive scope of the computed `GOTO` statement (C1170)
119    * if a label does not exist, error nonexistent label
120    * if a label is out of scope, error out of inclusive scope
121  - the branch target statement must be valid
122    * if the statement is not allowed as a branch target, error not a valid branch target
123- the _scalar-int-expr_ needs to have `INTEGER` type
124  * check the type of the expression (type checking done elsewhere)
125
126
127#### R853 _arithmetic-if-stmt_ (F08:8.2.4)
128
129This control-flow construct is deleted in F18.
130
131```fortran
132  IF (scalar-numeric-expr) label1,label2,label3
133```
134
135The arithmetic if statement is like a three-way branch operator. If the scalar numeric expression is less than zero goto _label-1_, else if the variable is equal to zero goto _label-2_, else if the variable is greater than zero goto _label-3_.
136
137##### Semantics Checks
138
139- the labels in the _arithmetic-if-stmt_ triple must all be present in the inclusive scope (F08:C848)
140  * if a label does not exist, error nonexistent label
141  * if a label is out of scope, error out of inclusive scope
142- the _scalar-numeric-expr_ must not be `COMPLEX` (F08:C849)
143  * check the type of the expression (type checking done elsewhere)
144
145
146#### _alt-return-spec_ (15.5.1, R1525)
147
148These are a Fortran control-flow construct for combining a return from a subroutine with a branch to a labelled statement in the calling routine all in one operation. A typical implementation is for the subroutine to return a hidden integer, which is used as a key in the calling code to then, possibly, branch to a labelled statement in inclusive scope.
149
150The labels are passed by the calling routine. We want to check those labels at the call-site, that is instances of _alt-return-spec_.
151
152##### Semantics Checks
153
154- each _alt-return-spec_ (11.2.1 constraints, same as `GOTO`)
155  - must refer to a label that is in inclusive scope of the `CALL` statement
156    * if a label does not exist, error nonexistent label
157    * if a label is out of scope, error out of inclusive scope
158  - the branch target statement must be valid
159    * if the statement is not allowed as a branch target, error not a valid branch target
160
161
162#### **END**, **EOR**, **ERR** specifiers (12.11)
163
164These specifiers can appear in I/O statements and can transfer control to specific labelled statements under exceptional conditions like end-of-file, end-of-record, and other error conditions.  (The PGI compiler adds code to test the results from the runtime routines to determine if these branches should take place.)
165
166##### Semantics Checks
167
168- each END, EOR, and ERR specifier (11.2.1 constraints, same as `GOTO`)
169  - must refer to a label that is in inclusive scope of the I/O statement
170    * if a label does not exist, error nonexistent label
171    * if a label is out of scope, error out of inclusive scope
172  - the branch target statement must be valid
173    * if the statement is not allowed as a branch target, error not a valid branch target
174
175#### _assigned-goto-stmt_ and _assign-stmt_ (F90:8.2.4)
176
177Deleted feature since Fortran 95.
178
179The _assigned-goto-stmt_ and _assign-stmt_ were _action-stmt_ in the Fortran 90 standard. They are included here for completeness. This pair of obsolete statements can (will) be enabled as part of the compiler's legacy Fortran support.
180
181The _assign-stmt_ stores a _label_ in an integer variable.  The _assigned-goto-stmt_ will then transfer control to the _label_ stored in that integer variable.
182
183```fortran
184  ASSIGN 10 TO i
185  ...
186  GOTO i (10,20,30)
187```
188
189##### Semantic Checks
190
191- an _assigned-goto-stmt_ cannot be a _do-term-action-stmt_ (F90:R829)
192- an _assigned-goto-stmt_ cannot be a _do-term-shared-stmt_ (F90:R833)
193- constraints from (F90:R839)
194  - each _label_ in an optional _label-list_ must be the statement label of a branch target statement that appears in the same scoping unit as the _assigned-goto-stmt_
195  - _scalar-int-variable_ (`i` in the example above) must be named and of type default integer
196  - an integer variable that has been assigned a label may only be referenced in an _assigned-goto_ or as a format specifier in an I/O statement
197  - when an I/O statement with a _format-specifier_ that is an integer variable is executed or when an _assigned-goto_ is executed, the variable must have been assigned a _label_
198  - an integer variable can only be assigned a label via the `ASSIGN` statement
199  - the label assigned to the variable must be in the same scoping unit as the _assigned-goto_ that branches to the _label_ value
200  - if the parameterized list of labels is present, the label value assigned to the integer variable must appear in that _label-list_
201  - a distinct _label_ can appear more than once in the _label-list_
202
203Some interpretation is needed as the terms of the older standard are different.
204
205A "scoping unit" is defined as
206  - a derived-type definition
207  - a procedure interface body, excluding derived-types and interfaces contained within it
208  - a program unit or subprogram, excluding derived-types, interfaces, and subprograms contained within it
209
210This is a more lax definition of scope than inclusive scope.
211
212A _named variable_ distinguishes a variable such as, `i`, from an element of an array, `a(i)`, for example.
213
214### Labels used in I/O
215
216#### Data transfer statements
217
218In data transfer (I/O) statements (e.g., `READ`), the user can specify a `FMT=` specifier that can take a label as its argument. (R1215)
219
220##### Semantic Checks
221
222- if the `FMT=` specifier has a label as its argument (C1230)
223  - the label must correspond to a `FORMAT` statement
224    * if the statement is not a `FORMAT`, error statement must be a `FORMAT`
225  - the labelled `FORMAT` statement must be in the same inclusive scope as the originating data transfer statement (also in 2008)
226    * if the label statement does not exist, error label does not exist
227    * if the label statement is not in scope, error label is not in inclusive scope
228  - Exceptions (errors demoted to warnings)
229    - PGI extension: referenced `FORMAT` statements may appear in a host procedure
230    - Possible relaxation: the scope of the referenced `FORMAT` statement may be ignored, allowing a `FORMAT` to be referenced from any scope in the compilation.
231
232### Construct Name generalities
233
234Various Fortran constructs can have names. These include
235  - the `WHERE` construct (10.2.3)
236  - the `FORALL` construct (10.2.4)
237  - the `ASSOCIATE` construct (11.1.3)
238  - the `BLOCK` construct (11.1.4)
239  - the `CHANGE TEAM` construct (11.1.5)
240  - the `CRITICAL` construct (11.1.6)
241  - the `DO` construct (11.1.7)
242  - the `IF` construct (11.1.8)
243  - the `SELECT CASE` construct (11.1.9)
244  - the `SELECT RANK` construct (11.1.10)
245  - the `SELECT TYPE` construct (11.1.11)
246
247#### Semantics Checks
248
249A construct name is a name formed under 6.2.2.  A name is an identifier. Identifiers are parsed by the parser.
250  - the maximum length of a name is 63 characters (C601)
251
252Names must either not be given for the construct or used throughout when specified.
253- if a construct is given a name, the construct's `END` statement must also specify the same name (`WHERE` C1033, `FORALL` C1035, ...)
254- `WHERE` has additional `ELSEWHERE` clauses
255- `IF` has additional `ELSE IF` and `ELSE` clauses
256- `SELECT CASE` has additional `CASE` clauses
257- `SELECT RANK` has additional `RANK` clauses
258- `SELECT TYPE` has additional _type-guard-stmt_
259These additional statements must meet the same constraint as the `END` of the construct. Names must match, if present, or there must be no names for any of the clauses.
260
261### `CYCLE` statement (11.1.7.4.4)
262
263The `CYCLE` statement takes an optional _do-construct-name_.
264
265#### Semantics Checks
266
267- if the `CYCLE` has a _construct-name_, then the `CYCLE` statement must appear within that named _do-construct_ (C1134)
268- if the `CYCLE` does not have a _do-construct-name_, the `CYCLE` statement must appear within a _do-construct_ (C1134)
269
270### `EXIT` statement (11.1.12)
271
272The `EXIT` statement takes an optional _construct-name_.
273
274#### Semantics Checks
275
276- if the `EXIT` has a _construct-name_, then the `EXIT` statement must appear within that named construct (C1166)
277- if the `EXIT` does not have a _construct-name_, the `EXIT` statement must appear within a _do-construct_ (C1166)
278- an _exit-stmt_ must not appear in a `DO CONCURRENT` if the `EXIT` belongs to the `DO CONCURRENT` or an outer construct enclosing the `DO CONCURRENT` (C1167)
279- an _exit-stmt_ must not appear in a `CHANGE TEAM` (`CRITICAL`) if the `EXIT` belongs to an outer construct enclosing the `CHANGE TEAM` (`CRITICAL`) (C1168)
280
281