[flang][NFC] Add GetTopLevelUnitContaining functions

[tskeith]

Summary

GetTopLevelUnitContaining returns the Scope nested in the global scope
that contains the given Scope or Symbol.

Use "Get" rather than "Find" in the name because "Find" implies it might
not be found, which can't happen. Following that logic, rename
FindProgramUnitContaining to GetProgramUnitContaining and have it
also return a reference rather that a pointer.

Note that the use of "ProgramUnit" is slightly confusing. In the Fortran
standard, "program-unit" refers to what is called a "TopLevelUnit" here.
What we are calling a "ProgramUnit" (here and in ProgramTree) includes
internal subprograms while "TopLevelUnit" does not.

[PeteSteinfeld]

All builds, tests, and looks good.

[klausler]

flang/include/flang/Semantics/tools.h

33

"top level unit" is self-defining and I like it. Can we avoid "program unit" altogether, though? (It can't be "subprogram", either.)

[tskeith]

flang/include/flang/Semantics/tools.h

33

Avoiding "program unit" would be good but I haven't been able to come up with a better term.

flang/include/flang/Semantics/tools.h

 
 namespace Fortran::semantics {
 
 class DeclTypeSpec;
 class DerivedTypeSpec;
 class Scope;
 class Symbol;
 
+// Note: Here ProgramUnit includes internal subprograms while TopLevelUnit
+// does not. "program-unit" in the Fortran standard matches TopLevelUnit.
+const Scope &GetTopLevelUnitContaining(const Scope &);
+const Scope &GetTopLevelUnitContaining(const Symbol &);
+const Scope &GetProgramUnitContaining(const Scope &);
+const Scope &GetProgramUnitContaining(const Symbol &);
+
 const Scope *FindModuleContaining(const Scope &);
-const Scope *FindProgramUnitContaining(const Scope &);
-const Scope *FindProgramUnitContaining(const Symbol &);
 const Scope *FindPureProcedureContaining(const Scope &);
 const Scope *FindPureProcedureContaining(const Symbol &);
 const Symbol *FindPointerComponent(const Scope &);
 const Symbol *FindPointerComponent(const DerivedTypeSpec &);
 const Symbol *FindPointerComponent(const DeclTypeSpec &);
 const Symbol *FindPointerComponent(const Symbol &);
 const Symbol *FindInterface(const Symbol &);
 const Symbol *FindSubprogram(const Symbol &);

flang/lib/Semantics/check-return.cpp

 #include "flang/Parser/message.h"
 #include "flang/Parser/parse-tree.h"
 #include "flang/Semantics/semantics.h"
 #include "flang/Semantics/tools.h"
 
 namespace Fortran::semantics {
 
 static const Scope *FindContainingSubprogram(const Scope &start) {
-  const Scope *scope{FindProgramUnitContaining(start)};
-  return scope &&
-          (scope->kind() == Scope::Kind::MainProgram ||
-              scope->kind() == Scope::Kind::Subprogram)
-      ? scope
+  const Scope &scope{GetProgramUnitContaining(start)};
+  return scope.kind() == Scope::Kind::MainProgram ||
+          scope.kind() == Scope::Kind::Subprogram
+      ? &scope
       : nullptr;
 }
 
 void ReturnStmtChecker::Leave(const parser::ReturnStmt &returnStmt) {
   // R1542 Expression analysis validates the scalar-int-expr
   // C1574 The return-stmt shall be in the inclusive scope of a function or
   // subroutine subprogram.
   // C1575 The scalar-int-expr is allowed only in the inclusive scope of a

flang/lib/Semantics/resolve-names.cpp

if (isImplicitNoneType()) {
     symbol.get<HostAssocDetails>().implicitOrExplicitTypeError = true;
   } else {
     symbol.get<HostAssocDetails>().implicitOrSpecExprError = true;
   }
   return true;
 }
 
 bool DeclarationVisitor::IsUplevelReference(const Symbol &symbol) {
-  const Scope *symbolUnit{FindProgramUnitContaining(symbol)};
-  if (symbolUnit == FindProgramUnitContaining(currScope())) {
+  const Scope &symbolUnit{GetProgramUnitContaining(symbol)};
+  if (symbolUnit == GetProgramUnitContaining(currScope())) {
     return false;
   } else {
-    Scope::Kind kind{DEREF(symbolUnit).kind()};
+    Scope::Kind kind{symbolUnit.kind()};
     return kind == Scope::Kind::Subprogram || kind == Scope::Kind::MainProgram;
   }
 }
 
 // base is a part-ref of a derived type; find the named component in its type.
 // Also handles intrinsic type parameter inquiries (%kind, %len) and
 // COMPLEX component references (%re, %im).
 const parser::Name *DeclarationVisitor::FindComponent(

flang/lib/Semantics/tools.cpp

if (predicate(*scope)) {
       return scope;
     }
     if (scope->IsGlobal()) {
       return nullptr;
     }
   }
 }
 
+const Scope &GetTopLevelUnitContaining(const Scope &start) {
+  CHECK(!start.IsGlobal());
+  return DEREF(FindScopeContaining(
+      start, [](const Scope &scope) { return scope.parent().IsGlobal(); }));
+}
+
+const Scope &GetTopLevelUnitContaining(const Symbol &symbol) {
+  return GetTopLevelUnitContaining(symbol.owner());
+}
+
 const Scope *FindModuleContaining(const Scope &start) {
   return FindScopeContaining(
       start, [](const Scope &scope) { return scope.IsModule(); });
 }
 
-const Scope *FindProgramUnitContaining(const Scope &start) {
-  return FindScopeContaining(start, [](const Scope &scope) {
+const Scope &GetProgramUnitContaining(const Scope &start) {
+  CHECK(!start.IsGlobal());
+  return DEREF(FindScopeContaining(start, [](const Scope &scope) {
     switch (scope.kind()) {
     case Scope::Kind::Module:
     case Scope::Kind::MainProgram:
     case Scope::Kind::Subprogram:
     case Scope::Kind::BlockData:
       return true;
     default:
       return false;
     }
-  });
+  }));
 }
 
-const Scope *FindProgramUnitContaining(const Symbol &symbol) {
-  return FindProgramUnitContaining(symbol.owner());
+const Scope &GetProgramUnitContaining(const Symbol &symbol) {
+  return GetProgramUnitContaining(symbol.owner());
 }
 
 const Scope *FindPureProcedureContaining(const Scope &start) {
   // N.B. We only need to examine the innermost containing program unit
   // because an internal subprogram of a pure subprogram must also
   // be pure (C1592).
-  if (const Scope * scope{FindProgramUnitContaining(start)}) {
-    if (IsPureProcedure(*scope)) {
-      return scope;
-    }
-  }
-  return nullptr;
+  const Scope &scope{GetProgramUnitContaining(start)};
+  return IsPureProcedure(scope) ? &scope : nullptr;
 }
 
 Tristate IsDefinedAssignment(
     const std::optional<evaluate::DynamicType> &lhsType, int lhsRank,
     const std::optional<evaluate::DynamicType> &rhsType, int rhsRank) {
   if (!lhsType || !rhsType) {
     return Tristate::No; // error or rhs is untyped
   }

 
 bool IsCommonBlockContaining(const Symbol &block, const Symbol &object) {
   const auto &objects{block.get<CommonBlockDetails>().objects()};
   auto found{std::find(objects.begin(), objects.end(), object)};
   return found != objects.end();
 }
 
 bool IsUseAssociated(const Symbol &symbol, const Scope &scope) {
-  const Scope *owner{FindProgramUnitContaining(symbol.GetUltimate().owner())};
-  return owner && owner->kind() == Scope::Kind::Module &&
-      owner != FindProgramUnitContaining(scope);
+  const Scope &owner{GetProgramUnitContaining(symbol.GetUltimate().owner())};
+  return owner.kind() == Scope::Kind::Module &&
+      owner != GetProgramUnitContaining(scope);
 }
 
 bool DoesScopeContain(
     const Scope *maybeAncestor, const Scope &maybeDescendent) {
   return maybeAncestor && !maybeDescendent.IsGlobal() &&
       FindScopeContaining(maybeDescendent.parent(),
           [&](const Scope &scope) { return &scope == maybeAncestor; });
 }
 
 bool DoesScopeContain(const Scope *maybeAncestor, const Symbol &symbol) {
   return DoesScopeContain(maybeAncestor, symbol.owner());
 }
 
 static const Symbol &FollowHostAssoc(const Symbol &symbol) {
   for (const Symbol *s{&symbol};;) {
     const auto *details{s->detailsIf<HostAssocDetails>()};
     if (!details) {
       return *s;
     }
     s = &details->symbol();
   }
 }
 
 bool IsHostAssociated(const Symbol &symbol, const Scope &scope) {
-  const Scope *subprogram{FindProgramUnitContaining(scope)};
-  return subprogram &&
-      DoesScopeContain(
-          FindProgramUnitContaining(FollowHostAssoc(symbol)), *subprogram);
+  const Scope &subprogram{GetProgramUnitContaining(scope)};
+  return DoesScopeContain(
+      &GetProgramUnitContaining(FollowHostAssoc(symbol)), subprogram);
 }
 
 bool IsInStmtFunction(const Symbol &symbol) {
   if (const Symbol * function{symbol.owner().symbol()}) {
     return IsStmtFunction(*function);
   }
   return false;
 }