ASIS-for-GNAT User's Guide
**************************

ASIS-for-GNAT User's Guide

The GNAT Pro Ada Compiler
GNAT Pro Version 7.0.0w
Configuration level 147314
Date: 2009/07/17

Copyright (C) 2000-2009, AdaCore

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU Free Documentation License", with the
Front-Cover Texts being "ASIS-for-GNAT User's Guide", and with no
Back-Cover Texts.  A copy of the license is included in the section
entitled "GNU Free Documentation License".

About This Guide
****************

This guide has two aims. The first one is to introduce you to the Ada
Semantic Interface Specification (ASIS) and show you how you can build
various useful tools on top of ASIS. The second is to describe the ASIS
implementation for the GNAT Pro Ada compiler.

   GNAT Pro implements both Ada 95 and Ada 2005.  As of January 2008,
the ASIS standard is specific to Ada 95 and has not yet been updated to
Ada 2005.  Notwithstanding the status of the ASIS standard,
ASIS-for-GNAT includes extensions that account for the new Ada 2005
functionality.  You can therefore use ASIS-for-GNAT for Ada 2005
programs, keeping in mind that the Ada 2005-specific support may
subsequently change as work on updating the ASIS standard proceeds.

   For further information on ASIS-for-GNAT and Ada 2005, please refer
to the auxilliary documents `asis-2005-transition.txt' and
`features-asis2005' in the ASIS source directory.

What This Guide Contains
========================

This guide contains the following chapters:
   * *note Introduction::, contains the general definition of ASIS and
     gives some  examples of tools which can be built on top of ASIS.

   * *note Getting Started::, contains a short guided tour through the
     development and use of ASIS-for-GNAT-based tools.

   * *note ASIS Overview::, gives an overview of ASIS, allowing an ASIS
     newcomer to navigate through the ASIS definition (readers already
     familiar with ASIS can skip this section).

   * *note ASIS Context::, defines the ASIS `Context' concept in
     ASIS-for-GNAT and explains how to prepare a set of Ada  components
     to be processed by an ASIS application.

   * *note ASIS Application Templates::, describes a set of Ada source
     components  provided by the ASIS-for-GNAT distribution that may be
     used as a basis for  developing ASIS applications.

   * *note ASIS Tutorials::, describes some examples included in  the
     ASIS-for-GNAT distribution.

   * *note How to Build Efficient ASIS Applications::, describes how to
     deal with "tree swapping", a potential performance issue with ASIS
     applications.

   * *note Processing an Ada Library by an ASIS-Based Tool::, shows how
     to use an ASIS tool on pre-compiled Ada libraries.

   * *note Compiling Binding and Linking Applications with
     ASIS-for-GNAT::, explains  how to compile an ASIS application with
     ASIS-for-GNAT and how to create  the resulting executable.

   * *note ASIS-for-GNAT Warnings::, describes the warnings generated by
     the ASIS implementation.

   * *note Exception Handling and Reporting Internal Bugs::, explains
     what happens if an ASIS implementation internal problem is
     detected during  the processing of an ASIS or ASIS Extensions query

   * *note File Naming Conventions and Application Name Space::,
     explains  which names can and cannot be used as names of ASIS
     application  components.

What You Should Know Before Reading This Guide
==============================================

This User's Guide assumes that you are familiar with Ada 95 language, as
described in the International Standard ANSI/ISO/IEC-8652:1995
(hereafter referred to as the `Ada Reference Manual'), and that you
have some basic experience in Ada programming with GNAT.

   This User's Guide also assumes that you have ASIS-for-GNAT properly
installed for your GNAT compiler, and that you are familiar with the
structure of the ASIS-for-GNAT distribution (if not, see the top ASIS
README file).

   This guide does not require previous knowledge of or experience with
ASIS itself.

Related Information
===================

The following sources contain useful supplemental information:
   * `GNAT User's Guide', for information about the GNAT environment

   * `ASIS-for-GNAT Installation Guide'

   * The `ASIS-for-GNAT Reference Manual'

   * The `ASIS 95 definition', available as ISO/IEC International
     Standard 15291.

   * The Web site for the ASIS Working Group:
     `http://www.acm.org/sigada/wg/asiswg'

Conventions
===========

Following are examples of the typographical and graphic conventions used
in this guide:

   * `Functions', `utility program names', `standard names', and
     `classes'.

   * `Option flags'

   * `File Names', `button names', and `field names'.

   * VARIABLES.

   * _Emphasis_.

   * [optional information or parameters]

   * Examples are described by text
          and then shown this way.

Commands that are entered by the user are preceded in this manual by the
characters "`$ '" (dollar sign followed by space). If your system uses
this sequence as a prompt, then the commands will appear exactly as you
see them in the manual. If your system uses some other prompt, then the
command will appear with the `$' replaced by whatever prompt character
you are using.

   Full file names are shown with the "`/'" character as the directory
separator; e.g., `parent-dir/subdir/myfile.adb'.  If you are using GNAT
on a Windows platform, please note that the "`\'" character should be
used instead.

1 Introduction
**************

1.1 What Is ASIS?
=================

The _Ada Semantic Interface Specification_ (ASIS) is an open and
published callable interface that allows a tool to access syntactic and
semantic information about an Ada program, independent of the
compilation environment that compiled the program.

   Technically, ASIS comprises a hierarchy of Ada packages rooted at
the package `Asis'.  These packages define a set of Ada private types
that model the components of an Ada program (e.g., declarations,
statements, expressions) and their interrelationships. Operations for
these types, called _ASIS queries_, give you statically determinable
information about Ada compilation units in your environment.

   You may use ASIS as a third-part Ada library to implement a number
of useful program analysis tools.

1.2 ASIS Scope - Which Kinds of Tools Can Be Built with ASIS?
=============================================================

The following ASIS properties define the ASIS scope:

   * ASIS is a read-only interface.

   * ASIS provides only statically-determinable information about Ada
     programs.

   * ASIS provides access to the syntactic and basic semantic
     properties of compiled Ada units. If some semantic property of a
     program cannot be directly queried by means of ASIS queries, an
     ASIS application can compute the needed piece of information
     itself from the information available through ASIS queries.

   * ASIS provides information from/about Ada units in high-level terms
     that conform with the `Ada Reference Manual' and that are
     Ada/ASIS-implementation-independent in nature.

Examples of tools that benefit from the ASIS interface include, but are
not limited to: automated code monitors, browsers, call tree tools, code
reformators, coding standards compliance tools, correctness verifiers,
debuggers, dependency tree analysis tools, design tools, document
generators, metrics tools, quality assessment tools, reverse
engineering tools, re-engineering tools, style checkers, test tools,
timing estimators, and translators.  

2 Getting Started
*****************

This section outlines the ASIS application development and usage cycle.
We first take a sample problem and present an ASIS application that
offers a solution; then we show how to build the executable with
ASIS-for-GNAT and how to prepare an ASIS "Context" to be processed by
the program; and finally we show the output produced by our program
when it is applied to itself.

2.1 The Problem
===============

