[This README should be converted into the corresponding section
in the ASIS Users Guide]

This subdirectory contains the code implementing a set of compilable
and workable, but "empty" ASIS applications. The purposes of this
code are:

1. To illustrate the main components (building blocks) of a
   typical ASIS application and the basic ASIS application
   cycle, as it is defined in the ASIS Standard

2. To be used as a general framework (or a set of templates) for
   fast developing of some simple ASIS applications (such as style
   rules checkers, metrics collectors etc)

3. No be used as the basis for the ASIS Tutorial included in
   ASIS-for-GNAT.

That is why the code is extensively documented. The comments in the
code explain what parts of the code may be reused in real applications,
what parts may require some adjustments, what parts are just place-holders
to be replaced by the real code in a real application.

This set of ASIS application templates is provided in a hope that it
may be helpful and useful for ASIS newcomers, but with no guarantee
that this framework is exactly what you need for your particular ASIS
tool.

This set of templates is based on the following idea: all of them
implement the basic steps performed by many ASIS applications:

- initializing the ASIS implementation;
  - defining the ASIS Context by associating it with physical
    environment;
    - opening the ASIS Context;
      - obtaining Compilation Units from the Context
        (or iterating through the content of the Context);
        - selecting some Compilation Units for detailed processing;
          - decomposing a Compilation Unit into Element hierarchies;
            - processing Element hierarchies by using an
              instantiation of the general ASIS traversal algorithm
              provided by the generic Traverse_Element procedure
    - closing the Context;
  - dissociating the Context from physical environment
- finalizing the ASIS implementation;

In these templates the processing of Element hierarchies is empty,
because they use dummy procedures which do nothing as actual parameters
to instantiate Traverse_Element. The basic idea of this set of ASIS
application templates is that you can build some useful application
by providing some real code only for actual Pre- and Post-operations
(package Element_Processing) and reusing the rest of the code as is
(or with small adjustments)

This set of templates has the following structure:

- library procedures with names of the form
      ASIS_Application_Driver_<integer>
  (files asis_application_driver_<integer>.ad[b|s]) contain driver
  procedures for ASIS applications.

 - package Context_Processing (files context_processing.ads and
   context_processing.adb) contains routines for general processing of an
   ASIS Context (iterating through the Context, obtaining ASIS Compilation
   Units from the Context);

 - package Unit_Processing (files unit_processing.ads and
   unit_processing.adb) contains routines for black-box Compilation Units
   processing and for general processing of a separate Unit (that is,
   decomposing the Unit into Element hierarchies);

 - package Element_Processing (files element_processing.ads and
   element_processing.adb) contains the instantiation of the
   Asis.Iterator.Traverse_Element procedure with dummy actual Pre- and
   Post-Operation. These dummy procedures are supposed to be replaced by
   user's code when using this set of templates to build real ASIS
   applications.

 - package Actuals_For_Traversing (files actuals_for_traversing.ads and
   actuals_for_traversing.adb) contains the declarations of actual types
   and subprograms needed to instantiate Asis.Iterator.Traverse_Element in
   Element_Processing. These declarations are templates to be replaced
   with the users code when building ASIS applications. Bodies of template
   Pre- and Post-operations are implemented as subunits to localize
   changes needed to build an ASIS applications from the templates.

In many cases a user may build an ASIS application from the given set of
templates by replacing the subunits implementing bodies of the actual Pre-
and Post-operations (files actuals_for_traversing-pre_op.adb and
actuals_for_traversing-post_op.adb) and reusing the rest of the code of
the ASIS Application Templates.

See the solutions provided for the tasks included in the ASIS Tutorial
as the example of using the ASIS Application Templates.

Currently the following ASIS application top-level drivers are provided:

- ASIS_Application_Driver_1 - processes all the user-defined units
     contained in the Context and generates the trace from the names of
     the compilation units being processed. The Context is made up by the
     set of tree files in the current directory. The driver does not have
     any parameter.

- To be continued...