gcc/ada/tbuild.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                               T B U I L D                                --
   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 --  This package contains various utility procedures to assist in building
  27 --  specific types of tree nodes.
  28
  29 with Namet; use Namet;
  30 with Sinfo; use Sinfo;
  31 with Types; use Types;
  32 with Uintp; use Uintp;
  33
  34 package Tbuild is
  35
  36    function Checks_Off (N : Node_Id) return Node_Id;
  37    pragma Inline (Checks_Off);
  38    --  Returns an N_Unchecked_Expression node whose expression is the given
  39    --  argument. The results is a subexpression identical to the argument,
  40    --  except that it will be analyzed and resolved with checks off.
  41
  42    function Convert_To (Typ : Entity_Id; Expr : Node_Id) return Node_Id;
  43    --  Returns an expression that represents the result of a checked convert
  44    --  of expression Exp to type T. If the base type of Exp is T, then no
  45    --  conversion is required, and Exp is returned unchanged. Otherwise an
  46    --  N_Type_Conversion node is constructed to convert the expression.
  47    --  If an N_Type_Conversion node is required, Relocate_Node is used on
  48    --  Exp. This means that it is safe to replace a node by a Convert_To
  49    --  of itself to some other type.
  50
  51    procedure Convert_To_And_Rewrite (Typ : Entity_Id; Expr : Node_Id);
  52    pragma Inline (Convert_To_And_Rewrite);
  53    --  Like the function, except that there is an extra step of calling
  54    --  Rewrite on the Expr node and replacing it with the converted result.
  55    --  As noted above, this is safe, because Relocate_Node is called.
  56
  57    procedure Discard_Node (N : Node_Or_Entity_Id);
  58    pragma Inline (Discard_Node);
  59    --  This is a dummy procedure that simply returns and does nothing. It is
  60    --  used when a function returning a Node_Id value is called for its side
  61    --  effect (e.g. a call to Make to construct a node) but the Node_Id value
  62    --  is not required.
  63
  64    procedure Discard_List (L : List_Id);
  65    pragma Inline (Discard_List);
  66    --  This is a dummy procedure that simply returns and does nothing. It is
  67    --  used when a function returning a Node_Id value is called for its side
  68    --  effect (e.g. a call to the parser to parse a list of compilation
  69    --  units), but the List_Id value is not required.
  70
  71    function Make_Byte_Aligned_Attribute_Reference
  72      (Sloc           : Source_Ptr;
  73       Prefix         : Node_Id;
  74       Attribute_Name : Name_Id) return Node_Id;
  75    pragma Inline (Make_Byte_Aligned_Attribute_Reference);
  76    --  Like the standard Make_Attribute_Reference but the special flag
  77    --  Must_Be_Byte_Aligned is set in the attribute reference node. The
  78    --  Attribute_Name must be Name_Address or Name_Unrestricted_Access.
  79
  80    function Make_DT_Access
  81      (Loc : Source_Ptr; Rec : Node_Id; Typ : Entity_Id) return Node_Id;
  82    --  Create an access to the Dispatch Table by using the Tag field of a
  83    --  tagged record : Acc_Dt (Rec.tag).all
  84
  85    function Make_Float_Literal
  86      (Loc         : Source_Ptr;
  87       Radix       : Uint;
  88       Significand : Uint;
  89       Exponent    : Uint) return Node_Id;
  90    --  Create a real literal for the floating point expression value
  91    --  Significand * Radix ** Exponent. Radix must be greater than 1.
  92
  93    function Make_Implicit_Exception_Handler
  94      (Sloc              : Source_Ptr;
  95       Choice_Parameter  : Node_Id := Empty;
  96       Exception_Choices : List_Id;
  97       Statements        : List_Id) return Node_Id;
  98    pragma Inline (Make_Implicit_Exception_Handler);
  99    --  This is just like Make_Exception_Handler, except that it also sets the
 100    --  Local_Raise_Statements field to No_Elist, ensuring that it is properly
 101    --  initialized. This should always be used when creating implicit exception
 102    --  handlers during expansion (i.e. handlers that do not correspond to user
 103    --  source program exception handlers).
 104
 105    function Make_Implicit_If_Statement
 106      (Node            : Node_Id;
 107       Condition       : Node_Id;
 108       Then_Statements : List_Id;
 109       Elsif_Parts     : List_Id := No_List;
 110       Else_Statements : List_Id := No_List) return Node_Id;
 111    pragma Inline (Make_Implicit_If_Statement);
 112    --  This function makes an N_If_Statement node whose fields are filled
 113    --  in with the indicated values (see Sinfo), and whose Sloc field is
 114    --  is set to Sloc (Node). The effect is identical to calling function
 115    --  Nmake.Make_If_Statement except that there is a check for restriction
 116    --  No_Implicit_Conditionals, and if this restriction is being violated,
 117    --  an error message is posted on Node.
 118
 119    function Make_Implicit_Label_Declaration
 120      (Loc                 : Source_Ptr;
 121       Defining_Identifier : Node_Id;
 122       Label_Construct     : Node_Id) return Node_Id;
 123    --  Used to construct an implicit label declaration node, including setting
 124    --  the proper Label_Construct field (since Label_Construct is a semantic
 125    --  field, the normal call to Make_Implicit_Label_Declaration does not
 126    --  set this field).
 127
 128    function Make_Implicit_Loop_Statement
 129      (Node                   : Node_Id;
 130       Statements             : List_Id;
 131       Identifier             : Node_Id := Empty;
 132       Iteration_Scheme       : Node_Id := Empty;
 133       Has_Created_Identifier : Boolean := False;
 134       End_Label              : Node_Id := Empty) return Node_Id;
 135    --  This function makes an N_Loop_Statement node whose fields are filled
 136    --  in with the indicated values (see Sinfo), and whose Sloc field is
 137    --  is set to Sloc (Node). The effect is identical to calling function
 138    --  Nmake.Make_Loop_Statement except that there is a check for restrictions
 139    --  No_Implicit_Loops and No_Implicit_Conditionals (the first applying in
 140    --  all cases, and the second only for while loops), and if one of these
 141    --  restrictions is being violated, an error message is posted on Node.
 142
 143    function Make_Increment
 144      (Loc : Source_Ptr; Index : Entity_Id; Typ : Entity_Id) return Node_Id;
 145    --  Return an assignment statement of the form "Index := Typ'Succ (Index);"
 146
 147    function Make_Integer_Literal
 148      (Loc    : Source_Ptr;
 149       Intval : Int) return Node_Id;
 150    pragma Inline (Make_Integer_Literal);
 151    --  A convenient form of Make_Integer_Literal taking Int instead of Uint
 152
 153    function Make_Linker_Section_Pragma
 154      (Ent : Entity_Id;
 155       Loc : Source_Ptr;
 156       Sec : String) return Node_Id;
 157    --  Construct a Linker_Section pragma for entity Ent, using string Sec as
 158    --  the section name. Loc is the Sloc value to use in building the pragma.
 159
 160    function Make_Pragma
 161      (Sloc                         : Source_Ptr;
 162       Chars                        : Name_Id;
 163       Pragma_Argument_Associations : List_Id := No_List) return Node_Id;
 164    --  A convenient form of Make_Pragma not requiring a Pragma_Identifier
 165    --  argument (this argument is built from the value given for Chars).
 166
 167    function Make_Raise_Constraint_Error
 168      (Sloc      : Source_Ptr;
 169       Condition : Node_Id := Empty;
 170       Reason    : RT_Exception_Code) return Node_Id;
 171    pragma Inline (Make_Raise_Constraint_Error);
 172    --  A convenient form of Make_Raise_Constraint_Error where the Reason
 173    --  is given simply as an enumeration value, rather than a Uint code.
 174
 175    function Make_Raise_Program_Error
 176      (Sloc      : Source_Ptr;
 177       Condition : Node_Id := Empty;
 178       Reason    : RT_Exception_Code) return Node_Id;
 179    pragma Inline (Make_Raise_Program_Error);
 180    --  A convenient form of Make_Raise_Program_Error where the Reason
 181    --  is given simply as an enumeration value, rather than a Uint code.
 182
 183    function Make_Raise_Storage_Error
 184      (Sloc      : Source_Ptr;
 185       Condition : Node_Id := Empty;
 186       Reason    : RT_Exception_Code) return Node_Id;
 187    pragma Inline (Make_Raise_Storage_Error);
 188    --  A convenient form of Make_Raise_Storage_Error where the Reason is given
 189    --  simply as an enumeration value, rather than a Uint code.
 190
 191    function Make_String_Literal
 192      (Sloc   : Source_Ptr;
 193       Strval : String) return Node_Id;
 194    --  A convenient form of Make_String_Literal, where the string value is
 195    --  given as a normal string instead of a String_Id value.
 196
 197    function Make_Temporary
 198      (Loc          : Source_Ptr;
 199       Id           : Character;
 200       Related_Node : Node_Id := Empty) return Entity_Id;
 201    --  This function should be used for all cases where a defining identifier
 202    --  is to be built with a name to be obtained by New_Internal_Name (here Id
 203    --  is the character passed as the argument to New_Internal_Name). Loc is
 204    --  the location for the Sloc value of the resulting Entity. Note that this
 205    --  can be used for all kinds of temporary defining identifiers used in
 206    --  expansion (objects, subtypes, functions etc).
 207    --
 208    --  Related_Node is used when the defining identifier is for an object that
 209    --  captures the value of an expression (e.g. an aggregate). It should be
 210    --  set whenever possible to point to the expression that is being captured.
 211    --  This is provided to get better error messages, e.g. from CodePeer.
 212
 213    function Make_Unsuppress_Block
 214      (Loc   : Source_Ptr;
 215       Check : Name_Id;
 216       Stmts : List_Id) return Node_Id;
 217    --  Build a block with a pragma Suppress on 'Check'. Stmts is the statements
 218    --  list that needs protection against the check
 219
 220    function New_Constraint_Error (Loc : Source_Ptr) return Node_Id;
 221    --  This function builds a tree corresponding to the Ada statement
 222    --  "raise Constraint_Error" and returns the root of this tree,
 223    --  the N_Raise_Statement node.
 224
 225    function New_Op_Node
 226      (New_Node_Kind : Node_Kind;
 227       New_Sloc      : Source_Ptr) return Node_Id;
 228    --  Create node using New_Node and, if its kind is in N_Op, set its Chars
 229    --  field accordingly.
 230
 231    function New_External_Name
 232      (Related_Id   : Name_Id;
 233       Suffix       : Character := ' ';
 234       Suffix_Index : Int       := 0;
 235       Prefix       : Character := ' ') return Name_Id;
 236    function New_External_Name
 237      (Related_Id   : Name_Id;
 238       Suffix       : String;
 239       Suffix_Index : Int       := 0;
 240       Prefix       : Character := ' ') return Name_Id;
 241    --  Builds a new entry in the names table of the form:
 242    --
 243    --    [Prefix  &] Related_Id [& Suffix] [& Suffix_Index]
 244    --
 245    --  Prefix is prepended only if Prefix is non-blank (in which case it
 246    --  must be an upper case letter other than O,Q,U,W (which are used for
 247    --  identifier encoding, see Namet), or an underscore, and T is reserved for
 248    --  use by implicit types, and X is reserved for use by debug type encoding
 249    --  (see package Exp_Dbug). Note: the reason that Prefix is last is that it
 250    --  is almost always omitted. The notable case of Prefix being non-null is
 251    --  when it is 'T' for an implicit type.
 252
 253    --  Suffix_Index'Image is appended only if the value of Suffix_Index is
 254    --  positive, or if Suffix_Index is negative 1, then a unique serialized
 255    --  suffix is added. If Suffix_Index is zero, then no index is appended.
 256
 257    --  Suffix is also a single upper case letter other than O,Q,U,W,X (T is
 258    --  allowed in this context), or a string of such upper case letters. In
 259    --  the case of a string, an initial underscore may be given.
 260    --
 261    --  The constructed name is stored using Name_Find so that it can be located
 262    --  using a subsequent Name_Find operation (i.e. it is properly hashed into
 263    --  the names table). The upper case letter given as the Suffix argument
 264    --  ensures that the name does not clash with any Ada identifier name. These
 265    --  generated names are permitted, but not required, to be made public by
 266    --  setting the flag Is_Public in the associated entity.
 267    --
 268    --  Note: it is dubious to make them public if they have serial numbers,
 269    --  since we are counting on the serial numbers being the same for the
 270    --  clients with'ing a package and the actual compilation of the package
 271    --  with full expansion. This is a dubious assumption ???
 272
 273    function New_External_Name
 274      (Suffix       : Character;
 275       Suffix_Index : Nat) return Name_Id;
 276    --  Builds a new entry in the names table of the form
 277    --    Suffix & Suffix_Index'Image
 278    --  where Suffix is a single upper case letter other than O,Q,U,W,X and is
 279    --  a required parameter (T is permitted). The constructed name is stored
 280    --  using Name_Find so that it can be located using a subsequent Name_Find
 281    --  operation (i.e. it is properly hashed into the names table). The upper
 282    --  case letter given as the Suffix argument ensures that the name does
 283    --  not clash with any Ada identifier name. These generated names are
 284    --  permitted, but not required, to be made public by setting the flag
 285    --  Is_Public in the associated entity.
 286    --
 287    --  Note: it is dubious to make these public since they have serial numbers,
 288    --  which means we are counting on the serial numbers being the same for the
 289    --  clients with'ing a package and the actual compilation of the package
 290    --  with full expansion. This is a dubious assumption ???
 291
 292    function New_Internal_Name (Id_Char : Character) return Name_Id;
 293    --  Id_Char is an upper case letter other than O,Q,U,W (which are reserved
 294    --  for identifier encoding (see Namet package for details) and X which is
 295    --  used for debug encoding (see Exp_Dbug). The letter T is permitted, but
 296    --  is reserved by convention for the case of internally generated types.
 297    --  The result of the call is a new generated unique name of the form XyyyU
 298    --  where X is Id_Char, yyy is a unique serial number, and U is either a
 299    --  lower case s or b indicating if the current unit is a spec or a body.
 300    --
 301    --  The name is entered into the names table using Name_Enter rather than
 302    --  Name_Find, because there can never be a need to locate the entry using
 303    --  the Name_Find procedure later on. Names created by New_Internal_Name
 304    --  are guaranteed to be consistent from one compilation to another (i.e.
 305    --  if the identical unit is compiled with a semantically consistent set
 306    --  of sources, the numbers will be consistent). This means that it is fine
 307    --  to use these as public symbols.
 308    --
 309    --  Note: Nearly all uses of this function are via calls to Make_Temporary,
 310    --  but there are just a few cases where it is called directly.
 311    --
 312    --  Note: despite the guarantee of consistency stated above, it is dubious
 313    --  to make these public since they have serial numbers, which means we are
 314    --  counting on the serial numbers being the same for the clients with'ing
 315    --  a package and the actual compilation of the package with full expansion.
 316    --  This is a dubious assumption ???
 317
 318    function New_Occurrence_Of
 319      (Def_Id : Entity_Id;
 320       Loc    : Source_Ptr) return Node_Id;
 321    --  New_Occurrence_Of creates an N_Identifier node which is an occurrence
 322    --  of the defining identifier which is passed as its argument. The Entity
 323    --  and Etype of the result are set from the given defining identifier as
 324    --  follows: Entity is simply a copy of Def_Id. Etype is a copy of Def_Id
 325    --  for types, and a copy of the Etype of Def_Id for other entities. Note
 326    --  that Is_Static_Expression is set if this call creates an occurrence of
 327    --  an enumeration literal.
 328
 329    function New_Suffixed_Name
 330      (Related_Id : Name_Id;
 331       Suffix     : String) return Name_Id;
 332    --  This function is used to create special suffixed names used by the
 333    --  debugger. Suffix is a string of upper case letters, used to construct
 334    --  the required name. For instance, the special type used to record the
 335    --  fixed-point small is called typ_SMALL where typ is the name of the
 336    --  fixed-point type (as passed in Related_Id), and Suffix is "SMALL".
 337
 338    function Sel_Comp (Pre, Sel : String; Loc : Source_Ptr) return Node_Id;
 339    function Sel_Comp (Pre : Node_Id; Sel : String) return Node_Id;
 340    --  Create a selected component of the form Pre.Sel; that is, Pre is the
 341    --  prefix, and Sel is the selector name.
 342
 343    function OK_Convert_To (Typ : Entity_Id; Expr : Node_Id) return Node_Id;
 344    --  Like Convert_To, except that a conversion node is always generated, and
 345    --  the Conversion_OK flag is set on this conversion node.
 346
 347    function Unchecked_Convert_To
 348      (Typ  : Entity_Id;
 349       Expr : Node_Id) return Node_Id;
 350    --  Like Convert_To, but if a conversion is actually needed, constructs an
 351    --  N_Unchecked_Type_Conversion node to do the required conversion.
 352
 353    -------------------------------------
 354    -- Subprograms for Use by Gnat1drv --
 355    -------------------------------------
 356
 357    function  Make_Id (Str : Text_Buffer) return Node_Id;
 358    function  Make_SC (Pre, Sel : Node_Id) return Node_Id;
 359    procedure Set_NOD (Unit : Node_Id);
 360    procedure Set_NSA (Asp  : Name_Id; OK : out Boolean);
 361    procedure Set_NUA (Attr : Name_Id; OK : out Boolean);
 362    procedure Set_NUP (Prag : Name_Id; OK : out Boolean);
 363    --  Subprograms for call to Get_Target_Parameters in Gnat1drv, see spec
 364    --  of package Targparm for full description of these four subprograms.
 365    --  These have to be declared at the top level of a package (accessibility
 366    --  issues), and Gnat1drv is a procedure, so they can't go there.
 367
 368 end Tbuild;