Generated by Sphinx 1.3b2.
Table of Contents
*****************

ASIS-for-GNAT User's Guide
1 About This Guide
2 Introduction
  2.1 What Is ASIS?
  2.2 ASIS Scope -- Which Kinds of Tools Can Be Built with ASIS?
3 Getting Started
  3.1 The Problem
  3.2 An ASIS Application that Solves the Problem
  3.3 Required Sequence of Calls
  3.4 Building the Executable for an ASIS application
  3.5 Preparing Data for an ASIS Application -- Generating Tree Files
  3.6 Running an ASIS Application
4 ASIS Overview
  4.1 Main ASIS Abstractions
  4.2 ASIS Package Hierarchy
  4.3 Structural and Semantic Queries
  4.4 ASIS Error Handling Policy
  4.5 Dynamic Typing of ASIS Queries
  4.6 ASIS Iterator
  4.7 How to Navigate through the `Asis' Package Hierarchy
5 ASIS `Context'
  5.1 ASIS `Context' and Tree Files
  5.2 Creating Tree Files for Use by ASIS
    5.2.1 Creating Trees for Data Decomposition Annex
  5.3 Different Ways to Define an ASIS `Context' in ASIS-for-GNAT
    5.3.1 Defining a set of tree files making up a `Context'
    5.3.2 Dealing with tree files when opening a `Context' and processing ASIS queries
    5.3.3 Processing source files during the consistency check
    5.3.4 Setting search paths
  5.4 Consistency Problems
    5.4.1 Inconsistent versions of ASIS and GNAT
    5.4.2 Consistency of a set of tree and source files
  5.5 Processing Several `Context's at a Time
  5.6 Using ASIS with a cross-compiler
6 ASIS Interpreter `asistant'
  6.1 `asistant' Introduction
  6.2 `asistant' commands
  6.3 `asistant' variables
  6.4 Browsing an ASIS tree
  6.5 Example
7 ASIS Application Templates
8 ASIS Tutorials
9 How to Build Efficient ASIS Applications
  9.1 Tree Swapping as a Performance Issue
  9.2 Queries That Can Cause Tree Swapping
  9.3 How to Avoid Unnecessary Tree Swapping
  9.4 Using `gnatmake' to Create Tree Files
10 Processing an Ada Library by an ASIS-Based Tool
11 Compiling, Binding, and Linking Applications with ASIS-for-GNAT
12 ASIS-for-GNAT Warnings
13 Exception Handling and Reporting Internal Bugs
14 File Naming Conventions and Application Name Space
15 GNU Free Documentation License
Index


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

     ASIS-for-GNAT User's Guide 2018, May 25, 2018

     AdaCore

     Copyright (C) 2008-2018, AdaCore

    `GNAT, The GNU Ada Development Environment' 
    The GNAT Ada Compiler 
    Version 2018 

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'.

1 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 Ada compiler.

`What This Guide Contains'

This guide contains the following chapters:

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

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

   * *note ASIS Overview: 7, 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: 8, 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: 9, 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: a, describes some examples included in the
     ASIS-for-GNAT distribution.

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

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

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

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

   * *note Exception Handling and Reporting Internal Bugs: f, 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: 10,
     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 language, as
