gcc/ada/sem_aux.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                              S E M _ A U X                               --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2020, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  17 -- for  more details.  You should have  received  a copy of the GNU General --
  18 -- Public License  distributed with GNAT; see file COPYING3.  If not, go to --
  19 -- http://www.gnu.org/licenses for a complete copy of the license.          --
  20 --                                                                          --
  21 -- GNAT was originally developed  by the GNAT team at  New York University. --
  22 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  23 --                                                                          --
  24 ------------------------------------------------------------------------------
  25
  26 --  Package containing utility procedures used throughout the compiler.
  27
  28 --  Historical note. Many of the routines here were originally in Einfo, but
  29 --  Einfo is supposed to be a relatively low level package dealing with the
  30 --  content of entities in the tree, so this package is used for routines that
  31 --  require more than minimal semantic knowledge.
  32
  33 with Alloc;
  34 with Namet; use Namet;
  35 with Table;
  36 with Types; use Types;
  37 with Sinfo; use Sinfo;
  38
  39 package Sem_Aux is
  40
  41    --------------------------------
  42    -- Obsolescent Warnings Table --
  43    --------------------------------
  44
  45    --  This table records entities for which a pragma Obsolescent with a
  46    --  message argument has been processed.
  47
  48    type OWT_Record is record
  49       Ent : Entity_Id;
  50       --  The entity to which the pragma applies
  51
  52       Msg : String_Id;
  53       --  The string containing the message
  54    end record;
  55
  56    package Obsolescent_Warnings is new Table.Table (
  57      Table_Component_Type => OWT_Record,
  58      Table_Index_Type     => Int,
  59      Table_Low_Bound      => 0,
  60      Table_Initial        => Alloc.Obsolescent_Warnings_Initial,
  61      Table_Increment      => Alloc.Obsolescent_Warnings_Increment,
  62      Table_Name           => "Obsolescent_Warnings");
  63
  64    procedure Initialize;
  65    --  Called at the start of compilation of each new main source file to
  66    --  initialize the allocation of the Obsolescent_Warnings table.
  67
  68    -----------------
  69    -- Subprograms --
  70    -----------------
  71
  72    function Ancestor_Subtype (Typ : Entity_Id) return Entity_Id;
  73    --  The argument Typ is a type or subtype entity. If the argument is a
  74    --  subtype then it returns the subtype or type from which the subtype was
  75    --  obtained, otherwise it returns Empty.
  76
  77    --  WARNING: There is a matching C declaration of this subprogram in fe.h
  78
  79    function Available_View (Ent : Entity_Id) return Entity_Id;
  80    --  Ent denotes an abstract state or a type that may come from a limited
  81    --  with clause. Return the non-limited view of Ent if there is one or Ent
  82    --  if this is not the case.
  83
  84    function Constant_Value (Ent : Entity_Id) return Node_Id;
  85    --  Ent is a variable, constant, named integer, or named real entity. This
  86    --  call obtains the initialization expression for the entity. Will return
  87    --  Empty for a deferred constant whose full view is not available or
  88    --  in some other cases of internal entities, which cannot be treated as
  89    --  constants from the point of view of constant folding. Empty is also
  90    --  returned for variables with no initialization expression.
  91
  92    --  WARNING: There is a matching C declaration of this subprogram in fe.h
  93
  94    function Corresponding_Unsigned_Type (Typ : Entity_Id) return Entity_Id;
  95    --  Typ is a signed integer subtype. This routine returns the standard
  96    --  unsigned type with the same Esize as the implementation base type of
  97    --  Typ, e.g. Long_Integer => Long_Unsigned.
  98
  99    function Enclosing_Dynamic_Scope (Ent : Entity_Id) return Entity_Id;
 100    --  For any entity, Ent, returns the closest dynamic scope in which the
 101    --  entity is declared or Standard_Standard for library-level entities.
 102
 103    function First_Discriminant (Typ : Entity_Id) return Entity_Id;
 104    --  Typ is a type with discriminants. The discriminants are the first
 105    --  entities declared in the type, so normally this is equivalent to
 106    --  First_Entity. The exception arises for tagged types, where the tag
 107    --  itself is prepended to the front of the entity chain, so the
 108    --  First_Discriminant function steps past the tag if it is present.
 109    --  The caller is responsible for checking that the type has discriminants.
 110    --  When called on a private type with unknown discriminants, the function
 111    --  always returns Empty.
 112
 113    --  WARNING: There is a matching C declaration of this subprogram in fe.h
 114
 115    function First_Stored_Discriminant (Typ : Entity_Id) return Entity_Id;
 116    --  Typ is a type with discriminants. Gives the first discriminant stored
 117    --  in an object of this type. In many cases, these are the same as the
 118    --  normal visible discriminants for the type, but in the case of renamed
 119    --  discriminants, this is not always the case.
 120    --
 121    --  For tagged types, and untagged types which are root types or derived
 122    --  types but which do not rename discriminants in their root type, the
 123    --  stored discriminants are the same as the actual discriminants of the
 124    --  type, and hence this function is the same as First_Discriminant.
 125    --
 126    --  For derived untagged types that rename discriminants in the root type
 127    --  this is the first of the discriminants that occur in the root type. To
 128    --  be precise, in this case stored discriminants are entities attached to
 129    --  the entity chain of the derived type which are a copy of the
 130    --  discriminants of the root type. Furthermore their Is_Completely_Hidden
 131    --  flag is set since although they are actually stored in the object, they
 132    --  are not in the set of discriminants that is visible in the type.
 133    --
 134    --  For derived untagged types, the set of stored discriminants are the real
 135    --  discriminants from Gigi's standpoint, i.e. those that will be stored in
 136    --  actual objects of the type.
 137
 138    --  WARNING: There is a matching C declaration of this subprogram in fe.h
 139
 140    function First_Subtype (Typ : Entity_Id) return Entity_Id;
 141    --  Applies to all types and subtypes. For types, yields the first subtype
 142    --  of the type. For subtypes, yields the first subtype of the base type of
 143    --  the subtype.
 144
 145    --  WARNING: There is a matching C declaration of this subprogram in fe.h
 146
 147    function First_Tag_Component (Typ : Entity_Id) return Entity_Id;
 148    --  Typ must be a tagged record type. This function returns the Entity for
 149    --  the first _Tag field in the record type.
 150
 151    function Get_Binary_Nkind (Op : Entity_Id) return Node_Kind;
 152    --  Op must be an entity with an Ekind of E_Operator. This function returns
 153    --  the Nkind value that would be used to construct a binary operator node
 154    --  referencing this entity. It is an error to call this function if Ekind
 155    --  (Op) /= E_Operator.
 156
 157    function Get_Called_Entity (Call : Node_Id) return Entity_Id;
 158    --  Obtain the entity of the entry, operator, or subprogram being invoked
 159    --  by call Call.
 160
 161    function Get_Unary_Nkind (Op : Entity_Id) return Node_Kind;
 162    --  Op must be an entity with an Ekind of E_Operator. This function returns
 163    --  the Nkind value that would be used to construct a unary operator node
 164    --  referencing this entity. It is an error to call this function if Ekind
 165    --  (Op) /= E_Operator.
 166
 167    function Get_Rep_Item
 168      (E             : Entity_Id;
 169       Nam           : Name_Id;
 170       Check_Parents : Boolean := True) return Node_Id;
 171    --  Searches the Rep_Item chain for a given entity E, for an instance of a
 172    --  rep item (pragma, attribute definition clause, or aspect specification)
 173    --  whose name matches the given name Nam. If Check_Parents is False then it
 174    --  only returns rep item that has been directly specified for E (and not
 175    --  inherited from its parents, if any). If one is found, it is returned,
 176    --  otherwise Empty is returned. A special case is that when Nam is
 177    --  Name_Priority, the call will also find Interrupt_Priority.
 178
 179    function Get_Rep_Item
 180      (E             : Entity_Id;
 181       Nam1          : Name_Id;
 182       Nam2          : Name_Id;
 183       Check_Parents : Boolean := True) return Node_Id;
 184    --  Searches the Rep_Item chain for a given entity E, for an instance of a
 185    --  rep item (pragma, attribute definition clause, or aspect specification)
 186    --  whose name matches one of the given names Nam1 or Nam2. If Check_Parents
 187    --  is False then it only returns rep item that has been directly specified
 188    --  for E (and not inherited from its parents, if any). If one is found, it
 189    --  is returned, otherwise Empty is returned. A special case is that when
 190    --  one of the given names is Name_Priority, the call will also find
 191    --  Interrupt_Priority.
 192
 193    function Get_Rep_Pragma
 194      (E             : Entity_Id;
 195       Nam           : Name_Id;
 196       Check_Parents : Boolean := True) return Node_Id;
 197    --  Searches the Rep_Item chain for a given entity E, for an instance of a
 198    --  representation pragma whose name matches the given name Nam. If
 199    --  Check_Parents is False then it only returns representation pragma that
 200    --  has been directly specified for E (and not inherited from its parents,
 201    --  if any). If one is found and if it is the first rep item in the list
 202    --  that matches Nam, it is returned, otherwise Empty is returned. A special
 203    --  case is that when Nam is Name_Priority, the call will also find
 204    --  Interrupt_Priority.
 205
 206    function Get_Rep_Pragma
 207      (E             : Entity_Id;
 208       Nam1          : Name_Id;
 209       Nam2          : Name_Id;
 210       Check_Parents : Boolean := True) return Node_Id;
 211    --  Searches the Rep_Item chain for a given entity E, for an instance of a
 212    --  representation pragma whose name matches one of the given names Nam1 or
 213    --  Nam2. If Check_Parents is False then it only returns representation
 214    --  pragma that has been directly specified for E (and not inherited from
 215    --  its parents, if any). If one is found and if it is the first rep item in
 216    --  the list that matches one of the given names, it is returned, otherwise
 217    --  Empty is returned. A special case is that when one of the given names is
 218    --  Name_Priority, the call will also find Interrupt_Priority.
 219
 220    function Has_Rep_Item
 221      (E             : Entity_Id;
 222       Nam           : Name_Id;
 223       Check_Parents : Boolean := True) return Boolean;
 224    --  Searches the Rep_Item chain for the given entity E, for an instance of a
 225    --  rep item (pragma, attribute definition clause, or aspect specification)
 226    --  with the given name Nam. If Check_Parents is False then it only checks
 227    --  for a rep item that has been directly specified for E (and not inherited
 228    --  from its parents, if any). If found then True is returned, otherwise
 229    --  False indicates that no matching entry was found.
 230
 231    function Has_Rep_Item
 232      (E             : Entity_Id;
 233       Nam1          : Name_Id;
 234       Nam2          : Name_Id;
 235       Check_Parents : Boolean := True) return Boolean;
 236    --  Searches the Rep_Item chain for the given entity E, for an instance of a
 237    --  rep item (pragma, attribute definition clause, or aspect specification)
 238    --  with the given names Nam1 or Nam2. If Check_Parents is False then it
 239    --  only checks for a rep item that has been directly specified for E (and
 240    --  not inherited from its parents, if any). If found then True is returned,
 241    --  otherwise False indicates that no matching entry was found.
 242
 243    function Has_Rep_Pragma
 244      (E             : Entity_Id;
 245       Nam           : Name_Id;
 246       Check_Parents : Boolean := True) return Boolean;
 247    --  Searches the Rep_Item chain for the given entity E, for an instance of a
 248    --  representation pragma with the given name Nam. If Check_Parents is False
 249    --  then it only checks for a representation pragma that has been directly
 250    --  specified for E (and not inherited from its parents, if any). If found
 251    --  and if it is the first rep item in the list that matches Nam then True
 252    --  is returned, otherwise False indicates that no matching entry was found.
 253
 254    function Has_Rep_Pragma
 255      (E             : Entity_Id;
 256       Nam1          : Name_Id;
 257       Nam2          : Name_Id;
 258       Check_Parents : Boolean := True) return Boolean;
 259    --  Searches the Rep_Item chain for the given entity E, for an instance of a
 260    --  representation pragma with the given names Nam1 or Nam2. If
 261    --  Check_Parents is False then it only checks for a rep item that has been
 262    --  directly specified for E (and not inherited from its parents, if any).
 263    --  If found and if it is the first rep item in the list that matches one of
 264    --  the given names then True is returned, otherwise False indicates that no
 265    --  matching entry was found.
 266
 267    function Has_External_Tag_Rep_Clause (T : Entity_Id) return Boolean;
 268    --  Defined in tagged types. Set if an External_Tag rep. clause has been
 269    --  given for this type. Use to avoid the generation of the default
 270    --  External_Tag.
 271    --
 272    --  Note: we used to use an entity flag for this purpose, but that was wrong
 273    --  because it was not propagated from the private view to the full view. We
 274    --  could have added that propagation, but it would have been an annoying
 275    --  irregularity compared to other representation aspects, and the cost of
 276    --  looking up the aspect when needed is small.
 277
 278    function Has_Unconstrained_Elements (T : Entity_Id) return Boolean;
 279    --  True if T has discriminants and is unconstrained, or is an array type
 280    --  whose element type Has_Unconstrained_Elements.
 281
 282    function Has_Variant_Part (Typ : Entity_Id) return Boolean;
 283    --  Return True if the first subtype of Typ is a discriminated record type
 284    --  which has a variant part. False otherwise.
 285
 286    function In_Generic_Body (Id : Entity_Id) return Boolean;
 287    --  Determine whether entity Id appears inside a generic body
 288
 289    function Initialization_Suppressed (Typ : Entity_Id) return Boolean;
 290    pragma Inline (Initialization_Suppressed);
 291    --  Returns True if initialization should be suppressed for the given type
 292    --  or subtype. This is true if Suppress_Initialization is set either for
 293    --  the subtype itself, or for the corresponding base type.
 294
 295    function Is_Body (N : Node_Id) return Boolean;
 296    --  Determine whether an arbitrary node denotes a body
 297
 298    function Is_By_Copy_Type (Ent : Entity_Id) return Boolean;
 299    --  Ent is any entity. Returns True if Ent is a type entity where the type
 300    --  is required to be passed by copy, as defined in (RM 6.2(3)).
 301
 302    function Is_By_Reference_Type (Ent : Entity_Id) return Boolean;
 303    --  Ent is any entity. Returns True if Ent is a type entity where the type
 304    --  is required to be passed by reference, as defined in (RM 6.2(4-9)).
 305
 306    --  WARNING: There is a matching C declaration of this subprogram in fe.h
 307
 308    function Is_Definite_Subtype (T : Entity_Id) return Boolean;
 309    --  T is a type entity. Returns True if T is a definite subtype.
 310    --  Indefinite subtypes are unconstrained arrays, unconstrained
 311    --  discriminated types without defaulted discriminants, class-wide types,
 312    --  and types with unknown discriminants. Definite subtypes are all others
 313    --  (elementary, constrained composites (including the case of records
 314    --  without discriminants), and types with defaulted discriminants).
 315
 316    function Is_Derived_Type (Ent : Entity_Id) return Boolean;
 317    --  Determines if the given entity Ent is a derived type. Result is always
 318    --  false if argument is not a type.
 319
 320    --  WARNING: There is a matching C declaration of this subprogram in fe.h
 321
 322    function Is_Generic_Formal (E : Entity_Id) return Boolean;
 323    --  Determine whether E is a generic formal parameter. In particular this is
 324    --  used to set the visibility of generic formals of a generic package
 325    --  declared with a box or with partial parameterization.
 326
 327    function Is_Immutably_Limited_Type (Ent : Entity_Id) return Boolean;
 328    --  Implements definition in Ada 2012 RM-7.5 (8.1/3). This differs from the
 329    --  following predicate in that an untagged record with immutably limited
 330    --  components is NOT by itself immutably limited. This matters, e.g. when
 331    --  checking the legality of an access to the current instance.
 332
 333    function Is_Limited_View (Ent : Entity_Id) return Boolean;
 334    --  Ent is any entity. True for a type that is "inherently" limited (i.e.
 335    --  cannot become nonlimited). From the Ada 2005 RM-7.5(8.1/2), "a type with
 336    --  a part that is of a task, protected, or explicitly limited record type".
 337    --  These are the types that are defined as return-by-reference types in Ada
 338    --  95 (see RM95-6.5(11-16)). In Ada 2005, these are the types that require
 339    --  build-in-place for function calls. Note that build-in-place is allowed
 340    --  for other types, too. This is also used for identifying pure procedures
 341    --  whose calls should not be eliminated (RM 10.2.1(18/2)).
 342
 343    function Is_Limited_Type (Ent : Entity_Id) return Boolean;
 344    --  Ent is any entity. Returns true if Ent is a limited type (limited
 345    --  private type, limited interface type, task type, protected type,
 346    --  composite containing a limited component, or a subtype of any of
 347    --  these types). This older routine overlaps with the previous one, this
 348    --  should be cleaned up???
 349
 350    function Is_Protected_Operation (E : Entity_Id) return Boolean;
 351    --  Given a subprogram or entry, determines whether E is a protected entry
 352    --  or subprogram.
 353
 354    function Is_Record_Or_Limited_Type (Typ : Entity_Id) return Boolean;
 355    --  Return True if Typ requires is a record or limited type.
 356
 357    function Nearest_Ancestor (Typ : Entity_Id) return Entity_Id;
 358    --  Given a subtype Typ, this function finds out the nearest ancestor from
 359    --  which constraints and predicates are inherited. There is no simple link
 360    --  for doing this, consider:
 361    --
 362    --     subtype R is Integer range 1 .. 10;
 363    --     type T is new R;
 364    --
 365    --  In this case the nearest ancestor is R, but the Etype of T'Base will
 366    --  point to R'Base, so we have to go rummaging in the declarations to get
 367    --  this information. It is used for making sure we freeze this before we
 368    --  freeze Typ, and also for retrieving inherited predicate information.
 369    --  For the case of base types or first subtypes, there is no useful entity
 370    --  to return, so Empty is returned.
 371    --
 372    --  Note: this is similar to Ancestor_Subtype except that it also deals
 373    --  with the case of derived types.
 374
 375    function Nearest_Dynamic_Scope (Ent : Entity_Id) return Entity_Id;
 376    --  This is similar to Enclosing_Dynamic_Scope except that if Ent is itself
 377    --  a dynamic scope, then it is returned. Otherwise the result is the same
 378    --  as that returned by Enclosing_Dynamic_Scope.
 379
 380    function Next_Tag_Component (Tag : Entity_Id) return Entity_Id;
 381    --  Tag must be an entity representing a _Tag field of a tagged record.
 382    --  The result returned is the next _Tag field in this record, or Empty
 383    --  if this is the last such field.
 384
 385    function Number_Components (Typ : Entity_Id) return Nat;
 386    --  Typ is a record type, yields number of components (including
 387    --  discriminants) in type.
 388
 389    function Number_Discriminants (Typ : Entity_Id) return Pos;
 390    --  Typ is a type with discriminants, yields number of discriminants in type
 391
 392    function Object_Type_Has_Constrained_Partial_View
 393      (Typ  : Entity_Id;
 394       Scop : Entity_Id) return Boolean;
 395    --  Return True if type of object has attribute Has_Constrained_Partial_View
 396    --  set to True; in addition, within a generic body, return True if subtype
 397    --  of the object is a descendant of an untagged generic formal private or
 398    --  derived type, and the subtype is not an unconstrained array subtype
 399    --  (RM 3.3(23.10/3)).
 400
 401    function Package_Body (E : Entity_Id) return Node_Id;
 402    --  Given an entity for a package (spec or body), return the corresponding
 403    --  package body if any, or else Empty.
 404
 405    function Package_Spec (E : Entity_Id) return Node_Id;
 406    --  Given an entity for a package spec, return the corresponding package
 407    --  spec if any, or else Empty.
 408
 409    function Package_Specification (E : Entity_Id) return Node_Id;
 410    --  Given an entity for a package, return the corresponding package
 411    --  specification.
 412
 413    function Subprogram_Body (E : Entity_Id) return Node_Id;
 414    --  Given an entity for a subprogram (spec or body), return the
 415    --  corresponding subprogram body if any, or else Empty.
 416
 417    function Subprogram_Body_Entity (E : Entity_Id) return Entity_Id;
 418    --  Given an entity for a subprogram (spec or body), return the entity
 419    --  corresponding to the subprogram body, which may be the same as E or
 420    --  Empty if no body is available.
 421
 422    function Subprogram_Spec (E : Entity_Id) return Node_Id;
 423    --  Given an entity for a subprogram spec, return the corresponding
 424    --  subprogram spec if any, or else Empty.
 425
 426    function Subprogram_Specification (E : Entity_Id) return Node_Id;
 427    --  Given an entity for a subprogram, return the corresponding subprogram
 428    --  specification. If the entity is an inherited subprogram without
 429    --  specification itself, return the specification of the inherited
 430    --  subprogram.
 431
 432    function Ultimate_Alias (Prim : Entity_Id) return Entity_Id;
 433    pragma Inline (Ultimate_Alias);
 434    --  Return the last entity in the chain of aliased entities of Prim. If Prim
 435    --  has no alias return Prim.
 436
 437    function Unit_Declaration_Node (Unit_Id : Entity_Id) return Node_Id;
 438    --  Unit_Id is the simple name of a program unit, this function returns the
 439    --  corresponding xxx_Declaration node for the entity. Also applies to the
 440    --  body entities for subprograms, tasks and protected units, in which case
 441    --  it returns the subprogram, task or protected body node for it. The unit
 442    --  may be a child unit with any number of ancestors.
 443
 444 end Sem_Aux;