We wish to process some set of Ada compilation units as follows: for
every unit, print its full expanded Ada name, whether this unit is a
spec(1), a body or a subunit, and whether this unit is a user-defined
unit, an Ada predefined unit or an implementation-specific unit (such
as a part of a Run-Time Library).

   ---------- Footnotes ----------

   (1) It may seem that an Ada unit such as
     package Pack is
       type T is array(Positive range <>) of Float;
       procedure Proc(X : in out T);
     end Pack;
   is a package _specification_, but in fact the "specification" (as
defined in the `Ada Reference Manual') comprises all but the final
semicolon.  The form with the final semicolon is known as a "package
declaration".  Since this official term is not familiar to most Ada
users, the GNAT documentation uses the term "spec" (for a unit) to mean
that unit's _declaration_ - thus a package spec includes the final
semicolon.

2.2 An ASIS Application that Solves the Problem
===============================================


     with Ada.Wide_Text_IO;        use Ada.Wide_Text_IO;
     with Ada.Characters.Handling; use Ada.Characters.Handling;

     --  ASIS-specific context clauses:
     with Asis;
     with Asis.Implementation;
     with Asis.Ada_Environments;
     with Asis.Compilation_Units;
     with Asis.Exceptions;
     with Asis.Errors;

     procedure Example1 is
        My_Context : Asis.Context;
        --  ASIS Context is an abstraction of an Ada compilation environment,
        --  it defines a set of ASIS Compilation Units available through
        --  ASIS queries

     begin
        --  first, by initializing an ASIS implementation, we make it
        --  ready for work
        Asis.Implementation.Initialize ("-ws");
        --  The "-ws" parameter of the Initialize procedure means
        --  "turn off all the ASIS warnings"

        --  then we define our Context by making an association with
        --  the "physical" environment:
        Asis.Ada_Environments.Associate
         (My_Context, "My Asis Context", "-CA");
        --  "-CA" as a Context parameter means "consider all the tree
        --  files in the current directory"
        --  See ASIS-for-GNAT Reference Manual for the description of the
        --  parameters of the Associate query, see also chapter
        --  "ASIS Context" for the description of different kinds of
        --  ASIS Context in case of ASIS-for-GNAT

        --  by opening a Context we make it ready for processing by ASIS
        --  queries
        Asis.Ada_Environments.Open (My_Context);
     
        Processing_Units: declare
           Next_Unit : Asis.Compilation_Unit;
           --  ASIS Compilation_Unit is the abstraction to represent Ada
           --  compilation units as described in RM 95

           All_Units : Asis.Compilation_Unit_List :=
           --  ASIS lists are one-dimensional unconstrained arrays.
           --  Therefore, when declaring an object of an ASIS list type,
           --  we have to provide either a constraint or explicit
           --  initialization expression:

              Asis.Compilation_Units.Compilation_Units (My_Context);
           --  The Compilation_Units query returns a list of all the units
           --  contained in an ASIS Context
        begin
           Put_Line
             ("A Context contains the following compilation units:");
           New_Line;
           for I in All_Units'Range loop
              Next_Unit := All_Units (I);
              Put ("   ");

              --  to get a unit name, we just need a Unit_Full_Name
              --  query. ASIS uses Wide_String as a string type,
              --  that is why we are using Ada.Wide_Text_IO

              Put (Asis.Compilation_Units.Unit_Full_Name (Next_Unit));
     
              --  to get more info about a unit, we ask about unit class
              --  and about unit origin

              case Asis.Compilation_Units.Unit_Kind (Next_Unit) is
                 when Asis.A_Library_Unit_Body =>
                    Put (" (body)");
                 when Asis.A_Subunit =>
                    Put (" (subunit)");
                 when others =>
                    Put (" (spec)");
              end case;

              case Asis.Compilation_Units.Unit_Origin (Next_Unit) is
                 when Asis.An_Application_Unit =>
                    Put_Line (" - user-defined unit");
                 when Asis.An_Implementation_Unit =>
                    Put_Line (" - implementation-specific unit");
                 when Asis.A_Predefined_Unit =>
                    Put_Line (" - Ada predefined unit");
                 when Asis.Not_An_Origin =>
                    Put_Line
                      (" - unit does not actually exist in a Context");
              end case;

           end loop;
        end Processing_Units;

        --  Cleaning up: we have to close out the Context, break its
        --  association with the external environment and finalize
        --  our ASIS implementation to release all the resources used:
        Asis.Ada_Environments.Close (My_Context);
        Asis.Ada_Environments.Dissociate (My_Context);
        Asis.Implementation.Finalize;
     
     exception
        when Asis.Exceptions.ASIS_Inappropriate_Context |
             Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit |
             Asis.Exceptions.ASIS_Failed =>
     
           --  we check not for all the ASIS-defined exceptions, but only
           --  those of them which can actually be raised in our ASIS
           --  application.
           --
           --  If an ASIS exception is raised, we output the ASIS error
           --  status and the ASIS diagnosis string:

           Put_Line ("ASIS exception is raised:");
           Put_Line ("ASIS diagnosis is:");
           Put_Line (Asis.Implementation.Diagnosis);
           Put      ("ASIS error status is: ");
           Put_Line
             (Asis.Errors.Error_Kinds'Wide_Image
                (Asis.Implementation.Status));
     end Example1;

2.3 Required Sequence of Calls
==============================

An ASIS application must use the following sequence of calls:

  1. `Asis.Implementation.Initialize (...);' 

     This initializes the ASIS implementation's internal data
     structures.  In general, calling an ASIS query is erroneous unless
     the `Initialize' procedure has been invoked.  

  2. `Asis.Ada_Environments.Associate (...);' 

     This call is the only means to define a value of a variable of the
     ASIS limited private type `Context'.  The value represents some
     specific association of the ASIS `Context' with the "external
     world". The way of making this association and the meaning of the
     corresponding parameters of the `Associate' query are
     implementation-specific, but as soon as this association has been
     made and a `Context' variable is opened, the ASIS `Context'
     designated by this variable may be considered to be a set of ASIS
     `Compilation_Unit's available through the ASIS queries.

  3. `Asis.Ada_Environments.Open (...);' 

     Opening an ASIS `Context' variable makes the corresponding
     `Context' accessible to all ASIS queries.

     After opening the `Context', an ASIS application can start
     obtaining  ASIS `Compilation_Unit's from it, can further analyze
     `Compilation_Unit's  by decomposing them into ASIS `Element's, etc.  

     ASIS relies on the fact that the content of a `Context' remains
     "frozen"  as long as the `Context' remains open.   It is erroneous to
     change through some non-ASIS program any data  structures used by
     an ASIS implementation to define and implement  this `Context'
     while the `Context' is open.

  4. Now all the ASIS queries can be used. It is possible to access
     `Compilation_Unit's from the `Context', to decompose units into
     syntactic `Element's, to query syntactic and semantic properties
     of these `Element's and so on.

  5. `Asis.Ada_Environments.Close (...);' 

     After closing the `Context' it is impossible to retrieve any
     information from it. All the values of the ASIS objects of
     `Compilation_Unit', `Element' and `Line' types obtained when this
     `Context' was open become obsolete, and it is erroneous to use
     them after the `Context' was closed.   The content of this
     `Context' need not be frozen while  the `Context' remains closed.
     Note that a closed `Context' keeps its  association with the
     "external world" and it may be opened again with  the same
     association. Note also that the content (that is, the
     corresponding set of ASIS `Compilation_Unit's) of the `Context'
     may be  different from what was in the `Context' before, because
     the "external  world" may have changed while the `Context'
     remained closed.

  6. `Asis.Ada_Environments.Dissociate (...);' 

     This query breaks the association between the corresponding ASIS
     `Context' and the "external world", and the corresponding `Context'
     variable becomes undefined.

  7. `Asis.Implementation.Finalize (...);' 

     This releases all the resources used by an ASIS implementation.

An application can perform these steps in a loop. It may initialize and
finalize an ASIS implementation several times, it may associate and
dissociate the same `Context' several times while an ASIS
implementation remains initialized, and it may open and close the same
`Context' several times while the `Context' keeps its association with
the "external world".  

   An application can have several ASIS `Context's opened at a time
(the upper limit is implementation-specific), and for each open
`Context', an application can process several `Compilation_Unit's
obtained from this `Context' at a time (the upper limit is also
implementation-specific). ASIS-for-GNAT does not impose any special
limitations on the number of ASIS `Context's and on the number of the
ASIS `Compilation_Unit's processed at a time, as long as an ASIS
application is within the general resource limitations of the underlying
system.

2.4 Building the Executable for an ASIS application
===================================================

The rest of this section assumes that you have ASIS-for-GNAT properly
installed as an Ada library.  

   To get the executable for the ASIS application from *note An ASIS
Application that Solves the Problem:: (assuming that it is located in
your current directory as the Ada source file named `example1.adb'),
invoke `gnatmake' as follows(1):

     $ gnatmake example1.adb -largs -lasis

For more details concerning compiling ASIS applications and building
executables for them with ASIS-for-GNAT see *note Compiling Binding and
Linking Applications with ASIS-for-GNAT::.

   ---------- Footnotes ----------

   (1) The `.adb' is optional

2.5 Preparing Data for an ASIS Application - Generating Tree Files
==================================================================

The general ASIS implementation technique is to use some information
generated by the underlying Ada compiler as the basis for retrieving
information from the Ada environment. As a consequence, an ASIS
application can process only legal (compilable) Ada code, and in most
of the cases to make a compilation unit "visible" for ASIS means to
compile this unit (probably with some ASIS-specific options)

   ASIS-for-GNAT uses _tree output files_ (or, in short, _tree files_)
to capture information about an Ada unit from an Ada environment. A
tree file is generated by GNAT, and it contains a snapshot of the
compiler's internal data structures at the end of the successful
compilation of the corresponding source file.

   To create a tree file for a unit contained in some source file, you
should compile this file with the `-gnatct' compiler option.  If you
want to apply the program described in section *note An ASIS
Application that Solves the Problem:: to itself, compile the source of
this application with the command:

     $ gcc -c -gnatct example1.adb

and as a result, GNAT will generate the tree file named `example1.adt'
in the current directory.

   For more information on how to generate and deal with tree files, see
*note ASIS Context::, and *note ASIS Tutorials::.

2.6 Running an ASIS Application
===============================

To complete our example, let's execute our ASIS application. If you have
followed all the steps described in this chapter, your current
directory should contain the executable `example1' (`example1.exe' on a
Windows platform) and the tree file `example1.adt'.  If we run our
application, it will process an ASIS `Context' defined by one tree file
`example1.adt' (for more details about defining an ASIS `Context' see
*note ASIS Context::, and the `ASIS-for-GNAT Reference Manual').  The
result will be:

        A `Context' contains the following compilation units:

           Standard (spec) - Ada predefined unit
           Example1 (body) - user-defined unit
           Ada (spec) - Ada predefined unit
           Ada.Wide_Text_IO (spec) - Ada predefined unit
           Ada.IO_Exceptions (spec) - Ada predefined unit
           Ada.Streams (spec) - Ada predefined unit
           System (spec) - Ada predefined unit
           System.File_Control_Block (spec) - implementation-specific unit
           Interfaces (spec) - Ada predefined unit
           Interfaces.C_Streams (spec) - implementation-specific unit
           System.Parameters (spec) - implementation-specific unit
           System.WCh_Con (spec) - implementation-specific unit
           Ada.Characters (spec) - Ada predefined unit
           Ada.Characters.Handling (spec) - Ada predefined unit
           Asis (spec) - user-defined unit
           A4G (spec) - user-defined unit
           A4G.A_Types (spec) - user-defined unit
           Ada.Characters.Latin_1 (spec) - Ada predefined unit
           GNAT (spec) - implementation-specific unit
           GNAT.OS_Lib (spec) - implementation-specific unit
           GNAT.Strings (spec) - implementation-specific unit
           Unchecked_Deallocation (spec) - Ada predefined unit
           Sinfo (spec) - user-defined unit
           Types (spec) - user-defined unit
           Uintp (spec) - user-defined unit
           Alloc (spec) - user-defined unit
           Table (spec) - user-defined unit
           Urealp (spec) - user-defined unit
           A4G.Int_Knds (spec) - user-defined unit
           Asis.Implementation (spec) - user-defined unit
           Asis.Errors (spec) - user-defined unit
           Asis.Ada_Environments (spec) - user-defined unit
           Asis.Compilation_Units (spec) - user-defined unit
           Asis.Ada_Environments.Containers (spec) - user-defined unit
           Asis.Exceptions (spec) - user-defined unit
           System.Unsigned_Types (spec) - implementation-specific unit

Note that the tree file contains the full syntactic and semantic
information not only about the unit compiled by the given call to
`gcc', but also about all the units upon which this unit depends
semantically; that is why you can see in the output list a number of
units which are not mentioned in our example.

   In the current version of ASIS-for-GNAT, ASIS implementation
components are considered user-defined, rather than
implementation-specific, units.

3 ASIS Overview
***************

This chapter contains a short overview of the ASIS definition as given
in the ISO/IEC 15291:1999 ASIS Standard. This overview is aimed at
helping an ASIS newcomer find needed information in the ASIS definition.  

   For more details, please refer to the ASIS definition itself. To
gain some initial experience with ASIS, try the examples in *note ASIS
Tutorials::.

3.1 Main ASIS Abstractions
==========================

ASIS is based on three main abstractions used to describe Ada programs;
these abstractions are implemented as Ada private types:

`Context'
     An ASIS `Context' is a logical handle to an Ada environment, as
     defined in the `Ada Reference Manual', Chapter 10. An ASIS
     application developer may view an ASIS `Context' as a way to
     define a set of compilation units available through the ASIS
     queries.  

`Compilation_Unit'
     An ASIS `Compilation_Unit' is a logical handle to an Ada
     compilation unit. It reflects practically all the properties of
     compilation units defined by the `Ada Reference Manual', and it
     also reflects some properties of "physical objects" used by an
     underlying Ada implementation to model compilation units.
     Examples of such properties are the time of the last update, and
     the name of the object containing the unit's source text.  An ASIS
     `Compilation_Unit' provides the "black-box" view of a compilation
     unit, considering the unit as a whole. It may be decomposed into
     ASIS `Element's and then analyzed in "white-box" fashion.

`Element'
     An ASIS `Element' is a logical handle to a syntactic component of
     an ASIS `Compilation_Unit' (either explicit or implicit).

Some ASIS components use additional abstractions (private types) needed
for specific pieces of functionality:

`Container'
     An ASIS `Container' (defined by the
     `Asis.Ada_Environments.Containers' package) provides a means for
     structuring the content of an ASIS `Context'; i.e., ASIS
     `Compilation_Unit's are grouped into `Container's.

`Line'
     An ASIS `Line' (defined by the `Asis.Text' package) is the
     abstraction of a line of code in an Ada source text. An ASIS
     `Line' has a length, a string image and a number.

`Span'
     An ASIS `Span' (defined by the `Asis.Text' package) defines the
     location of an `Element', a `Compilation_Unit', or a whole
     compilation in the corresponding source text.

`Id'
     An ASIS `Id' (defined by the `Asis.Ids' package)  provides a way to
     store some "image" of an ASIS `Element' outside an ASIS
     application. An application may create an `Id' value from an
     `Element' and store it in a file. Subsequently the same or another
     application may read this `Id' value and convert it back into the
     corresponding `Element' value.

3.2 ASIS Package Hierarchy
==========================

ASIS is defined as a hierarchy of Ada packages. Below is a short
description of this hierarchy.

`Asis'
     The root package of the hierarchy. It defines the main ASIS
     abstractions - `Context', `Compilation_Unit' and `Element' - as
     Ada private types. It also contains a set of enumeration types
     that define  the classification hierarchy for ASIS `Element's
     (which closely reflects the  Ada syntax defined in the `Ada
     Reference Manual') and the classification of  ASIS
     `Compilation_Unit's.   This package does not contain any queries.

`Asis.Implementation'
     Contains subprograms that control an ASIS implementation:
     initializing and  finalizing it, retrieving and resetting
     diagnosis information. Its child  package
     `Asis.Implementation.Permissions' contains boolean queries that
     reflect how ASIS implementation-specific features are implemented.

`Asis.Ada_Environments'
     Contains queries that deal with an ASIS `Context': associating and
     dissociating,  opening and closing a `Context'.  

`Asis.Compilation_Units'
     Contains queries that work with ASIS `Compilation_Unit's:
     obtaining units from a  `Context', getting semantic dependencies
     between units and "black-box" unit  properties.

`Asis.Compilation_Units.Relations'
     Contains queries that return integrated semantic dependencies
     among ASIS  `Compilation_Unit's; e.g., all the units needed by a
     given unit to be included  in a partition.

`Asis.Elements'
     Contains queries working on `Element's and implementing general
     `Element'  properties: gateway queries from ASIS Compilation Units
     to ASIS `Element's,  queries defining the position of an `Element'
     in the `Element' classification  hierarchy, queries which define
     for a given `Element' its enclosing  `Compilation_Unit' and its
     enclosing `Element'.   It also contains queries for processing
     pragmas.

Packages working on specific `Element's
     This group contains the following packages: `Asis.Declarations',  `Asis.Definitions',  `Asis.Statements', `Asis.Expressions' and
     `ASIS.Clauses'.  Each of these packages contains queries working on
     `Element's of the corresponding kind - that is, representing Ada
     declarations,  definitions, statements, expressions and clauses
     respectively.

`Asis.Text'
     Contains queries returning information about the source
     representation of ASIS `Compilation_Unit's and ASIS `Element's.

