	

                            ASIS/Program View Layer
 
                                Namespace View


 
INTRODUCTION
------------

The purpose of the namespace view is to identify the set of Ada
entities declared within an Ada unit.  An entity is something
declared by an Ada declaration (LRM 3.1), e.g., a type, an object, a
subprogram, a task, etc.

The namespace view is a view of a "declarative region part."  
A declarative region (LRM 8.1) is a logical portion of program text
that bounds the scope of declarations.  Every program unit is a
declarative region, as are other constructs such as record types and
task entries.  The text of a declarative region may be distributed
across multiple compilation units (e.g., the specification and body of
a package may not reside in the same compilation unit).

We found it useful to create a term for each such physical part - a
"declarative region part" - which is defined to be a physical,
contiguous text fragment, residing in single compilation unit, that is
a distinct part of one declarative region.  A declarative region
contains one or more non-overlapping region parts which, taken
together, comprise the entire text of the region.  For example, in the
case of a package region, there are three region parts: one for the
visible part of the spec, one for the private part, and one for the
body. (Although the visible and private parts of the spec are
physically adjacent, for certain analyses it is convenient to treat them
as separate parts.)

The namespace view of a region part contains the set of ASIS entity
name definition elements declared by declarations occurring in the
region part.  The elements are ordered according to their appearance
in the source code.


FILES
-----

This directory contains the following files:

   README (this file)
   build_namespace_views.2.ada
   namespace_scan.1.ada
   namespace_scan.2.ada
   namespace_scan.error_handling_support.2.ada
   namespace_scan.scan_any.2.ada
   namespace_scan.scan_any_list.2.ada
   namespace_scan.scan_argument_association.2.ada
   namespace_scan.scan_argument_association_list.2.ada
   namespace_scan.scan_case_statement_alternative.2.ada
   namespace_scan.scan_case_statement_alternative_list.2.ada
   namespace_scan.scan_choice.2.ada
   namespace_scan.scan_choice_list.2.ada
   namespace_scan.scan_compilation_unit.2.ada
   namespace_scan.scan_component_association.2.ada
   namespace_scan.scan_component_association_list.2.ada
   namespace_scan.scan_component_clause.2.ada
   namespace_scan.scan_component_clause_list.2.ada
   namespace_scan.scan_constraint.2.ada
   namespace_scan.scan_context_clause_list.2.ada
   namespace_scan.scan_declaration.2.ada
   namespace_scan.scan_declaration_list.2.ada
   namespace_scan.scan_declarative_item_list.2.ada
   namespace_scan.scan_declarative_region_part.2.ada
   namespace_scan.scan_discrete_range.2.ada
   namespace_scan.scan_discrete_range_list.2.ada
   namespace_scan.scan_discriminant_association.2.ada
   namespace_scan.scan_discriminant_association_list.2.ada
   namespace_scan.scan_entity_name_definition.2.ada
   namespace_scan.scan_entity_name_definition_list.2.ada
   namespace_scan.scan_exception_handler.2.ada
   namespace_scan.scan_exception_handler_list.2.ada
   namespace_scan.scan_expression.2.ada
   namespace_scan.scan_expression_list.2.ada
   namespace_scan.scan_if_statement_arm.2.ada
   namespace_scan.scan_if_statement_arm_list.2.ada
   namespace_scan.scan_null_component.2.ada
   namespace_scan.scan_parameter_association.2.ada
   namespace_scan.scan_parameter_association_list.2.ada
   namespace_scan.scan_pragma.2.ada
   namespace_scan.scan_pragma_list.2.ada
   namespace_scan.scan_record_component_list.2.ada
   namespace_scan.scan_representation_clause.2.ada
   namespace_scan.scan_select_alternative.2.ada
   namespace_scan.scan_select_statement_arm.2.ada
   namespace_scan.scan_select_statement_arm_list.2.ada
   namespace_scan.scan_statement.2.ada
   namespace_scan.scan_statement_list.2.ada
   namespace_scan.scan_subtype_indication.2.ada
   namespace_scan.scan_type_definition.2.ada
   namespace_scan.scan_use_clause.2.ada
   namespace_scan.scan_variant.2.ada
   namespace_scan.scan_variant_list.2.ada
   namespace_scan.scan_variant_part.2.ada
   namespace_scan.scan_with_clause.2.ada
   namespace_scan.trace_support.2.ada
   namespace_view.1.ada
   namespace_view.2.ada
   tests (directory)


