	

                            ASIS/Program View Layer
 
                                  Region View


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

Ada specifies the rules of declaration scope and visibility using the 
concept of a "declarative region".  A declarative region (LRM 8.1) is a
logical portion of program text that bounds the scope of declarations.
Regions can be nested within other regions, thus forming a hierarchy.
A declaration's scope extends from the point of declaration to the end
of the declarative region that immediately contains it.  For certain 
forms of declaration, such as those occurring in the visible part of
a package declaration, the scope also extends into the enclosing
region.

The region view identifies the declarative regions of an Ada library
unit and organizes them into a tree structure to reflect their nesting
relationships.  The view is useful for navigating among the program
units internal to a library unit and for building more elaborate
static analysis structures such as a hierarchical symbol table.

A declarative region is a logical, not a physical, concept.  Regions
formed by program units may span multiple compilation units.  For
example, the region for a package can include a package declaration,
a package body stub, and the proper body, each of which may reside
in a different compilation unit.  A region view is therefore a view of 
a "logical" library unit, i.e., a physical library unit together with
its corresponding secondary units (body and subunits), if any.  We 
refer to this collection of compilation units as a Library Unit Group
(LUG).


FILES
-----

This directory contains the following files:


   README (this file)
   build_region_view.2.ada
   build_region_view_using_region_scan.2.ada
   dump_region_view.1.ada
   dump_region_view.2.ada
   region_view.1.ada
   region_view.2.ada
   region_view_structures.1.ada
   test (directory)


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

The region subsystem contains 3 Ada library units.

   package Region_View_Structures

	Declares the view data structures.

   package Region_View

        Contains operations for constructing and destroying
        a view.

   package Dump_Region_View

	Contains an operation for dumping a region view to a text
	file.

In addition, procedure Build_Region_View is a test driver for 
demonstrating the operation of the subsystem.  Given an ASIS library
and the name of an Ada library unit, the test driver builds a view for
the unit and dumps the view to a text file.

Procedure Build_Region_View_Using_Region_Scan is a second test driver
which is functionally identical to Build_Region_View.  This driver,
however, uses the region_scan subsystem to perform the ASIS element
traversal rather than Asis.Elements.Traverse_Elements.  region_scan is
a generic traversal which identifies the elements in a compilation
unit that begin new declarative regions.


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

The region subsystem imports the following subsystems:

   common
   asis
   region_scan (used only by the Build_Region_View_Using_Region_Scan
                test driver)


VIEW DESCRIPTION
----------------

The region view is described in detail in the specification of package
Region_View (see file region_view.1.ada).  We also recommend reading
the specification of package Region_Support (file region_support.1.ada
in the common subsystem) for additional background.

A key requirement for the view component was to separate view
construction from the ASIS element traversal that locates declarative
regions. (This approach is different from that taken, for example, by
the control flow view builder, which traverses the elements of a
program unit AND constructs the view in a single operation.) The
purpose of this requirement is to enable integration of region view
construction into a traversal that performs additional functions,
including adding information to or even reading a partially
constructed view while it is being generated.

Therefore, the Region_View package simply exports a set of operations
that are called at appropriate times during an ASIS element traversal.
The required order of traversal and sequence of calls is documented in the
package spec.  The called operations add information to the view under
construction, which may be examined at any time during the traversal.

As an example of how a view might be used during construction, suppose
an application wishes to determine the set of entities declared in a
package that are visible outside the package.  This requires locating
the declarations in the package and establishing the declarative
context of each one.  It's easy to locate the entities declared
immediately in the package spec visible part, but there may also be
constructs (e.g., tasks, records, and nested packages) with nested
declarations that are also visible outside the package.  By building
the region view during a traversal of the package, it is possible to
determine the set of declarative regions that enclose a given
declaration.  An examination of the region kinds will reveal if the
declaration is externally visible.  For example, an entry declared in
a task which is in turn declared in a package spec visible part is
externally visible.


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

The test directory contains some sample library units and text dumps
of the region views created from these units using the
Build_Region_View test driver.  Files with the suffix ".region" are
the text dumps. 

A ".region" file contains:

 * The names of the compilation units that comprise the LUG.

 * The region part tree for each compilation unit.

 * The declarative region tree for the LUG as a whole.

The trees are output in an indented text format.  Appearing
immediately beneath each declaration region is the set of region parts
comprising the region.  Each region part is keyed with a unique number
so the part can be traced back to its position in a region part tree.
