Subversion Repositories openrisc

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

--                                                                          --

--                         GNAT COMPILER COMPONENTS                         --

--                                                                          --

--                                S I N F O                                 --

--                                                                          --

--                                 S p e c                                  --

--                                                                          --

--          Copyright (C) 1992-2009, 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 3,  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.                                     --

--                                                                          --

-- As a special exception under Section 7 of GPL version 3, you are granted --

-- additional permissions described in the GCC Runtime Library Exception,   --

-- version 3.1, as published by the Free Software Foundation.               --

--                                                                          --

-- You should have received a copy of the GNU General Public License and    --

-- a copy of the GCC Runtime Library Exception along with this program;     --

-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --

-- <http://www.gnu.org/licenses/>.                                          --

--                                                                          --

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

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

--                                                                          --

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

--  This package defines the structure of the abstract syntax tree. The Tree

--  package provides a basic tree structure. Sinfo describes how this structure

--  is used to represent the syntax of an Ada program.

--  The grammar in the RM is followed very closely in the tree design, and is

--  repeated as part of this source file.

--  The tree contains not only the full syntactic representation of the

--  program, but also the results of semantic analysis. In particular, the

--  nodes for defining identifiers, defining character literals and defining

--  operator symbols, collectively referred to as entities, represent what

--  would normally be regarded as the symbol table information. In addition a

--  number of the tree nodes contain semantic information.

--  WARNING: Several files are automatically generated from this package.

--  See below for details.

with Namet;  use Namet;

with Types;  use Types;

with Uintp;  use Uintp;

with Urealp; use Urealp;

