

                            ASIS/Program View Layer
 
                                 Scan Utility



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

Scan is a utility package that we have used to build some of the PVL
views.  Scan provides operations for traversing the element hierarchy
rooted at any ASIS element.  The traversal is generic, not in the Ada
sense of the word, but rather in the more general sense that the
package can be copied, and code can be emplaced in the copied
procedures to cause the traversal to perform a specific function.

The traversal has the following properties:

   1. The traversal is in top-down, source code order (unless flags such
   as Normalize_Procedure_Call_Parameters are set).

   2. An object of a user-defined type is carried throughout the
   traversal.  It can be used to hold contextual information.

   3. The traversal can be traced.  If tracing is on, a textual
   representation of each element encountered is indented appropriately
   and written to a user-defined file.

   4. Asis exceptions (e.g., Asis_Inappropriate_Element and Asis_Failed)
   are caught at each step of the traversal.  When an exception is
   caught, a message is written using the Msg_Log package (in the
   common subsystem) and the universal exception Traversal_Error is 
   raised.  This causes a stack traceback to be produced and results 
   in Traversal_Error being propagated outside the package.

Scan is similar in function to the generic unit
Asis.Elements.Traverse_Element, which also performs a source code
order traversal of the ASIS element hierarchy.  We feel that
Traverse_Element is more useful for an application that needs to
examine only a few element kinds, ignoring the rest.  When the
majority of element kinds are examined, say by a metric tool, the code
used to instantiate Traverse_Element can become unwieldly, not unlike
the massive case statements observed in DIANA-based tools.

The Scan package structure maps directly to the top-level element
kinds in Asis.Elements.Element_Kinds.  There is one Scan operation for
each top-level element kind and also for lists of these kinds (when
such lists can be returned by an ASIS query).  The operation calls
each of the appropriate ASIS queries that return the element's
syntactic children, and then calls the appropriate Scan operation for
each child.  When an element kind has subkinds (e.g., A_Statement), the
subkind influences which queries are called.

This package organization makes it easy to locate the processing for
each element kind, simplifying maintenance.  The Scan operations are
arguably more flexible than Traverse_Element, which permits the
application to act on an element only 1) when the element is
first visited and 2) after all of the elements children has been
visited.  In some applications, it is desirable to perform operations
IN BETWEEN the traversals of an element's individual children.  Using
Scan, this can be accomplished simply by inserting code between the
calls that scan child elements.

Scan is also valuable to those learning ASIS because it provides a
complete example demonstrating the use of all ASIS syntactic queries.
The trace feature, which produces an indented listing of the element
hierarchy, can be used to answer the question, "What does the ASIS
structure look like for this piece of code?"


FILES
-----

This directory contains the following files:

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

SUBSYSTEM COMPONENTS
--------------------

The scan subsystem contains a single library unit:

   package Scan

	Declares a traversal operation for each kind of ASIS element.
        Also contains settings that control aspects of the traversal.

In addition, procedure Scan_Unit is a test driver for demonstrating
the operation of the subsystem.  Given an ASIS library and the name of
an Ada compilation unit, the test driver invokes Scan to traverse the
complete element hierarchy of the unit.  The trace feature of the Scan
package is used to output the element hierarchy in an indented tree
format.


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

The scan subsystem imports the following subsystems:

   common
   asis

