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-2003, 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 2,  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 COPYING.  If not, write --
  19 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  20 -- MA 02111-1307, USA.                                                      --
  21 --                                                                          --
  22 -- GNAT was originally developed  by the GNAT team at  New York University. --
  23 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  24 --                                                                          --
  25 ------------------------------------------------------------------------------
  26
  27 --  This package contains various utility procedures to assist in
  28 --  building specific types of tree nodes.
  29
  30 with Types; use Types;
  31
  32 package Tbuild is
  33
  34    function Checks_Off (N : Node_Id) return Node_Id;
  35    pragma Inline (Checks_Off);
  36    --  Returns an N_Unchecked_Expression node whose expression is the given
  37    --  argument. The results is a subexpression identical to the argument,
  38    --  except that it will be analyzed and resolved with checks off.
  39
  40    function Convert_To (Typ : Entity_Id; Expr : Node_Id) return Node_Id;
  41    --  Returns an expression that represents the result of a checked convert
  42    --  of expression Exp to type T. If the base type of Exp is T, then no
  43    --  conversion is required, and Exp is returned unchanged. Otherwise an
  44    --  N_Type_Conversion node is constructed to convert the expression.
  45    --  If an N_Type_Conversion node is required, Relocate_Node is used on
  46    --  Exp. This means that it is safe to replace a node by a Convert_To
  47    --  of itself to some other type.
  48
  49    procedure Discard_Node (N : Node_Or_Entity_Id);
  50    pragma Inline (Discard_Node);
  51    --  This is a dummy procedure that simply returns and does nothing.
  52    --  It is used when a function returning a Node_Id value is called
  53    --  for its side effect (e.g. a call to Make to construct a node)
  54    --  but the Node_Id value is not required.
  55
  56    procedure Discard_List (L : List_Id);
  57    pragma Inline (Discard_List);
  58    --  This is a dummy procedure that simply returns and does nothing.
  59    --  It is used when a function returning a Node_Id value is called
  60    --  for its side effect (e.g. a call to the pareser to parse a list
  61    --  of compilation units), but the List_Id value is not required.
  62
  63    function Make_Byte_Aligned_Attribute_Reference
  64      (Sloc           : Source_Ptr;
  65       Prefix         : Node_Id;
  66       Attribute_Name : Name_Id)
  67       return           Node_Id;
  68    pragma Inline (Make_Byte_Aligned_Attribute_Reference);
  69    --  Like the standard Make_Attribute_Reference but the special flag
  70    --  Must_Be_Byte_Aligned is set in the attribute reference node. The
  71    --  Attribute_Name must be Name_Address or Name_Unrestricted_Access.
  72
  73    function Make_DT_Component
  74      (Loc  : Source_Ptr;
  75       Typ  : Entity_Id;
  76       I    : Positive)
  77       return Node_Id;
  78    --  Gives a reference to the Ith component of the Dispatch Table of
  79    --  a given Tagged Type.
  80    --
  81    --  I = 1    --> Inheritance_Depth
  82    --  I = 2    --> Tags (array of ancestors)
  83    --  I = 3, 4 --> predefined primitive
  84    --            function _Size (X : Typ) return Long_Long_Integer;
  85    --            function _Equality (X : Typ; Y : Typ'Class) return Boolean;
  86    --  I >= 5   --> User-Defined Primitive Operations
  87
  88    function Make_DT_Access
  89      (Loc : Source_Ptr; Rec : Node_Id; Typ : Entity_Id) return Node_Id;
  90    --  Create an access to the Dispatch Table by using the Tag field
  91    --  of a tagged record : Acc_Dt (Rec.tag).all
  92
  93    function Make_Implicit_If_Statement
  94      (Node            : Node_Id;
  95       Condition       : Node_Id;
  96       Then_Statements : List_Id;
  97       Elsif_Parts     : List_Id := No_List;
  98       Else_Statements : List_Id := No_List)
  99       return            Node_Id;
 100    pragma Inline (Make_Implicit_If_Statement);
 101    --  This function makes an N_If_Statement node whose fields are filled
 102    --  in with the indicated values (see Sinfo), and whose Sloc field is
 103    --  is set to Sloc (Node). The effect is identical to calling function
 104    --  Nmake.Make_If_Statement except that there is a check for restriction
 105    --  No_Implicit_Conditionals, and if this restriction is being violated,
 106    --  an error message is posted on Node.
 107
 108    function Make_Implicit_Label_Declaration
 109      (Loc                 : Source_Ptr;
 110       Defining_Identifier : Node_Id;
 111       Label_Construct     : Node_Id)
 112       return                Node_Id;
 113    --  Used to contruct an implicit label declaration node, including setting
 114    --  the proper Label_Construct field (since Label_Construct is a semantic
 115    --  field, the normal call to Make_Implicit_Label_Declaration does not
 116    --  set this field).
 117
 118    function Make_Implicit_Loop_Statement
 119      (Node                   : Node_Id;
 120       Statements             : List_Id;
 121       Identifier             : Node_Id := Empty;
 122       Iteration_Scheme       : Node_Id := Empty;
 123       Has_Created_Identifier : Boolean := False;
 124       End_Label              : Node_Id := Empty)
 125       return                   Node_Id;
 126    --  This function makes an N_Loop_Statement node whose fields are filled
 127    --  in with the indicated values (see Sinfo), and whose Sloc field is
 128    --  is set to Sloc (Node). The effect is identical to calling function
 129    --  Nmake.Make_Loop_Statement except that there is a check for restrictions
 130    --  No_Implicit_Loops and No_Implicit_Conditionals (the first applying in
 131    --  all cases, and the second only for while loops), and if one of these
 132    --  restrictions is being violated, an error message is posted on Node.
 133
 134    function Make_Integer_Literal
 135      (Loc    : Source_Ptr;
 136       Intval : Int)
 137       return   Node_Id;
 138    pragma Inline (Make_Integer_Literal);
 139    --  A convenient form of Make_Integer_Literal taking Int instead of Uint
 140
 141    function Make_Raise_Constraint_Error
 142      (Sloc      : Source_Ptr;
 143       Condition : Node_Id := Empty;
 144       Reason    : RT_Exception_Code)
 145       return      Node_Id;
 146    pragma Inline (Make_Raise_Constraint_Error);
 147    --  A convenient form of Make_Raise_Constraint_Error where the Reason
 148    --  is given simply as an enumeration value, rather than a Uint code.
 149
 150    function Make_Raise_Program_Error
 151      (Sloc      : Source_Ptr;
 152       Condition : Node_Id := Empty;
 153       Reason    : RT_Exception_Code)
 154       return      Node_Id;
 155    pragma Inline (Make_Raise_Program_Error);
 156    --  A convenient form of Make_Raise_Program_Error where the Reason
 157    --  is given simply as an enumeration value, rather than a Uint code.
 158
 159    function Make_Raise_Storage_Error
 160      (Sloc      : Source_Ptr;
 161       Condition : Node_Id := Empty;
 162       Reason    : RT_Exception_Code)
 163       return      Node_Id;
 164    pragma Inline (Make_Raise_Storage_Error);
 165    --  A convenient form of Make_Raise_Storage_Error where the Reason
 166    --  is given simply as an enumeration value, rather than a Uint code.
 167
 168    function Make_Unsuppress_Block
 169      (Loc   : Source_Ptr;
 170       Check : Name_Id;
 171       Stmts : List_Id)
 172       return  Node_Id;
 173    --  Build a block with a pragma Suppress on 'Check'. Stmts is the
 174    --  statements list that needs protection against the check
 175
 176    function New_Constraint_Error (Loc : Source_Ptr) return Node_Id;
 177    --  This function builds a tree corresponding to the Ada statement
 178    --  "raise Constraint_Error" and returns the root of this tree,
 179    --  the N_Raise_Statement node.
 180
 181    function New_External_Name
 182      (Related_Id   : Name_Id;
 183       Suffix       : Character := ' ';
 184       Suffix_Index : Int       := 0;
 185       Prefix       : Character := ' ')
 186       return         Name_Id;
 187    function New_External_Name
 188      (Related_Id   : Name_Id;
 189       Suffix       : String;
 190       Suffix_Index : Int       := 0;
 191       Prefix       : Character := ' ')
 192       return         Name_Id;
 193    --  Builds a new entry in the names table of the form:
 194    --
 195    --    [Prefix  &] Related_Id [& Suffix] [& Suffix_Index]
 196    --
 197    --  Prefix is prepended only if Prefix is non-blank (in which case it
 198    --  must be an upper case letter other than O,Q,U,W (which are used for
 199    --  identifier encoding, see Namet), and T is reserved for use by implicit
 200    --  types. and X is reserved for use by debug type encoding (see package
 201    --  Exp_Dbug). Note: the reason that Prefix is last is that it is almost
 202    --  always omitted. The notable case of Prefix being non-null is when
 203    --  it is 'T' for an implicit type.
 204
 205    --  Suffix_Index'Image is appended only if the value of Suffix_Index is
 206    --  positive, or if Suffix_Index is negative 1, then a unique serialized
 207    --  suffix is added. If Suffix_Index is zero, then no index is appended.
 208
 209    --  Suffix is also a single upper case letter other than O,Q,U,W,X and is a
 210    --  required parameter (T is permitted). The constructed name is stored
 211    --  using Find_Name so that it can be located using a subsequent Find_Name
 212    --  operation (i.e. it is properly hashed into the names table). The upper
 213    --  case letter given as the Suffix argument ensures that the name does
 214    --  not clash with any Ada identifier name. These generated names are
 215    --  permitted, but not required, to be made public by setting the flag
 216    --  Is_Public in the associated entity.
 217
 218    function New_External_Name
 219      (Suffix       : Character;
 220       Suffix_Index : Nat)
 221       return         Name_Id;
 222    --  Builds a new entry in the names table of the form
 223    --    Suffix & Suffix_Index'Image
 224    --  where Suffix is a single upper case letter other than O,Q,U,W,X and is
 225    --  a required parameter (T is permitted). The constructed name is stored
 226    --  using Find_Name so that it can be located using a subsequent Find_Name
 227    --  operation (i.e. it is properly hashed into the names table). The upper
 228    --  case letter given as the Suffix argument ensures that the name does
 229    --  not clash with any Ada identifier name. These generated names are
 230    --  permitted, but not required, to be made public by setting the flag
 231    --  Is_Public in the associated entity.
 232
 233    function New_Internal_Name (Id_Char : Character) return Name_Id;
 234    --  Id_Char is an upper case letter other than O,Q,U,W (which are reserved
 235    --  for identifier encoding (see Namet package for details) and X which is
 236    --  used for debug encoding (see Exp_Dbug). The letter T is permitted, but
 237    --  is reserved by convention for the case of internally generated types.
 238    --  The result of the call is a new generated unique name of the form XyyyU
 239    --  where X is Id_Char, yyy is a unique serial number, and U is either a
 240    --  lower case s or b indicating if the current unit is a spec or a body.
 241    --
 242    --  The name is entered into the names table using Name_Enter rather than
 243    --  Name_Find, because there can never be a need to locate the entry using
 244    --  the Name_Find procedure later on. Names created by New_Internal_Name
 245    --  are guaranteed to be consistent from one compilation to another (i.e.
 246    --  if the identical unit is compiled with a semantically consistent set
 247    --  of sources, the numbers will be consistent. This means that it is fine
 248    --  to use these as public symbols.
 249
 250    function New_Occurrence_Of
 251      (Def_Id : Entity_Id;
 252       Loc    : Source_Ptr)
 253       return   Node_Id;
 254    --  New_Occurrence_Of creates an N_Identifier node which is an
 255    --  occurrence of the defining identifier which is passed as its
 256    --  argument. The Entity and Etype of the result are set from
 257    --  the given defining identifier as follows: Entity is simply
 258    --  a copy of Def_Id. Etype is a copy of Def_Id for types, and
 259    --  a copy of the Etype of Def_Id for other entities.
 260
 261    function New_Reference_To
 262      (Def_Id : Entity_Id;
 263       Loc    : Source_Ptr)
 264       return   Node_Id;
 265    --  This is like New_Occurrence_Of, but it does not set the Etype field.
 266    --  It is used from the expander, where Etype fields are generally not set,
 267    --  since they are set when the expanded tree is reanalyzed.
 268
 269    function New_Suffixed_Name
 270      (Related_Id : Name_Id;
 271       Suffix     : String)
 272       return       Name_Id;
 273    --  This function is used to create special suffixed names used by the
 274    --  debugger. Suffix is a string of upper case letters, used to construct
 275    --  the required name. For instance, the special type used to record the
 276    --  fixed-point small is called typ_SMALL where typ is the name of the
 277    --  fixed-point type (as passed in Related_Id), and Suffix is "SMALL".
 278
 279    function OK_Convert_To (Typ : Entity_Id; Expr : Node_Id) return Node_Id;
 280    --  Like Convert_To, except that a conversion node is always generated,
 281    --  and the Conversion_OK flag is set on this conversion node.
 282
 283    function Unchecked_Convert_To
 284      (Typ  : Entity_Id;
 285       Expr : Node_Id)
 286       return Node_Id;
 287    --  Like Convert_To, but if a conversion is actually needed, constructs
 288    --  an N_Unchecked_Type_Conversion node to do the required conversion.
 289
 290 end Tbuild;