VIEW SUBSYSTEM COMPONENTS
-------------------------

The namespace subsystem contains 1 Ada library unit in its interface.

   package Namespace_View

        Provides operations to create, destroy, dump a view, merge two
        views and save/restore a view on a file. Declares the data
        type for the view.

One additional unit resides in the subsystem implementation.

   package Namespace_Scan

        Performs the ASIS element traversal that constructs a view.

The test driver Build_Namespace_Views is also provided to demonstrate
the operation of view. The test driver creates a view for each
declarative region part in a compilation unit and dumps each view to
standard output.  The region_scan subsystem is used to locate region
parts in the unit.


VIEW SUBSYSTEM DEPENDENCIES
---------------------------

The namespace subsystem imports the following subsystems:

   common
   asis
   region_scan (used by driver Build_Namespace_Views only)


TEST CASES
----------

The tests directory contains text dumps of two sets of namespace views
created by the test driver.  The views were created from
two of the view construction compilation units:

   namespace_view.1.ada
   namespace_view.2.ada

Below is an excerpt from the dump for namespace_view.1.ada.  By
convention, the outermost region part for a compilation unit has kind
A_COMPILATION_UNIT. (This represents a part of the declarative region
for package Standard which encloses every library unit.) There is one
entity declared in the region part, in this case an entity declaring a
package. 

For each entity in the view, the dump shows the name from the entity
name definition element and, on the next line, the kind of enclosing
declaration element.  The pair of numbers shown is the line/column
number of the declaration in the source code.

Next in the example is the region part for the visible part of the
package. The "head element" of the region part is the ASIS element
that begins a new part - see the package Region_Support in the common
system for a complete definition.  Each of the entities declared in
the visible part are then listed in source code order.

----------------------------------------
View for Region Part of Kind : A_COMPILATION_UNIT

Entity names defined in region part:

AN_ENTITY_NAME_DEFINITION A_SIMPLE_NAME "NAMESPACE_VIEW"
    26   1 A_DECLARATION A_PACKAGE_DECLARATION

----------------------------------------
View for Region Part of Kind : A_PACKAGE_SPECIFICATION_VISIBLE_PART
  Region Part Head Element :
    26   1 A_DECLARATION A_PACKAGE_DECLARATION

Entity names defined in region part:

AN_ENTITY_NAME_DEFINITION A_SIMPLE_NAME "ASIS_ID_IO"
    28   1 A_DECLARATION A_PACKAGE_RENAME_DECLARATION

AN_ENTITY_NAME_DEFINITION A_SIMPLE_NAME "DEFINITION"
    30   1 A_DECLARATION A_FULL_TYPE_DECLARATION

AN_ENTITY_NAME_DEFINITION A_SIMPLE_NAME "DEFINITION_LIST"
    36   1 A_DECLARATION A_FULL_TYPE_DECLARATION

AN_ENTITY_NAME_DEFINITION A_SIMPLE_NAME "NAMESPACE_VIEW"
    38   1 A_DECLARATION A_FULL_TYPE_DECLARATION

AN_ENTITY_NAME_DEFINITION A_SIMPLE_NAME "TRACE_FILE"
    49   1 A_DECLARATION AN_OBJECT_RENAME_DECLARATION

AN_ENTITY_NAME_DEFINITION A_SIMPLE_NAME "CONSTRUCT"
    51   1 A_DECLARATION A_PROCEDURE_DECLARATION

AN_ENTITY_NAME_DEFINITION A_SIMPLE_NAME "CONSTRUCT"
    56   1 A_DECLARATION A_PROCEDURE_DECLARATION

AN_ENTITY_NAME_DEFINITION A_SIMPLE_NAME "DUMP"
    69   1 A_DECLARATION A_PROCEDURE_DECLARATION

AN_ENTITY_NAME_DEFINITION A_SIMPLE_NAME "MERGE"
    76   1 A_DECLARATION A_FUNCTION_DECLARATION
 .
 .
 .