described in the International Standard ANSI/ISO/IEC-8652:2012(E)
(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
character '$' (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.

2 Introduction
**************

2.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.

2.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.

3 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.

3.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, 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).

3.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;

3.3 Required Sequence of Calls
==============================

An ASIS application must use the following sequence of calls:

   * `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.

   * `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.

   * `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.

   * 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.

   * `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.

   * `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.

   * `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.

3.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.  As for other components of the GNAT
technology, the structure of the ASIS distribution and the ASIS
building and installation process is based on project files. So, the
same should be the case for ASIS application.

For your ASIS application you should create a project file that depends
on the main ASIS project file `asis.gpr'. Here is the simplest version
of such a project file:

    with "asis";
    project Example1 is
       for Main use ("example1.adb");
    end Example1;

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

    $ gprbuild example1.gpr

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: d.

3.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: 19. 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: 8, and *note ASIS Tutorials: a.

3.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: 8, 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.

4 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: a.

4.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.

4.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.

4.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'.

4.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.

4.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.

4.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: a.

4.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: 22, 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.

5 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.

5.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'.

5.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: 2c, 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: 2d. 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: b, 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.

5.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.

5.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.

5.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.

5.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.

5.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: 2c,
concerning consistency issues in ASIS-for-GNAT.

5.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.

5.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.

5.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.  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.

5.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).

5.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.

5.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.

6 ASIS Interpreter `asistant'
*****************************

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

6.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 (unless you have installed ASIS from
the binary distribution, in which case the executable for `asistant'
has been added to other GNAT executables).  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:

    > ...

6.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'.

6.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.

6.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.

6.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

7 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.

8 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.

9 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.

9.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'.

9.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.

9.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.

9.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.

10 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.

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

The recommended way of building ASIS applications is to define for an
application a project file that depends on the main ASIS project file
`asis.gpr'. All you have to do is to add a with clause

    with "asis";

to the application project file. After that you can build an executable
for an application using `gprbuild' in the usual way.

12 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.

13 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.

14 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.

15 GNU Free Documentation License
*********************************

Version 1.3, 3 November 2008

Copyright  2000, 2001, 2002, 2007, 2008  Free Software Foundation, Inc
<http://fsf.org/>

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

`Preamble'

The purpose of this License is to make a manual, textbook, or other
functional and useful 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, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License.  Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein.  The `Document', below, refers
to any such manual or work.  Any member of the public is a licensee,
and is addressed as "`you'".  You accept the license if you copy,
modify or distribute the work in a way requiring permission under
copyright law.

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.  (Thus, 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.  If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant.  The Document may contain zero
Invariant Sections.  If the Document does not identify any Invariant
Sections then there are none.

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 Front-Cover Text may be
at most 5 words, and a Back-Cover Text may be at most 25 words.

A "`Transparent'" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the general
public, that is suitable for revising the document 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, or absence of markup, has been arranged to thwart or discourage
subsequent modification by readers is not Transparent.  An image format
is not Transparent if used for any substantial amount of text.  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,
PostScript or PDF designed for human modification.  Examples of
transparent image formats include PNG, XCF and JPG.  Opaque formats
include 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, PostScript or PDF 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.

The "`publisher'" means any person or entity that distributes copies of
the Document to the public.

A section "`Entitled XYZ'" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language.  (Here XYZ stands for a
specific section name mentioned below, such as "`Acknowledgements'",
"`Dedications'", "`Endorsements'", or "`History'".)  To "`Preserve the
Title'" of such a section when you modify the Document means that it
remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document.  These Warranty
Disclaimers are considered to be included by reference in this License,
but only as regards disclaiming warranties: any other implication that
these Warranty Disclaimers may have is void and has no effect on the
meaning of this License.

`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 (or copies in media that commonly have
printed covers) 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 computer-network location from which the general network-using public
has access to download using public-standard network protocols a
complete Transparent copy of the Document, free of added material.  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 fewer than
     five), unless they release you from this requirement.

  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", Preserve 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. For any section Entitled "Acknowledgements" or "Dedications",
     Preserve the Title of the section, 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 to be Entitled "Endorsements"
     or to conflict in title with any Invariant Section.

  O. Preserve any Warranty Disclaimers.

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, and that you preserve all their Warranty Disclaimers.

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".

`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, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights of
the compilation's users beyond what the individual works permit.  When
the Document is included in an aggregate, this License does not apply
to the other works in the aggregate which 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 half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket 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, and
all the license notices in the Document, and any Warranty Disclaimers,
provided that you also include the original English version of this
License and the original versions of those notices and disclaimers.  In
case of a disagreement between the translation and the original version
of this License or a notice or disclaimer, the original version will
prevail.

If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual title.

`9. TERMINATION'

You may not copy, modify, sublicense, or distribute the Document except
as expressly provided under this License.  Any attempt otherwise to
copy, modify, sublicense, or distribute it is void, and will
automatically terminate your rights under this License.

However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally terminates
your license, and (b) permanently, if the copyright holder fails to
notify you of the violation by some reasonable means prior to 60 days
after the cessation.

Moreover, your license from a particular copyright holder is reinstated
permanently if the copyright holder notifies you of the violation by
some reasonable means, this is the first time you have received notice
of violation of this License (for any work) from that copyright holder,
and you cure the violation prior to 30 days after your receipt of the
notice.

Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License.  If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.

`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.  If the Document specifies
that a proxy can decide which future versions of this License can be
used, that proxy's public statement of acceptance of a version
permanently authorizes you to choose that version for the Document.

`11. RELICENSING'

"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works.  A
public wiki that anybody can edit is an example of such a server.  A
"Massive Multiauthor Collaboration" (or "MMC") contained in the site
means any set of copyrightable works thus published on the MMC site.

"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.

"Incorporate" means to publish or republish a Document, in whole or in
part, as part of another Document.

An MMC is "eligible for relicensing" if it is licensed under this
License, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole
or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.

The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.

`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 © 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.3 or any later version
     published by the Free Software Foundation; with no Invariant
     Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy
     of the license is included in the section entitled "GNU Free
     Documentation License".

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the "with ... Texts." line with this:

     with the Invariant Sections being LIST THEIR TITLES, with the
     Front-Cover Texts being LIST, and with the Back-Cover Texts being
     LIST.

If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

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 5.6.      (line 1400)
-gnatc option:                                 See 5.2.      (line 1002)
-gnatct option <1>:                            See 9.4.      (line 1886)
-gnatct option <2>:                            See 5.2.      (line  997)
-gnatct option:                                See 3.5.      (line  520)
-gnatt option <1>:                             See 5.2.      (line 1002)
-gnatt option:                                 See 5.1.      (line  960)
-lasis option:                                 See 11.       (line 2018)
;file;adt extension for tree files:            See 5.1.      (line  983)
A4G package:                                   See 14.       (line 2095)
Ada predefined library (processing by an ASIS tool):See 10.  (line 1938)
Ada_Environments.Close procedure:              See 3.3.      (line  433)
All trees Context:                             See 5.3.1.    (line 1194)
ASIS application templates:                    See 7.        (line 1741)
ASIS Example <1>:                              See 6.5.      (line 1676)
ASIS Example:                                  See 3.2.      (line  273)
ASIS Iterator:                                 See 4.6.      (line  873)
ASIS overview:                                 See 4.        (line  597)
Asis package <1>:                              See 14.       (line 2079)
Asis package <2>:                              See 4.2.      (line  678)
Asis package:                                  See 2.1.      (line  213)
ASIS package hierarchy:                        See 4.2.      (line  673)
ASIS Performance:                              See 9.        (line 1770)
ASIS queries <1>:                              See 6.        (line 1421)
ASIS queries <2>:                              See 5.        (line  948)
ASIS queries <3>:                              See 4.3.      (line  746)
ASIS queries <4>:                              See 4.2.      (line  696)
ASIS queries <5>:                              See 4.1.      (line  619)
ASIS queries <6>:                              See 2.2.      (line  233)
ASIS queries:                                  See 2.1.      (line  213)
ASIS queries (dynamic typing):                 See 4.5.      (line  823)
ASIS Tutorials:                                See 8.        (line 1756)
ASIS-for-GNAT <1>:                             See 11.       (line 2009)
ASIS-for-GNAT <2>:                             See 6.1.      (line 1454)
ASIS-for-GNAT <3>:                             See 5.4.      (line 1287)
ASIS-for-GNAT <4>:                             See 5.3.      (line 1140)
ASIS-for-GNAT <5>:                             See 5.2.      (line 1016)
ASIS-for-GNAT <6>:                             See 5.1.      (line  960)
ASIS-for-GNAT <7>:                             See 3.4.      (line  477)
ASIS-for-GNAT:                                 See 3.3.      (line  459)
Asis.Ada_Environments package:                 See 4.2.      (line  696)
Asis.Ada_Environments.Associate query:         See 5.3.      (line 1140)
Asis.Ada_Environments.Associate query (example):See 3.2.     (line  273)
Asis.Ada_Environments.Close procedure (example):See 3.2.     (line  273)
Asis.Ada_Environments.Containers package:      See 4.1.      (line  644)
Asis.Ada_Environments.Dissociate procedure:    See 3.3.      (line  449)
Asis.Ada_Environments.Dissociate procedure (example):See 3.2.
                                                             (line  273)
Asis.Ada_Environments.Open procedure:          See 3.3.      (line  414)
Asis.Ada_Environments.Open procedure (example):See 3.2.      (line  273)
Asis.Ada_Environments.Open query:              See 5.4.2.    (line 1344)
ASIS.Clauses package:                          See 4.2.      (line  723)
Asis.Compilation_Units package <1>:            See 4.5.      (line  832)
Asis.Compilation_Units package:                See 4.2.      (line  701)
Asis.Compilation_Units.Corresponding_Body function:See 10.   (line 1988)
Asis.Compilation_Units.Is_Body_Required function:See 10.     (line 1988)
Asis.Compilation_Units.Relations package:      See 4.2.      (line  707)
Asis.Compilation_Units.Unit_Full_Name query (example):See 3.2.
                                                             (line  273)
Asis.Compilation_Units.Unit_Kind query (example):See 3.2.    (line  273)
Asis.Compilation_units.Unit_Origin:            See 10.       (line 2003)
Asis.Compilation_Units.Unit_Origin query:      See 10.       (line 1964)
Asis.Compilation_Units.Unit_Origin query (example):See 3.2.  (line  273)
Asis.Declarations package:                     See 4.2.      (line  723)
Asis.Definitions package:                      See 4.2.      (line  723)
Asis.Elements package <1>:                     See 4.5.      (line  823)
Asis.Elements package:                         See 4.2.      (line  713)
Asis.Elements.Enclosing_Element query:         See 4.3.      (line  746)
Asis.Elements.Statement_Kind query:            See 4.5.      (line  862)
Asis.Errors package:                           See 4.2.      (line  741)
Asis.Errors.Error_Kinds type:                  See 4.4.      (line  802)
Asis.Errors.Value_Error error status:          See 4.5.      (line  841)
Asis.Exceptions package <1>:                   See 4.4.      (line  802)
Asis.Exceptions package:                       See 4.2.      (line  737)
Asis.Exceptions.ASIS_Failed exception (example):See 3.2.     (line  273)
Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit exception:See 4.5.
                                                             (line  853)
Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit exception (example):See 3.2.
                                                             (line  273)
Asis.Exceptions.ASIS_Inappropriate_Context exception (example):See 3.2.
                                                             (line  273)
Asis.Exceptions.ASIS_Inappropriate_Element exception:See 4.5.
                                                             (line  841)
Asis.Expressions package:                      See 4.2.      (line  723)
Asis.Extensions package <1>:                   See 14.       (line 2079)
Asis.Extensions package:                       See 10.       (line 1964)
Asis.Ids package:                              See 4.1.      (line  663)
Asis.Implementation package:                   See 4.2.      (line  693)
Asis.Implementation.Associate procedure:       See 3.3.      (line  402)
Asis.Implementation.Diagnosis query:           See 4.4.      (line  802)
Asis.Implementation.Finalize procedure:        See 3.3.      (line  455)
Asis.Implementation.Finalize procedure (example):See 3.2.    (line  273)
Asis.Implementation.Initialize procedure <1>:  See 12.       (line 2053)
Asis.Implementation.Initialize procedure <2>:  See 9.3.      (line 1878)
Asis.Implementation.Initialize procedure:      See 3.3.      (line  396)
Asis.Implementation.Initialize procedure (example):See 3.2.  (line  273)
Asis.Implementation.Permissions package:       See 4.2.      (line  693)
Asis.Implementation.Set_Status procedure:      See 4.4.      (line  802)
Asis.Implementation.Status function (example): See 3.2.      (line  273)
Asis.Implementation.Status query:              See 4.4.      (line  802)
Asis.Iterator.Traverse_Element generic procedure <1>:See 9.2.
                                                             (line 1827)
Asis.Iterator.Traverse_Element generic procedure:See 4.6.    (line  873)
Asis.Set_Get package:                          See 14.       (line 2079)
Asis.Statements package:                       See 4.2.      (line  723)
Asis.Text package <1>:                         See 4.2.      (line  732)
Asis.Text package:                             See 4.1.      (line  651)
Asis.Text.Set_Get package:                     See 14.       (line 2079)
Asis_Failed exception <1>:                     See 12.       (line 2040)
Asis_Failed exception <2>:                     See 5.4.2.    (line 1368)
Asis_Failed exception:                         See 5.3.1.    (line 1202)
asistant:                                      See 6.        (line 1421)
asistant commands:                             See 6.2.      (line 1523)
asistant variables:                            See 6.3.      (line 1586)
AST (Abstract Syntax Tree) <1>:                See 5.2.      (line 1002)
AST (Abstract Syntax Tree):                    See 5.1.      (line  960)
Browse (asistant command):                     See 6.2.      (line 1566)
Browser (asistant utility):                    See 6.4.      (line 1599)
Compilation_Unit type <1>:                     See 4.5.      (line  823)
Compilation_Unit type <2>:                     See 4.2.      (line  678)
Compilation_Unit type <3>:                     See 4.1.      (line  622)
Compilation_Unit type:                         See 3.3.      (line  404)
Compilation_Unit type (example):               See 3.2.      (line  273)
Consistency problems:                          See 5.4.      (line 1283)
Container type:                                See 4.1.      (line  644)
Context type <1>:                              See 5.3.      (line 1140)
Context type <2>:                              See 5.        (line  948)
Context type <3>:                              See 4.2.      (line  678)
Context type <4>:                              See 4.1.      (line  613)
Context type <5>:                              See 3.6.      (line  537)
Context type:                                  See 3.3.      (line  404)
Context type (example):                        See 3.2.      (line  273)
Data Decomposition Annex (DDA):                See 5.2.1.    (line 1113)
Diagnosis string <1>:                          See 12.       (line 2040)
Diagnosis string:                              See 4.4.      (line  802)
Element type <1>:                              See 4.5.      (line  823)
Element type <2>:                              See 4.2.      (line  678)
Element type <3>:                              See 4.1.      (line  633)
Element type:                                  See 3.3.      (line  419)
Enclosing_Element query <1>:                   See 6.4.      (line 1629)
Enclosing_Element query:                       See 4.3.      (line  746)
Erroneous execution <1>:                       See 5.2.      (line 1106)
Erroneous execution:                           See 3.3.      (line  396)
Error Handling:                                See 4.4.      (line  802)
gnatmake (for creating tree files):            See 9.4.      (line 1886)
Help (asistant command):                       See 6.2.      (line 1530)
Id type:                                       See 4.1.      (line  663)
Line type <1>:                                 See 4.1.      (line  651)
Line type:                                     See 3.3.      (line  433)
Log (asistant command):                        See 6.2.      (line 1570)
N-trees Context:                               See 5.3.1.    (line 1187)
One-tree Context:                              See 5.3.1.    (line 1181)
Pause (asistant command):                      See 6.2.      (line 1558)
Print (asistant command):                      See 6.2.      (line 1546)
PrintDetail (asistant command):                See 6.2.      (line 1577)
Program_Error exception:                       See 5.4.1.    (line 1298)
Quit (asistant command):                       See 6.2.      (line 1581)
Run (asistant command):                        See 6.2.      (line 1552)
Script file (for asistant) <1>:                See 6.2.      (line 1555)
Script file (for asistant):                    See 6.1.      (line 1445)
Semantic ASIS queries:                         See 4.3.      (line  746)
Set (asistant command):                        See 6.2.      (line 1535)
Span type:                                     See 4.1.      (line  657)
Spec (definition of term):                     See 3.1.      (line  264)
Storage_Error (propagated from ASIS queries):  See 4.4.      (line  802)
Structural ASIS queries:                       See 4.3.      (line  746)
Subunits and the Data Decomposition Annex:     See 5.2.1.    (line 1113)
Tasking and error information:                 See 4.4.      (line  814)
Templates (for ASIS applications):             See 7.        (line 1741)
Tools (that can use ASIS):                     See 2.2.      (line  243)
Tree file <1>:                                 See 5.4.2.    (line 1336)
Tree file <2>:                                 See 5.4.      (line 1287)
Tree file <3>:                                 See 5.2.1.    (line 1113)
Tree file <4>:                                 See 5.2.      (line  990)
Tree file <5>:                                 See 5.1.      (line  960)
Tree file <6>:                                 See 3.6.      (line  585)
Tree file:                                     See 3.5.      (line  514)
Tree swapping (ASIS performance issue) <1>:    See 9.3.      (line 1836)
Tree swapping (ASIS performance issue) <2>:    See 9.1.      (line 1776)
Tree swapping (ASIS performance issue):        See 5.2.      (line 1096)
Warnings (from ASIS-for-GNAT):                 See 12.       (line 2021)


Local Variables:
coding: utf-8
End:
