| ------------------------------------------------------------------------------ |
| -- -- |
| -- GNAT COMPILER COMPONENTS -- |
| -- -- |
| -- S E M _ C H 6 -- |
| -- -- |
| -- S p e c -- |
| -- -- |
| -- Copyright (C) 1992-2025, Free Software Foundation, Inc. -- |
| -- -- |
| -- GNAT is free software; you can redistribute it and/or modify it under -- |
| -- terms of the GNU General Public License as published by the Free Soft- -- |
| -- ware Foundation; either version 3, or (at your option) any later ver- -- |
| -- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- |
| -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- |
| -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -- |
| -- for more details. You should have received a copy of the GNU General -- |
| -- Public License distributed with GNAT; see file COPYING3. If not, go to -- |
| -- http://www.gnu.org/licenses for a complete copy of the license. -- |
| -- -- |
| -- GNAT was originally developed by the GNAT team at New York University. -- |
| -- Extensive contributions were provided by Ada Core Technologies Inc. -- |
| -- -- |
| ------------------------------------------------------------------------------ |
| |
| with Types; use Types; |
| package Sem_Ch6 is |
| |
| type Conformance_Type is |
| (Type_Conformant, Mode_Conformant, Subtype_Conformant, Fully_Conformant); |
| pragma Ordered (Conformance_Type); |
| -- Conformance type used in conformance checks between specs and bodies, |
| -- and for overriding. The literals match the RM definitions of the |
| -- corresponding terms. This is an ordered type, since each conformance |
| -- type is stronger than the ones preceding it. |
| |
| procedure Analyze_Abstract_Subprogram_Declaration (N : Node_Id); |
| procedure Analyze_Expression_Function (N : Node_Id); |
| procedure Analyze_Extended_Return_Statement (N : Node_Id); |
| procedure Analyze_Function_Call (N : Node_Id); |
| procedure Analyze_Operator_Symbol (N : Node_Id); |
| procedure Analyze_Parameter_Association (N : Node_Id); |
| procedure Analyze_Procedure_Call (N : Node_Id); |
| procedure Analyze_Return_When_Statement (N : Node_Id); |
| procedure Analyze_Simple_Return_Statement (N : Node_Id); |
| procedure Analyze_Subprogram_Declaration (N : Node_Id); |
| procedure Analyze_Subprogram_Body (N : Node_Id); |
| |
| function Analyze_Subprogram_Specification (N : Node_Id) return Entity_Id; |
| -- Analyze subprogram specification in both subprogram declarations |
| -- and body declarations. Returns the defining entity for the |
| -- specification N. |
| |
| procedure Analyze_SPARK_Subprogram_Specification (N : Node_Id); |
| -- Check SPARK legality rules that require that the specification has been |
| -- analyzed already. |
| |
| function Can_Override_Operator (Subp : Entity_Id) return Boolean; |
| -- Returns true if Subp can override a predefined operator |
| |
| procedure Check_Conventions (Typ : Entity_Id); |
| -- Ada 2005 (AI-430): Check that the conventions of all inherited and |
| -- overridden dispatching operations of type Typ are consistent with their |
| -- respective counterparts. |
| |
| procedure Check_Delayed_Subprogram (Designator : Entity_Id); |
| -- Designator can be a E_Subprogram_Type, E_Procedure or E_Function. Set |
| -- Has_Delayed_Freeze on Designator if its freezing needs to be delayed. |
| |
| procedure Check_Formal_Subprogram_Conformance |
| (New_Id : Entity_Id; |
| Old_Id : Entity_Id; |
| Err_Loc : Node_Id := Empty); |
| -- Check RM 6.3.1(17/3): the profile of a generic formal subprogram is not |
| -- subtype conformant with any other profile and post an error message if |
| -- either New_Id or Old_Id denotes a formal subprogram, with the flag being |
| -- placed on the Err_Loc node if it is specified, and on New_Id if not. See |
| -- also spec of Check_Fully_Conformant below for New_Id and Old_Id usage. |
| |
| procedure Check_Fully_Conformant |
| (New_Id : Entity_Id; |
| Old_Id : Entity_Id; |
| Err_Loc : Node_Id := Empty); |
| -- Check that two callable entities (subprograms, entries, literals) |
| -- are fully conformant, post error message if not (RM 6.3.1(17)) with |
| -- the flag being placed on the Err_Loc node if it is specified, and |
| -- on the appropriate component of the New_Id construct if not. Note: |
| -- when checking spec/body conformance, New_Id must be the body entity |
| -- and Old_Id is the spec entity (the code in the implementation relies |
| -- on this ordering, and in any case, this makes sense, since if flags |
| -- are to be placed on the construct, they clearly belong on the body. |
| |
| procedure Check_Mode_Conformant |
| (New_Id : Entity_Id; |
| Old_Id : Entity_Id; |
| Err_Loc : Node_Id := Empty; |
| Get_Inst : Boolean := False); |
| -- Check that two callable entities (subprograms, entries, literals) |
| -- are mode conformant, post error message if not (RM 6.3.1(15)) with |
| -- the flag being placed on the Err_Loc node if it is specified, and |
| -- on the appropriate component of the New_Id construct if not. The |
| -- argument Get_Inst is set to True when this is a check against a |
| -- formal access-to-subprogram type, indicating that mapping of types |
| -- is needed. |
| |
| procedure Check_Overriding_Indicator |
| (Subp : Entity_Id; |
| Overridden_Subp : Entity_Id; |
| Is_Primitive : Boolean); |
| -- Verify the consistency of an overriding_indicator given for subprogram |
| -- declaration, body, renaming, or instantiation. Overridden_Subp is set |
| -- if the scope where we are introducing the subprogram contains a |
| -- type-conformant subprogram that becomes hidden by the new subprogram. |
| -- Is_Primitive indicates whether the subprogram is primitive. |
| |
| procedure Check_Subtype_Conformant |
| (New_Id : Entity_Id; |
| Old_Id : Entity_Id; |
| Err_Loc : Node_Id := Empty; |
| Skip_Controlling_Formals : Boolean := False; |
| Get_Inst : Boolean := False); |
| -- Check that two callable entities (subprograms, entries, literals) |
| -- are subtype conformant, post error message if not (RM 6.3.1(16)), |
| -- the flag being placed on the Err_Loc node if it is specified, and |
| -- on the appropriate component of the New_Id construct if not. |
| -- Skip_Controlling_Formals is True when checking the conformance of |
| -- a subprogram that implements an interface operation. In that case, |
| -- only the non-controlling formals can (and must) be examined. The |
| -- argument Get_Inst is set to True when this is a check against a |
| -- formal access-to-subprogram type, indicating that mapping of types |
| -- is needed. |
| |
| procedure Check_Synchronized_Overriding |
| (Def_Id : Entity_Id; |
| Overridden_Subp : out Entity_Id); |
| -- First determine if Def_Id is an entry or a subprogram either defined in |
| -- the scope of a task or protected type, or that is a primitive of such |
| -- a type. Check whether Def_Id overrides a subprogram of an interface |
| -- implemented by the synchronized type, returning the overridden entity |
| -- or Empty. |
| |
| procedure Check_Type_Conformant |
| (New_Id : Entity_Id; |
| Old_Id : Entity_Id; |
| Err_Loc : Node_Id := Empty); |
| -- Check that two callable entities (subprograms, entries, literals) |
| -- are type conformant, post error message if not (RM 6.3.1(14)) with |
| -- the flag being placed on the Err_Loc node if it is specified, and |
| -- on the appropriate component of the New_Id construct if not. |
| |
| function Conforming_Types |
| (T1 : Entity_Id; |
| T2 : Entity_Id; |
| Ctype : Conformance_Type; |
| Get_Inst : Boolean := False) return Boolean; |
| -- Check that the types of two formal parameters are conforming. In most |
| -- cases this is just a name comparison, but within an instance it involves |
| -- generic actual types, and in the presence of anonymous access types |
| -- it must examine the designated types. The argument Get_Inst is set to |
| -- True when this is a check against a formal access-to-subprogram type, |
| -- indicating that mapping of types is needed. |
| |
| procedure Create_Extra_Formals |
| (E : Entity_Id; |
| Related_Nod : Node_Id := Empty); |
| -- For each parameter of a subprogram or entry that requires an additional |
| -- formal (such as for access parameters and indefinite discriminated |
| -- parameters), creates the appropriate formal and attach it to its |
| -- associated parameter. Each extra formal will also be appended to |
| -- the end of Subp's parameter list (with each subsequent extra formal |
| -- being attached to the preceding extra formal). |
| -- |
| -- Related_Nod is the node motivating the frontend call to create the |
| -- extra formals; it is not passed when the node causing the call is E |
| -- (for example, as part of freezing E). Related_Nod provides the context |
| -- where the extra formals are created, and it is used to determine if |
| -- the creation of the extra formals can be deferred when the underlying |
| -- type of some formal (or its return type) is not available, and thus |
| -- improve the support for AI05-0151-1/08. |
| |
| function Extra_Formals_Match_OK |
| (E : Entity_Id; |
| Ref_E : Entity_Id) return Boolean; |
| -- Return True if the extra formals of the given entities match. E is a |
| -- subprogram, and Ref_E is the reference entity that will be used to check |
| -- the extra formals of E: a subprogram type or another subprogram. For |
| -- example, if E is a dispatching primitive of a tagged type then Ref_E |
| -- may be the overridden primitive of its parent type or its ultimate |
| -- renamed entity; however, if E is a subprogram to which 'Access is |
| -- applied then Ref_E is its corresponding subprogram type. Used in |
| -- assertions. |
| |
| function Extra_Formals_OK (E : Entity_Id) return Boolean; |
| -- Return True if the decoration of the attributes associated with extra |
| -- formals are properly set. Used in assertions. |
| |
| function Find_Corresponding_Spec |
| (N : Node_Id; |
| Post_Error : Boolean := True) return Entity_Id; |
| -- Use the subprogram specification in the body to retrieve the previous |
| -- subprogram declaration, if any. |
| |
| procedure Freeze_Extra_Formals (E : Entity_Id); |
| -- Given a subprogram, subprogram type, or entry, flag E to indicate that |
| -- its extra formals (if any) are known (by setting Extra_Formals_Known). |
| -- This subprogram serves three purposes: (1) Document the places where |
| -- the extra formals are known, (2) Ensure that extra formals are added |
| -- only once, and (3) Provide a convenient place for setting a debugger |
| -- breakpoint to locate when extra formals are known. |
| |
| function Fully_Conformant (New_Id, Old_Id : Entity_Id) return Boolean; |
| -- Determine whether two callable entities (subprograms, entries, |
| -- literals) are fully conformant (RM 6.3.1(17)) |
| |
| function Fully_Conformant_Expressions |
| (Given_E1 : Node_Id; |
| Given_E2 : Node_Id; |
| Report : Boolean := False) return Boolean; |
| -- Determines if two (non-empty) expressions are fully conformant |
| -- as defined by (RM 6.3.1(18-21)) |
| |
| function Fully_Conformant_Discrete_Subtypes |
| (Given_S1 : Node_Id; |
| Given_S2 : Node_Id) return Boolean; |
| -- Determines if two subtype definitions are fully conformant. Used |
| -- for entry family conformance checks (RM 6.3.1 (24)). |
| |
| function Has_BIP_Formals (E : Entity_Id) return Boolean; |
| -- Determines if a given entity has build-in-place formals |
| |
| procedure Install_Entity (E : Entity_Id); |
| -- Place a single entity on the visibility chain |
| |
| procedure Install_Formals (Id : Entity_Id); |
| -- On entry to a subprogram body, make the formals visible. Note that |
| -- simply placing the subprogram on the scope stack is not sufficient: |
| -- the formals must become the current entities for their names. This |
| -- procedure is also used to get visibility to the formals when analyzing |
| -- preconditions and postconditions appearing in the spec. |
| |
| function Is_Interface_Conformant |
| (Tagged_Type : Entity_Id; |
| Iface_Prim : Entity_Id; |
| Prim : Entity_Id) return Boolean; |
| -- Returns true if both primitives have a matching name (including support |
| -- for names of inherited private primitives --which have suffix 'P'), they |
| -- are type conformant, and Prim is defined in the scope of Tagged_Type. |
| -- Special management is done for functions returning interfaces. |
| |
| procedure List_Inherited_Pre_Post_Aspects (E : Entity_Id); |
| -- E is the entity for a subprogram or generic subprogram spec. This call |
| -- lists all inherited Pre/Post aspects if List_Inherited_Pre_Post is True. |
| |
| procedure May_Need_Actuals (Fun : Entity_Id); |
| -- Flag functions that can be called without parameters, i.e. those that |
| -- have no parameters, or those for which defaults exist for all parameters |
| -- Used for subprogram declarations and for access subprogram declarations, |
| -- where they apply to the anonymous designated type. On return the flag |
| -- Set_Needs_No_Actuals is set appropriately in Fun. |
| |
| function Mode_Conformant (New_Id, Old_Id : Entity_Id) return Boolean; |
| -- Determine whether two callable entities (subprograms, entries, |
| -- literals) are mode conformant (RM 6.3.1(15)) |
| |
| procedure New_Overloaded_Entity |
| (S : Entity_Id; |
| Derived_Type : Entity_Id := Empty); |
| -- Process new overloaded entity. Overloaded entities are created by |
| -- enumeration type declarations, subprogram specifications, entry |
| -- declarations, and (implicitly) by type derivations. If Derived_Type |
| -- is non-empty then this is a subprogram derived for that type. |
| |
| procedure Process_Formals (T : List_Id; Related_Nod : Node_Id); |
| -- Enter the formals in the scope of the subprogram or entry, and |
| -- analyze default expressions if any. The implicit types created for |
| -- access parameter are attached to the Related_Nod which comes from the |
| -- context. |
| |
| procedure Reference_Body_Formals (Spec : Entity_Id; Bod : Entity_Id); |
| -- If there is a separate spec for a subprogram or generic subprogram, the |
| -- formals of the body are treated as references to the corresponding |
| -- formals of the spec. This reference does not count as an actual use of |
| -- the formal, in order to diagnose formals that are unused in the body. |
| -- This procedure is also used in renaming_as_body declarations, where |
| -- the formals of the specification must be treated as body formals that |
| -- correspond to the previous subprogram declaration, and not as new |
| -- entities with their defining entry in the cross-reference information. |
| |
| procedure Set_Actual_Subtypes (N : Node_Id; Subp : Entity_Id); |
| -- If the formals of a subprogram are unconstrained, build a subtype |
| -- declaration that uses the bounds or discriminants of the actual to |
| -- construct an actual subtype for them. This is an optimization that |
| -- is done only in some cases where the actual subtype cannot change |
| -- during execution of the subprogram. By setting the actual subtype |
| -- once, we avoid recomputing it unnecessarily. |
| |
| function Subtype_Conformant |
| (New_Id : Entity_Id; |
| Old_Id : Entity_Id; |
| Skip_Controlling_Formals : Boolean := False) return Boolean; |
| -- Determine whether two callable entities (subprograms, entries, literals) |
| -- are subtype conformant (RM 6.3.1(16)). Skip_Controlling_Formals is True |
| -- when checking the conformance of a subprogram that implements an |
| -- interface operation. In that case, only the non-controlling formals |
| -- can (and must) be examined. |
| |
| function Type_Conformant |
| (New_Id : Entity_Id; |
| Old_Id : Entity_Id; |
| Skip_Controlling_Formals : Boolean := False) return Boolean; |
| -- Determine whether two callable entities (subprograms, entries, literals) |
| -- are type conformant (RM 6.3.1(14)). Skip_Controlling_Formals is True |
| -- when checking the conformance of a subprogram that implements an |
| -- interface operation. In that case, only the non-controlling formals |
| -- can (and must) be examined. |
| |
| procedure Valid_Operator_Definition (Designator : Entity_Id); |
| -- Verify that an operator definition has the proper number of formals |
| |
| ------------------------------------ |
| -- Deferred_Extra_Formals_Support -- |
| ------------------------------------ |
| |
| -- This package provides support for deferring the addition of extra |
| -- formals to subprograms, entries, and subprogram types; it also provides |
| -- support for deferring the addition of extra actuals to direct calls to |
| -- subprograms and entries, and indirect calls through subprogram types. |
| -- The addition of the extra formals and actuals is deferred until the |
| -- underlying type of all the parameters and result types of registered |
| -- subprograms, entries, and subprogram types is known. |
| |
| -- Functional Description |
| -- ---------------------- |
| -- |
| -- When Create_Extra_Formals identifies that the underlying type of |
| -- some parameter or result type of an entity E is not available, E is |
| -- registered by this package, and the addition of its extra formals is |
| -- deferred. As part of this registration, the types of all the params |
| -- and result types of E with no underlying type are also registered. |
| -- |
| -- When Expand_Call_Helper identifies that the underlying type of some |
| -- parameter or result type of a called entity is not available, the call |
| -- is registered by Register_Deferred_Extra_Formals_Call, and the addition |
| -- of its extra actuals is deferred. |
| -- |
| -- When the full type declaration of some registered type T is analyzed, |
| -- the subprogram Add_Deferred_Extra_Params is invoked; this subprogram |
| -- does the following actions: |
| -- 1) Check all the registered entities (subprograms, entries, and |
| -- subprogram types); for each registered entity that has all its |
| -- underlying types available, call Create_Extra_Formals, and |
| -- unregister the entity. |
| -- 2) Check all the registered calls; for each registered call that |
| -- has available the underlying type of all the parameters and result |
| -- types of the called entity, call Create_Extra_Actuals, and |
| -- unregister the call. |
| -- 3) Unregister T. |
| -- |
| -- Example 1 |
| -- --------- |
| -- A package spec has a private type declaration T, and declarations of |
| -- expression functions and/or primitives with class-wide conditions |
| -- invoking primitives of type T before the full view of T is defined. |
| -- |
| -- As part of processing the early freezing of the called subprograms |
| -- (and as part of processing the calls) the functions are registered as |
| -- subprograms with deferred extra formals, and the calls are registered |
| -- as calls with deferred extra actuals. |
| -- |
| -- When the full type declaration of T is analyzed, extra formals are |
| -- added to all the registered subprograms, and extra actuals are added |
| -- to all the registered calls with deferred extra actuals. |
| -- |
| -- Example 2 |
| -- --------- |
| -- The specification of package P has a limited_with_clause on package Q, |
| -- and the type of the formals of subprograms defined in P are types |
| -- defined in Q. |
| -- |
| -- When compiling the spec of P, similarly to the previous example, |
| -- subprograms with incomplete formals are registered as subprograms |
| -- with deferred extra formals; if the spec of P has calls to these |
| -- subprograms, then these calls are registered as calls with deferred |
| -- extra actuals. That is, when the analysis of package P completes, |
| -- deferred extra formals and actuals have not been added. |
| -- |
| -- When another compilation unit is analyzed (including the body of |
| -- package P), and a regular with-clause on Q is processed, when the |
| -- full type declaration of deferred entities is analyzed, deferred |
| -- extra formals and deferred extra actuals are added. |
| -- |
| -- This machinery relies on the GNAT Compilation Model; that is, when |
| -- we analyze the spec of P (for which we generally don't generate code), |
| -- it is safe to complete the compilation and still have entities with |
| -- deferred extra formals, and calls with deferred extra actuals. |
| -- |
| -- The body package P generally has a regular with-clause on package Q. |
| -- Hence, when we compile the body of package P, the implicit dependence |
| -- on its package spec causes the analysis of the spec of P (thus |
| -- registering deferred entities), followed by the analysis of context |
| -- clauses in the body of P. When the regular with-clause on package Q |
| -- is analyzed, we add the extra formals and extra actuals to deferred |
| -- entities. Thus, the generated code will have all the needed formals. |
| -- |
| -- The (still) unsupported case is when the body of package P does not |
| -- have a regular with-clause on package Q (AI05-0151-1/08). This case |
| -- is left documented in the front-end sources by means of calls to |
| -- the following subprograms: Is_Unsupported_Extra_Formals_Entity, and |
| -- Is_Unsupported_Extra_Actuals_Call. |
| |
| package Deferred_Extra_Formals_Support is |
| |
| procedure Add_Deferred_Extra_Params (Typ : Entity_Id); |
| -- Check all the registered subprograms, entries, and subprogram types |
| -- with deferred addition of their extra formals; if the underlying |
| -- types of all their formals is available then add their extra formals. |
| -- Check also all the registered calls with deferred addition of their |
| -- extra actuals; add their extra actuals if the underlying types of all |
| -- their parameters and result types are available. Finally unregister |
| -- Typ from the list of types used for the deferral of extra formals/ |
| -- actuals. |
| |
| procedure Register_Deferred_Extra_Formals_Entity (Id : Entity_Id); |
| -- Register the given subprogram, entry, or subprogram type to defer the |
| -- addition of its extra formals. |
| |
| procedure Register_Deferred_Extra_Formals_Call |
| (Call_Node : Node_Id; |
| Scope_Id : Entity_Id); |
| -- Register the given call, performed from the given scope, to defer the |
| -- addition of its extra actuals. |
| |
| function Has_Deferred_Extra_Formals (Typ : Entity_Id) return Boolean; |
| -- Return True if there some registered subprogram, subprogram type, or |
| -- entry with deferred extra formals that has some formal type or |
| -- result type of type Typ (i.e. which depends on the given type to |
| -- add its extra formals). |
| |
| function Is_Deferred_Extra_Formals_Entity |
| (Id : Entity_Id) return Boolean; |
| -- Return True if Id is a subprogram, subprogram type, or entry that has |
| -- been registered to defer the addition of its extra formals. |
| |
| function Is_Unsupported_Extra_Formals_Entity |
| (Id : Entity_Id; |
| Related_Nod : Node_Id := Empty) return Boolean; |
| -- Id is a subprogram, subprogram type, or entry. Return True if Id is |
| -- unsupported for deferring the addition of its extra formals; that is, |
| -- it is defined in a compilation unit that is a package body or a |
| -- subprogram body, and the underlying type of some of its parameters |
| -- or result type is not available. Related_Nod is the node where this |
| -- check is performed (it is generally a subprogram call); if it is not |
| -- available then the location of entity Id is used as its related node. |
| -- |
| -- The context for this case is an unsupported case of AI05-0151-1/08 |
| -- that allows incomplete tagged types as parameter and result types. |
| -- More concretely, a type T is visible in a package spec through a |
| -- limited_with_clause, and the body of the package has no regular |
| -- with_clause. In such a case, the machinery for deferring the |
| -- addition of extra formals does not work because the underlying |
| -- type of the type is not seen during the compilation of the |
| -- package body. |
| -- |
| -- The purpose of this function is to facilitate locating in the sources |
| -- the places where the front end performs the current (incomplete) |
| -- management of such case (to facilitate further work) ??? |
| |
| function Is_Unsupported_Extra_Actuals_Call |
| (Call_Node : Node_Id; Id : Entity_Id) return Boolean; |
| -- Same as previous function but applicable to a call to the given |
| -- entity Id. |
| |
| end Deferred_Extra_Formals_Support; |
| |
| end Sem_Ch6; |