`Asis.Exceptions'
     Defines ASIS exceptions.

`Asis.Errors'
     Defines possible ASIS error status values.

3.3 Structural and Semantic Queries
===================================

Queries working on `Element's and returning `Element's or `Element'
lists are divided into structural and semantic queries.  

   Each structural query (except `Enclosing_Element') implements one
step of the parent-to-child decomposition of an Ada program according
to the ASIS `Element' classification hierarchy.
`Asis.Elements.Enclosing_Element' query implements the reverse
child-to-parent step. (For implicit `Element's obtained as results of
semantic queries, `Enclosing_Element' might not correspond to what
could be expected from the Ada syntax and semantics; in this case the
documentation of a semantic query also defines the effect of
`Enclosing_Element' applied to its result).

   A semantic query for a given `Element' returns the `Element' or the
list of `Element's representing some semantic property - e.g., a type
declaration for an expression as the expression's type, a defining
identifier as a definition for a simple name, etc.

   For example, if we have `Element' `El' representing an assignment
statement:

         X := A + B;

then we can retrieve the structural components of this assignment
statement by applying the appropriate structural queries:

        El_Var  := Asis.Statements.Assignment_Variable_Name (El); --  X
        El_Expr := Asis.Statements.Assignment_Expression    (El); --  A + B

Then we can analyze semantic properties of the variable name
represented by `El_Var' and of the expression represented by `El_Expr'
by means of appropriate semantic queries:

        El_Var_Def   :=
           Asis.Expressions.Corresponding_Name_Definition (El_Var);
        El_Expt_Type :=
           Asis.Expressions.Corresponding_Expression_Type (El_Expr);

As a result, `El_Var_Def' will be of `A_Defining_Identifier' kind and
will represent the defining occurrence of `X', while `El_Expt_Type' of
a kind `An_Ordinary_Type_Declaration' will represent the declaration of
the type of the expression `A + B'.

   If we apply `Asis.Elements.Enclosing_Element' to `El_Var' or to
`El_Expr', we will get back to the `Element' representing the
assignment statement.

   An important difference between classifying queries working on
`Element's as structural versus semantic is that all the structural
queries must be within one ASIS `Compilation_Unit', but for semantic
queries it is typical for the argument of a query to be in one ASIS
`Compilation_Unit', while the result of this query is in another ASIS
`Compilation_Unit'.

3.4 ASIS Error Handling Policy
==============================

Only ASIS-defined exceptions (and the Ada predefined `Storage_Error' exception)
propagate out from ASIS queries. ASIS exceptions are defined in the
`Asis.Exceptions' package.  

   When an ASIS exception is raised, ASIS sets the Error Status (the
possible ASIS error conditions are defined as the values of the
`Asis.Errors.Error_Kinds' type) and forms the `Diagnosis' string.  An
application can query the current value of the ASIS Error Status by the
`Asis.Implementation.Status' query, and the current content of the
`Diagnosis' string by `Asis.Implementation.Diagnosis' query.  An
application can reset the Error Status and the `Diagnosis' string by
invoking the `Asis.Implementation.Set_Status' procedure.  

   _Caution:_ The ASIS way of providing error information is not
tasking safe.  The `Diagnosis' string and Error Kind are global to an
entire partition, and are not "per task".  If ASIS exceptions are
raised in more then one task of a multi-tasking ASIS application, the
result of querying the error information in a particular task may be
incorrect.  

3.5 Dynamic Typing of ASIS Queries
==================================

The ASIS type `Element' covers all Ada syntactic constructs, and
`Compilation_Unit' covers all Ada compilation units. ASIS defines an
`Element' classification hierarchy (which reflects very closely the
hierarchy of Ada syntactic categories defined in the `Ada Reference
Manual', and ASIS similarly defines a classification scheme for ASIS
`Compilation_Unit's.  For any `Element' you can get its position in the
`Element' classification hierarchy by means of classification queries
defined in the package `Asis.Elements'.  The classification queries for
`Compilation_Unit's are defined in the package `Asis.Compilation_Units'.  

   Many of the queries working on `Element's and `Compilation_Unit's
can be applied only to specific kinds of `Element's and
`Compilation_Unit's respectively. For example, it does not make sense
to query `Assignment_Variable_Name' for an `Element' of
`An_Ordinary_Type_Declaration' kind.  An attempt to perform such an
operation will be detected at run-time, and an exception will be raised
as explained in the next paragraph.

   ASIS may be viewed as a dynamically typed interface. For any
`Element' structural or semantic query (that is, for a query having an
`Element' as an argument and returning either an `Element' or `Element'
list as a result) a list of appropriate `Element' kinds is explicitly
defined in the query documentation which immediately follows the
declaration of the corresponding subprogram in the code of the ASIS
package. This means that the query can be applied only to argument
`Element's being of the kinds from this list. If the kind of the
argument `Element' does not belong to this list, the corresponding call
to this query raises the `Asis.Exceptions.ASIS_Inappropriate_Element'
exception with `Asis.Errors.Value_Error' error status set.  

   The situation for the queries working on `Compilation_Unit's is
similar. If a query lists appropriate unit kinds in its documentation,
then this query can work only on `Compilation_Unit's of the kinds from
this list. The query should raise
`Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit' with
`Asis.Errors.Value_Error' error status set when called for any
`Compilation_Unit' with a kind not from the list of the appropriate
unit kinds.

   If a query has a list of expected `Element' kinds or expected
`Compilation_Unit' kinds in its documentation, this query does not
raise any exception when called with any argument, but it produces a
meaningful result only when called with an argument with the kind from
this list. For example, if `Asis.Elements.Statement_Kind' query is
called for an argument of `A_Declaration' kind, it just returns
`Not_A_Statement', but without raising any exception.

3.6 ASIS Iterator
=================

ASIS provides a powerful mechanism to traverse an Ada unit, the generic
procedure `Asis.Iterator.Traverse_Element'.  This procedure makes a
top-down left-to-right (or depth-first) traversal of the ASIS tree
(that is, of the syntax structure of the Ada code viewed as the
hierarchy of ASIS `Element's). In the course of this traversal, it
applies to each `Element' the formal `Pre_Operation' procedure when
visiting this `Element' for the first time, and the formal
`Post_Operation' procedure when leaving this `Element'.  By providing
specific procedures for `Pre_Operation' and `Post_Operation' when
instantiating the generic unit, you can automatically process all ASIS
`Element's found in a given ASIS tree.

   For example, suppose we have an assignment statement:

         X := F (Y);

When called for an `Element' representing this statement, a
`Traverse_Element' instantiation does the following (below `Pre_Op' and
`Post_Op' stand for actual procedures provided for formal
`Pre_Operation' and `Post_Operation', and numbers indicate the sequence
of calls to `Pre_Op' and `Post_Op' during traversal):

                  (1 Pre_Op)  X := F (Y) (10 Post_Op)
                                  |
                                  |
                -----------------------------------
                |                                 |
     (2 Pre_Op) X (3 Post_Op)                     |
                                                  |
                                     (4 Pre_Op) F(Y) (9 Post_Op)
                                                  |
                                                  |
                                     ---------------------------
                                     |                         |
                         (5 Pre_Op)  F (6 Post_Op)  (7 Pre_Op) Y (8 Post_Op)

To see in more detail how `Traverse_Element' may be used for rapid
development of a number of useful ASIS applications, try the examples in
*note ASIS Tutorials::.

3.7 How to Navigate through the `Asis' Package Hierarchy
========================================================

The following hints and tips may be useful when looking for some
specific information in the ASIS source files:

   * Use the short overview of the ASIS packages given in *note ASIS
     Package Hierarchy::, to limit your browsing to a smaller set of
     ASIS packages (e.g., if  you are interested in what can be done
     with `Compilation_Unit's then look only in
     `Asis.Compilation_Units'; if you are looking for queries that can
     be  used to decompose and analyze declarations, limit your search
     to  `Asis.Declarations').

   * Inside ASIS packages working with particular kinds of `Element's
     (`Asis.Declarations', `Asis.Definitions', `Asis.Statements',
     `Asis.Expressions' and `ASIS.Clauses') queries are ordered
     according  to the order of the description of the corresponding
     constructions in the  `Ada Reference Manual'  (e.g., package
     `Asis.Statements' starts from a query retrieving labels  and ends
     with the query decomposing a code statement).

   * The names of all the semantic queries (and only ones) start from
     `Corresponding_...' or `Implicit_...'

   * Use comment sentinels given in the specification of the ASIS
     packages. A  sentinel of the form "`--|ER'" (from "`Element'
     Reference") introduces a new  `Element' kind, and it is followed
     by a group of sentinels of the form "`--|CR'" (from "Child
     Reference"), which list queries yielding the child  `Element's for
     the `Element' just introduced.

4 ASIS `Context'
****************

From an ASIS application viewpoint we may view an ASIS `Context' as a
set of ASIS `Compilation_Unit's accessible through ASIS queries.  The
common ASIS implementation technique is to base an implementation of an
ASIS `Context' on some persistent data structures created by the
underlying Ada compiler when compiling Ada compilation units maintained
by this compiler. An ASIS `Context' can only contain compilable (that
is, legal) compilation units.

4.1 ASIS `Context' and Tree Files
=================================

The ASIS-for-GNAT implementation is based on _tree output files_, or,
simply, _tree files_. When called with the special option `-gnatt', GNAT
creates and outputs a tree file if no error was detected during the
compilation. The tree file is a kind of snapshot of the compiler
internal data structures (basically, of the Abstract Syntax Tree (AST)) at
the end of the successful compilation. ASIS then inputs tree files and
recreates in its internal data structures exactly the same picture the
compiler had at the end of the corresponding successful compilation.

   An important consequence of the GNAT source-based compilation model
is that the AST contains full information not only about the unit being
compiled, but also about all the units upon which this unit depends
semantically. Therefore, having read a tree file, ASIS can in general
provide information about more than one unit. By processing a tree
file, a tool can provide information about the unit for which this tree
was created and about all the units upon which it depends semantically.
However, to process several units, ASIS sometimes has to change the
tree being processed (in particular, this occurs when an application
switches between units which do not semantically depend on each other,
for example, two package bodies). Therefore, in the course of an ASIS
application, ASIS may read different tree files and it may read the
same tree file more then once.

   The name of a tree file is obtained from the name of the source file
being compiled by replacing its suffix with '`.adt''. For example, the
tree file for `foo.adb' is named `foo.adt'.  

4.2 Creating Tree Files for Use by ASIS
=======================================

Neither `gcc' nor `gnatmake' will create tree files automatically when
you are working with your Ada program. It is your responsibility as a
user of an ASIS application to create a set of tree files that
correctly reflect the set of the Ada components to be processed by the
ASIS application, as well as to maintain the consistency of the trees
and the related source files.

   To create a tree file for a given source file, you need to compile
the corresponding source file with the `-gnatct' option.  

     $ gcc -c -gnatct foo.adb

will produce `foo.adt', provided that `foo.adb' contains the source of
a legal Ada compilation unit. Actially, the `-gnatct' is an
ASIS-specific combination of two compileation options, `-gnatt' and
`-gnatc'. The `-gnatt' option generates a tree file, and `-gnatc' turns
off AST expansion. ASIS needs tree files created without AST expansion,
whereas to create an object file, GNAT needs an expanded AST.  Therefore
it is impossible for one compilation command to to produce both a tree
file and an object file for a given source file.

   The following points are important to remember when generating and
dealing with tree files:

   * ASIS-for-GNAT is distributed for a particular version of  GNAT.  All
     the trees to be processed by an ASIS application should be
     generated by this specific version of the compiler.

   * A tree file is not created if an error has been detected during the
     compilation.

   * In contrast with object files, a tree file may be generated for
     any legal Ada  compilation unit, including a library package
     declaration requiring a body  or a subunit.

   * A set of tree files processed by an ASIS application may be
     inconsistent; for example, two tree files may have been created
     with different versions  of the source of the same unit. This will
     lead to inconsistencies in the  corresponding ASIS `Context'. See
     *note Consistency Problems::, for more details.

   * Do not move tree, object or source files among directories in the
     underlying  file system! ASIS might assume an inconsistency between
     tree and source files when opening a `Context', or you may get
     wrong results  when querying the source or object file for a given
     ASIS  `Compilation_Unit'.

   * When invoking `gcc' or `gnatmake' to create tree files, make sure
     that all file and  directory names containing relative path
     information start from  `./'  or `../' (`.\' and `..\'
     respectively in MS Windows).   That is, to create a  tree file for
     the source file `foo.adb' located in the inner directory  named
     `inner', you should invoke gcc (assuming an MS Windows platform)
     as:

          $ gcc -c -gnatct  .\inner\foo.adb

     but not as

          $ gcc -c -gnatct inner\foo.ads

     Otherwise ASIS will not perform correctly.

   * When reading in a tree file, ASIS checks that this tree file was
     created with the `-gnatc' option, and it does not accept trees
     created without this option.  

   * If called to create a tree, GNAT does not destroy an `ALI' file if
     the `ALI' file  already exists for the unit being compiled and if
     this `ALI' file is  up-to-date. Moreover, GNAT may place some
     information from the existing `ALI'  file into the tree file. If
     you would like to have both object  and tree files for your
     program, first create the object files, and then the tree  files.

   * There is only one extension for tree files, namely `.adt', whereas
     the standard  GNAT name convention for the Ada source files uses
     different extensions  for a spec (`.ads') and for a body (`.adb').
     This means that if you  first generate a tree for a unit's body:

          $ gcc -c -gnatct foo.adb

     and then generate the tree for the corresponding spec:

          $ gcc -c -gnatct foo.ads

     then the tree file `foo.adt' will be created twice: first for the
     body, and then for the spec. The tree for the spec will override
     the tree for the body, and the information about the body will be
     lost  for ASIS. If you first create the tree for a spec, and then
     for a body,  the second tree will also override the first one, but
     no information will  be lost for ASIS, because the tree for a body
     contains full  information about the corresponding spec.

     To avoid losing information when creating trees for a set of Ada
     sources,  try to use `gnatmake' whenever possible (see  *note
     Using gnatmake to Create Tree Files:: for more details).
     Otherwise, first create trees for specs and then for bodies:

          $ gcc -c -gnatct *.ads
          $ gcc -c -gnatct *.adb

   * Reading tree files is a time-consuming operation. Try to minimize
     the number  of tree files to be processed by your application, and
     try to avoid unnecessary  tree swappings.   (See *note How to
     Build Efficient ASIS Applications::, for some  tips).

   * It is possible to create tree files "on the fly", as part of the
     processing of the ASIS queries that obtain units from a `Context'.
     In this  case there is no need to create tree files before running
     an ASIS application  using the corresponding `Context' mode. Note
     that this possibility goes beyond  the ASIS Standard, and there
     are some limitations imposed on  some ASIS queries, but this
     functionality may be useful for  ASIS tools that process only one
     `Compilation_Unit' at a time. See the  `ASIS-for-GNAT Reference
     Manual' for more details.

Note that between opening and closing a `Context', an ASIS application
should not change its working directory; otherwise execution of the
application is erroneous.  

4.2.1 Creating Trees for Data Decomposition Annex
-------------------------------------------------

Using the ASIS Data Decomposition Annex (DDA) does not require anything
special to be done by an ASIS user, with one exception. The
implementation of the ASIS DDA is based on some special annotations
added by the compiler to the trees used by ASIS. An ASIS user should be
aware of the fact that trees created for subunits do not have this
special annotation.  Therefore ASIS DDA queries do not work correctly
on trees created for subunits (and these queries might not work
correctly if a set of tree files making up a `Context' contains a tree
created for a subunit).

   Thus, when working with the ASIS DDA, you should avoid creating
separate trees for subunits. Actually, this is not a limitation: to
create a tree for a subunit, you should also have the source of the
parent body available. If in this situation you create the tree for the
parent body, it will contain the full information (including
DDA-specific annotation) for all the subunits that are present. From
the other side, a tree created for a single subunit has to contain
information about the parent body, so it has about the same size as the
tree for the parent body.

   The best way to create trees when using ASIS DDA is to use
`gnatmake': it will never create separate trees for subunits.

4.3 Different Ways to Define an ASIS `Context' in ASIS-for-GNAT
===============================================================

The `Asis.Ada_Environments.Associate' query that defines a `Context'
has the following spec:

     procedure Associate
                  (The_Context : in out Asis.Context;
                   Name        : in Wide_String;
                   Parameters  : in Wide_String := Default_Parameters);

In ASIS-for-GNAT, `Name' does not have any special meaning, and the
properties of the `Context' are set by "options" specified in the
`Parameters' string:

   * How to define a set of tree files making up the `Context' (`-C'
     options);

   * How to deal with tree files when opening a `Context' and when
     processing ASIS queries (`-F' options);

   * How to process the source files during the consistency check when
     opening the `Context' (`-S' options):

   * The search path for tree files making up the `Context' (`-T'
     options);

   * The search path for source files used for calling GNAT to create a
     tree file "on the fly" (`-I' options);

The association parameters may (and in some cases must) also contain the
names of tree files or directories making up search paths for tree
and/or source files. Below is the overview of the `Context' association
parameters in ASIS-for-GNAT; for full details refer to the
`ASIS-for-GNAT Reference Manual'.

4.3.1 Defining a set of tree files making up a `Context'
--------------------------------------------------------

The following options are available:

`-C1'
     "One tree" `Context', defining a `Context' comprising a single
     tree file; this tree  file name should be given explicitly in the
     `Parameters' string.

`-CN'
     "N-trees" `Context', defining a `Context' comprising a set of tree
     files; the names  of the tree files making up the `Context' should
     be given explicitly in the  `Parameters' string.

`-CA'
     "All trees" `Context', defining a `Context' comprising all the
     tree files in the  tree search path given in the same `Parameters'
     string; if this option  is set together with `-FM' option, ASIS
     can also create new tree files  "on the fly" when processing
     queries yielding ASIS `Compilation_Unit's.

The default option is `-CA'.

   Note that for `-C1', the `Parameters' string should contain the name
of exactly one tree file. Moreover, if during the opening of such a
`Context' this tree file could not be successfully read in because of
any reason, the `Asis_Failed' exception is raised.  

4.3.2 Dealing with tree files when opening a `Context' and processing ASIS queries
----------------------------------------------------------------------------------

The following options are available:

`-FT'
     Only pre-created trees are used, no tree file can be created by
     ASIS.

`-FS'
     All the trees considered as making up a given `Context' are
     created "on  the fly", whether or not the corresponding tree file
     already exists;  once created, a tree file may then be reused
     while the `Context' remains  open. This option can be set only
     with `-CA' option.

`-FM'
     Mixed approach: if a needed tree does not exist, the attempt to
     create  it "on the fly" is made. This option can only be set with
     `-CA' option.

The default option is `-FT'.

   Note that the `-FS' and `-FM' options go beyond the scope of the
official ASIS standard. They may be useful for some ASIS applications
with specific requirements for defining and processing an ASIS
`Context', but in each case the ramifications of using such
non-standard options should be carefully considered. See the
`ASIS-for-GNAT Reference Manual' for a detailed description of these
option.

4.3.3 Processing source files during the consistency check
----------------------------------------------------------

When ASIS reads a tree fule as a part of opening a `Context', it
checks, that the tree is consistent with the source files of the
`Compilation_Unit's represented by this tree.

   The following options are available to control this check:

`-SA'
     Source files for all the `Compilation_Unit's belonging to the
     `Context' (except   the predefined `Standard' package) have to be
     available, and all of them   are taken into account for
     consistency checks when opening the `Context'.

`-SE'
     Only existing source files for all the `Compilation_Unit's
     belonging to the  `Context' are taken into account for consistency
     checks when opening the `Context'.

`-SN'
     None of the source files from the underlying file system are taken
     into  account when checking the consistency of the set of tree
     files making up a  `Context' (that is, no check is made).

The default option is `-SA'.  See *note Consistency Problems::,
concerning consistency issues in ASIS-for-GNAT.

4.3.4 Setting search paths
--------------------------

Using the `-I', `-gnatec' and `-gnatA' options for defining an ASIS
`Context' is similar to using the same optionsfor `gcc'.  The `-T'
option is used in the same way, for tree files.  For full details about
the `-T' and `-I' options, refer to the `ASIS-for-GNAT Reference
Manual'. Note that the `-T' option is used only to locate existing tree
files, and it has no effect for `-FS' `Context's. On the other hand,
the `-I' option is used only to construct a set of arguments when ASIS
calls GNAT to create a tree file "on the fly"; it has no effect for
`-FT' `Context's, and it cannot be used to tell ASIS where it should
look for source files for ASIS `Compilation_Unit's.

4.4 Consistency Problems
========================

There are two different kinds of consistency problems existing for
ASIS-for-GNAT, and both of them can show up when opening an ASIS
`Context'.

   First, a tree file may have been created by another version of GNAT
(see the README file about the coordination between the GNAT and
ASIS-for-GNAT versions). This means that there is an ASIS-for-GNAT
installation problem.  

   Second, the tree files may be inconsistent with the existing source
files or with each other.

4.4.1 Inconsistent versions of ASIS and GNAT
--------------------------------------------

When ASIS-for-GNAT reads a tree file created by the version of the
compiler for which a given version of ASIS-for-GNAT is not supposed to
be used, ASIS treats the situation as an ASIS-for-GNAT installation
problem and raises `Program_Error' with a corresponding exception
message. In this case, `Program_Error' is not caught by any ASIS query,
and it propagates outside ASIS.(1) Note that the real cause may be an
old tree file you have forgotten to remove when reinstalling
ASIS-for-GNAT. This is also considered an installation error.

   ASIS uses the tree files created by the GNAT compiler installed on
your machine, and the ASIS implementation includes some compiler
components to define and to get access to the corresponding data
structures. Therefore, the version of the GNAT compiler installed on
your machine and the version of the GNAT compiler whose sources are
used as a part of the ASIS implementation should be close enough to
define the same data structures.  We do not require these versions to
be exactly the same, and, by default, when ASIS reads a tree file it
only checks for significant differences.  That is, it will accept tree
files from previous versions of GNAT as long as it is possible for such
files to be read. In theory, this check is not 100% safe; that is, a
tree created by one version of GNAT might not be correctly processed by
ASIS built with GNAT sources taken from another version.  But in
practice this situation is extremely unlikely.

   An ASIS application may set a strong GNAT version check by providing
the `-vs' parameter for the ASIS `Initialize' procedure, see
`ASIS-for-GNAT Reference Manual' for more details. If the strong
version check is set, then only a tree created by exactly the same
version of GNAT whose sources are used as a part of the ASIS
implementation can be successfully read in, and `Program_Error' will be
raised otherwise.

   Be careful when using a `when others' exception handler in your ASIS
application: do not use it just to catch non-ASIS exceptions and to
ignore them without any analysis.

   ---------- Footnotes ----------

   (1) This is not a violation of the requirement stated in the ASIS
definition that only ASIS-defined exceptions are allowed to propagate
outside ASIS queries, because in this case you do not have ASIS-for-GNAT
properly installed and therefore you do not have a valid ASIS
implementation.

4.4.2 Consistency of a set of tree and source files
---------------------------------------------------

When processing a set of more then one tree file making up the same
`Context', ASIS may face a consistency problem. A set of tree files is
inconsistent if it contains two trees representing the same compilation
unit, and these trees were created with different versions of the
source of this unit. A tree file is inconsistent with a source of a
unit represented by this tree if the source file currently available
for the unit differs from the source used to create the tree file.

   When opening a `Context' (via the `Asis.Ada_Environments.Open'
query), ASIS does the following checks for all the tree files making up
the `Context':

   * If the `-SA' option is set for the `Context', ASIS checks that for
     every   `Compilation_Unit' represented by a tree, the source file
     is available and it   is the same as the source file used to
     create the tree (a tree file contains   references to all the
     source files used to create this tree file).

   * If the `-SE' option is set for the `Context', then if for a
     `Compilation_Unit'   represented by a tree a source file is
     available, ASIS checks that this   source is the same as the
     source used to create the tree. If for a   `Compilation_Unit'
     belonging to a `Context' a source file is not available, ASIS
     checks that all the tree files containing this unit were created
     with the   same version of the source of this unit.

   * If the `-SN' option is set for the `Context', ASIS checks that all
     the trees   were created from the same versions of the sources
     involved. It does not check if any of   these sources is available
     or if this is the same version of the source that has been   used
     to create the tree files.

   If any of these checks fail, the `Asis_Failed' exception is raised
as a result of opening a `Context'. If the `Context' has been
successfully opened, you are guaranteed that ASIS will process only
consistent sets of tree and source files until the `Context' is closed
(provided that this set is not changed by some non-ASIS actions).

4.5 Processing Several `Context's at a Time
===========================================

If your application processes more then one open `Context' at a time,
and if at least one of the `Context's is defined with an `-FS' or `-FM'
option, be aware that all the tree files created by ASIS "on the fly"
are placed in the current directory. Therefore, to be on the safe side
when processing several opened `Context's at a time, an ASIS
application should have at most one `Context' defined with an `-FS' or
`-FM' option. If the application has such a `Context', all the other
`Context's should not use tree files located in the current directory.

4.6 Using ASIS with a cross-compiler
====================================

If you would like to use ASIS with a cross-compiler, you should use
this cross-compiler to create the tree files to be used for the ASIS
`Context' defined with `-FS' option. If you would like to use trees
created on the fly (that is, to use a `Context' defined with the `-FS'
or `-FM' option), you have to tell ASIS which compiler should be called
to perform this function. There are two ways to do this.

   * You can use the `--GCC' option in the `Context' definition to
     specify explicitly the name of the command to be called to create
     the trees on the fly 

   * You may use the prefix of the name of your ASIS tool to indicate
     the name of the command   to be used to call the compiler. If the
     name of your tool contains a hyphen character "`-'",   for example
     `some_specific-foo', then ASIS will try to call the command with
     the   name created as a concatenation of the tool name prefix
     preceding the rightmost   hyphen, the hyphen character itself, and
     `gcc'. For example, for `some_specific-foo',   ASIS will try to
     call `some_specific-gcc' to create the tree file.

   The algorithm for defining the name of the command to be used to
create trees on the fly is as follows. If the `--GCC' option is used in
the `Context' definition and if the name that is the parameter of this
option denotes some executable existing in the path, this executable is
used. Otherwise ASIS tries to define the name of the executable from
the name of the ASIS application. If the corresponding executable
exists on the path, it is used. Otherwise the standard `gcc'
installation is used.

5 ASIS Interpreter `asistant'
*****************************

This chapter describes `asistant', an interactive interface to ASIS
queries.  

5.1 `asistant' Introduction
===========================

The `asistant' tool allows you to use ASIS without building your own
ASIS applications. It provides a simple command language that allows
you to define variables of ASIS types and to assign them values by
calling ASIS queries.

   This tool may be very useful while you are learning ASIS: it lets
you try different ASIS queries and see the results immediately.  It
does not crash when there is an error in calling an ASIS query (such as
passing an inappropriate `Element'); instead `asistant' reports an
error and lets you try again.

   You can also use `asistant' as a debug and "ASIS visualization" tool
in an ASIS application project.  If you have problems finding out which
query should be used in a given situation, or why a given query does
not work correctly with a given piece of Ada code, you may use
`asistant' to reconstruct the situation that causes the problems, and
then experiment with ASIS queries.

   Though primarily an interactive tool, `asistant' also can interpret
sequences of commands written to a file (called a "script file" below).
The `asistant' tool can also store in a file the log of an interactive
session that can then be reused as a script file.

   The full documentation of `asistant' may be found in the ``asistant'
Users' Guide' (file `asistant.ug' in the `asistant' source directory).
Here is a brief overview of `asistant' usage.

   The executable for `asistant' is created in the `asistant' source
directory as a part of the standard procedure of installing
ASIS-for-GNAT as an Ada library (or it is placed in the `GNATPRO/bin'
directory when installing ASIS from the binary distribution). Put this
executable somewhere on your path(1), and then type "`asistant'" to
call `asistant' in an interactive mode. As a result, the program will
output brief information about itself and then the `asistant' prompt
"`>'" will appear: 

     ASIStant - ASIS Tester And iNTerpreter, v1.2
     (C) 1997-2002, Free Software Foundation, Inc.
       Asis Version: ASIS 2.0.R

     >

Now you can input `asistant' commands (`asistant' supports in its
command language the same form of comments as Ada, and names in
`asistant' are not case-sensitive):

     >Initialize ("") -- the ASIS Initialize query is called with an
                      -- empty string as a parameter

     >set (Cont) --  the non-initialized variable Cont of the ASIS
                 --  Context type is created

     >Associate (Cont, "", "") --  the ASIS Associate query with two empty
                               --  strings as parameters is called for Cont

     >Open (Cont)  --  the ASIS Open query is called for Cont

     >set (C_U, Compilation_Unit_Body ("Test", Cont)) -- the variable C_U
       --  of the ASIS Compilation_Unit type is created and initialized as
       --  the result of the call to the ASIS query Compilation_Unit_Body.
       --  As a result, C_U will represent a compilation unit named "Test"
       --  and contained in the ASIS Context named Cont

     >set (Unit, Unit_Declaration (C_U))  --  the variable Unit of the ASIS
       --  Element type is created and initialized as the result of calling
       --  the ASIS Unit_Declaration query

     >print (Unit) --  as a result of this command, some information about
                   --  the current value of Unit will be printed (a user can set
                   --  the desired level of detail of this information):

     A_PROCEDURE_BODY_DECLARATION at ( 1 : 1 )-( 9 : 9 )

     --  suppose now, that we do make an error - we call an ASIS query for
     --  an inappropriate element:

     >set (Elem, Assignment_Expression (Unit))

     --  ASIS will raise an exception, asistant will output the ASIS debug
     --  information:

     Exception is raised by ASIS query ASSIGNMENT_EXPRESSION.
     Status : VALUE_ERROR
     Diagnosis :
     Inappropriate Element Kind in Asis.Statements.Assignment_Expression

     --  it does not change any of the existing variables and it prompts
     --  a user again:

     > ...

   ---------- Footnotes ----------

   (1) You do not have to do this if you have installed ASIS from the
binary distribution, because the executable for `asistant' has been
added to other GNAT executables

5.2 `asistant' commands
=======================

The list of `asistant' commands given in this section is incomplete;
its purpose is only to give a general idea of `asistant''s capabilities.
Standard metalanguage is assumed (i.e., "`['_construct_`]'" denotes an
optional instance of "_construct_").

`Help [(name)]'
     Outputs the profile of the ASIS query "`name'"; when called with
     no argument,  generates general `asistant' help information.

`Set (name)'
     Creates a (non-initialized) variable "`name'" of the ASIS
     `Context' type.

`Set (name, expr)'
     Evaluates the expression "`expr'" (it may be any legal `asistant'
     expression; a call to some ASIS query is the most common case in
     practice)  and creates the variable "`name'" of the type and with
     the value of "`expr'".

`Print (expr)'
     Evaluates the expression "`expr'" and outputs its value (some
     information may be  omitted depending on the level specified by
     the `PrintDetail' command).

`Run (`filename')'
     Launches the script from a file `filename', reading further
     commands from it.  

`Pause'
     Pauses the current script and turns `asistant' into interactive
     mode.

`Run'
     Resumes a previously `Pause'd script.

`Browse'
     Switches `asistant' into step-by-step ASIS tree browsing.

`Log (`filename')'
     Opens the file `filename' for session logging.

`Log'
     Closes the current log file.

`PrintDetail'
     Toggles whether the `Print' command outputs additional information.

`Quit [(exit-status)]'
     Quits `asistant'.

5.3 `asistant' variables
========================

The `asistant' tool lets you define variables with Ada-style (simple)
names.  Variables can be of any ASIS type and of conventional
`Integer', `Boolean' and `String' type.  All the variables are created
and assigned dynamically by the `Set' command; there are no predefined
variables.

   There is no type checking in `asistant': each call to a `Set'
command may be considered as creating the first argument from scratch
and initializing it by the value provided by the second argument.

5.4 Browsing an ASIS tree
=========================

You perform ASIS tree browsing by invoking the `asistant' service
function `Browse'. This will disable the `asistant' command interpreter
and activate the Browser command interpreter. The Browser `Q' command
switches back into the `asistant' environment by enabling the `asistant'
command interpreter and disabling the Browser interpreter.

   `Browse' has a single parameter of `Element' type, which establishes
where the ASIS tree browsing will begin.  `Browse' returns a result of
type `Element', namely the `Element' at which the tree browsing was
stopped. Thus, if you type:

     > set (e0, Browse (e1))

you will start ASIS tree browsing from `e1'; when you finish browsing,
`e0' will represent the last `Element' visited during the browsing.

   If you type:

     > Browse (e1)

you will be able to browse the ASIS tree, but the last `Element' of the
browsing will be discarded.

   Browser displays the ASIS `Element' it currently points at and
expects one of the following commands:

`U'
     Go one step up the ASIS tree (equivalent to calling the ASIS
     `Enclosing_Element' query); 

`D'
     Go one step down the ASIS tree, to the left-most component of the
     current `Element'

`N'
     Go to the right sibling (to the next `Element' in the ASIS tree
     hierarchy)

`P'
     Go to the left sibling (to the previous `Element' in the ASIS tree
     hierarchy)

`\k1k2'
     where `k1' is either `D' or `d', and `k2' is either `T' or `t'.
     Change the form of displaying the current `Element': `D' turns ON
     displaying the debug image, `d' turns it OFF. `T' turns ON
     displaying the text image, `t' turns it OFF.

`<SPACE><query>'
     Call the <query> for the current `Element'.

`Q'
     Go back to the `asistant' environment; the Browser command
     interpreter is disabled and the `asistant' command interpreter is
     enabled with the current `Element' returned as a result of the
     call to `Browse'.

Browser immediately interprets the keystroke and displays the new
current `Element'. If the message `"Cannot go in this direction."'
appears, this means that traversal in this direction from current node
is impossible (that is, the current node is either a terminal `Element'
and it is not possible to go down, or it is the leftmost or the
rightmost component of some `Element', and it is not possible to go
left or right, or it is the top `Element' in its enclosing unit
structure and it is not possible to go up).

   It is possible to issue some ordinary ASIS queries from inside the
Browser (for example, semantic queries). These queries should accept
one parameter of type `Element' and return `Element' as a result.

   When you press `<SPACE>', you are asked to enter the query name. If
the query is legal, the current `Element' is replaced by the result of
the call to the given query with the current `Element' as a parameter.

5.5 Example
===========

Suppose we have an ASIS `Compilation_Unit' `Demo' in the source file
`demo.adb':

     procedure Demo is
        function F (I : Integer) return Integer;

        function F (I : Integer) return Integer is
        begin
           return (I + 1);
        end F;

        N : Integer;

     begin
         N := F (3);
     end Demo;

Suppose also that the tree for this source is created in the current
directory.  Below is a sequence of `asistant' commands which does
process this unit. Explanation is provided via `asistant' comments.

     initialize ("")

     --  Create and open a Context comprising all the tree files
     --  in the current directory:

     Set (Cont)
     Associate (Cont, "", "")
     Open (Cont)

     -- Get a Compilation_Unit (body) named "Demo" from this Context:

     Set (CU, Compilation_Unit_Body ("Demo", Cont))

     --  Go into the unit structure and get to the expression
     --  in the right part of the assignment statements in the unit body:

     Set (Unit, Unit_Declaration (CU))
     Set (Stmts, Body_Statements (Unit, False))
     Set (Stmt, Stmts (1))
     Set (Expr, Assignment_Expression (Stmt))

     -- Output the debug image and the text image of this expression:

     Print (Expr)
     Print (Element_Image (Expr))

     --  This expression is of A_Function_Call kind, so it's possible to ask
     --  for the declaration of the called function:

     Set (Corr_Called_Fun, Corresponding_Called_Function (Expr))

     --  Print the debug and the text image of the declaration of the called
     --  function:

     Print (Corr_Called_Fun)
     Print (Element_Image (Corr_Called_Fun))

     -- Close the asistant session:

     Quit

6 ASIS Application Templates
****************************

The subdirectory `templates' of the ASIS distribution contains a set of
Ada source components that can be used as templates for developing
simple ASIS applications. The general idea is that you can easily build
an ASIS application by adding the code performing some specific ASIS
analysis in well-defined places in these templates.

   Refer to the ASIS tutorial's solutions for examples of the use of the
templates.

   For more information see the `README' file in the `templates'
subdirectory.

7 ASIS Tutorials
****************

The subdirectory `tutorial' of the ASIS distribution contains a simple
hands-on ASIS tutorial which may be useful in getting a quick start with
ASIS. The tutorial contains a set of simple exercises based on the
`asistant' tool and on a set of the ASIS Application Templates provided
as a part of the ASIS distribution. The complete solutions are provided
for all the exercises, so the tutorial may also be considered as a set
of ASIS examples.

   For more information see the `README' file in the `tutorial'
subdirectory.

8 How to Build Efficient ASIS Applications
******************************************

This chapter identifies some potential performance issues with ASIS
applications and offers some advice on how to address these issues.

8.1 Tree Swapping as a Performance Issue
========================================

If an ASIS `Context' comprises more then one tree, then ASIS may need
to switch between different trees during an ASIS application run.
Switching between trees may require ASIS to repeatedly read in the same
set of trees, and this may slow down an application considerably.

   Basically, there are two causes for tree swapping:

   * _Processing of semantically independent units._ Suppose in
     `Context' `Cont' we have  units `P' and `Q' that do not depend on
     each other, and `Cont' does  not contain any third unit depending
     on both `P' and `Q'. This  means that `P' and `Q' cannot be
     represented by the same tree. To  obtain information about `P',
     ASIS needs to access the tree `p.adt',  and to get some
     information about `Q', ASIS needs  `q.adt'. Therefore, if an
     application retrieves some information from  `P', and then starts
     processing `Q', ASIS has to read  `q.adt'.

   * _Processing of information from dependent units._ A unit `U' may
     be present not only in the tree created for `U', but also in all
     the trees created for units which semantically depend upon `U'.
     Suppose we have a library procedure `Proc' depending on a  library
     package `Pack', and in the set of trees making up our `Context' we
     have trees `pack.adt' and `proc.adt'. Suppose we have some
     `Element' representing a component of `Pack', when `pack.adt' was
     accessed by ASIS, and suppose that because of some other actions
     undertaken  by an application ASIS changed the tree being accessed
     to `proc.adt'.   Suppose that now the application wants to do
     something with the `Element'  representing some component of
     `Pack' and obtained from `pack.adt'. Even  though the unit `Pack'
     is represented by the currently accessed tree  `proc.adt', ASIS
     has to switch back to `pack.adt', because all the  references into
     the tree structure kept as a part of the value of this  `Element'
     are valid only for `pack.adt'.

8.2 Queries That Can Cause Tree Swapping
========================================

In ASIS-for-GNAT, tree swapping can currently take place only when
processing queries defined in:

     Asis.Elements
     Asis.Declarations
     Asis.Definitions
     Asis.Statements
     Asis.Clauses
     Asis.Expressions
     Asis.Text

but not for those queries in the above packages that return enumeration
or boolean results.

   For any instantiation of `Asis.Iterator.Traverse_Element', the
traversal itself can cause at most one tree read to get the tree
appropriate for processing the `Element' to be traversed, but
procedures provided as actuals for `Pre_Operation' and `Post_Operation'
may cause additional tree swappings.

8.3 How to Avoid Unnecessary Tree Swapping
==========================================

To speed up your application, try to avoid unnecessary tree swapping.
The following guidelines may help:

   *  Try to minimize the set of tree files processed by your
     application. In  particular, try to avoid having separate trees
     created for subunits.

     Minimizing the set of tree files processed by the application also
     cuts  down the time needed for opening a `Context'. Try to use
     `gnatmake' to create  a suitable set of tree files covering an Ada
     program for processing by  an ASIS application.

   *  Choose the `Context' definition appropriate to your application.
     For  example, use "one tree" `Context' (`-C1') for applications
     that are limited  to processing single units (such as a pretty
     printer or `gnatstub'). By  processing the tree file created for
     this unit, ASIS can get all the  syntactic and semantic
     information about this unit. Using the "one tree" `Context'
     definition, an application has only one tree file to read when
     opening a `Context', and no other tree file will be read during the
     application run. An "N-trees" `Context' is a natural extension of
     "one tree"  `Context' for applications that know in advance which
     units will be  processed, but opening a `Context' takes longer,
     and ASIS may switch among  different tree files during an
     application run. Use "all trees" `Context'  only for applications
     which are not targeted at processing a specific  unit or a
     specific set of units, but are supposed to process all the
     available units, or when an application has to process a large
     system consisting of a many units. When using an  application
     based on an "all trees" `Context', use the approach for creating
     tree files described above to minimize a set of tree files to be
     processed.

   *  In your ASIS application, try to avoid switching between
     processing units or  sets of units with no dependencies among
     them; such a switching will  cause tree swapping.

   *  If you are going to analyze a library unit having both a spec and
     a body,  start by obtaining an `Element' from the body of this
     unit. This will set  the tree created for the body as the tree
     accessed by ASIS, and this tree  will allow both the spec and the
     body of this unit to be processed  without tree swapping.

   *  To see a "tree swapping profile" of your application use the
     `-dt' debug flag  when initializing ASIS
     (`Asis.Implementation.Initialize ("-dt")').   The  information
     returned may give you some hints on  how to avoid tree swapping.

8.4 Using `gnatmake' to Create Tree Files
=========================================

To create a suitable set of tree files, you may use `gnatmake'. GNAT
creates an `ALI' file for every successful compilation, whether or not
code has been generated. Therefore, it is possible to run `gnatmake'
with the `-gnatct' option; this will create the set of tree files for
all the compilation units needed in the resulting program.  Below we
will use `gnatmake' to create a set of tree files for a complete Ada
program (partition). You may adapt this approach to an incomplete
program or to a partition without a main subprogram, applying
`gnatmake' to some of its components.

   Using `gnatmake' for creating tree files has another advantage: it
will keep tree files consistent among themselves and with the sources.

   There are two different ways to use `gnatmake' to create a set of
tree files.

   First, suppose you have object, `ALI' and tree files for your
program in the same directory, and `main_subprogram.adb' contains the
body of the main subprogram. If you run `gnatmake' as

     $ gnatmake -f -c -gnatct ... main_subprogram.adb

this will create the trees representing the full program for which
`main_subprogram' is the main procedure. The trees will be created
"from scratch"; that is, if some tree files already exist, they will be
recreated. This is because `gnatmake' is being called with the `-f'
option (which means "force recompilation").  Usng `gnatmake' without
the `-f' option for creating tree files is not reliable if your tree
files are in the same directory as the object files, because object and
tree files "share" the same set of `ALI' files.  If the object files
exist and are consistent with the `ALI' and source files, the source
will not be recompiled for creating a tree file unless the `-f' option
is set.

   A different approach is to combine the tree files and the associated
`ALI' files in a separate directory, and to use this directory only for
keeping the tree files and maintaining their consistency with source
files. Thus, the object files and their associated `ALI' files should
be in another directory.  In this case, by invoking `gnatmake' through:

     $ gnatmake -c -gnatct ... main_subprogram.adb

(that is, without forcing recompilation) you will still obtain a full
and consistent set of tree files representing your program, but in this
case the existing tree files will be reused.

   See the next chapter for specific details related to Ada compilation
units belonging to precompiled Ada libraries.

9 Processing an Ada Library by an ASIS-Based Tool
*************************************************

When an Ada unit to be processed by some ASIS-based tool makes use of
an Ada library, you need to be aware of the following features of using
Ada libraries with GNAT:

   * An Ada library is a collection of precompiled Ada components. The
     sources   of the Ada components belonging to the library are
     present,   but if your program uses some components from a
     library, these components are not recompiled by `gnatmake'
     (except in circumstances described below).    For example,
     `Ada.Text_IO' is not recompiled   when you invoke `gnatmake' on a
     unit that `with's   `Ada.Text_IO'.

   * According to the GNAT source-based compilation model, the spec of
     a library   component is processed when an application unit
     depending on such a component is   compiled, but the body of the
     library component is not processed. As a result,   if you invoke
     `gnatmake' to create a set of tree files covering a given
     program, and if this program references an entity from an Ada
     library, then the   set of tree files created by such a call will
     contain only specs, but not   bodies for library components.

   * Any GNAT installation contains the GNAT Run-Time Library (RTL) as a
      precompiled Ada library. In some cases, a GNAT installation may
     contain some   other libraries (such as Win32Ada Binding on a
     Windows GNAT   platform).

   * In ASIS-for-GNAT, there is no standard way to define whether a
     given   `Compilation_Unit' belongs to some precompiled Ada library
     other than   the GNAT Run-Time Library (some heuristics may be
     added to `Asis.Extensions').    ASIS-for-GNAT classifies (by means
     of the   `Asis.Compilation_Units.Unit_Origin' query) a unit as
     `A_Predefined_Unit', if it is from the Run-Time Library   and if
     it is mentioned in the `Ada Reference Manual', Annex A, Paragraph 2
      as an Ada 95 predefined unit;   a unit is classified as
     `An_Implementation_Unit' if is belongs to Run-Time Library but is
     not mentioned in   the paragraph just cited.    Components of Ada
     libraries other than the Run-Time Library are always classified
     as `An_Application_Unit';

   * It is possible to recompile the components of the Ada libraries
     used   by a given program. To do this, you have to invoke
     `gnatmake' for this   program with the `-a' option. If you create
     a set of   tree files for your program by invoking `gnatmake' with
     the `-a' option, the   resulting set of tree files will contain
     all the units needed by this   program to make up a complete
     partition.

Therefore, there are two possibilities for an ASIS-based tool if
processing (or avoiding processing) of Ada libraries is important for
the functionality of the tool:

   * If the tool is not to process components of Ada libraries, then
     a set of tree files for this tool may be created by invoking
     `gnatmake'    without the `-a' option (this is the usual way of
     using `gnatmake').     When the tool encounters a
     `Compilation_Unit' which represents a spec of some    library
     unit, and for which `Asis.Compilation_Units.Is_Body_Required'      returns
     `True', but `Asis.Compilation_Units.Corresponding_Body' yields a
     result of `A_Nonexistent_Body' kind, then the tool may conclude
     that    this library unit belongs to some precompiled Ada library.

   *  If a tool needs to process all the Ada compilation units making
     up a    program, then a set of tree files for this program should
     be created by    invoking `gnatmake' with the `-a' option.

You can use `Asis.Compilation_units.Unit_Origin' to filter out Run-Time
Library components.

10 Compiling, Binding and Linking Applications with ASIS-for-GNAT
*****************************************************************

If you have installed ASIS-for-GNAT as an Ada library and added the
directory containing all source, `ALI' and library files of this
library to the values of the `ADA_INCLUDE_PATH' and `ADA_OBJECTS_PATH'
environment variables (which is a recommended way to install
ASIS-for-GNAT), you do not need to supply any ASIS-specific options for
`gcc' or for `gnatbind' when working with your ASIS applications.
However for `gnatlink' you have to provide an additional parameter
`-lasis': 

     $ gnatlink my_application -lasis

When using `gnatmake', you also have to provide this linker parameter
whenever a call to `gnatmake' invokes `gnatlink':

     $ gnatmake ... my_application -largs -lasis

You do not need these linker parameters if a call to `gnatmake' is not
creating the executable:

     $ gnatmake -c ... my_application

If you have installed ASIS-for-GNAT without building an ASIS library,
then you have to do the following when working with your ASIS
application code:

   * When compiling, you have to put catalogs with ASIS-for-GNAT
     implementation   sources   (`asis-[version#]-src/asis' and
     `asis-[version#]-src/gnat') in the   search path for the source
     files. You may do this either by the `-I'   option to `gcc' or by
     adding these directories to the `ADA_INCLUDE_PATH'   environment
     variable.

   * When binding, you have to put the directory where all the object
     and `ALI'  files for the ASIS-for-GNAT components were created
     (`asis-[version#]-src/obj', if you followed the manual
     installation procedure  described in the top-level ASIS `README'
     file) in the search path for  `gnatbind'. You can do this either
     with the `-aO' option to  `gnatbind' or by  adding this directory
     to the `ADA_OBJECTS_PATH' environment variable.  

If you have added directories with ASIS-for-GNAT source, object and
`ALI' files to the values of the GNAT-specific environment variables,
you do not have to provide any ASIS-specific parameter when using
`gnatmake' for your ASIS application.

11 ASIS-for-GNAT Warnings
*************************

The ASIS definition specifies the situations when certain ASIS-defined
exceptions should be raised, and ASIS-for-GNAT conforms to these rules.

   ASIS-for-GNAT also generates warnings if it considers some situation
arising during the ASIS query processing to be potentially wrong, and
if the ASIS definition does not require raising an exception. Usually
this occurs with actual or potential problems in an
implementation-specific part of ASIS, such as providing
implementation-specific parameters to the queries `Initialize',
`Finalize' and `Associate' or opening a `Context'.

   There are three warning modes in ASIS-for-GNAT:

_default_
     Warning messages are output to `Standard_Error'.

_suppress_
     Warning messages are suppressed.

_treat as error_
     A warning is treated as an error by ASIS-for-GNAT: instead of
     sending a message to `Standard_Error', ASIS-for-GNAT raises
     `Asis_Failed' and converts the warning message into the ASIS
     `Diagnosis' string.  ASIS Error Status depends on the cause of the
     warning.

The ASIS-for-GNAT warning mode may be set when initializing the ASIS
implementation. The `-ws' parameter of `Asis.Implementation.Initialize' query
suppresses warnings, the `-we' parameter of this query sets treating
all the warnings as errors. When set, the warning mode remains the same
for all `Context's processed until ASIS-for-GNAT has completed.

12 Exception Handling and Reporting Internal Bugs
*************************************************

According to the ASIS Standard, only ASIS-defined exceptions can be
propagated from ASIS queries. The same holds for the ASIS Extensions
queries supported by ASIS-for-GNAT.

   If a non-ASIS exception is raised during the processing of an ASIS
or ASIS extension query, this symptom reflects an internal
implementation problem. Under such a circumstance, by default the ASIS
query will output some diagnostic information to `Standard_Error' and
then exit to the OS; that is, the execution of the ASIS application is
aborted.

   In order to allow the execution of an ASIS-based program to continue
even in case of such internal ASIS implementation errors, you can
change the default behavior by supplying appropriate parameters to
`Asis.Implementation.Initialize'. See `ASIS-for-GNAT Reference Manual'
for more details.

13 File Naming Conventions and Application Name Space
*****************************************************

Any ASIS application depends on the ASIS interface components; an ASIS
application programmer thus needs to be alert to (and to avoid) clashes
with the names of these components.

   ASIS-for-GNAT includes the full specification of the ASIS Standard,
and also adds the following children and grandchildren of the root
`Asis' package: 

   * `Asis.Extensions' hierarchy (the source file names start with
     `asis-extensions') defines some useful ASIS extensions, see ASIS
     Reference Manual for more details.  

   * `Asis.Set_Get' (the source files `asis-set_get.ad(b|s)'
     respectively) contains the access and update subprograms for the
     implementation of the main ASIS abstractions defined in `Asis'.  

   * `Asis.Text.Set_Get' (the source files `asis-text-set_get.ad(b|s)'
     respectively) contains the access and update subprograms for the
     implementation of the ASIS abstractions defined in `Asis.Text'; 

All other ASIS-for-GNAT Ada implementation components belong to the
hierarchy rooted at the package `A4G' (which comes from
"ASIS-for-GNAT").

   ASIS-for-GNAT also incorporates the following GNAT components as a
part of the ASIS implementation:

        Alloc
        Atree
        Casing
        Csets
        Debug
        Einfo
        Elists
        Fname
        Gnatvsn
        Hostparm
        Krunch
        Lib
          Lib.List
          Lib.Sort
        Namet
        Nlists
        Opt
        Output
        Repinfo
        Scans
        Sinfo
        Sinput
        Snames
        Stand
        Stringt
        Table
        Tree_In
        Tree_Io
        Types
        Uintp
        Uname
        Urealp
        Widechar

Therefore, in your ASIS application you should not add children at any
level of the `Asis' or `A4G' hierarchies, and you should avoid using
any name from the list of the GNAT component names above.

   All Ada source files making up the ASIS implementation for GNAT
(including the GNAT components being a part of ASIS-for-GNAT) follow
the GNAT file name conventions without any name "krunch"ing.

Appendix A GNU Free Documentation License
*****************************************

Version 1.1, March 2000

Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

0. PREAMBLE
===========

The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone the
effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially.  Secondarily,
this License preserves for the author and publisher a way to get credit
for their work, while not being considered responsible for
modifications made by others.

   This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft license
designed for free software.

   We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals; it
can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS
================================

This License applies to any manual or other work that contains a notice
placed by the copyright holder saying it can be distributed under the
terms of this License.  The "Document", below, refers to any such
manual or work.  Any member of the public is a licensee, and is
addressed as "you".

   A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

   A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject.  (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding them.

   The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.

   The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.

   A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the general
public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input to
text formatters.  A copy made in an otherwise Transparent file format
whose markup has been designed to thwart or discourage subsequent
modification by readers is not Transparent.  A copy that is not
"Transparent" is called "Opaque".

   Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML or
XML using a publicly available DTD, and standard-conforming simple HTML
designed for human modification.  Opaque formats include PostScript,
PDF, proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the machine-generated
HTML produced by some word processors for output purposes only.

   The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.

2. VERBATIM COPYING
===================

You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

   You may also lend copies, under the same conditions stated above, and
you may publicly display copies.

3. COPYING IN QUANTITY
======================

If you publish printed copies of the Document numbering more than 100,
and the Document's license notice requires Cover Texts, you must enclose
the copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify you
as the publisher of these copies.  The front cover must present the
full title with all words of the title equally prominent and visible.
You may add other material on the covers in addition.  Copying with
changes limited to the covers, as long as they preserve the title of
the Document and satisfy these conditions, can be treated as verbatim
copying in other respects.

   If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

   If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols.  If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.

   It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of copies, to
give them a chance to provide you with an updated version of the
Document.

4. MODIFICATIONS
================

You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release the
Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy of
it.  In addition, you must do these things in the Modified Version:
  A. Use in the Title Page (and on the covers, if any) a title distinct
       from that of the Document, and from those of previous versions
     (which should, if there were any, be listed in the History section
       of the Document).  You may use the same title as a previous
     version    if the original publisher of that version gives
     permission.

  B. List on the Title Page, as authors, one or more persons or entities
       responsible for authorship of the modifications in the Modified
      Version, together with at least five of the principal authors of
     the    Document (all of its principal authors, if it has less than
     five).

  C. State on the Title page the name of the publisher of the
     Modified Version, as the publisher.

  D. Preserve all the copyright notices of the Document.

  E. Add an appropriate copyright notice for your modifications
     adjacent to the other copyright notices.

  F. Include, immediately after the copyright notices, a license notice
       giving the public permission to use the Modified Version under
     the    terms of this License, in the form shown in the Addendum
     below.

  G. Preserve in that license notice the full lists of Invariant
     Sections    and required Cover Texts given in the Document's
     license notice.

  H. Include an unaltered copy of this License.

  I. Preserve the section entitled "History", and its title, and add to
       it an item stating at least the title, year, new authors, and
     publisher of the Modified Version as given on the Title Page.  If
      there is no section entitled "History" in the Document, create one
       stating the title, year, authors, and publisher of the Document
     as    given on its Title Page, then add an item describing the
     Modified    Version as stated in the previous sentence.

  J. Preserve the network location, if any, given in the Document for
     public access to a Transparent copy of the Document, and likewise
      the network locations given in the Document for previous versions
       it was based on.  These may be placed in the "History" section.
       You may omit a network location for a work that was published at
       least four years before the Document itself, or if the original
      publisher of the version it refers to gives permission.

  K. In any section entitled "Acknowledgements" or "Dedications",
     preserve the section's title, and preserve in the section all the
      substance and tone of each of the contributor acknowledgements
     and/or dedications given therein.

  L. Preserve all the Invariant Sections of the Document,    unaltered
     in their text and in their titles.  Section numbers    or the
     equivalent are not considered part of the section titles.

  M. Delete any section entitled "Endorsements".  Such a section    may
     not be included in the Modified Version.

  N. Do not retitle any existing section as "Endorsements"    or to
     conflict in title with any Invariant Section.

   If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

   You may add a section entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various parties -
for example, statements of peer review or that the text has been
approved by an organization as the authoritative definition of a
standard.

   You may add a passage of up to five words as a Front-Cover Text, and
a passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or through
arrangements made by) any one entity.  If the Document already includes
a cover text for the same cover, previously added by you or by
arrangement made by the same entity you are acting on behalf of, you
may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS
======================

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.

   The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of Invariant
Sections in the license notice of the combined work.

   In the combination, you must combine any sections entitled "History"
in the various original documents, forming one section entitled
"History"; likewise combine any sections entitled "Acknowledgements",
and any sections entitled "Dedications".  You must delete all sections
entitled "Endorsements."

   Heading 6. COLLECTIONS OF DOCUMENTS

   You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy that
is included in the collection, provided that you follow the rules of
this License for verbatim copying of each of the documents in all other
respects.

   You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert a
copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.

7. AGGREGATION WITH INDEPENDENT WORKS
=====================================

A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version of
the Document, provided no compilation copyright is claimed for the
compilation.  Such a compilation is called an "aggregate", and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they are
not themselves derivative works of the Document.

   If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.  Otherwise
they must appear on covers around the whole aggregate.

8. TRANSLATION
==============

Translation is considered a kind of modification, so you may distribute
translations of the Document under the terms of section 4.  Replacing
Invariant Sections with translations requires special permission from
their copyright holders, but you may include translations of some or
all Invariant Sections in addition to the original versions of these
Invariant Sections.  You may include a translation of this License
provided that you also include the original English version of this
License.  In case of a disagreement between the translation and the
original English version of this License, the original English version
will prevail.

9. TERMINATION
==============

You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License.  Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License.  However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such parties
remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE
====================================

The Free Software Foundation may publish new, revised versions of the
GNU Free Documentation License from time to time.  Such new versions
will be similar in spirit to the present version, but may differ in
detail to address new problems or concerns.  See
http://www.gnu.org/copyleft/.

   Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

     Copyright (c)  YEAR  YOUR NAME.
     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation; with the Invariant Sections being LIST THEIR TITLES,
     with the Front-Cover Texts being LIST, and with the Back-Cover
     Texts being LIST.  A copy of the license is included in the
     section entitled "GNU Free Documentation License".

   If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no Front-Cover
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.

Index
*****

-GCC option:                                   See 4.6.      (line 1350)
-gnatc option:                                 See 4.2.      (line  954)
-gnatct option <1>:                            See 8.4.      (line 1836)
-gnatct option <2>:                            See 4.2.      (line  947)
-gnatct option:                                See 2.5.      (line  487)
-gnatt option <1>:                             See 4.2.      (line  954)
-gnatt option:                                 See 4.1.      (line  910)
-lasis option:                                 See 10.       (line 1963)
A4G package:                                   See 13.       (line 2080)
Ada predefined library (processing by an ASIS tool):See 9.   (line 1885)
Ada_Environments.Close procedure:              See 2.3.      (line  406)
ADA_INCLUDE_PATH environment variable:         See 10.       (line 1985)
ADA_OBJECTS_PATH environment variable:         See 10.       (line 1994)
adt extension for tree files:                  See 4.1.      (line  934)
All trees Context:                             See 4.3.1.    (line 1137)
ASIS application templates:                    See 6.        (line 1687)
ASIS Example <1>:                              See 5.5.      (line 1622)
ASIS Example:                                  See 2.2.      (line  240)
ASIS Iterator:                                 See 3.6.      (line  823)
ASIS overview:                                 See 3.        (line  566)
Asis package <1>:                              See 13.       (line 2065)
Asis package <2>:                              See 3.2.      (line  635)
Asis package:                                  See 1.1.      (line  166)
ASIS package hierarchy:                        See 3.2.      (line  631)
ASIS Performance:                              See 8.        (line 1716)
ASIS queries <1>:                              See 5.        (line 1374)
ASIS queries <2>:                              See 4.        (line  899)
ASIS queries <3>:                              See 3.3.      (line  693)
ASIS queries <4>:                              See 3.2.      (line  651)
ASIS queries <5>:                              See 3.1.      (line  583)
ASIS queries <6>:                              See 1.2.      (line  188)
ASIS queries:                                  See 1.1.      (line  170)
ASIS queries (dynamic typing):                 See 3.5.      (line  773)
ASIS Tutorials:                                See 7.        (line 1702)
ASIS-for-GNAT <1>:                             See 10.       (line 1956)
ASIS-for-GNAT <2>:                             See 5.1.      (line 1413)
ASIS-for-GNAT <3>:                             See 4.4.      (line 1233)
ASIS-for-GNAT <4>:                             See 4.3.      (line 1088)
ASIS-for-GNAT <5>:                             See 4.2.      (line  963)
ASIS-for-GNAT <6>:                             See 4.1.      (line  909)
ASIS-for-GNAT <7>:                             See 2.4.      (line  453)
ASIS-for-GNAT:                                 See 2.3.      (line  443)
Asis.Ada_Environments package:                 See 3.2.      (line  651)
Asis.Ada_Environments.Associate query:         See 4.3.      (line 1088)
Asis.Ada_Environments.Associate query (example):See 2.2.     (line  269)
Asis.Ada_Environments.Close procedure (example):See 2.2.     (line  339)
Asis.Ada_Environments.Containers package:      See 3.1.      (line  606)
Asis.Ada_Environments.Dissociate procedure:    See 2.3.      (line  422)
Asis.Ada_Environments.Dissociate procedure (example):See 2.2.
                                                             (line  340)
Asis.Ada_Environments.Open procedure:          See 2.3.      (line  386)
Asis.Ada_Environments.Open procedure (example):See 2.2.      (line  279)
Asis.Ada_Environments.Open query:              See 4.4.2.    (line 1297)
ASIS.Clauses package:                          See 3.2.      (line  675)
Asis.Compilation_Units package <1>:            See 3.5.      (line  781)
Asis.Compilation_Units package:                See 3.2.      (line  655)
Asis.Compilation_Units.Corresponding_Body function:See 9.    (line 1942)
Asis.Compilation_Units.Is_Body_Required function:See 9.      (line 1941)
Asis.Compilation_Units.Relations package:      See 3.2.      (line  660)
Asis.Compilation_Units.Unit_Full_Name query (example):See 2.2.
                                                             (line  307)
Asis.Compilation_Units.Unit_Kind query (example):See 2.2.    (line  312)
Asis.Compilation_units.Unit_Origin:            See 9.        (line 1950)
Asis.Compilation_Units.Unit_Origin query:      See 9.        (line 1915)
Asis.Compilation_Units.Unit_Origin query (example):See 2.2.  (line  321)
Asis.Declarations package:                     See 3.2.      (line  674)
Asis.Definitions package:                      See 3.2.      (line  674)
Asis.Elements package <1>:                     See 3.5.      (line  780)
Asis.Elements package:                         See 3.2.      (line  665)
Asis.Elements.Enclosing_Element query:         See 3.3.      (line  699)
Asis.Elements.Statement_Kind query:            See 3.5.      (line  816)
Asis.Errors package:                           See 3.2.      (line  688)
Asis.Errors.Error_Kinds type:                  See 3.4.      (line  756)
Asis.Errors.Value_Error error status:          See 3.5.      (line  801)
Asis.Exceptions package <1>:                   See 3.4.      (line  752)
Asis.Exceptions package:                       See 3.2.      (line  685)
Asis.Exceptions.ASIS_Failed exception (example):See 2.2.     (line  346)
Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit exception:See 3.5.
                                                             (line  807)
Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit exception (example):See 2.2.
                                                             (line  345)
Asis.Exceptions.ASIS_Inappropriate_Context exception (example):See 2.2.
                                                             (line  344)
Asis.Exceptions.ASIS_Inappropriate_Element exception:See 3.5.
                                                             (line  801)
Asis.Expressions package:                      See 3.2.      (line  674)
Asis.Extensions package <1>:                   See 13.       (line 2069)
Asis.Extensions package:                       See 9.        (line 1914)
Asis.Ids package:                              See 3.1.      (line  621)
Asis.Implementation package:                   See 3.2.      (line  644)
Asis.Implementation.Associate procedure:       See 2.3.      (line  374)
Asis.Implementation.Diagnosis query:           See 3.4.      (line  759)
Asis.Implementation.Finalize procedure:        See 2.3.      (line  428)
Asis.Implementation.Finalize procedure (example):See 2.2.    (line  341)
Asis.Implementation.Initialize procedure <1>:  See 11.       (line 2031)
Asis.Implementation.Initialize procedure <2>:  See 8.3.      (line 1827)
Asis.Implementation.Initialize procedure:      See 2.3.      (line  368)
Asis.Implementation.Initialize procedure (example):See 2.2.  (line  262)
Asis.Implementation.Permissions package:       See 3.2.      (line  647)
Asis.Implementation.Set_Status procedure:      See 3.4.      (line  761)
Asis.Implementation.Status function (example): See 2.2.      (line  361)
Asis.Implementation.Status query:              See 3.4.      (line  758)
Asis.Iterator.Traverse_Element generic procedure <1>:See 8.2.
                                                             (line 1773)
Asis.Iterator.Traverse_Element generic procedure:See 3.6.    (line  824)
Asis.Set_Get package:                          See 13.       (line 2073)
Asis.Statements package:                       See 3.2.      (line  674)
Asis.Text package <1>:                         See 3.2.      (line  681)
Asis.Text package:                             See 3.1.      (line  611)
Asis.Text.Set_Get package:                     See 13.       (line 2077)
Asis_Failed exception <1>:                     See 11.       (line 2026)
Asis_Failed exception <2>:                     See 4.4.2.    (line 1320)
Asis_Failed exception:                         See 4.3.1.    (line 1148)
asistant:                                      See 5.        (line 1373)
asistant commands:                             See 5.2.      (line 1479)
asistant variables:                            See 5.3.      (line 1532)
AST (Abstract Syntax Tree) <1>:                See 4.2.      (line  956)
AST (Abstract Syntax Tree):                    See 4.1.      (line  913)
Browse (asistant command):                     See 5.2.      (line 1515)
Browser (asistant utility):                    See 5.4.      (line 1545)
Compilation_Unit type <1>:                     See 3.5.      (line  774)
Compilation_Unit type <2>:                     See 3.2.      (line  636)
Compilation_Unit type <3>:                     See 3.1.      (line  586)
Compilation_Unit type:                         See 2.3.      (line  384)
Compilation_Unit type (example_:               See 2.2.      (line  282)
Consistency problems:                          See 4.4.      (line 1226)
Container type:                                See 3.1.      (line  605)
Context type <1>:                              See 4.3.      (line 1088)
Context type <2>:                              See 4.        (line  898)
Context type <3>:                              See 3.2.      (line  636)
Context type <4>:                              See 3.1.      (line  579)
Context type <5>:                              See 2.6.      (line  509)
Context type:                                  See 2.3.      (line  377)
Context type (example):                        See 2.2.      (line  254)
Data Decomposition Annex (DDA):                See 4.2.1.    (line 1062)
Diagnosis string <1>:                          See 11.       (line 2027)
Diagnosis string:                              See 3.4.      (line  756)
Element type <1>:                              See 3.5.      (line  773)
Element type <2>:                              See 3.2.      (line  636)
Element type <3>:                              See 3.1.      (line  595)
Element type:                                  See 2.3.      (line  393)
Enclosing_Element query <1>:                   See 5.4.      (line 1573)
Enclosing_Element query:                       See 3.3.      (line  696)
Erroneous execution <1>:                       See 4.2.      (line 1057)
Erroneous execution:                           See 2.3.      (line  372)
Error Handling:                                See 3.4.      (line  750)
Free Documentation License, GNU:               See Appendix A.
                                                             (line 2131)
gnatmake (for creating tree files):            See 8.4.      (line 1833)
GNU Free Documentation License:                See Appendix A.
                                                             (line 2131)
Help (asistant command):                       See 5.2.      (line 1485)
Id type:                                       See 3.1.      (line  621)
License, GNU Free Documentation:               See Appendix A.
                                                             (line 2131)
Line type <1>:                                 See 3.1.      (line  611)
Line type:                                     See 2.3.      (line  410)
Log (asistant command):                        See 5.2.      (line 1518)
N-trees Context:                               See 4.3.1.    (line 1132)
One-tree Context:                              See 4.3.1.    (line 1127)
Pause (asistant command):                      See 5.2.      (line 1508)
Print (asistant command):                      See 5.2.      (line 1499)
PrintDetail (asistant command):                See 5.2.      (line 1524)
Program_Error exception:                       See 4.4.1.    (line 1244)
Quit (asistant command):                       See 5.2.      (line 1527)
Run (asistant command):                        See 5.2.      (line 1504)
Script file (for asistant) <1>:                See 5.2.      (line 1505)
Script file (for asistant):                    See 5.1.      (line 1398)
Semantic ASIS queries:                         See 3.3.      (line  694)
Set (asistant command):                        See 5.2.      (line 1489)
Span type:                                     See 3.1.      (line  616)
Spec (definition of term):                     See 2.1.      (line  224)
Storage_Error (propagated from ASIS queries):  See 3.4.      (line  750)
Structural ASIS queries:                       See 3.3.      (line  694)
Subunits and the Data Decomposition Annex:     See 4.2.1.    (line 1067)
Tasking and error information:                 See 3.4.      (line  768)
Templates (for ASIS applications):             See 6.        (line 1687)
Tools (that can use ASIS):                     See 1.2.      (line  201)
Tree file <1>:                                 See 4.4.2.    (line 1288)
Tree file <2>:                                 See 4.4.      (line 1233)
Tree file <3>:                                 See 4.2.1.    (line 1062)
Tree file <4>:                                 See 4.2.      (line  939)
Tree file <5>:                                 See 4.1.      (line  909)
Tree file <6>:                                 See 2.6.      (line  551)
Tree file:                                     See 2.5.      (line  481)
Tree swapping (ASIS performance issue) <1>:    See 8.3.      (line 1782)
Tree swapping (ASIS performance issue) <2>:    See 8.1.      (line 1722)
Tree swapping (ASIS performance issue):        See 4.2.      (line 1042)
Warnings (from ASIS-for-GNAT):                 See 11.       (line 2004)
Table of Contents
*****************

ASIS-for-GNAT User's Guide
About This Guide
  What This Guide Contains
  What You Should Know Before Reading This Guide
  Related Information
  Conventions
1 Introduction
  1.1 What Is ASIS?
  1.2 ASIS Scope - Which Kinds of Tools Can Be Built with ASIS?
2 Getting Started
  2.1 The Problem
  2.2 An ASIS Application that Solves the Problem
  2.3 Required Sequence of Calls
  2.4 Building the Executable for an ASIS application
  2.5 Preparing Data for an ASIS Application - Generating Tree Files
  2.6 Running an ASIS Application
3 ASIS Overview
  3.1 Main ASIS Abstractions
  3.2 ASIS Package Hierarchy
  3.3 Structural and Semantic Queries
  3.4 ASIS Error Handling Policy
  3.5 Dynamic Typing of ASIS Queries
  3.6 ASIS Iterator
  3.7 How to Navigate through the `Asis' Package Hierarchy
4 ASIS `Context'
  4.1 ASIS `Context' and Tree Files
  4.2 Creating Tree Files for Use by ASIS
    4.2.1 Creating Trees for Data Decomposition Annex
  4.3 Different Ways to Define an ASIS `Context' in ASIS-for-GNAT
    4.3.1 Defining a set of tree files making up a `Context'
    4.3.2 Dealing with tree files when opening a `Context' and processing ASIS queries
    4.3.3 Processing source files during the consistency check
    4.3.4 Setting search paths
  4.4 Consistency Problems
    4.4.1 Inconsistent versions of ASIS and GNAT
    4.4.2 Consistency of a set of tree and source files
  4.5 Processing Several `Context's at a Time
  4.6 Using ASIS with a cross-compiler
5 ASIS Interpreter `asistant'
  5.1 `asistant' Introduction
  5.2 `asistant' commands
  5.3 `asistant' variables
  5.4 Browsing an ASIS tree
  5.5 Example
6 ASIS Application Templates
7 ASIS Tutorials
8 How to Build Efficient ASIS Applications
  8.1 Tree Swapping as a Performance Issue
  8.2 Queries That Can Cause Tree Swapping
  8.3 How to Avoid Unnecessary Tree Swapping
  8.4 Using `gnatmake' to Create Tree Files
9 Processing an Ada Library by an ASIS-Based Tool
10 Compiling, Binding and Linking Applications with ASIS-for-GNAT
11 ASIS-for-GNAT Warnings
12 Exception Handling and Reporting Internal Bugs
13 File Naming Conventions and Application Name Space
Appendix A GNU Free Documentation License
Index