package Sinfo is

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

   -- Making Changes to This File --

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

   --  If changes are made to this file, a number of related steps must be

   --  carried out to ensure consistency. First, if a field access function is

   --  added, it appears in seven places:

   --    The documentation associated with the node

   --    The spec of the access function in sinfo.ads

   --    The body of the access function in sinfo.adb

   --    The pragma Inline at the end of sinfo.ads for the access function

   --    The spec of the set procedure in sinfo.ads

   --    The body of the set procedure in sinfo.adb

   --    The pragma Inline at the end of sinfo.ads for the set procedure

   --  The field chosen must be consistent in all places, and, for a node that

   --  is a subexpression, must not overlap any of the standard expression

   --  fields.

   --  In addition, if any of the standard expression fields is changed, then

   --  the utility program which creates the Treeprs spec (in file treeprs.ads)

   --  must be updated appropriately, since it special cases expression fields.

   --  If a new tree node is added, then the following changes are made

   --    Add it to the documentation in the appropriate place

   --    Add its fields to this documentation section

   --    Define it in the appropriate classification in Node_Kind

   --    In the body (sinfo), add entries to the access functions for all

   --     its fields (except standard expression fields) to include the new

   --     node in the checks.

   --    Add an appropriate section to the case statement in sprint.adb

   --    Add an appropriate section to the case statement in sem.adb

   --    Add an appropriate section to the case statement in exp_util.adb

   --     (Insert_Actions procedure)

   --    For a subexpression, add an appropriate section to the case

   --     statement in sem_eval.adb

   --    For a subexpression, add an appropriate section to the case

   --     statement in sem_res.adb

   --  Finally, four utility programs must be run:

   --    Run CSinfo to check that you have made the changes consistently. It

   --     checks most of the rules given above, with clear error messages. This

   --     utility reads sinfo.ads and sinfo.adb and generates a report to

   --     standard output.

   --    Run XSinfo to create sinfo.h, the corresponding C header. This

   --     utility reads sinfo.ads and generates sinfo.h. Note that it does

   --     not need to read sinfo.adb, since the contents of the body are

   --     algorithmically determinable from the spec.

   --    Run XTreeprs to create treeprs.ads, an updated version of the module

   --     that is used to drive the tree print routine. This utility reads (but

   --     does not modify) treeprs.adt, the template that provides the basic

   --     structure of the file, and then fills in the data from the comments

   --     in sinfo.ads.

   --    Run XNmake to create nmake.ads and nmake.adb, the package body and

   --     spec of the Nmake package which contains functions for constructing

   --     nodes.

   --  All of the above steps except CSinfo are done automatically by the

   --  build scripts when you do a full bootstrap.

   --  Note: sometime we could write a utility that actually generated the body

   --  of sinfo from the spec instead of simply checking it, since, as noted

   --  above, the contents of the body can be determined from the spec.

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

   -- Implicit Nodes in the Tree --

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

   --  Generally the structure of the tree very closely follows the grammar as

   --  defined in the RM. However, certain nodes are omitted to save space and

   --  simplify semantic processing. Two general classes of such omitted nodes

   --  are as follows:

   --   If the only possibilities for a non-terminal are one or more other

   --   non-terminals (i.e. the rule is a "skinny" rule), then usually the

   --   corresponding node is omitted from the tree, and the target construct

   --   appears directly. For example, a real type definition is either

   --   floating point definition or a fixed point definition. No explicit node

   --   appears for real type definition. Instead either the floating point

   --   definition or fixed point definition appears directly.

   --   If a non-terminal corresponds to a list of some other non-terminal

   --   (possibly with separating punctuation), then usually it is omitted from

   --   the tree, and a list of components appears instead. For example,

   --   sequence of statements does not appear explicitly in the tree. Instead

   --   a list of statements appears directly.

   --  Some additional cases of omitted nodes occur and are documented

   --  individually. In particular, many nodes are omitted in the tree

   --  generated for an expression.

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

   -- Handling of Defining Identifier Lists --

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

   --  In several declarative forms in the syntax, lists of defining

   --  identifiers appear (object declarations, component declarations, number

   --  declarations etc.)

   --  The semantics of such statements are equivalent to a series of identical

   --  declarations of single defining identifiers (except that conformance

   --  checks require the same grouping of identifiers in the parameter case).

   --  To simplify semantic processing, the parser breaks down such multiple

   --  declaration cases into sequences of single declarations, duplicating

   --  type and initialization information as required. The flags More_Ids and

   --  Prev_Ids are used to record the original form of the source in the case

   --  where the original source used a list of names, More_Ids being set on

   --  all but the last name and Prev_Ids being set on all but the first name.

   --  These flags are used to reconstruct the original source (e.g. in the

   --  Sprint package), and also are included in the conformance checks, but

   --  otherwise have no semantic significance.

   --  Note: the reason that we use More_Ids and Prev_Ids rather than

   --  First_Name and Last_Name flags is so that the flags are off in the

   --  normal one identifier case, which minimizes tree print output.

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

   -- Use of Node Lists --

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

   --  With a few exceptions, if a construction of the form {non-terminal}

   --  appears in the tree, lists are used in the corresponding tree node (see

   --  package Nlists for handling of node lists). In this case a field of the

   --  parent node points to a list of nodes for the non-terminal. The field

   --  name for such fields has a plural name which always ends in "s". For

   --  example, a case statement has a field Alternatives pointing to list of

   --  case statement alternative nodes.

   --  Only fields pointing to lists have names ending in "s", so generally the

   --  structure is strongly typed, fields not ending in s point to single

   --  nodes, and fields ending in s point to lists.

   --  The following example shows how a traversal of a list is written. We

   --  suppose here that Stmt points to a N_Case_Statement node which has a

   --  list field called Alternatives:

   --   Alt := First (Alternatives (Stmt));

   --   while Present (Alt) loop

   --      ..

   --      -- processing for case statement alternative Alt

   --      ..

   --      Alt := Next (Alt);

   --   end loop;

   --  The Present function tests for Empty, which in this case signals the end

   --  of the list. First returns Empty immediately if the list is empty.

   --  Present is defined in Atree, First and Next are defined in Nlists.

   --  The exceptions to this rule occur with {DEFINING_IDENTIFIERS} in all

   --  contexts, which is handled as described in the previous section, and

   --  with {,library_unit_NAME} in the N_With_Clause mode, which is handled

   --  using the First_Name and Last_Name flags, as further detailed in the

   --  description of the N_With_Clause node.

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

   -- Pragmas --

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

   --  Pragmas can appear in many different context, but are not included in

   --  the grammar. Still they must appear in the tree, so they can be properly

   --  processed.

   --  Two approaches are used. In some cases, an extra field is defined in an

   --  appropriate node that contains a list of pragmas appearing in the

   --  expected context. For example pragmas can appear before an

   --  Accept_Alternative in a Selective_Accept_Statement, and these pragmas

   --  appear in the Pragmas_Before field of the N_Accept_Alternative node.

   --  The other approach is to simply allow pragmas to appear in syntactic

   --  lists where the grammar (of course) does not include the possibility.

   --  For example, the Variants field of an N_Variant_Part node points to a

   --  list that can contain both N_Pragma and N_Variant nodes.

   --  To make processing easier in the latter case, the Nlists package

   --  provides a set of routines (First_Non_Pragma, Last_Non_Pragma,

   --  Next_Non_Pragma, Prev_Non_Pragma) that allow such lists to be handled

   --  ignoring all pragmas.

   --  In the case of the variants list, we can either write:

   --      Variant := First (Variants (N));

   --      while Present (Variant) loop

   --         ...

   --         Variant := Next (Variant);

   --      end loop;

   --  or

   --      Variant := First_Non_Pragma (Variants (N));

   --      while Present (Variant) loop

   --         ...

   --         Variant := Next_Non_Pragma (Variant);

   --      end loop;

   --  In the first form of the loop, Variant can either be an N_Pragma or an

   --  N_Variant node. In the second form, Variant can only be N_Variant since

   --  all pragmas are skipped.

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

   -- Optional Fields --

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

   --  Fields which correspond to a section of the syntax enclosed in square

   --  brackets are generally omitted (and the corresponding field set to Empty

   --  for a node, or No_List for a list). The documentation of such fields

   --  notes these cases. One exception to this rule occurs in the case of

   --  possibly empty statement sequences (such as the sequence of statements

   --  in an entry call alternative). Such cases appear in the syntax rules as

   --  [SEQUENCE_OF_STATEMENTS] and the fields corresponding to such optional

   --  statement sequences always contain an empty list (not No_List) if no

   --  statements are present.

   --  Note: the utility program that constructs the body and spec of the Nmake

   --  package relies on the format of the comments to determine if a field

   --  should have a default value in the corresponding make routine. The rule

   --  is that if the first line of the description of the field contains the

   --  string "(set to xxx if", then a default value of xxx is provided for

   --  this field in the corresponding Make_yyy routine.

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

   -- Note on Body/Spec Terminology --

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

   --  In informal discussions about Ada, it is customary to refer to package

   --  and subprogram specs and bodies. However, this is not technically

   --  correct, what is normally referred to as a spec or specification is in

   --  fact a package declaration or subprogram declaration. We are careful in

   --  GNAT to use the correct terminology and in particular, the full word

   --  specification is never used as an incorrect substitute for declaration.

   --  The structure and terminology used in the tree also reflects the grammar

   --  and thus uses declaration and specification in the technically correct

   --  manner.

   --  However, there are contexts in which the informal terminology is useful.

   --  We have the word "body" to refer to the Interp_Etype declared by the

   --  declaration of a unit body, and in some contexts we need similar term to

   --  refer to the entity declared by the package or subprogram declaration,

   --  and simply using declaration can be confusing since the body also has a

   --  declaration.

   --  An example of such a context is the link between the package body and

   --  its declaration. With_Declaration is confusing, since the package body

   --  itself is a declaration.

   --  To deal with this problem, we reserve the informal term Spec, i.e. the

   --  popular abbreviation used in this context, to refer to the entity

   --  declared by the package or subprogram declaration. So in the above

   --  example case, the field in the body is called With_Spec.

   --  Another important context for the use of the word Spec is in error

   --  messages, where a hyper-correct use of declaration would be confusing to

   --  a typical Ada programmer, and even for an expert programmer can cause

   --  confusion since the body has a declaration as well.

   --  So, to summarize:

   --     Declaration    always refers to the syntactic entity that is called

   --                    a declaration. In particular, subprogram declaration

   --                    and package declaration are used to describe the

   --                    syntactic entity that includes the semicolon.

   --     Specification  always refers to the syntactic entity that is called

   --                    a specification. In particular, the terms procedure

   --                    specification, function specification, package

   --                    specification, subprogram specification always refer

   --                    to the syntactic entity that has no semicolon.

   --     Spec           is an informal term, used to refer to the entity

   --                    that is declared by a task declaration, protected

   --                    declaration, generic declaration, subprogram

   --                    declaration or package declaration.

   --  This convention is followed throughout the GNAT documentation

   --  both internal and external, and in all error message text.

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

   -- Internal Use Nodes --

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

   --  These are Node_Kind settings used in the internal implementation which

   --  are not logically part of the specification.

   --  N_Unused_At_Start

   --  Completely unused entry at the start of the enumeration type. This

   --  is inserted so that no legitimate value is zero, which helps to get

   --  better debugging behavior, since zero is a likely uninitialized value).

   --  N_Unused_At_End

   --  Completely unused entry at the end of the enumeration type. This is

   --  handy so that arrays with Node_Kind as the index type have an extra

   --  entry at the end (see for example the use of the Pchar_Pos_Array in

   --  Treepr, where the extra entry provides the limit value when dealing with

   --  the last used entry in the array).

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

   -- Note on the settings of Sloc fields --

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

   --  The Sloc field of nodes that come from the source is set by the parser.

   --  For internal nodes, and nodes generated during expansion the Sloc is

   --  usually set in the call to the constructor for the node. In general the

   --  Sloc value chosen for an internal node is the Sloc of the source node

   --  whose processing is responsible for the expansion. For example, the Sloc

   --  of an inherited primitive operation is the Sloc of the corresponding

   --  derived type declaration.

   --  For the nodes of a generic instantiation, the Sloc value is encoded to

   --  represent both the original Sloc in the generic unit, and the Sloc of

   --  the instantiation itself. See Sinput.ads for details.

   --  Subprogram instances create two callable entities: one is the visible

   --  subprogram instance, and the other is an anonymous subprogram nested

   --  within a wrapper package that contains the renamings for the actuals.

   --  Both of these entities have the Sloc of the defining entity in the

   --  instantiation node. This simplifies some ASIS queries.

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

   -- Field Definitions --

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

   --  In the following node definitions, all fields, both syntactic and

   --  semantic, are documented. The one exception is in the case of entities

   --  (defining identifiers, character literals and operator symbols), where

   --  the usage of the fields depends on the entity kind. Entity fields are

   --  fully documented in the separate package Einfo.

   --  In the node definitions, three common sets of fields are abbreviated to

   --  save both space in the documentation, and also space in the string

   --  (defined in Tree_Print_Strings) used to print trees. The following

   --  abbreviations are used:

   --  Note: the utility program that creates the Treeprs spec (in the file

   --  xtreeprs.adb) knows about the special fields here, so it must be

   --  modified if any change is made to these fields.

   --    "plus fields for binary operator"

   --       Chars                    (Name1)      Name_Id for the operator

   --       Left_Opnd                (Node2)      left operand expression

   --       Right_Opnd               (Node3)      right operand expression

   --       Entity                   (Node4-Sem)  defining entity for operator

   --       Associated_Node          (Node4-Sem)  for generic processing

   --       Do_Overflow_Check        (Flag17-Sem) set if overflow check needed

   --       Has_Private_View         (Flag11-Sem) set in generic units.

   --    "plus fields for unary operator"

   --       Chars                    (Name1)      Name_Id for the operator

   --       Right_Opnd               (Node3)      right operand expression

   --       Entity                   (Node4-Sem)  defining entity for operator

   --       Associated_Node          (Node4-Sem)  for generic processing

   --       Do_Overflow_Check        (Flag17-Sem) set if overflow check needed

   --       Has_Private_View         (Flag11-Sem) set in generic units.

   --    "plus fields for expression"

   --       Paren_Count                           number of parentheses levels

   --       Etype                    (Node5-Sem)  type of the expression

   --       Is_Overloaded            (Flag5-Sem)  >1 type interpretation exists

   --       Is_Static_Expression     (Flag6-Sem)  set for static expression

   --       Raises_Constraint_Error  (Flag7-Sem)  evaluation raises CE

   --       Must_Not_Freeze          (Flag8-Sem)  set if must not freeze

   --       Do_Range_Check           (Flag9-Sem)  set if a range check needed

   --       Assignment_OK            (Flag15-Sem) set if modification is OK

   --       Is_Controlling_Actual    (Flag16-Sem) set for controlling argument

   --  Note: see under (EXPRESSION) for further details on the use of

   --  the Paren_Count field to record the number of parentheses levels.

   --  Node_Kind is the type used in the Nkind field to indicate the node kind.

   --  The actual definition of this type is given later (the reason for this

   --  is that we want the descriptions ordered by logical chapter in the RM,

   --  but the type definition is reordered to facilitate the definition of

   --  some subtype ranges. The individual descriptions of the nodes show how

   --  the various fields are used in each node kind, as well as providing

   --  logical names for the fields. Functions and procedures are provided for

   --  accessing and setting these fields using these logical names.

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

   -- Gigi Restrictions --

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

   --  The tree passed to Gigi is more restricted than the general tree form.

   --  For example, as a result of expansion, most of the tasking nodes can

   --  never appear. For each node to which either a complete or partial

   --  restriction applies, a note entitled "Gigi restriction" appears which

   --  documents the restriction.

   --  Note that most of these restrictions apply only to trees generated when

   --  code is being generated, since they involved expander actions that

   --  destroy the tree.

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

   -- Common Flag Fields --

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

   --  The following flag fields appear in all nodes

   --  Analyzed (Flag1)

   --    This flag is used to indicate that a node (and all its children have

   --    been analyzed. It is used to avoid reanalysis of a node that has

   --    already been analyzed, both for efficiency and functional correctness

   --    reasons.

   --  Comes_From_Source (Flag2)

   --    This flag is set if the node comes directly from an explicit construct

   --    in the source. It is normally on for any nodes built by the scanner or

   --    parser from the source program, with the exception that in a few cases

   --    the parser adds nodes to normalize the representation (in particular

   --    a null statement is added to a package body if there is no begin/end

   --    initialization section.

   --

   --    Most nodes inserted by the analyzer or expander are not considered

   --    as coming from source, so the flag is off for such nodes. In a few

   --    cases, the expander constructs nodes closely equivalent to nodes

   --    from the source program (e.g. the allocator built for build-in-place

   --    case), and the Comes_From_Source flag is deliberately set.

   --  Error_Posted (Flag3)

   --    This flag is used to avoid multiple error messages being posted on or

   --    referring to the same node. This flag is set if an error message

   --    refers to a node or is posted on its source location, and has the

   --    effect of inhibiting further messages involving this same node.

   --  Has_Dynamic_Length_Check (Flag10-Sem)

   --    This flag is present on all nodes. It is set to indicate that one of

   --    the routines in unit Checks has generated a length check action which

   --    has been inserted at the flagged node. This is used to avoid the

   --    generation of duplicate checks.

   --  Has_Dynamic_Range_Check (Flag12-Sem)

   --    This flag is present on all nodes. It is set to indicate that one of

   --    the routines in unit Checks has generated a range check action which

   --    has been inserted at the flagged node. This is used to avoid the

   --    generation of duplicate checks.

   --  Has_Local_Raise (Flag8-Sem)

   --    Present in exception handler nodes. Set if the handler can be entered

   --    via a local raise that gets transformed to a goto statement. This will

   --    always be set if Local_Raise_Statements is non-empty, but can also be

   --    set as a result of generation of N_Raise_xxx nodes, or flags set in

   --    nodes requiring generation of back end checks.

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

   -- Description of Semantic Fields --

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

   --  The meaning of the syntactic fields is generally clear from their names

   --  without any further description, since the names are chosen to

   --  correspond very closely to the syntax in the reference manual. This

   --  section describes the usage of the semantic fields, which are used to

   --  contain additional information determined during semantic analysis.

   --  ABE_Is_Certain (Flag18-Sem)

   --    This flag is set in an instantiation node or a call node is determined

   --    to be sure to raise an ABE. This is used to trigger special handling

   --    of such cases, particularly in the instantiation case where we avoid

   --    instantiating the body if this flag is set. This flag is also present

   --    in an N_Formal_Package_Declaration_Node since formal package

   --    declarations are treated like instantiations, but it is always set to

   --    False in this context.

   --  Accept_Handler_Records (List5-Sem)

   --    This field is present only in an N_Accept_Alternative node. It is used

   --    to temporarily hold the exception handler records from an accept

   --    statement in a selective accept. These exception handlers will

   --    eventually be placed in the Handler_Records list of the procedure

   --    built for this accept (see Expand_N_Selective_Accept procedure in

   --    Exp_Ch9 for further details).

   --  Access_Types_To_Process (Elist2-Sem)

   --    Present in N_Freeze_Entity nodes for Incomplete or private types.

   --    Contains the list of access types which may require specific treatment

   --    when the nature of the type completion is completely known. An example

   --    of such treatment is the generation of the associated_final_chain.

   --  Actions (List1-Sem)

   --    This field contains a sequence of actions that are associated with the

   --    node holding the field. See the individual node types for details of

   --    how this field is used, as well as the description of the specific use

   --    for a particular node type.

   --  Activation_Chain_Entity (Node3-Sem)

   --    This is used in tree nodes representing task activators (blocks,

   --    subprogram bodies, package declarations, and task bodies). It is

   --    initially Empty, and then gets set to point to the entity for the

   --    declared Activation_Chain variable when the first task is declared.

   --    When tasks are declared in the corresponding declarative region this

   --    entity is located by name (its name is always _Chain) and the declared

   --    tasks are added to the chain. Note that N_Extended_Return_Statement

   --    does not have this attribute, although it does have an activation

   --    chain. This chain is used to store the tasks temporarily, and is not

   --    used for activating them. On successful completion of the return

   --    statement, the tasks are moved to the caller's chain, and the caller

   --    activates them.

   --  Acts_As_Spec (Flag4-Sem)

   --    A flag set in the N_Subprogram_Body node for a subprogram body which

   --    is acting as its own spec, except in the case of a library level

   --    subprogram, in which case the flag is set on the parent compilation

   --    unit node instead (see further description in spec of Lib package).

   --    ??? Above note about Lib is dubious since lib.ads does not mention

   --    Acts_As_Spec at all.

   --  Actual_Designated_Subtype (Node4-Sem)

   --    Present in N_Free_Statement and N_Explicit_Dereference nodes. If gigi

   --    needs to known the dynamic constrained subtype of the designated

   --    object, this attribute is set to that type. This is done for

   --    N_Free_Statements for access-to-classwide types and access to

   --    unconstrained packed array types, and for N_Explicit_Dereference when

   --    the designated type is an unconstrained packed array and the

   --    dereference is the prefix of a 'Size attribute reference.

   --  Address_Warning_Posted (Flag18-Sem)

   --    Present in N_Attribute_Definition nodes. Set to indicate that we have

   --    posted a warning for the address clause regarding size or alignment

   --    issues. Used to inhibit multiple redundant messages.

   --  Aggregate_Bounds (Node3-Sem)

   --    Present in array N_Aggregate nodes. If the bounds of the aggregate are

   --    known at compile time, this field points to an N_Range node with those

   --    bounds. Otherwise Empty.

   --  All_Others (Flag11-Sem)

   --    Present in an N_Others_Choice node. This flag is set for an others

   --    exception where all exceptions are to be caught, even those that are

   --    not normally handled (in particular the tasking abort signal). This

   --    is used for translation of the at end handler into a normal exception

   --    handler.

   --  Assignment_OK (Flag15-Sem)

   --    This flag is set in a subexpression node for an object, indicating

   --    that the associated object can be modified, even if this would not

   --    normally be permissible (either by direct assignment, or by being

   --    passed as an out or in-out parameter). This is used by the expander

   --    for a number of purposes, including initialization of constants and

   --    limited type objects (such as tasks), setting discriminant fields,

   --    setting tag values, etc. N_Object_Declaration nodes also have this

   --    flag defined. Here it is used to indicate that an initialization

   --    expression is valid, even where it would normally not be allowed

   --    (e.g. where the type involved is limited).

   --  Associated_Node (Node4-Sem)

   --    Present in nodes that can denote an entity: identifiers, character

   --    literals, operator symbols, expanded names, operator nodes, and

   --    attribute reference nodes (all these nodes have an Entity field).

   --    This field is also present in N_Aggregate, N_Selected_Component, and

   --    N_Extension_Aggregate nodes. This field is used in generic processing

   --    to create links between the generic template and the generic copy.

   --    See Sem_Ch12.Get_Associated_Node for full details. Note that this

   --    field overlaps Entity, which is fine, since, as explained in Sem_Ch12,

   --    the normal function of Entity is not required at the point where the

   --    Associated_Node is set. Note also, that in generic templates, this

   --    means that the Entity field does not necessarily point to an Entity.

   --    Since the back end is expected to ignore generic templates, this is

   --    harmless.

   --  At_End_Proc (Node1)

   --    This field is present in an N_Handled_Sequence_Of_Statements node.

   --    It contains an identifier reference for the cleanup procedure to be

   --    called. See description of this node for further details.

   --  Backwards_OK (Flag6-Sem)

   --    A flag present in the N_Assignment_Statement node. It is used only

   --    if the type being assigned is an array type, and is set if analysis

   --    determines that it is definitely safe to do the copy backwards, i.e.

   --    starting at the highest addressed element. This is the case if either

   --    the operands do not overlap, or they may overlap, but if they do,

   --    then the left operand is at a higher address than the right operand.

   --

   --    Note: If neither of the flags Forwards_OK or Backwards_OK is set, it

   --    means that the front end could not determine that either direction is

   --    definitely safe, and a runtime check may be required if the backend

   --    cannot figure it out. If both flags Forwards_OK and Backwards_OK are

   --    set, it means that the front end can assure no overlap of operands.

   --  Body_To_Inline (Node3-Sem)

   --    present in subprogram declarations. Denotes analyzed but unexpanded

   --    body of subprogram, to be used when inlining calls. Present when the

   --    subprogram has an Inline pragma and inlining is enabled. If the

   --    declaration is completed by a renaming_as_body, and the renamed en-

   --    tity is a subprogram, the Body_To_Inline is the name of that entity,

   --    which is used directly in later calls to the original subprogram.

   --  Body_Required (Flag13-Sem)

   --    A flag that appears in the N_Compilation_Unit node indicating that

   --    the corresponding unit requires a body. For the package case, this

   --    indicates that a completion is required. In Ada 95, if the flag is not

   --    set for the package case, then a body may not be present. In Ada 83,

   --    if the flag is not set for the package case, then body is optional.

   --    For a subprogram declaration, the flag is set except in the case where

   --    a pragma Import or Interface applies, in which case no body is

   --    permitted (in Ada 83 or Ada 95).

   --  By_Ref (Flag5-Sem)

   --    Present in N_Simple_Return_Statement and N_Extended_Return_Statement,

   --    this flag is set when the returned expression is already allocated on

   --    the secondary stack and thus the result is passed by reference rather

   --    than copied another time.

   --  Check_Address_Alignment (Flag11-Sem)

   --    A flag present in N_Attribute_Definition clause for a 'Address

   --    attribute definition. This flag is set if a dynamic check should be

   --    generated at the freeze point for the entity to which this address

   --    clause applies. The reason that we need this flag is that we want to

   --    check for range checks being suppressed at the point where the

   --    attribute definition clause is given, rather than testing this at the

   --    freeze point.

   --  Coextensions (Elist4-Sem)

   --    Present in allocators nodes. Points to list of allocators for the

   --    access discriminants of the allocated object.

   --  Comes_From_Extended_Return_Statement (Flag18-Sem)

   --    Present in N_Simple_Return_Statement nodes. True if this node was

   --    constructed as part of the N_Extended_Return_Statement expansion.

   --  Compile_Time_Known_Aggregate (Flag18-Sem)

   --    Present in N_Aggregate nodes. Set for aggregates which can be fully

   --    evaluated at compile time without raising constraint error. Such

   --    aggregates can be passed as is to Gigi without any expansion. See

   --    Sem_Aggr for the specific conditions under which an aggregate has this

   --    flag set. See also the flag Static_Processing_OK.

   --  Componentwise_Assignment (Flag14-Sem)

   --    Present in N_Assignment_Statement nodes. Set for a record assignment

   --    where all that needs doing is to expand it into component-by-component

   --    assignments. This is used internally for the case of tagged types with

   --    rep clauses, where we need to avoid recursion (we don't want to try to

   --    generate a call to the primitive operation, because this is the case

   --    where we are compiling the primitive operation). Note that when we are

   --    expanding component assignments in this case, we never assign the _tag

   --    field, but we recursively assign components of the parent type.

   --  Condition_Actions (List3-Sem)

   --    This field appears in else-if nodes and in the iteration scheme node

   --    for while loops. This field is only used during semantic processing to

   --    temporarily hold actions inserted into the tree. In the tree passed

   --    to gigi, the condition actions field is always set to No_List. For

   --    details on how this field is used, see the routine Insert_Actions in

   --    package Exp_Util, and also the expansion routines for the relevant

   --    nodes.

   --  Context_Pending (Flag16-Sem)

   --    This field appears in Compilation_Unit nodes, to indicate that the

   --    context of the unit is being compiled. Used to detect circularities

   --    that are not otherwise detected by the loading mechanism. Such

   --    circularities can occur in the presence of limited and non-limited

   --    with_clauses that mention the same units.

   --  Controlling_Argument (Node1-Sem)

   --    This field is set in procedure and function call nodes if the call

   --    is a dispatching call (it is Empty for a non-dispatching call). It

   --    indicates the source of the call's controlling tag. For procedure

   --    calls, the Controlling_Argument is one of the actuals. For function

   --    that has a dispatching result, it is an entity in the context of the

   --    call that can provide a tag, or else it is the tag of the root type

   --    of the class. It can also specify a tag directly rather than being a

   --    tagged object. The latter is needed by the implementations of AI-239

   --    and AI-260.

   --  Conversion_OK (Flag14-Sem)

   --    A flag set on type conversion nodes to indicate that the conversion

   --    is to be considered as being valid, even though it is the case that

   --    the conversion is not valid Ada. This is used for attributes Enum_Rep,

   --    Fixed_Value and Integer_Value, for internal conversions done for

   --    fixed-point operations, and for certain conversions for calls to

   --    initialization procedures. If Conversion_OK is set, then Etype must be

   --    set (the analyzer assumes that Etype has been set). For the case of

   --    fixed-point operands, it also indicates that the conversion is to be

   --    direct conversion of the underlying integer result, with no regard to

   --    the small operand.

   --  Corresponding_Body (Node5-Sem)

   --    This field is set in subprogram declarations, package declarations,

   --    entry declarations of protected types, and in generic units. It

   --    points to the defining entity for the corresponding body (NOT the

   --    node for the body itself).

   --  Corresponding_Formal_Spec (Node3-Sem)

   --    This field is set in subprogram renaming declarations, where it points

   --    to the defining entity for a formal subprogram in the case where the

   --    renaming corresponds to a generic formal subprogram association in an

   --    instantiation. The field is Empty if the renaming does not correspond

   --    to such a formal association.

   --  Corresponding_Generic_Association (Node5-Sem)

   --    This field is defined for object declarations and object renaming

   --    declarations. It is set for the declarations within an instance that

   --    map generic formals to their actuals. If set, the field points to

   --    a generic_association which is the original parent of the expression

   --    or name appearing in the declaration. This simplifies ASIS queries.

   --  Corresponding_Integer_Value (Uint4-Sem)

   --    This field is set in real literals of fixed-point types (it is not

   --    used for floating-point types). It contains the integer value used

   --    to represent the fixed-point value. It is also set on the universal

   --    real literals used to represent bounds of fixed-point base types

   --    and their first named subtypes.

   --  Corresponding_Spec (Node5-Sem)

   --    This field is set in subprogram, package, task, and protected body

   --    nodes, where it points to the defining entity in the corresponding

   --    spec. The attribute is also set in N_With_Clause nodes where it points

   --    to the defining entity for the with'ed spec, and in a subprogram

   --    renaming declaration when it is a Renaming_As_Body. The field is Empty

   --    if there is no corresponding spec, as in the case of a subprogram body

   --    that serves as its own spec.

   --  Corresponding_Stub (Node3-Sem)

   --    This field is present in an N_Subunit node. It holds the node in

   --    the parent unit that is the stub declaration for the subunit. It is

   --    set when analysis of the stub forces loading of the proper body. If

   --    expansion of the proper body creates new declarative nodes, they are

   --    inserted at the point of the corresponding_stub.

   --  Dcheck_Function (Node5-Sem)

   --    This field is present in an N_Variant node, It references the entity

   --    for the discriminant checking function for the variant.

   --  Debug_Statement (Node3)

   --    This field is present in an N_Pragma node. It is used only for a Debug

   --    pragma. The parameter is of the form of an expression, as required by

   --    the pragma syntax, but is actually a procedure call. To simplify

   --    semantic processing, the parser creates a copy of the argument

   --    rearranged into a procedure call statement and places it in the

   --    Debug_Statement field. Note that this field is considered syntactic

   --    field, since it is created by the parser.

   --  Default_Expression (Node5-Sem)

   --    This field is Empty if there is no default expression. If there is a

   --    simple default expression (one with no side effects), then this field

   --    simply contains a copy of the Expression field (both point to the tree

   --    for the default expression). Default_Expression is used for

   --    conformance checking.

   --  Discr_Check_Funcs_Built (Flag11-Sem)

   --    This flag is present in N_Full_Type_Declaration nodes. It is set when

   --    discriminant checking functions are constructed. The purpose is to

   --    avoid attempting to set these functions more than once.

   --  Do_Accessibility_Check (Flag13-Sem)

   --    This flag is set on N_Parameter_Specification nodes to indicate

   --    that an accessibility check is required for the parameter. It is

   --    not yet decided who takes care of this check (TBD ???).

   --  Do_Discriminant_Check (Flag13-Sem)

   --    This flag is set on N_Selected_Component nodes to indicate that a

   --    discriminant check is required using the discriminant check routine

   --    associated with the selector. The actual check is generated by the

   --    expander when processing selected components.

   --  Do_Division_Check (Flag13-Sem)

   --    This flag is set on a division operator (/ mod rem) to indicate

   --    that a zero divide check is required. The actual check is dealt

   --    with by the backend (all the front end does is to set the flag).

   --  Do_Length_Check (Flag4-Sem)

   --    This flag is set in an N_Assignment_Statement, N_Op_And, N_Op_Or,

   --    N_Op_Xor, or N_Type_Conversion node to indicate that a length check

   --    is required. It is not determined who deals with this flag (???).

   --  Do_Overflow_Check (Flag17-Sem)

   --    This flag is set on an operator where an overflow check is required on

   --    the operation. The actual check is dealt with by the backend (all the

   --    front end does is to set the flag). The other cases where this flag is

   --    used is on a Type_Conversion node and for attribute reference nodes.

   --    For a type conversion, it means that the conversion is from one base

   --    type to another, and the value may not fit in the target base type.

   --    See also the description of Do_Range_Check for this case. The only

   --    attribute references which use this flag are Pred and Succ, where it

   --    means that the result should be checked for going outside the base

   --    range. Note that this flag is not set for modular types.

   --  Do_Range_Check (Flag9-Sem)

   --    This flag is set on an expression which appears in a context where a

   --    range check is required. The target type is clear from the context.

   --    The contexts in which this flag can appear are the following: