Subversion Repositories scarts

------------------------------------------------------------------------------

--                                                                          --

--                         GNAT COMPILER COMPONENTS                         --

--                                                                          --

--                                A T R E E                                 --

--                                                                          --

--                                 S p e c                                  --

--                                                                          --

--          Copyright (C) 1992-2005, Free Software Foundation, Inc.         --

--                                                                          --

-- GNAT is free software;  you can  redistribute it  and/or modify it under --

-- terms of the  GNU General Public License as published  by the Free Soft- --

-- ware  Foundation;  either version 2,  or (at your option) any later ver- --

-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --

-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --

-- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --

-- for  more details.  You should have  received  a copy of the GNU General --

-- Public License  distributed with GNAT;  see file COPYING.  If not, write --

-- to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor, --

-- Boston, MA 02110-1301, USA.                                              --

--                                                                          --

-- As a special exception,  if other files  instantiate  generics from this --

-- unit, or you link  this unit with other files  to produce an executable, --

-- this  unit  does not  by itself cause  the resulting  executable  to  be --

-- covered  by the  GNU  General  Public  License.  This exception does not --

-- however invalidate  any other reasons why  the executable file  might be --

-- covered by the  GNU Public License.                                      --

--                                                                          --

-- GNAT was originally developed  by the GNAT team at  New York University. --

-- Extensive contributions were provided by Ada Core Technologies Inc.      --

--                                                                          --

------------------------------------------------------------------------------

with Alloc;

with Sinfo;  use Sinfo;

with Einfo;  use Einfo;

with Types;  use Types;

with Snames; use Snames;

with System; use System;

with Table;

with Uintp;  use Uintp;

with Urealp; use Urealp;

with Unchecked_Conversion;

package Atree is

--  This package defines the format of the tree used to represent the Ada

--  program internally. Syntactic and semantic information is combined in

--  this tree. There is no separate symbol table structure.

--  WARNING: There is a C version of this package. Any changes to this

--  source file must be properly reflected in the C header file tree.h

--  Package Atree defines the basic structure of the tree and its nodes and

--  provides the basic abstract interface for manipulating the tree. Two

--  other packages use this interface to define the representation of Ada

--  programs using this tree format. The package Sinfo defines the basic

--  representation of the syntactic structure of the program, as output

--  by the parser. The package Entity_Info defines the semantic information

--  which is added to the tree nodes that represent declared entities (i.e.

--  the information which might typically be described in a separate symbol

--  table structure.

--  The front end of the compiler first parses the program and generates a

--  tree that is simply a syntactic representation of the program in abstract

--  syntax tree format. Subsequent processing in the front end traverses the

--  tree, transforming it in various ways and adding semantic information.

   ----------------------------------------

   -- Definitions of Fields in Tree Node --

   ----------------------------------------

   --  The representation of the tree is completely hidden, using a functional

   --  interface for accessing and modifying the contents of nodes. Logically

   --  a node contains a number of fields, much as though the nodes were

   --  defined as a record type. The fields in a node are as follows:

   --   Nkind         Indicates the kind of the node. This field is present

   --                 in all nodes. The type is Node_Kind, which is declared

   --                 in the package Sinfo.

   --   Sloc          Location (Source_Ptr) of the corresponding token

   --                 in the Source buffer. The individual node definitions

   --                 show which token is referenced by this pointer.

   --   In_List       A flag used to indicate if the node is a member

   --                    of a node list.

   --   Rewrite_Sub   A flag set if the node has been rewritten using

   --                 the Rewrite procedure. The original value of the

   --                 node is retrievable with Original_Node.

   --   Rewrite_Ins   A flag set if a node is marked as a rewrite inserted

   --                 node as a result of a call to Mark_Rewrite_Insertion.

   --   Paren_Count   A 2-bit count used on expression nodes to indicate

   --                 the level of parentheses. Up to 3 levels can be

   --                 accomodated. Anything more than 3 levels is treated

   --                 as 3 levels (conformance tests that complain about

   --                 this are hereby deemed pathological!) Set to zero

   --                 for non-subexpression nodes.

   --   Comes_From_Source

   --                 This flag is present in all nodes. It is set if the

   --                 node is built by the scanner or parser, and clear if

   --                 the node is built by the analyzer or expander. It

   --                 indicates that the node corresponds to a construct

   --                 that appears in the original source program.

   --   Analyzed      This flag is present in all nodes. It is set when

   --                 a node is analyzed, and is used to avoid analyzing

   --                 the same node twice. Analysis includes expansion if

   --                 expansion is active, so in this case if the flag is

   --                 set it means the node has been analyzed and expanded.

   --   Error_Posted  This flag is present in all nodes. It is set when

   --                 an error message is posted which is associated with

   --                 the flagged node. This is used to avoid posting more

   --                 than one message on the same node.

   --   Field1

   --   Field2

   --   Field3

   --   Field4

   --   Field5        Five fields holding Union_Id values

   --   ElistN        Synonym for FieldN typed as Elist_Id (Empty = No_Elist)

   --   ListN         Synonym for FieldN typed as List_Id

   --   NameN         Synonym for FieldN typed as Name_Id

   --   NodeN         Synonym for FieldN typed as Node_Id

   --   StrN          Synonym for FieldN typed as String_Id

   --   UintN         Synonym for FieldN typed as Uint (Empty = Uint_0)

   --   UrealN        Synonym for FieldN typed as Ureal

   --   Note: in the case of ElistN and UintN fields, it is common that we

   --   end up with a value of Union_Id'(0) as the default value. This value

   --   is meaningless as a Uint or Elist_Id value. We have two choices here.

   --   We could require that all Uint and Elist fields be initialized to an

   --   appropriate value, but that's error prone, since it would be easy to

   --   miss an initialization. So instead we have the retrieval functions

   --   generate an appropriate default value (Uint_0 or No_Elist). Probably

   --   it would be cleaner to generate No_Uint in the Uint case but we got

   --   stuck with representing an "unset" size value as zero early on, and

   --   it will take a bit of fiddling to change that ???

   --   Note: the actual usage of FieldN (i.e. whether it contains a Elist_Id,

   --   List_Id, Name_Id, Node_Id, String_Id, Uint or Ureal), depends on the

   --   value in Nkind. Generally the access to this field is always via the

   --   functional interface, so the field names ElistN, ListN, NameN, NodeN,

   --   StrN, UintN and UrealN are used only in the bodies of the access

   --   functions (i.e. in the bodies of Sinfo and Einfo). These access

   --   functions contain debugging code that checks that the use is

   --   consistent with Nkind and Ekind values.

   --   However, in specialized circumstances (examples are the circuit in

   --   generic instantiation to copy trees, and in the tree dump routine),

   --   it is useful to be able to do untyped traversals, and an internal

   --   package in Atree allows for direct untyped accesses in such cases.

   --   Flag4         Fifteen Boolean flags (use depends on Nkind and

   --   Flag5         Ekind, as described for FieldN). Again the access

   --   Flag6         is usually via subprograms in Sinfo and Einfo which

   --   Flag7         provide high-level synonyms for these flags, and

   --   Flag8         contain debugging code that checks that the values

   --   Flag9         in Nkind and Ekind are appropriate for the access.

   --   Flag10

   --   Flag11        Note that Flag1-3 are missing from this list. The

   --   Flag12        first three flag positions are reserved for the

   --   Flag13        standard flags (Comes_From_Source, Error_Posted,

   --   Flag14        and Analyzed)

   --   Flag15

   --   Flag16

   --   Flag17

   --   Flag18

   --   Link          For a node, points to the Parent. For a list, points

   --                 to the list header. Note that in the latter case, a

   --                 client cannot modify the link field. This field is

   --                 private to the Atree package (but is also modified

   --                 by the Nlists package).

   --  The following additional fields are present in extended nodes used

   --  for entities (Nkind in N_Entity).

   --   Ekind         Entity type. This field indicates the type of the

   --                 entity, it is of type Entity_Kind which is defined

   --                 in package Einfo.

   --   Flag19        197 additional flags

   --   ...

   --   Flag215

   --   Convention    Entity convention (Convention_Id value)

   --   Field6        Additional Union_Id value stored in tree

   --   Node6         Synonym for Field6 typed as Node_Id

   --   Elist6        Synonym for Field6 typed as Elist_Id (Empty = No_Elist)

   --   Uint6         Synonym for Field6 typed as Uint (Empty = Uint_0)

   --   Similar definitions for Field7 to Field27 (and Node7-Node27,

   --   Elist7-Elist27, Uint7-Uint27, Ureal7-Ureal27). Note that not all

   --   these functions are defined, only the ones that are actually used.

   type Paren_Count_Type is mod 4;

   for Paren_Count_Type'Size use 2;

   --  Type used for Paren_Count field

   function Last_Node_Id return Node_Id;

   pragma Inline (Last_Node_Id);

   --  Returns Id of last allocated node Id

   function Nodes_Address return System.Address;

   --  Return address of Nodes table (used in Back_End for Gigi call)

   function Num_Nodes return Nat;

   --  Total number of nodes allocated, where an entity counts as a single

   --  node. This count is incremented every time a node or entity is

   --  allocated, and decremented every time a node or entity is deleted.

   --  This value is used by Xref and by Treepr to allocate hash tables of

   --  suitable size for hashing Node_Id values.

   -----------------------

   -- Use of Empty Node --

   -----------------------

   --  The special Node_Id Empty is used to mark missing fields. Whenever the

   --  syntax has an optional component, then the corresponding field will be

   --  set to Empty if the component is missing.

   --  Note: Empty is not used to describe an empty list. Instead in this

   --  case the node field contains a list which is empty, and these cases

   --  should be distinguished (essentially from a type point of view, Empty

   --  is a Node, and is thus not a list).

   --  Note: Empty does in fact correspond to an allocated node. Only the

   --  Nkind field of this node may be referenced. It contains N_Empty, which

   --  uniquely identifies the empty case. This allows the Nkind field to be

   --  dereferenced before the check for Empty which is sometimes useful.

   -----------------------

   -- Use of Error Node --

   -----------------------

   --  The Error node is used during syntactic and semantic analysis to

   --  indicate that the corresponding piece of syntactic structure or

   --  semantic meaning cannot properly be represented in the tree because

   --  of an illegality in the program.

   --  If an Error node is encountered, then you know that a previous

   --  illegality has been detected. The proper reaction should be to

   --  avoid posting related cascaded error messages, and to propagate

   --  the error node if necessary.

   ------------------------

   -- Current_Error_Node --

   ------------------------

   --  The current error node is a global location indicating the current

   --  node that is being processed for the purposes of placing a compiler

   --  abort message. This is not necessarily perfectly accurate, it is

   --  just a reasonably accurate best guess. It is used to output the

   --  source location in the abort message by Comperr, and also to

   --  implement the d3 debugging flag. This is also used by Rtsfind

   --  to generate error messages for high integrity mode.

   --  There are two ways this gets set. During parsing, when new source

   --  nodes are being constructed by calls to New_Node and New_Entity,

   --  either one of these calls sets Current_Error_Node to the newly

   --  created node. During semantic analysis, this mechanism is not

   --  used, and instead Current_Error_Node is set by the subprograms in

   --  Debug_A that mark the start and end of analysis/expansion of a

   --  node in the tree.

   Current_Error_Node : Node_Id;

   --  Node to place error messages

   -------------------------------

   -- Default Setting of Fields --

   -------------------------------

   --  Nkind is set to N_Unused_At_Start

   --  Ekind is set to E_Void

   --  Sloc is always set, there is no default value

   --  Field1-5 fields are set to Empty

   --  Field6-22 fields in extended nodes are set to Empty

   --  Parent is set to Empty

   --  All Boolean flag fields are set to False

   --  Note: the value Empty is used in Field1-Field17 to indicate a null node.

   --  The usage varies. The common uses are to indicate absence of an

   --  optional clause or a completely unused Field1-17 field.

   -------------------------------------

   -- Use of Synonyms for Node Fields --

   -------------------------------------

   --  A subpackage Atree.Unchecked_Access provides routines for reading and

   --  writing the fields defined above (Field1-27, Node1-27, Flag1-215 etc).

   --  These unchecked access routines can be used for untyped traversals.

   --  In addition they are used in the implementations of the Sinfo and

   --  Einfo packages. These packages both provide logical synonyms for

   --  the generic fields, together with an appropriate set of access routines.

   --  Normally access to information within tree nodes uses these synonyms,

   --  providing a high level typed interface to the tree information.

   --------------------------------------------------

   -- Node Allocation and Modification Subprograms --

   --------------------------------------------------

   --  Generally the parser builds the tree and then it is further decorated

   --  (e.g. by setting the entity fields), but not fundamentally modified.

   --  However, there are cases in which the tree must be restructured by

   --  adding and rearranging nodes, as a result of disambiguating cases

   --  which the parser could not parse correctly, and adding additional

   --  semantic information (e.g. making constraint checks explicit). The

   --  following subprograms are used for constructing the tree in the first

   --  place, and then for subsequent modifications as required

   procedure Initialize;

   --  Called at the start of compilation to initialize the allocation of

   --  the node and list tables and make the standard entries for Empty,

   --  Error and Error_List. Note that Initialize must not be called if

   --  Tree_Read is used.

   procedure Lock;

   --  Called before the backend is invoked to lock the nodes table

   procedure Tree_Read;

   --  Initializes internal tables from current tree file using the relevant

   --  Table.Tree_Read routines. Note that Initialize should not be called if

   --  Tree_Read is used. Tree_Read includes all necessary initialization.

   procedure Tree_Write;

   --  Writes out internal tables to current tree file using the relevant

   --  Table.Tree_Write routines.

   function New_Node

     (New_Node_Kind : Node_Kind;

      New_Sloc      : Source_Ptr) return Node_Id;

   --  Allocates a completely new node with the given node type and source

   --  location values. All other fields are set to their standard defaults:

   --

   --    Empty for all FieldN fields

   --    False for all FlagN fields

   --

   --  The usual approach is to build a new node using this function and

   --  then, using the value returned, use the Set_xxx functions to set

   --  fields of the node as required. New_Node can only be used for

   --  non-entity nodes, i.e. it never generates an extended node.

   --

   --  If we are currently parsing, as indicated by a previous call to

   --  Set_Comes_From_Source_Default (True), then this call also resets

   --  the value of Current_Error_Node.

   function New_Entity

     (New_Node_Kind : Node_Kind;

      New_Sloc      : Source_Ptr) return Entity_Id;

   --  Similar to New_Node, except that it is used only for entity nodes

   --  and returns an extended node.

   procedure Set_Comes_From_Source_Default (Default : Boolean);

   --  Sets value of Comes_From_Source flag to be used in all subsequent

   --  New_Node and New_Entity calls until another call to this procedure

   --  changes the default. This value is set True during parsing and

   --  False during semantic analysis. This is also used to determine

   --  if New_Node and New_Entity should set Current_Error_Node.

   function Get_Comes_From_Source_Default return Boolean;

   pragma Inline (Get_Comes_From_Source_Default);

   --  Gets the current value of the Comes_From_Source flag

   procedure Preserve_Comes_From_Source (NewN, OldN : Node_Id);

   pragma Inline (Preserve_Comes_From_Source);

   --  When a node is rewritten, it is sometimes appropriate to preserve the

   --  original comes from source indication. This is true when the rewrite

   --  essentially corresponds to a transformation corresponding exactly to

   --  semantics in the reference manual. This procedure copies the setting

   --  of Comes_From_Source from OldN to NewN.

   function Has_Extension (N : Node_Id) return Boolean;

   pragma Inline (Has_Extension);

   --  Returns True if the given node has an extension (i.e. was created by

   --  a call to New_Entity rather than New_Node, and Nkind is in N_Entity)

   procedure Change_Node (N : Node_Id; New_Node_Kind : Node_Kind);

   --  This procedure replaces the given node by setting its Nkind field to

   --  the indicated value and resetting all other fields to their default

   --  values except for Sloc, which is unchanged, and the Parent pointer

   --  and list links, which are also unchanged. All other information in

   --  the original node is lost. The new node has an extension if the

   --  original node had an extension.

   procedure Copy_Node (Source : Node_Id; Destination : Node_Id);

   --  Copy the entire contents of the source node to the destination node.

   --  The contents of the source node is not affected. If the source node

   --  has an extension, then the destination must have an extension also.

   --  The parent pointer of the destination and its list link, if any, are

   --  not affected by the copy. Note that parent pointers of descendents

   --  are not adjusted, so the descendents of the destination node after

   --  the Copy_Node is completed have dubious parent pointers.

   function New_Copy (Source : Node_Id) return Node_Id;

   --  This function allocates a completely new node, and then initializes

   --  it by copying the contents of the source node into it. The contents

   --  of the source node is not affected. The target node is always marked

   --  as not being in a list (even if the source is a list member). The

   --  new node will have an extension if the source has an extension.

   --  New_Copy (Empty) returns Empty and New_Copy (Error) returns Error.

   --  Note that, unlike New_Copy_Tree, New_Copy does not recursively copy any

   --  descendents, so in general parent pointers are not set correctly for

   --  the descendents of the copied node. Both normal and extended nodes

   --  (entities) may be copied using New_Copy.

   function Relocate_Node (Source : Node_Id) return Node_Id;

   --  Source is a non-entity node that is to be relocated. A new node is

   --  allocated and the contents of Source are copied to this node using

   --  Copy_Node. The parent pointers of descendents of the node are then

   --  adjusted to point to the relocated copy. The original node is not

   --  modified, but the parent pointers of its descendents are no longer

   --  valid. This routine is used in conjunction with the tree rewrite

   --  routines (see descriptions of Replace/Rewrite).

   --

   --  Note that the resulting node has the same parent as the source

   --  node, and is thus still attached to the tree. It is valid for

   --  Source to be Empty, in which case Relocate_Node simply returns

   --  Empty as the result.

   function New_Copy_Tree

     (Source    : Node_Id;

      Map       : Elist_Id := No_Elist;

      New_Sloc  : Source_Ptr := No_Location;

      New_Scope : Entity_Id := Empty) return Node_Id;

   --  Given a node that is the root of a subtree, Copy_Tree copies the entire

   --  syntactic subtree, including recursively any descendents whose parent

   --  field references a copied node (descendents not linked to a copied node

   --  by the parent field are not copied, instead the copied tree references

   --  the same descendent as the original in this case, which is appropriate

   --  for non-syntactic fields such as Etype). The parent pointers in the

   --  copy are properly set. Copy_Tree (Empty/Error) returns Empty/Error.

   --  The one exception to the rule of not copying semantic fields is that

   --  any implicit types attached to the subtree are duplicated, so that

   --  the copy contains a distinct set of implicit type entities. The Map

   --  argument, if set to a non-empty Elist, specifies a set of mappings

   --  to be applied to entities in the tree. The map has the form:

   --

   --     old entity 1

   --     new entity to replace references to entity 1

   --     old entity 2

   --     new entity to replace references to entity 2

   --     ...

   --

   --  The call destroys the contents of Map in this case

   --

   --  The parameter New_Sloc, if set to a value other than No_Location, is

   --  used as the Sloc value for all nodes in the new copy. If New_Sloc is

   --  set to its default value No_Location, then the Sloc values of the

   --  nodes in the copy are simply copied from the corresponding original.

   --

   --  The Comes_From_Source indication is unchanged if New_Sloc is set to

   --  the default No_Location value, but is reset if New_Sloc is given, since

   --  in this case the result clearly is neither a source node or an exact

   --  copy of a source node.

   --

   --  The parameter New_Scope, if set to a value other than Empty, is the

   --  value to use as the Scope for any Itypes that are copied. The most

   --  typical value for this parameter, if given, is Current_Scope.

   function Copy_Separate_Tree (Source : Node_Id) return Node_Id;

   --  Given a node that is the root of a subtree, Copy_Separate_Tree copies

   --  the entire syntactic subtree, including recursively any descendants

   --  whose parent field references a copied node (descendants not linked to

   --  a copied node by the parent field are also copied.) The parent pointers

   --  in the copy are properly set. Copy_Separate_Tree (Empty/Error) returns

   --  Empty/Error. The semantic fields are not copied and the new subtree

   --  does not share any entity with source subtree.

   --  But the code *does* copy semantic fields, and the description above

   --  is in any case unclear on this point ??? (RBKD)

   procedure Exchange_Entities (E1 : Entity_Id; E2 : Entity_Id);

   --  Exchange the contents of two entities. The parent pointers are switched

   --  as well as the Defining_Identifier fields in the parents, so that the

   --  entities point correctly to their original parents. The effect is thus

   --  to leave the tree completely unchanged in structure, except that the

   --  entity ID values of the two entities are interchanged. Neither of the

   --  two entities may be list members.

   procedure Delete_Node (Node : Node_Id);

   --  The node, which must not be a list member, is deleted from the tree and

   --  its type is set to N_Unused_At_End. It is an error (not necessarily

   --  detected) to reference this node after it has been deleted. The

   --  implementation of the body of Atree is free to reuse the node to

   --  satisfy future node allocation requests, but is not required to do so.

   procedure Delete_Tree (Node : Node_Id);

   --  The entire syntactic subtree referenced by Node (i.e. the given node

   --  and all its syntactic descendents) are deleted as described above for

   --  Delete_Node.

   function Extend_Node (Node : Node_Id) return Entity_Id;

   --  This function returns a copy of its input node with an extension

   --  added. The fields of the extension are set to Empty. Due to the way

   --  extensions are handled (as four consecutive array elements), it may

   --  be necessary to reallocate the node, so that the returned value is

   --  not the same as the input value, but where possible the returned

   --  value will be the same as the input value (i.e. the extension will

   --  occur in place). It is the caller's responsibility to ensure that

   --  any pointers to the original node are appropriately updated. This

   --  function is used only by Sinfo.CN to change nodes into their

   --  corresponding entities.

   type Traverse_Result is (OK, OK_Orig, Skip, Abandon);

   --  This is the type of the result returned by the Process function passed

   --  to Traverse_Func and Traverse_Proc and also the type of the result of

   --  Traverse_Func itself. See descriptions below for details.

   generic

     with function Process (N : Node_Id) return Traverse_Result is <>;

   function Traverse_Func (Node : Node_Id) return Traverse_Result;

   --  This is a generic function that, given the parent node for a subtree,

   --  traverses all syntactic nodes of this tree, calling the given function

   --  Process on each one. The traversal is controlled as follows by the

   --  result returned by Process:

   --    OK       The traversal continues normally with the syntactic

   --             children of the node just processed.

   --    OK_Orig  The traversal continues normally with the syntactic

   --             children of the original node of the node just processed.

   --    Skip     The children of the node just processed are skipped and

   --             excluded from the traversal, but otherwise processing

   --             continues elsewhere in the tree.

   --    Abandon  The entire traversal is immediately abandoned, and the

   --             original call to Traverse returns Abandon.

   --  The result returned by Traverse is Abandon if processing was terminated

   --  by a call to Process returning Abandon, otherwise it is OK (meaning that

   --  all calls to process returned either OK or Skip).

   generic

     with function Process (N : Node_Id) return Traverse_Result is <>;

   procedure Traverse_Proc (Node : Node_Id);

   pragma Inline (Traverse_Proc);

   --  This is similar to Traverse_Func except that no result is returned,

   --  i.e. Traverse_Func is called and the result is simply discarded.

   ---------------------------

   -- Node Access Functions --

   ---------------------------

   --  The following functions return the contents of the indicated field of

   --  the node referenced by the argument, which is a Node_Id.

   function Nkind             (N : Node_Id) return Node_Kind;

   pragma Inline (Nkind);

   function Analyzed          (N : Node_Id) return Boolean;

   pragma Inline (Analyzed);

   function Comes_From_Source (N : Node_Id) return Boolean;

   pragma Inline (Comes_From_Source);

   function Error_Posted      (N : Node_Id) return Boolean;

   pragma Inline (Error_Posted);

   function Sloc              (N : Node_Id) return Source_Ptr;

   pragma Inline (Sloc);

   function Paren_Count       (N : Node_Id) return Paren_Count_Type;

   pragma Inline (Paren_Count);

   function Parent            (N : Node_Id) return Node_Id;

   pragma Inline (Parent);

   --  Returns the parent of a node if the node is not a list member, or

   --  else the parent of the list containing the node if the node is a

   --  list member.

   function No                (N : Node_Id) return Boolean;

   pragma Inline (No);

   --  Tests given Id for equality with the Empty node. This allows notations

   --  like "if No (Variant_Part)" as opposed to "if Variant_Part = Empty".

   function Present           (N : Node_Id) return Boolean;

   pragma Inline (Present);

   --  Tests given Id for inequality with the Empty node. This allows notations

   --  like "if Present (Statement)" as opposed to "if Statement /= Empty".

   -----------------------------

   -- Entity Access Functions --

   -----------------------------

   --  The following functions apply only to Entity_Id values, i.e.

   --  to extended nodes.

   function Ekind (E : Entity_Id) return Entity_Kind;

   pragma Inline (Ekind);

   function Convention (E : Entity_Id) return Convention_Id;

   pragma Inline (Convention);

   ----------------------------

   -- Node Update Procedures --

   ----------------------------

   --  The following functions set a specified field in the node whose Id is

   --  passed as the first argument. The second parameter is the new value

   --  to be set in the specified field. Note that Set_Nkind is in the next

   --  section, since its use is restricted.

   procedure Set_Sloc         (N : Node_Id; Val : Source_Ptr);

   pragma Inline (Set_Sloc);

   procedure Set_Paren_Count  (N : Node_Id; Val : Paren_Count_Type);

   pragma Inline (Set_Paren_Count);

   procedure Set_Parent       (N : Node_Id; Val : Node_Id);

   pragma Inline (Set_Parent);

   procedure Set_Analyzed     (N : Node_Id; Val : Boolean := True);

   pragma Inline (Set_Analyzed);

   procedure Set_Error_Posted (N : Node_Id; Val : Boolean := True);

   pragma Inline (Set_Error_Posted);

   procedure Set_Comes_From_Source (N : Node_Id; Val : Boolean);

   pragma Inline (Set_Comes_From_Source);

   --  Note that this routine is very rarely used, since usually the

   --  default mechanism provided sets the right value, but in some

   --  unusual cases, the value needs to be reset (e.g. when a source

   --  node is copied, and the copy must not have Comes_From_Source set.

   ------------------------------

   -- Entity Update Procedures --

   ------------------------------

   --  The following procedures apply only to Entity_Id values, i.e.

   --  to extended nodes.

   procedure Set_Ekind (E : Entity_Id; Val : Entity_Kind);

   pragma Inline (Set_Ekind);

   procedure Set_Convention (E : Entity_Id; Val : Convention_Id);

   pragma Inline (Set_Convention);

   ---------------------------

   -- Tree Rewrite Routines --

   ---------------------------

   --  During the compilation process it is necessary in a number of situations

   --  to rewrite the tree. In some cases, such rewrites do not affect the

   --  structure of the tree, for example, when an indexed component node is

   --  replaced by the corresponding call node (the parser cannot distinguish

   --  between these two cases).

   --  In other situations, the rewrite does affect the structure of the

   --  tree. Examples are the replacement of a generic instantiation by the

   --  instantiated spec and body, and the static evaluation of expressions.

   --  If such structural modifications are done by the expander, there are

   --  no difficulties, since the form of the tree after the expander has no

   --  special significance, except as input to the backend of the compiler.

   --  However, if these modifications are done by the semantic phase, then

   --  it is important that they be done in a manner which allows the original

   --  tree to be preserved. This is because tools like pretty printers need

   --  to have this original tree structure available.

   --  The subprograms in this section allow rewriting of the tree by either

   --  insertion of new nodes in an existing list, or complete replacement of

   --  a subtree. The resulting tree for most purposes looks as though it has

   --  been really changed, and there is no trace of the original. However,

   --  special subprograms, also defined in this section, allow the original

   --  tree to be reconstructed if necessary.

   --  For tree modifications done in the expander, it is permissible to

   --  destroy the original tree, although it is also allowable to use the

   --  tree rewrite routines where it is convenient to do so.

   procedure Mark_Rewrite_Insertion (New_Node : Node_Id);

   pragma Inline (Mark_Rewrite_Insertion);

   --  This procedure marks the given node as an insertion made during a tree

   --  rewriting operation. Only the root needs to be marked. The call does

   --  not do the actual insertion, which must be done using one of the normal

   --  list insertion routines. The node is treated normally in all respects

   --  except for its response to Is_Rewrite_Insertion. The function of these

   --  calls is to be able to get an accurate original tree. This helps the

   --  accuracy of Sprint.Sprint_Node, and in particular, when stubs are being

   --  generated, it is essential that the original tree be accurate.

   function Is_Rewrite_Insertion (Node : Node_Id) return Boolean;

   pragma Inline (Is_Rewrite_Insertion);

   --  Tests whether the given node was marked using Set_Rewrite_Insert. This

   --  is used in reconstructing the original tree (where such nodes are to

   --  be eliminated from the reconstructed tree).

   procedure Rewrite (Old_Node, New_Node : Node_Id);

   --  This is used when a complete subtree is to be replaced. Old_Node is the

   --  root of the old subtree to be replaced, and New_Node is the root of the

   --  newly constructed replacement subtree. The actual mechanism is to swap

   --  the contents of these two nodes fixing up the parent pointers of the

   --  replaced node (we do not attempt to preserve parent pointers for the

   --  original node). Neither Old_Node nor New_Node can be extended nodes.

   --

   --  Note: New_Node may not contain references to Old_Node, for example as

   --  descendents, since the rewrite would make such references invalid. If

   --  New_Node does need to reference Old_Node, then these references should

   --  be to a relocated copy of Old_Node (see Relocate_Node procedure).

   --

   --  Note: The Original_Node function applied to Old_Node (which has now

   --  been replaced by the contents of New_Node), can be used to obtain the

   --  original node, i.e. the old contents of Old_Node.

   procedure Replace (Old_Node, New_Node : Node_Id);

   --  This is similar to Rewrite, except that the old value of Old_Node is

   --  not saved, and the New_Node is deleted after the replace, since it

   --  is assumed that it can no longer be legitimately needed. The flag

   --  Is_Rewrite_Susbtitute will be False for the resulting node, unless

   --  it was already true on entry, and Original_Node will not return the

   --  original contents of the Old_Node, but rather the New_Node value (unless

   --  Old_Node had already been rewritten using Rewrite). Replace also

   --  preserves the setting of Comes_From_Source.

   --

   --  Note, New_Node may not contain references to Old_Node, for example as

   --  descendents, since the rewrite would make such references invalid. If

   --  New_Node does need to reference Old_Node, then these references should

   --  be to a relocated copy of Old_Node (see Relocate_Node procedure).

   --

   --  Replace is used in certain circumstances where it is desirable to

   --  suppress any history of the rewriting operation. Notably, it is used

   --  when the parser has mis-classified a node (e.g. a task entry call

   --  that the parser has parsed as a procedure call).

   function Is_Rewrite_Substitution (Node : Node_Id) return Boolean;

   pragma Inline (Is_Rewrite_Substitution);

   --  Return True iff Node has been rewritten (i.e. if Node is the root

   --  of a subtree which was installed using Rewrite).

   function Original_Node (Node : Node_Id) return Node_Id;

   pragma Inline (Original_Node);

   --  If Node has not been rewritten, then returns its input argument

   --  unchanged, else returns the Node for the original subtree.

   --

   --  Note: Parents are not preserved in original tree nodes that are

   --  retrieved in this way (i.e. their children may have children whose

   --  pointers which reference some other node).

   --  Note: there is no direct mechanism for deleting an original node (in

   --  a manner that can be reversed later). One possible approach is to use

   --  Rewrite to substitute a null statement for the node to be deleted.

   -----------------------------------

   -- Generic Field Access Routines --

   -----------------------------------

   --  This subpackage provides the functions for accessing and procedures

   --  for setting fields that are normally referenced by their logical

   --  synonyms defined in packages Sinfo and Einfo. As previously

   --  described the implementations of these packages use the package

   --  Atree.Unchecked_Access.

   package Unchecked_Access is

      --  Functions to allow interpretation of Union_Id values as Uint

      --  and Ureal values

      function To_Union is new Unchecked_Conversion (Uint,  Union_Id);

      function To_Union is new Unchecked_Conversion (Ureal, Union_Id);

      function From_Union is new Unchecked_Conversion (Union_Id, Uint);

      function From_Union is new Unchecked_Conversion (Union_Id, Ureal);

      --  Functions to fetch contents of indicated field. It is an error

      --  to attempt to read the value of a field which is not present.

      function Field1 (N : Node_Id) return Union_Id;

      pragma Inline (Field1);

      function Field2 (N : Node_Id) return Union_Id;

      pragma Inline (Field2);

      function Field3 (N : Node_Id) return Union_Id;

      pragma Inline (Field3);

      function Field4 (N : Node_Id) return Union_Id;

      pragma Inline (Field4);

      function Field5 (N : Node_Id) return Union_Id;

      pragma Inline (Field5);

      function Field6 (N : Node_Id) return Union_Id;

      pragma Inline (Field6);

      function Field7 (N : Node_Id) return Union_Id;

      pragma Inline (Field7);

      function Field8 (N : Node_Id) return Union_Id;

      pragma Inline (Field8);

      function Field9 (N : Node_Id) return Union_Id;

      pragma Inline (Field9);

      function Field10 (N : Node_Id) return Union_Id;