1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
9 -- Copyright (C) 1992-2009, Free Software Foundation, Inc. --
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. --
21 -- GNAT was originally developed by the GNAT team at New York University. --
22 -- Extensive contributions were provided by Ada Core Technologies Inc. --
24 ------------------------------------------------------------------------------
26 -- This package contains various utility procedures to assist in
27 -- building specific types of tree nodes.
29 with Namet
; use Namet
;
30 with Sinfo
; use Sinfo
;
31 with Types
; use Types
;
35 function Checks_Off
(N
: Node_Id
) return Node_Id
;
36 pragma Inline
(Checks_Off
);
37 -- Returns an N_Unchecked_Expression node whose expression is the given
38 -- argument. The results is a subexpression identical to the argument,
39 -- except that it will be analyzed and resolved with checks off.
41 function Convert_To
(Typ
: Entity_Id
; Expr
: Node_Id
) return Node_Id
;
42 -- Returns an expression that represents the result of a checked convert
43 -- of expression Exp to type T. If the base type of Exp is T, then no
44 -- conversion is required, and Exp is returned unchanged. Otherwise an
45 -- N_Type_Conversion node is constructed to convert the expression.
46 -- If an N_Type_Conversion node is required, Relocate_Node is used on
47 -- Exp. This means that it is safe to replace a node by a Convert_To
48 -- of itself to some other type.
50 procedure Discard_Node
(N
: Node_Or_Entity_Id
);
51 pragma Inline
(Discard_Node
);
52 -- This is a dummy procedure that simply returns and does nothing. It is
53 -- used when a function returning a Node_Id value is called for its side
54 -- effect (e.g. a call to Make to construct a node) but the Node_Id value
57 procedure Discard_List
(L
: List_Id
);
58 pragma Inline
(Discard_List
);
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 the parser to parse a list of compilation
62 -- units), but the List_Id value is not required.
64 function Make_Byte_Aligned_Attribute_Reference
67 Attribute_Name
: Name_Id
) 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.
73 function Make_DT_Access
74 (Loc
: Source_Ptr
; Rec
: Node_Id
; Typ
: Entity_Id
) return Node_Id
;
75 -- Create an access to the Dispatch Table by using the Tag field of a
76 -- tagged record : Acc_Dt (Rec.tag).all
78 function Make_Implicit_Exception_Handler
80 Choice_Parameter
: Node_Id
:= Empty
;
81 Exception_Choices
: List_Id
;
82 Statements
: List_Id
) return Node_Id
;
83 pragma Inline
(Make_Implicit_Exception_Handler
);
84 -- This is just like Make_Exception_Handler, except that it also sets the
85 -- Local_Raise_Statements field to No_Elist, ensuring that it is properly
86 -- initialized. This should always be used when creating implicit exception
87 -- handlers during expansion (i.e. handlers that do not correspond to user
88 -- source program exception handlers).
90 function Make_Implicit_If_Statement
93 Then_Statements
: List_Id
;
94 Elsif_Parts
: List_Id
:= No_List
;
95 Else_Statements
: List_Id
:= No_List
) return Node_Id
;
96 pragma Inline
(Make_Implicit_If_Statement
);
97 -- This function makes an N_If_Statement node whose fields are filled
98 -- in with the indicated values (see Sinfo), and whose Sloc field is
99 -- is set to Sloc (Node). The effect is identical to calling function
100 -- Nmake.Make_If_Statement except that there is a check for restriction
101 -- No_Implicit_Conditionals, and if this restriction is being violated,
102 -- an error message is posted on Node.
104 function Make_Implicit_Label_Declaration
106 Defining_Identifier
: Node_Id
;
107 Label_Construct
: Node_Id
) return Node_Id
;
108 -- Used to construct an implicit label declaration node, including setting
109 -- the proper Label_Construct field (since Label_Construct is a semantic
110 -- field, the normal call to Make_Implicit_Label_Declaration does not
113 function Make_Implicit_Loop_Statement
115 Statements
: List_Id
;
116 Identifier
: Node_Id
:= Empty
;
117 Iteration_Scheme
: Node_Id
:= Empty
;
118 Has_Created_Identifier
: Boolean := False;
119 End_Label
: Node_Id
:= Empty
) return Node_Id
;
120 -- This function makes an N_Loop_Statement node whose fields are filled
121 -- in with the indicated values (see Sinfo), and whose Sloc field is
122 -- is set to Sloc (Node). The effect is identical to calling function
123 -- Nmake.Make_Loop_Statement except that there is a check for restrictions
124 -- No_Implicit_Loops and No_Implicit_Conditionals (the first applying in
125 -- all cases, and the second only for while loops), and if one of these
126 -- restrictions is being violated, an error message is posted on Node.
128 function Make_Integer_Literal
130 Intval
: Int
) return Node_Id
;
131 pragma Inline
(Make_Integer_Literal
);
132 -- A convenient form of Make_Integer_Literal taking Int instead of Uint
134 function Make_Linker_Section_Pragma
137 Sec
: String) return Node_Id
;
138 -- Construct a Linker_Section pragma for entity Ent, using string Sec as
139 -- the section name. Loc is the Sloc value to use in building the pragma.
144 Pragma_Argument_Associations
: List_Id
:= No_List
;
145 Debug_Statement
: Node_Id
:= Empty
) return Node_Id
;
146 -- A convenient form of Make_Pragma not requiring a Pragma_Identifier
147 -- argument (this argument is built from the value given for Chars).
149 function Make_Raise_Constraint_Error
151 Condition
: Node_Id
:= Empty
;
152 Reason
: RT_Exception_Code
) return Node_Id
;
153 pragma Inline
(Make_Raise_Constraint_Error
);
154 -- A convenient form of Make_Raise_Constraint_Error where the Reason
155 -- is given simply as an enumeration value, rather than a Uint code.
157 function Make_Raise_Program_Error
159 Condition
: Node_Id
:= Empty
;
160 Reason
: RT_Exception_Code
) return Node_Id
;
161 pragma Inline
(Make_Raise_Program_Error
);
162 -- A convenient form of Make_Raise_Program_Error where the Reason
163 -- is given simply as an enumeration value, rather than a Uint code.
165 function Make_Raise_Storage_Error
167 Condition
: Node_Id
:= Empty
;
168 Reason
: RT_Exception_Code
) return Node_Id
;
169 pragma Inline
(Make_Raise_Storage_Error
);
170 -- A convenient form of Make_Raise_Storage_Error where the Reason
171 -- is given simply as an enumeration value, rather than a Uint code.
173 function Make_String_Literal
175 Strval
: String) return Node_Id
;
176 -- A convenient form of Make_String_Literal, where the string value
177 -- is given as a normal string instead of a String_Id value.
179 function Make_Temporary
182 Related_Node
: Node_Id
:= Empty
) return Entity_Id
;
183 -- This function should be used for all cases where a defining identifier
184 -- is to be built with a name to be obtained by New_Internal_Name (here Id
185 -- is the character passed as the argument to New_Internal_Name). Loc is
186 -- the location for the Sloc value of the resulting Entity. Note that this
187 -- can be used for all kinds of temporary defining identifiers used in
188 -- expansion (objects, subtypes, functions etc).
190 -- Related_Node is used when the defining identifier is for an object that
191 -- captures the value of an expression (e.g. an aggregate). It should be
192 -- set whenever possible to point to the expression that is being captured.
193 -- This is provided to get better error messages, e.g. from CodePeer.
195 -- Make_Temp_Id would probably be a better name for this function???
197 function Make_Unsuppress_Block
200 Stmts
: List_Id
) return Node_Id
;
201 -- Build a block with a pragma Suppress on 'Check'. Stmts is the
202 -- statements list that needs protection against the check
204 function New_Constraint_Error
(Loc
: Source_Ptr
) return Node_Id
;
205 -- This function builds a tree corresponding to the Ada statement
206 -- "raise Constraint_Error" and returns the root of this tree,
207 -- the N_Raise_Statement node.
210 (New_Node_Kind
: Node_Kind
;
211 New_Sloc
: Source_Ptr
) return Node_Id
;
212 -- Create node using New_Node and, if its kind is in N_Op, set its Chars
213 -- field accordingly.
215 function New_External_Name
216 (Related_Id
: Name_Id
;
217 Suffix
: Character := ' ';
218 Suffix_Index
: Int
:= 0;
219 Prefix
: Character := ' ') return Name_Id
;
220 function New_External_Name
221 (Related_Id
: Name_Id
;
223 Suffix_Index
: Int
:= 0;
224 Prefix
: Character := ' ') return Name_Id
;
225 -- Builds a new entry in the names table of the form:
227 -- [Prefix &] Related_Id [& Suffix] [& Suffix_Index]
229 -- Prefix is prepended only if Prefix is non-blank (in which case it
230 -- must be an upper case letter other than O,Q,U,W (which are used for
231 -- identifier encoding, see Namet), or an underscore, and T is reserved for
232 -- use by implicit types, and X is reserved for use by debug type encoding
233 -- (see package Exp_Dbug). Note: the reason that Prefix is last is that it
234 -- is almost always omitted. The notable case of Prefix being non-null is
235 -- when it is 'T' for an implicit type.
237 -- Suffix_Index'Image is appended only if the value of Suffix_Index is
238 -- positive, or if Suffix_Index is negative 1, then a unique serialized
239 -- suffix is added. If Suffix_Index is zero, then no index is appended.
241 -- Suffix is also a single upper case letter other than O,Q,U,W,X and is a
242 -- required parameter (T is permitted). The constructed name is stored
243 -- using Name_Find so that it can be located using a subsequent Name_Find
244 -- operation (i.e. it is properly hashed into the names table). The upper
245 -- case letter given as the Suffix argument ensures that the name does
246 -- not clash with any Ada identifier name. These generated names are
247 -- permitted, but not required, to be made public by setting the flag
248 -- Is_Public in the associated entity.
250 function New_External_Name
252 Suffix_Index
: Nat
) return Name_Id
;
253 -- Builds a new entry in the names table of the form
254 -- Suffix & Suffix_Index'Image
255 -- where Suffix is a single upper case letter other than O,Q,U,W,X and is
256 -- a required parameter (T is permitted). The constructed name is stored
257 -- using Name_Find so that it can be located using a subsequent Name_Find
258 -- operation (i.e. it is properly hashed into the names table). The upper
259 -- case letter given as the Suffix argument ensures that the name does
260 -- not clash with any Ada identifier name. These generated names are
261 -- permitted, but not required, to be made public by setting the flag
262 -- Is_Public in the associated entity.
264 function New_Internal_Name
(Id_Char
: Character) return Name_Id
;
265 -- Id_Char is an upper case letter other than O,Q,U,W (which are reserved
266 -- for identifier encoding (see Namet package for details) and X which is
267 -- used for debug encoding (see Exp_Dbug). The letter T is permitted, but
268 -- is reserved by convention for the case of internally generated types.
269 -- The result of the call is a new generated unique name of the form XyyyU
270 -- where X is Id_Char, yyy is a unique serial number, and U is either a
271 -- lower case s or b indicating if the current unit is a spec or a body.
273 -- The name is entered into the names table using Name_Enter rather than
274 -- Name_Find, because there can never be a need to locate the entry using
275 -- the Name_Find procedure later on. Names created by New_Internal_Name
276 -- are guaranteed to be consistent from one compilation to another (i.e.
277 -- if the identical unit is compiled with a semantically consistent set
278 -- of sources, the numbers will be consistent. This means that it is fine
279 -- to use these as public symbols.
281 -- Note: Nearly all uses of this function are via calls to Make_Temporary,
282 -- but there are just a few cases where it is called directly.
284 function New_Occurrence_Of
286 Loc
: Source_Ptr
) return Node_Id
;
287 -- New_Occurrence_Of creates an N_Identifier node which is an occurrence
288 -- of the defining identifier which is passed as its argument. The Entity
289 -- and Etype of the result are set from the given defining identifier as
290 -- follows: Entity is simply a copy of Def_Id. Etype is a copy of Def_Id
291 -- for types, and a copy of the Etype of Def_Id for other entities.
293 function New_Reference_To
295 Loc
: Source_Ptr
) return Node_Id
;
296 -- This is like New_Occurrence_Of, but it does not set the Etype field.
297 -- It is used from the expander, where Etype fields are generally not set,
298 -- since they are set when the expanded tree is reanalyzed.
300 function New_Suffixed_Name
301 (Related_Id
: Name_Id
;
302 Suffix
: String) return Name_Id
;
303 -- This function is used to create special suffixed names used by the
304 -- debugger. Suffix is a string of upper case letters, used to construct
305 -- the required name. For instance, the special type used to record the
306 -- fixed-point small is called typ_SMALL where typ is the name of the
307 -- fixed-point type (as passed in Related_Id), and Suffix is "SMALL".
309 function OK_Convert_To
(Typ
: Entity_Id
; Expr
: Node_Id
) return Node_Id
;
310 -- Like Convert_To, except that a conversion node is always generated,
311 -- and the Conversion_OK flag is set on this conversion node.
313 function Unchecked_Convert_To
315 Expr
: Node_Id
) return Node_Id
;
316 -- Like Convert_To, but if a conversion is actually needed, constructs
317 -- an N_Unchecked_Type_Conversion node to do the required conversion.