| blob | 8b08b524a1f3683478d2b8c26496225d483d0675 |
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- A T R E E --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1992-2005, 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 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
28 -- --
29 -- GNAT was originally developed by the GNAT team at New York University. --
30 -- Extensive contributions were provided by Ada Core Technologies Inc. --
31 -- --
32 ------------------------------------------------------------------------------
47 -- This package defines the format of the tree used to represent the Ada
48 -- program internally. Syntactic and semantic information is combined in
49 -- this tree. There is no separate symbol table structure.
51 -- WARNING: There is a C version of this package. Any changes to this
52 -- source file must be properly reflected in the C header file tree.h
54 -- Package Atree defines the basic structure of the tree and its nodes and
55 -- provides the basic abstract interface for manipulating the tree. Two
56 -- other packages use this interface to define the representation of Ada
57 -- programs using this tree format. The package Sinfo defines the basic
58 -- representation of the syntactic structure of the program, as output
59 -- by the parser. The package Entity_Info defines the semantic information
60 -- which is added to the tree nodes that represent declared entities (i.e.
61 -- the information which might typically be described in a separate symbol
62 -- table structure.
64 -- The front end of the compiler first parses the program and generates a
65 -- tree that is simply a syntactic representation of the program in abstract
66 -- syntax tree format. Subsequent processing in the front end traverses the
67 -- tree, transforming it in various ways and adding semantic information.
69 ----------------------------------------
70 -- Definitions of Fields in Tree Node --
71 ----------------------------------------
73 -- The representation of the tree is completely hidden, using a functional
74 -- interface for accessing and modifying the contents of nodes. Logically
75 -- a node contains a number of fields, much as though the nodes were
76 -- defined as a record type. The fields in a node are as follows:
78 -- Nkind Indicates the kind of the node. This field is present
79 -- in all nodes. The type is Node_Kind, which is declared
80 -- in the package Sinfo.
82 -- Sloc Location (Source_Ptr) of the corresponding token
83 -- in the Source buffer. The individual node definitions
84 -- show which token is referenced by this pointer.
86 -- In_List A flag used to indicate if the node is a member
87 -- of a node list.
89 -- Rewrite_Sub A flag set if the node has been rewritten using
90 -- the Rewrite procedure. The original value of the
91 -- node is retrievable with Original_Node.
93 -- Rewrite_Ins A flag set if a node is marked as a rewrite inserted
94 -- node as a result of a call to Mark_Rewrite_Insertion.
96 -- Paren_Count A 2-bit count used on expression nodes to indicate
97 -- the level of parentheses. Up to 3 levels can be
98 -- accomodated. Anything more than 3 levels is treated
99 -- as 3 levels (conformance tests that complain about
100 -- this are hereby deemed pathological!) Set to zero
101 -- for non-subexpression nodes.
103 -- Comes_From_Source
104 -- This flag is present in all nodes. It is set if the
105 -- node is built by the scanner or parser, and clear if
106 -- the node is built by the analyzer or expander. It
107 -- indicates that the node corresponds to a construct
108 -- that appears in the original source program.
110 -- Analyzed This flag is present in all nodes. It is set when
111 -- a node is analyzed, and is used to avoid analyzing
112 -- the same node twice. Analysis includes expansion if
113 -- expansion is active, so in this case if the flag is
114 -- set it means the node has been analyzed and expanded.
116 -- Error_Posted This flag is present in all nodes. It is set when
117 -- an error message is posted which is associated with
118 -- the flagged node. This is used to avoid posting more
119 -- than one message on the same node.
121 -- Field1
122 -- Field2
123 -- Field3
124 -- Field4
125 -- Field5 Five fields holding Union_Id values
127 -- ElistN Synonym for FieldN typed as Elist_Id
128 -- ListN Synonym for FieldN typed as List_Id
129 -- NameN Synonym for FieldN typed as Name_Id
130 -- NodeN Synonym for FieldN typed as Node_Id
131 -- StrN Synonym for FieldN typed as String_Id
132 -- UintN Synonym for FieldN typed as Uint (Empty = Uint_0)
133 -- UrealN Synonym for FieldN typed as Ureal
135 -- Note: the actual usage of FieldN (i.e. whether it contains a Elist_Id,
136 -- List_Id, Name_Id, Node_Id, String_Id, Uint or Ureal), depends on the
137 -- value in Nkind. Generally the access to this field is always via the
138 -- functional interface, so the field names ElistN, ListN, NameN, NodeN,
139 -- StrN, UintN and UrealN are used only in the bodies of the access
140 -- functions (i.e. in the bodies of Sinfo and Einfo). These access
141 -- functions contain debugging code that checks that the use is
142 -- consistent with Nkind and Ekind values.
144 -- However, in specialized circumstances (examples are the circuit in
145 -- generic instantiation to copy trees, and in the tree dump routine),
146 -- it is useful to be able to do untyped traversals, and an internal
147 -- package in Atree allows for direct untyped accesses in such cases.
149 -- Flag4 Fifteen Boolean flags (use depends on Nkind and
150 -- Flag5 Ekind, as described for FieldN). Again the access
151 -- Flag6 is usually via subprograms in Sinfo and Einfo which
152 -- Flag7 provide high-level synonyms for these flags, and
153 -- Flag8 contain debugging code that checks that the values
154 -- Flag9 in Nkind and Ekind are appropriate for the access.
155 -- Flag10
156 -- Flag11 Note that Flag1-3 are missing from this list. The
157 -- Flag12 first three flag positions are reserved for the
158 -- Flag13 standard flags (Comes_From_Source, Error_Posted,
159 -- Flag14 and Analyzed)
160 -- Flag15
161 -- Flag16
162 -- Flag17
163 -- Flag18
165 -- Link For a node, points to the Parent. For a list, points
166 -- to the list header. Note that in the latter case, a
167 -- client cannot modify the link field. This field is
168 -- private to the Atree package (but is also modified
169 -- by the Nlists package).
171 -- The following additional fields are present in extended nodes used
172 -- for entities (Nkind in N_Entity).
174 -- Ekind Entity type. This field indicates the type of the
175 -- entity, it is of type Entity_Kind which is defined
176 -- in package Einfo.
178 -- Flag19 197 additional flags
179 -- ...
180 -- Flag215
182 -- Convention Entity convention (Convention_Id value)
184 -- Field6 Additional Union_Id value stored in tree
186 -- Node6 Synonym for Field6 typed as Node_Id
187 -- Elist6 Synonym for Field6 typed as Elist_Id
188 -- Uint6 Synonym for Field6 typed as Uint (Empty = Uint_0)
190 -- Similar definitions for Field7 to Field27 (and Node7-Node27,
191 -- Elist7-Elist27, Uint7-Uint27, Ureal7-Ureal27). Note that not all
192 -- these functions are defined, only the ones that are actually used.
196 -- Type used for Paren_Count field
200 -- Returns Id of last allocated node Id
203 -- Return address of Nodes table (used in Back_End for Gigi call)
206 -- Total number of nodes allocated, where an entity counts as a single
207 -- node. This count is incremented every time a node or entity is
208 -- allocated, and decremented every time a node or entity is deleted.
209 -- This value is used by Xref and by Treepr to allocate hash tables of
210 -- suitable size for hashing Node_Id values.
212 -----------------------
213 -- Use of Empty Node --
214 -----------------------
216 -- The special Node_Id Empty is used to mark missing fields. Whenever the
217 -- syntax has an optional component, then the corresponding field will be
218 -- set to Empty if the component is missing.
220 -- Note: Empty is not used to describe an empty list. Instead in this
221 -- case the node field contains a list which is empty, and these cases
222 -- should be distinguished (essentially from a type point of view, Empty
223 -- is a Node, and is thus not a list).
225 -- Note: Empty does in fact correspond to an allocated node. Only the
226 -- Nkind field of this node may be referenced. It contains N_Empty, which
227 -- uniquely identifies the empty case. This allows the Nkind field to be
228 -- dereferenced before the check for Empty which is sometimes useful.
230 -----------------------
231 -- Use of Error Node --
232 -----------------------
234 -- The Error node is used during syntactic and semantic analysis to
235 -- indicate that the corresponding piece of syntactic structure or
236 -- semantic meaning cannot properly be represented in the tree because
237 -- of an illegality in the program.
239 -- If an Error node is encountered, then you know that a previous
240 -- illegality has been detected. The proper reaction should be to
241 -- avoid posting related cascaded error messages, and to propagate
242 -- the error node if necessary.
244 ------------------------
245 -- Current_Error_Node --
246 ------------------------
248 -- The current error node is a global location indicating the current
249 -- node that is being processed for the purposes of placing a compiler
250 -- abort message. This is not necessarily perfectly accurate, it is
251 -- just a reasonably accurate best guess. It is used to output the
252 -- source location in the abort message by Comperr, and also to
253 -- implement the d3 debugging flag. This is also used by Rtsfind
254 -- to generate error messages for high integrity mode.
256 -- There are two ways this gets set. During parsing, when new source
257 -- nodes are being constructed by calls to New_Node and New_Entity,
258 -- either one of these calls sets Current_Error_Node to the newly
259 -- created node. During semantic analysis, this mechanism is not
260 -- used, and instead Current_Error_Node is set by the subprograms in
261 -- Debug_A that mark the start and end of analysis/expansion of a
262 -- node in the tree.
265 -- Node to place error messages
267 -------------------------------
268 -- Default Setting of Fields --
269 -------------------------------
271 -- Nkind is set to N_Unused_At_Start
273 -- Ekind is set to E_Void
275 -- Sloc is always set, there is no default value
277 -- Field1-5 fields are set to Empty
279 -- Field6-22 fields in extended nodes are set to Empty
281 -- Parent is set to Empty
283 -- All Boolean flag fields are set to False
285 -- Note: the value Empty is used in Field1-Field17 to indicate a null node.
286 -- The usage varies. The common uses are to indicate absence of an
287 -- optional clause or a completely unused Field1-17 field.
289 -------------------------------------
290 -- Use of Synonyms for Node Fields --
291 -------------------------------------
293 -- A subpackage Atree.Unchecked_Access provides routines for reading and
294 -- writing the fields defined above (Field1-27, Node1-27, Flag1-215 etc).
295 -- These unchecked access routines can be used for untyped traversals.
296 -- In addition they are used in the implementations of the Sinfo and
297 -- Einfo packages. These packages both provide logical synonyms for
298 -- the generic fields, together with an appropriate set of access routines.
299 -- Normally access to information within tree nodes uses these synonyms,
300 -- providing a high level typed interface to the tree information.
302 --------------------------------------------------
303 -- Node Allocation and Modification Subprograms --
304 --------------------------------------------------
306 -- Generally the parser builds the tree and then it is further decorated
307 -- (e.g. by setting the entity fields), but not fundamentally modified.
308 -- However, there are cases in which the tree must be restructured by
309 -- adding and rearranging nodes, as a result of disambiguating cases
310 -- which the parser could not parse correctly, and adding additional
311 -- semantic information (e.g. making constraint checks explicit). The
312 -- following subprograms are used for constructing the tree in the first
313 -- place, and then for subsequent modifications as required
316 -- Called at the start of compilation to initialize the allocation of
317 -- the node and list tables and make the standard entries for Empty,
318 -- Error and Error_List. Note that Initialize must not be called if
319 -- Tree_Read is used.
322 -- Called before the backend is invoked to lock the nodes table
325 -- Initializes internal tables from current tree file using the relevant
326 -- Table.Tree_Read routines. Note that Initialize should not be called if
327 -- Tree_Read is used. Tree_Read includes all necessary initialization.
330 -- Writes out internal tables to current tree file using the relevant
331 -- Table.Tree_Write routines.
333 function New_Node
336 -- Allocates a completely new node with the given node type and source
337 -- location values. All other fields are set to their standard defaults:
338 --
339 -- Empty for all FieldN fields
340 -- False for all FlagN fields
341 --
342 -- The usual approach is to build a new node using this function and
343 -- then, using the value returned, use the Set_xxx functions to set
344 -- fields of the node as required. New_Node can only be used for
345 -- non-entity nodes, i.e. it never generates an extended node.
346 --
347 -- If we are currently parsing, as indicated by a previous call to
348 -- Set_Comes_From_Source_Default (True), then this call also resets
349 -- the value of Current_Error_Node.
351 function New_Entity
354 -- Similar to New_Node, except that it is used only for entity nodes
355 -- and returns an extended node.
358 -- Sets value of Comes_From_Source flag to be used in all subsequent
359 -- New_Node and New_Entity calls until another call to this procedure
360 -- changes the default. This value is set True during parsing and
361 -- False during semantic analysis. This is also used to determine
362 -- if New_Node and New_Entity should set Current_Error_Node.
366 -- Gets the current value of the Comes_From_Source flag
370 -- When a node is rewritten, it is sometimes appropriate to preserve the
371 -- original comes from source indication. This is true when the rewrite
372 -- essentially corresponds to a transformation corresponding exactly to
373 -- semantics in the reference manual. This procedure copies the setting
374 -- of Comes_From_Source from OldN to NewN.
378 -- Returns True if the given node has an extension (i.e. was created by
379 -- a call to New_Entity rather than New_Node, and Nkind is in N_Entity)
382 -- This procedure replaces the given node by setting its Nkind field to
383 -- the indicated value and resetting all other fields to their default
384 -- values except for Sloc, which is unchanged, and the Parent pointer
385 -- and list links, which are also unchanged. All other information in
386 -- the original node is lost. The new node has an extension if the
387 -- original node had an extension.
390 -- Copy the entire contents of the source node to the destination node.
391 -- The contents of the source node is not affected. If the source node
392 -- has an extension, then the destination must have an extension also.
393 -- The parent pointer of the destination and its list link, if any, are
394 -- not affected by the copy. Note that parent pointers of descendents
395 -- are not adjusted, so the descendents of the destination node after
396 -- the Copy_Node is completed have dubious parent pointers.
399 -- This function allocates a completely new node, and then initializes
400 -- it by copying the contents of the source node into it. The contents
401 -- of the source node is not affected. The target node is always marked
402 -- as not being in a list (even if the source is a list member). The
403 -- new node will have an extension if the source has an extension.
404 -- New_Copy (Empty) returns Empty and New_Copy (Error) returns Error.
405 -- Note that, unlike New_Copy_Tree, New_Copy does not recursively copy any
406 -- descendents, so in general parent pointers are not set correctly for
407 -- the descendents of the copied node. Both normal and extended nodes
408 -- (entities) may be copied using New_Copy.
411 -- Source is a non-entity node that is to be relocated. A new node is
412 -- allocated and the contents of Source are copied to this node using
413 -- Copy_Node. The parent pointers of descendents of the node are then
414 -- adjusted to point to the relocated copy. The original node is not
415 -- modified, but the parent pointers of its descendents are no longer
416 -- valid. This routine is used in conjunction with the tree rewrite
417 -- routines (see descriptions of Replace/Rewrite).
418 --
419 -- Note that the resulting node has the same parent as the source
420 -- node, and is thus still attached to the tree. It is valid for
421 -- Source to be Empty, in which case Relocate_Node simply returns
422 -- Empty as the result.
424 function New_Copy_Tree
429 -- Given a node that is the root of a subtree, Copy_Tree copies the entire
430 -- syntactic subtree, including recursively any descendents whose parent
431 -- field references a copied node (descendents not linked to a copied node
432 -- by the parent field are not copied, instead the copied tree references
433 -- the same descendent as the original in this case, which is appropriate
434 -- for non-syntactic fields such as Etype). The parent pointers in the
435 -- copy are properly set. Copy_Tree (Empty/Error) returns Empty/Error.
436 -- The one exception to the rule of not copying semantic fields is that
437 -- any implicit types attached to the subtree are duplicated, so that
438 -- the copy contains a distinct set of implicit type entities. The Map
439 -- argument, if set to a non-empty Elist, specifies a set of mappings
440 -- to be applied to entities in the tree. The map has the form:
441 --
442 -- old entity 1
443 -- new entity to replace references to entity 1
444 -- old entity 2
445 -- new entity to replace references to entity 2
446 -- ...
447 --
448 -- The call destroys the contents of Map in this case
449 --
450 -- The parameter New_Sloc, if set to a value other than No_Location, is
451 -- used as the Sloc value for all nodes in the new copy. If New_Sloc is
452 -- set to its default value No_Location, then the Sloc values of the
453 -- nodes in the copy are simply copied from the corresponding original.
454 --
455 -- The Comes_From_Source indication is unchanged if New_Sloc is set to
456 -- the default No_Location value, but is reset if New_Sloc is given, since
457 -- in this case the result clearly is neither a source node or an exact
458 -- copy of a source node.
459 --
460 -- The parameter New_Scope, if set to a value other than Empty, is the
461 -- value to use as the Scope for any Itypes that are copied. The most
462 -- typical value for this parameter, if given, is Current_Scope.
465 -- Given a node that is the root of a subtree, Copy_Separate_Tree copies
466 -- the entire syntactic subtree, including recursively any descendants
467 -- whose parent field references a copied node (descendants not linked to
468 -- a copied node by the parent field are also copied.) The parent pointers
469 -- in the copy are properly set. Copy_Separate_Tree (Empty/Error) returns
470 -- Empty/Error. The semantic fields are not copied and the new subtree
471 -- does not share any entity with source subtree.
472 -- But the code *does* copy semantic fields, and the description above
473 -- is in any case unclear on this point ??? (RBKD)
476 -- Exchange the contents of two entities. The parent pointers are switched
477 -- as well as the Defining_Identifier fields in the parents, so that the
478 -- entities point correctly to their original parents. The effect is thus
479 -- to leave the tree completely unchanged in structure, except that the
480 -- entity ID values of the two entities are interchanged. Neither of the
481 -- two entities may be list members.
484 -- The node, which must not be a list member, is deleted from the tree and
485 -- its type is set to N_Unused_At_End. It is an error (not necessarily
486 -- detected) to reference this node after it has been deleted. The
487 -- implementation of the body of Atree is free to reuse the node to
488 -- satisfy future node allocation requests, but is not required to do so.
491 -- The entire syntactic subtree referenced by Node (i.e. the given node
492 -- and all its syntactic descendents) are deleted as described above for
493 -- Delete_Node.
496 -- This function returns a copy of its input node with an extension
497 -- added. The fields of the extension are set to Empty. Due to the way
498 -- extensions are handled (as four consecutive array elements), it may
499 -- be necessary to reallocate the node, so that the returned value is
500 -- not the same as the input value, but where possible the returned
501 -- value will be the same as the input value (i.e. the extension will
502 -- occur in place). It is the caller's responsibility to ensure that
503 -- any pointers to the original node are appropriately updated. This
504 -- function is used only by Sinfo.CN to change nodes into their
505 -- corresponding entities.
508 -- This is the type of the result returned by the Process function passed
509 -- to Traverse_Func and Traverse_Proc and also the type of the result of
510 -- Traverse_Func itself. See descriptions below for details.
512 generic
515 -- This is a generic function that, given the parent node for a subtree,
516 -- traverses all syntactic nodes of this tree, calling the given function
517 -- Process on each one. The traversal is controlled as follows by the
518 -- result returned by Process:
520 -- OK The traversal continues normally with the syntactic
521 -- children of the node just processed.
523 -- OK_Orig The traversal continues normally with the syntactic
524 -- children of the original node of the node just processed.
526 -- Skip The children of the node just processed are skipped and
527 -- excluded from the traversal, but otherwise processing
528 -- continues elsewhere in the tree.
530 -- Abandon The entire traversal is immediately abandoned, and the
531 -- original call to Traverse returns Abandon.
533 -- The result returned by Traverse is Abandon if processing was terminated
534 -- by a call to Process returning Abandon, otherwise it is OK (meaning that
535 -- all calls to process returned either OK or Skip).
537 generic
541 -- This is similar to Traverse_Func except that no result is returned,
542 -- i.e. Traverse_Func is called and the result is simply discarded.
544 ---------------------------
545 -- Node Access Functions --
546 ---------------------------
548 -- The following functions return the contents of the indicated field of
549 -- the node referenced by the argument, which is a Node_Id.
571 -- Returns the parent of a node if the node is not a list member, or
572 -- else the parent of the list containing the node if the node is a
573 -- list member.
577 -- Tests given Id for equality with the Empty node. This allows notations
578 -- like "if No (Variant_Part)" as opposed to "if Variant_Part = Empty".
582 -- Tests given Id for inequality with the Empty node. This allows notations
583 -- like "if Present (Statement)" as opposed to "if Statement /= Empty".
585 -----------------------------
586 -- Entity Access Functions --
587 -----------------------------
589 -- The following functions apply only to Entity_Id values, i.e.
590 -- to extended nodes.
598 ----------------------------
599 -- Node Update Procedures --
600 ----------------------------
602 -- The following functions set a specified field in the node whose Id is
603 -- passed as the first argument. The second parameter is the new value
604 -- to be set in the specified field. Note that Set_Nkind is in the next
605 -- section, since its use is restricted.
624 -- Note that this routine is very rarely used, since usually the
625 -- default mechanism provided sets the right value, but in some
626 -- unusual cases, the value needs to be reset (e.g. when a source
627 -- node is copied, and the copy must not have Comes_From_Source set.
629 ------------------------------
630 -- Entity Update Procedures --
631 ------------------------------
633 -- The following procedures apply only to Entity_Id values, i.e.
634 -- to extended nodes.
642 ---------------------------
643 -- Tree Rewrite Routines --
644 ---------------------------
646 -- During the compilation process it is necessary in a number of situations
647 -- to rewrite the tree. In some cases, such rewrites do not affect the
648 -- structure of the tree, for example, when an indexed component node is
649 -- replaced by the corresponding call node (the parser cannot distinguish
650 -- between these two cases).
652 -- In other situations, the rewrite does affect the structure of the
653 -- tree. Examples are the replacement of a generic instantiation by the
654 -- instantiated spec and body, and the static evaluation of expressions.
656 -- If such structural modifications are done by the expander, there are
657 -- no difficulties, since the form of the tree after the expander has no
658 -- special significance, except as input to the backend of the compiler.
659 -- However, if these modifications are done by the semantic phase, then
660 -- it is important that they be done in a manner which allows the original
661 -- tree to be preserved. This is because tools like pretty printers need
662 -- to have this original tree structure available.
664 -- The subprograms in this section allow rewriting of the tree by either
665 -- insertion of new nodes in an existing list, or complete replacement of
666 -- a subtree. The resulting tree for most purposes looks as though it has
667 -- been really changed, and there is no trace of the original. However,
668 -- special subprograms, also defined in this section, allow the original
669 -- tree to be reconstructed if necessary.
671 -- For tree modifications done in the expander, it is permissible to
672 -- destroy the original tree, although it is also allowable to use the
673 -- tree rewrite routines where it is convenient to do so.
677 -- This procedure marks the given node as an insertion made during a tree
678 -- rewriting operation. Only the root needs to be marked. The call does
679 -- not do the actual insertion, which must be done using one of the normal
680 -- list insertion routines. The node is treated normally in all respects
681 -- except for its response to Is_Rewrite_Insertion. The function of these
682 -- calls is to be able to get an accurate original tree. This helps the
683 -- accuracy of Sprint.Sprint_Node, and in particular, when stubs are being
684 -- generated, it is essential that the original tree be accurate.
688 -- Tests whether the given node was marked using Set_Rewrite_Insert. This
689 -- is used in reconstructing the original tree (where such nodes are to
690 -- be eliminated from the reconstructed tree).
693 -- This is used when a complete subtree is to be replaced. Old_Node is the
694 -- root of the old subtree to be replaced, and New_Node is the root of the
695 -- newly constructed replacement subtree. The actual mechanism is to swap
696 -- the contents of these two nodes fixing up the parent pointers of the
697 -- replaced node (we do not attempt to preserve parent pointers for the
698 -- original node). Neither Old_Node nor New_Node can be extended nodes.
699 --
700 -- Note: New_Node may not contain references to Old_Node, for example as
701 -- descendents, since the rewrite would make such references invalid. If
702 -- New_Node does need to reference Old_Node, then these references should
703 -- be to a relocated copy of Old_Node (see Relocate_Node procedure).
704 --
705 -- Note: The Original_Node function applied to Old_Node (which has now
706 -- been replaced by the contents of New_Node), can be used to obtain the
707 -- original node, i.e. the old contents of Old_Node.
710 -- This is similar to Rewrite, except that the old value of Old_Node is
711 -- not saved, and the New_Node is deleted after the replace, since it
712 -- is assumed that it can no longer be legitimately needed. The flag
713 -- Is_Rewrite_Susbtitute will be False for the resulting node, unless
714 -- it was already true on entry, and Original_Node will not return the
715 -- original contents of the Old_Node, but rather the New_Node value (unless
716 -- Old_Node had already been rewritten using Rewrite). Replace also
717 -- preserves the setting of Comes_From_Source.
718 --
719 -- Note, New_Node may not contain references to Old_Node, for example as
720 -- descendents, since the rewrite would make such references invalid. If
721 -- New_Node does need to reference Old_Node, then these references should
722 -- be to a relocated copy of Old_Node (see Relocate_Node procedure).
723 --
724 -- Replace is used in certain circumstances where it is desirable to
725 -- suppress any history of the rewriting operation. Notably, it is used
726 -- when the parser has mis-classified a node (e.g. a task entry call
727 -- that the parser has parsed as a procedure call).
731 -- Return True iff Node has been rewritten (i.e. if Node is the root
732 -- of a subtree which was installed using Rewrite).
736 -- If Node has not been rewritten, then returns its input argument
737 -- unchanged, else returns the Node for the original subtree.
738 --
739 -- Note: Parents are not preserved in original tree nodes that are
740 -- retrieved in this way (i.e. their children may have children whose
741 -- pointers which reference some other node).
743 -- Note: there is no direct mechanism for deleting an original node (in
744 -- a manner that can be reversed later). One possible approach is to use
745 -- Rewrite to substitute a null statement for the node to be deleted.
747 -----------------------------------
748 -- Generic Field Access Routines --
749 -----------------------------------
751 -- This subpackage provides the functions for accessing and procedures
752 -- for setting fields that are normally referenced by their logical
753 -- synonyms defined in packages Sinfo and Einfo. As previously
754 -- described the implementations of these packages use the package
755 -- Atree.Unchecked_Access.
759 -- Functions to allow interpretation of Union_Id values as Uint
760 -- and Ureal values
768 -- Functions to fetch contents of indicated field. It is an error
769 -- to attempt to read the value of a field which is not present.
993 -- Note: the following Uintnn functions have a special test for
994 -- the Field value being Empty. If an Empty value is found then
995 -- Uint_0 is returned. This avoids the rather tricky requirement
996 -- of initializing all Uint fields in nodes and entities.
1688 -- Procedures to set value of indicated field
2606 -- The following versions of Set_Noden also set the parent
2607 -- pointer of the referenced node if it is non_Empty
2624 -- The following versions of Set_Listn also set the parent pointer of
2625 -- the referenced node if it is non_Empty. The procedures for List6
2626 -- to List12 can only be applied to nodes which have an extension.
2645 -----------------------------
2646 -- Private Part Subpackage --
2647 -----------------------------
2649 -- The following package contains the definition of the data structure
2650 -- used by the implementation of the Atree package. Logically it really
2651 -- corresponds to the private part, hence the name. The reason that it
2652 -- is defined as a sub-package is to allow special access from clients
2653 -- that need to see the internals of the data structures.
2657 -------------------------
2658 -- Tree Representation --
2659 -------------------------
2661 -- The nodes of the tree are stored in a table (i.e. an array). In the
2662 -- case of extended nodes four consecutive components in the array are
2663 -- used. There are thus two formats for array components. One is used
2664 -- for non-extended nodes, and for the first component of extended
2665 -- nodes. The other is used for the extension parts (second, third and
2666 -- fourth components) of an extended node. A variant record structure
2667 -- is used to distinguish the two formats.
2671 -- Logically, the only field in the common part is the above
2672 -- Is_Extension discriminant (a single bit). However, Gigi cannot
2673 -- yet handle such a structure, so we fill out the common part of
2674 -- the record with fields that are used in different ways for
2675 -- normal nodes and node extensions.
2678 -- The Paren_Count field is represented using two boolean flags,
2679 -- where Pflag1 is worth 1, and Pflag2 is worth 2. This is done
2680 -- because we need to be easily able to reuse this field for
2681 -- extra flags in the extended node case.
2684 -- Flag used to indicate if node is a member of a list.
2685 -- This field is considered private to the Atree package.
2688 -- Currently unused flag
2691 -- Flag set by Mark_Rewrite_Insertion procedure.
2692 -- This field is considered private to the Atree package.
2695 -- Flag to indicate the node has been analyzed (and expanded)
2698 -- Flag to indicate that node comes from the source program (i.e.
2699 -- was built by the parser or scanner, not the analyzer or expander).
2702 -- Flag to indicate that an error message has been posted on the
2703 -- node (to avoid duplicate flags on the same node)
2720 -- The eighteen flags for a normal node
2722 -- The above fields are used as follows in components 2-4 of
2723 -- an extended node entry. These fields are not currently
2724 -- used in component 5 (where we still have lots of room!)
2726 -- In_List used as Flag19, Flag40, Flag129
2727 -- Unused_1 used as Flag20, Flag41, Flag130
2728 -- Rewrite_Ins used as Flag21, Flag42, Flag131
2729 -- Analyzed used as Flag22, Flag43, Flag132
2730 -- Comes_From_Source used as Flag23, Flag44, Flag133
2731 -- Error_Posted used as Flag24, Flag45, Flag134
2732 -- Flag4 used as Flag25, Flag46, Flag135
2733 -- Flag5 used as Flag26, Flag47, Flag136
2734 -- Flag6 used as Flag27, Flag48, Flag137
2735 -- Flag7 used as Flag28, Flag49, Flag138
2736 -- Flag8 used as Flag29, Flag50, Flag139
2737 -- Flag9 used as Flag30, Flag51, Flag140
2738 -- Flag10 used as Flag31, Flag52, Flag141
2739 -- Flag11 used as Flag32, Flag53, Flag142
2740 -- Flag12 used as Flag33, Flag54, Flag143
2741 -- Flag13 used as Flag34, Flag55, Flag144
2742 -- Flag14 used as Flag35, Flag56, Flag145
2743 -- Flag15 used as Flag36, Flag57, Flag146
2744 -- Flag16 used as Flag37, Flag58, Flag147
2745 -- Flag17 used as Flag38, Flag59, Flag148
2746 -- Flag18 used as Flag39, Flag60, Flag149
2747 -- Pflag1 used as Flag61, Flag62, Flag150
2748 -- Pflag2 used as Flag63, Flag64, Flag151
2751 -- For a non-extended node, or the initial section of an extended
2752 -- node, this field holds the Node_Kind value. For an extended node,
2753 -- The Nkind field is used as follows:
2754 --
2755 -- Second entry: holds the Ekind field of the entity
2756 -- Third entry: holds 8 additional flags (Flag65-Flag72)
2757 -- Fourth entry: not currently used
2759 -- Now finally (on an 32-bit boundary!) comes the variant part
2763 -- Non-extended node, or first component of extended node
2768 -- Source location for this node
2771 -- This field is used either as the Parent pointer (if In_List
2772 -- is False), or to point to the list header (if In_List is
2773 -- True). This field is considered private and can be modified
2774 -- only by Atree or by Nlists.
2781 -- Five general use fields, which can contain Node_Id, List_Id,
2782 -- Elist_Id, String_Id, or Name_Id values depending on the
2783 -- values in Nkind and (for extended nodes), in Ekind. See
2784 -- packages Sinfo and Einfo for details of their use.
2786 -- Extension (second component) of extended node
2796 -- Seven additional general fields available only for entities
2797 -- See package Einfo for details of their use (which depends
2798 -- on the value in the Ekind field).
2800 -- In the third component, the extension format as described
2801 -- above is used to hold additional general fields and flags
2802 -- as follows:
2804 -- Field6-11 Holds Field13-Field18
2805 -- Field12 Holds Flag73-Flag96 and Convention
2807 -- In the fourth component, the extension format as described
2808 -- above is used to hold additional general fields and flags
2809 -- as follows:
2811 -- Field6-10 Holds Field19-Field23
2812 -- Field11 Holds Flag152-Flag183
2813 -- Field12 Holds Flag97-Flag128
2815 -- In the fifth component, the extension format as described
2816 -- above is used to hold additional general fields and flags
2817 -- as follows:
2819 -- Field6-9 Holds Field24-Field27
2820 -- Field10 currently unused, reserved for expansion
2821 -- Field11 Holds Flag184-Flag215
2822 -- Field12 currently unused, reserved for expansion
2831 -- The following defines the extendible array used for the nodes table
2832 -- Nodes with extensions use two consecutive entries in the array