\input texinfo   @c -*-texinfo-*-
@input texiplus

@c %**start of header

@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c                                                                            o
@c                        ASIS-for-GNAT DOCUMENTATION                         o
@c                                                                            o
@c                              A S I S _ U G                                 o
@c                                                                            o
@c                            1.22
@c                                                                            o
@c          Copyright (C) 2000-2004 Ada Core Technologies, Inc.               o
@c                                                                            o
@c ASIS-for-GNAT is free software; you can redistribute it and/or modify it   o
@c under terms of the  GNU General Public License  as published by the Free   o
@c Software Foundation;  either version 2,  or  (at your option)  any later   o
@c version. ASIS-for-GNAT is distributed  in the hope  that it will be use-   o
@c ful, but WITHOUT ANY WARRANTY; without even the implied warranty of MER-   o
@c CHANTABILITY or  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General    o
@c Public License for more details. You should have received a copy of the    o
@c GNU General Public License  distributed with ASIS-for-GNAT; see file       o
@c COPYING. If not, write to the Free Software Foundation,  59 Temple Place   o
@c Suite 330, Boston, MA 02111-1307, USA.                                     o
@c                                                                            o
@c ASIS-for-GNAT was originally developed  by the ASIS-for-GNAT team at the   o
@c Software  Engineering  Laboratory  of  the Swiss  Federal  Institute  of   o
@c Technology (LGL-EPFL) in Lausanne,  Switzerland, in cooperation with the   o
@c Scientific  Research  Computer  Center of  Moscow State University (SRCC   o
@c MSU), Russia,  with funding partially provided  by grants from the Swiss   o
@c National  Science  Foundation  and  the  Swiss  Academy  of  Engineering   o
@c Sciences.                                                                  o
@c                                                                            o
@c ASIS-for-GNAT is now maintained by  Ada Core Technologies Inc              o
@c (http://www.gnat.com).                                                     o
@c                                                                            o
@c  GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com).    o
@c                                                                            o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo

@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c
@c                           ASIS_UG Style Guide
@c
@c  1. Always put a @noindent on the line before the first paragraph
@c     after any of these commands:
@c
@c          @chapter
@c          @section
@c          @subsection
@c          @subsubsection
@c          @subsubsubsection
@c
@c          @end smallexample
@c          @end itemize
@c          @end enumerate
@c
@c  2. DO NOT use @example. Use @smallexample instead.
@c
@c  3. Each @chapter, @section, @subsection, @subsubsection, etc.
@c     command must be preceded by two empty lines
@c
@c  4. The @item command must be on a line of its own if it is in an
@c     @itemize or @enumerate command.
@c
@c  5. When talking about ALI files use "ALI" (all uppercase), not "Ali"
@c     or "ali".
@c
@c  6. DO NOT put trailing spaces at the end of a line.  Such spaces will
@c     cause the document build to fail.
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo

@setfilename asis_ug.info
@include version.texi

@settitle ASIS-for-GNAT User's Guide
@setchapternewpage odd
@syncodeindex fn cp
@c %**end of header

@titlepage

@title ASIS-for-GNAT User's Guide
@sp 2
@subtitle Document revision level 1.22
@subtitle Date: 2004/04/13 08:37:18
@sp 1
@subtitle GNAT @value{gnat_version}

@author Ada Core Technologies, Inc.

@page
@vskip 0pt plus 1filll

Copyright @copyright{} 2000-2002, Ada Core Technologies

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@end titlepage


@ifinfo
@node Top, About This Guide, (dir), (dir)
@top ASIS-for-GNAT User's Guide

@noindent
ASIS-for-GNAT User's Guide

@noindent
Document revision level 1.22
@*
Date: 2004/04/13 08:37:18
@*
GNAT @value{gnat_version}

@noindent
Copyright @copyright{} 2000-2002, Ada Core Technologies

@noindent
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.


@menu
* About This Guide::
* Introduction::
* Getting Started::
* ASIS Overview::
* ASIS Context::
* ASIS Interpreter asistant::
* ASIS Application Templates::
* ASIS Tutorials::
* How to Build Efficient ASIS Applications::
* Processing an Ada Library by an ASIS-Based Tool::
* Compiling Binding and Linking Applications with ASIS-for-GNAT::
* ASIS-for-GNAT Warnings::
* Exception Handling and Reporting Internal Bugs::
* File Naming Conventions and Application Name Space::
* Index::
@detailmenu
 --- The Detailed Node Listing ---

About This Guide

* What This Guide Contains::
* What You Should Know Before Reading This Guide::
* Related Information::
* Conventions::

Introduction

* What Is ASIS?::
* ASIS Scope - Which Kinds of Tools Can Be Built with ASIS?::

Getting Started

* The Problem::
* An ASIS Application that Solves the Problem::
* Required Sequence of Calls::
* Building the Executable for an ASIS application::
* Preparing Data for an ASIS Application - Generating Tree Files::
* Running an ASIS Application::

ASIS Overview

* Main ASIS Abstractions::
* ASIS Package Hierarchy::
* Structural and Semantic Queries::
* ASIS Error Handling Policy::
* Dynamic Typing of ASIS Queries::
* ASIS Iterator::
* How to Navigate through the Asis Package Hierarchy::

ASIS Context

* ASIS Context and Tree Files::
* Creating Tree Files for Use by ASIS::
*   Creating Trees for Data Decomposition Annex::
* Different Ways to Define an ASIS Context in ASIS-for-GNAT::
* Consistency Problems::
*   Inconsistent versions of ASIS and GNAT::
*   Consistency of a set of tree and source files::
* Processing Several Contexts at a Time::
* Using ASIS with a cross-compiler::

ASIS Interpreter asistant

* asistant introduction::
* asistant commands::
* asistant variables::
* Browsing an ASIS tree::
* Example::

ASIS Application Templates

ASIS Tutorials

How to Build Efficient ASIS Applications

* Tree Swapping as a Performance Issue::
* Queries That Can Cause Tree Swapping::
* How to Avoid Unnecessary Tree Swapping::
* Using gnatmake to Create Tree Files::

Processing an Ada Library by an ASIS-Based Tool

Compiling Building and Linking Applications with ASIS-for-GNAT

ASIS-for-GNAT Warnings

Exception Handling and Reporting Internal Bugs

File Naming Conventions and Application Name Space

Index
@end detailmenu
@end menu
@end ifinfo


@node About This Guide
@unnumbered About This Guide

@noindent
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 95 compiler.

@menu
* What This Guide Contains::
* What You Should Know Before Reading This Guide::
* Related Information::
* Conventions::
@end menu

@c ***************************
@node What This Guide Contains
@c ***************************
@unnumberedsec What This Guide Contains

@noindent
This guide contains the following chapters:
@itemize @bullet

@item
@ref{Introduction}, contains the general definition of ASIS and gives some
 examples of tools which can be built on top of ASIS.

@item
@ref{Getting Started}, contains a short guided tour through the
 development and use of ASIS-for-GNAT-based tools.

@item
@ref{ASIS Overview}, gives an overview of ASIS, allowing
an ASIS newcomer to navigate through the ASIS definition
(readers already familiar with ASIS can skip this section).

@item
@ref{ASIS Context}, defines the ASIS @code{Context} concept in
 ASIS-for-GNAT and explains how to prepare a set of Ada
 components to be processed by an ASIS application.

@item
@ref{ASIS Application Templates}, describes a set of Ada source components
 provided by the ASIS-for-GNAT distribution that may be used as a basis for
 developing ASIS applications.

@item
@ref{ASIS Tutorials}, describes some examples included in
 the ASIS-for-GNAT distribution.

@item
@ref{How to Build Efficient ASIS Applications}, describes how to
deal with ``tree swapping'', a potential performance issue with ASIS
applications.

@item
@ref{Processing an Ada Library by an ASIS-Based Tool}, shows how to use an
ASIS tool on pre-compiled Ada libraries.

@item
@ref{Compiling Binding and Linking Applications with ASIS-for-GNAT}, explains
 how to compile an ASIS application with ASIS-for-GNAT and how to create
 the resulting executable.

@item
@ref{ASIS-for-GNAT Warnings}, describes the warnings generated by
 the ASIS implementation.

@item
@ref{Exception Handling and Reporting Internal Bugs}, explains
 what happens if an ASIS implementation internal problem is detected during
 the processing of an ASIS or ASIS Extensions query

@item
@ref{File Naming Conventions and Application Name Space}, explains
 which names can and cannot be used as names of ASIS application
 components.
@end itemize


@c *************************************************
@node What You Should Know Before Reading This Guide
@c *************************************************
@unnumberedsec What You Should Know Before Reading This Guide

@noindent
This User's Guide assumes that you are familiar with Ada 95 language, as
described in the International Standard ANSI/ISO/IEC-8652:1995 (hereafter
referred to as the @cite{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.


@c **********************
@node Related Information
@c **********************
@unnumberedsec Related Information

@noindent
The following sources contain useful supplemental information:
@itemize @bullet
@item
@cite{GNAT User's Guide}, for information about the GNAT environment

@item
@cite{ASIS-for-GNAT Installation Guide}

@item
The @cite{ASIS-for-GNAT Reference Manual}

@item
The @cite{ASIS 95 definition}, available as ISO/IEC International Standard
15291.

@item
The Web site for the ASIS Working Group:
@url{http://www.acm.org/sigada/wg/asiswg}
@end itemize


@c **************
@node Conventions
@c **************
@unnumberedsec Conventions

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

@itemize @bullet
@item
@code{Functions}, @code{utility program names}, @code{standard names},
and @code{classes}.

@item
@samp{Option flags}

@item
@file{File Names}, @file{button names}, and @file{field names}.

@item
@var{Variables}.

@item
@emph{Emphasis}.

@item
[optional information or parameters]

@item
Examples are described by text
@smallexample
and then shown this way.
@end smallexample
@end itemize

@noindent
Commands that are entered by the user are preceded in this manual by the
characters @w{``@code{$ }''} (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 @code{$} replaced by whatever prompt
character you are using.

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



@c ***************
@node Introduction
@c ***************
@chapter Introduction

@menu
* What Is ASIS?::
* ASIS Scope - Which Kinds of Tools Can Be Built with ASIS?::
@end menu


@c ****************
@node What Is ASIS?
@c ****************
@section What Is ASIS?

@noindent
The @emph{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 @code{Asis}.
@cindex @code{Asis} package
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
@emph{ASIS queries}, give you statically determinable information about
@cindex ASIS queries
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.


@c **********************************************************
@node ASIS Scope - Which Kinds of Tools Can Be Built with ASIS?
@c **********************************************************
@section ASIS Scope @minus{} Which Kinds of Tools Can Be Built with ASIS?

@noindent
The following ASIS properties define the ASIS scope:

@itemize @bullet{}
@item
ASIS is a read-only interface.

@item
ASIS provides only statically-determinable information about Ada programs.

@item
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
@cindex ASIS queries
piece of information itself from the information available through ASIS
queries.

@item
ASIS provides
information from/about Ada units in high-level terms that
conform with the @cite{Ada Reference Manual} and that are
Ada/ASIS-implementation-independent in nature.
@end itemize

@noindent
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.
@cindex Tools (that can use ASIS)


@c ******************
@node Getting Started
@c ******************
@chapter Getting Started

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

@menu
* The Problem::
* An ASIS Application that Solves the Problem::
* Required Sequence of Calls::
* Building the Executable for an ASIS application::
* Preparing Data for an ASIS Application - Generating Tree Files::
* Running an ASIS Application::
@end menu


@c **************
@node The Problem
@c **************
@section The Problem

@noindent
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@footnote{
@cindex Spec (definition of term)
It may seem that an Ada unit such as
@smallexample @c ada
package Pack is
  type T is array(Positive range <>) of Float;
  procedure Proc(X : in out T);
end Pack;
@end smallexample
is a package @emph{specification}, but in fact the ``specification''
(as defined in the @cite{Ada Reference Manual}) comprises all but the final
semicolon.  The form with the final semicolon is known as a
``package declaration''.  Since this official term is not
familiar to most Ada users, the GNAT documentation uses the term
``spec'' (for a unit) to mean that unit's @emph{declaration}
@minus{} thus a package spec includes the final semicolon.
}, 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).


@c ***********************************************
@node An ASIS Application that Solves the Problem
@c ***********************************************
@section An ASIS Application that Solves the Problem
@cindex ASIS Example

@noindent
@smallexample @c ada
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;
@cindex @code{Context} type (example)
   --  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");
@cindex @code{Asis.Implementation.Initialize} procedure (example)
   --  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");
@cindex @code{Asis.Ada_Environments.Associate} query (example)
   --  "-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);
@cindex @code{Asis.Ada_Environments.Open} procedure (example)

   Processing_Units: declare
      Next_Unit : Asis.Compilation_Unit;
@cindex @code{Compilation_Unit} type (example_
      --  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));
@cindex @code{Asis.Compilation_Units.Unit_Full_Name} query (example)

         --  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
@cindex @code{Asis.Compilation_Units.Unit_Kind} query (example)
            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
@cindex @code{Asis.Compilation_Units.Unit_Origin} query (example)
            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);
@cindex @code{Asis.Ada_Environments.Close} procedure (example)
   Asis.Ada_Environments.Dissociate (My_Context);
@cindex @code{Asis.Ada_Environments.Dissociate} procedure (example)
   Asis.Implementation.Finalize;
@cindex @code{Asis.Implementation.Finalize} procedure (example)

exception
   when Asis.Exceptions.ASIS_Inappropriate_Context |
@cindex @code{Asis.Exceptions.ASIS_Inappropriate_Context} exception (example)
        Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit |
@cindex @code{Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit} exception (example)
        Asis.Exceptions.ASIS_Failed =>
@cindex @code{Asis.Exceptions.ASIS_Failed} exception (example)

      --  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));
@cindex @code{Asis.Implementation.Status} function (example)
end Example1;
@end smallexample


@c *****************************
@node Required Sequence of Calls
@c *****************************
@section Required Sequence of Calls

@noindent
An ASIS application must use the following sequence of calls:

@enumerate
@item
@code{Asis.Implementation.Initialize (...);}
@cindex @code{Asis.Implementation.Initialize} procedure

This initializes the ASIS implementation's internal data structures.
In general, calling an ASIS
query is erroneous unless the @code{Initialize} procedure has been invoked.
@cindex Erroneous execution

@item
@code{Asis.Ada_Environments.Associate (...);}
@cindex @code{Asis.Implementation.Associate} procedure

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

@item
@code{Asis.Ada_Environments.Open (...);}
@cindex @code{Asis.Ada_Environments.Open} procedure

Opening an ASIS @code{Context} variable makes the corresponding @code{Context}
accessible to all ASIS queries.

 After opening the @code{Context}, an ASIS application can start obtaining
 ASIS @code{Compilation_Unit}s from it, can further analyze @code{Compilation_Unit}s
 by decomposing them into ASIS @code{Element}s, etc.
@cindex @code{Compilation_Unit} type
@cindex @code{Element} type

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

@item
Now all the ASIS queries can be used. It is possible to access @code{Compilation_Unit}s
from the @code{Context}, to decompose units into syntactic @code{Element}s,
@cindex @code{Compilation_Unit} type
@cindex @code{Element} type
to query syntactic and semantic properties of these
@code{Element}s and so on.

@item
@code{Asis.Ada_Environments.Close (...);}
@cindex @code{Ada_Environments.Close} procedure

After closing the @code{Context} it is impossible to retrieve any information
from it. All the values of the ASIS objects of @code{Compilation_Unit},
@cindex @code{Context} type
@cindex @code{Compilation_Unit} type
@code{Element}
@cindex @code{Element} type
and @code{Line}
@cindex @code{Line} type
types obtained when this @code{Context} was open become
obsolete, and it is erroneous
@cindex Erroneous execution
to use them after the @code{Context} was closed.
 The content of this @code{Context} need not be frozen while
 the @code{Context} remains closed. Note that a closed @code{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 @code{Compilation_Unit}s) of the @code{Context} may be
 different from what was in the @code{Context} before, because the ``external
 world'' may have changed while the @code{Context} remained closed.

@item
@code{Asis.Ada_Environments.Dissociate (...);}
@cindex @code{Asis.Ada_Environments.Dissociate} procedure

This query breaks the association between the corresponding ASIS
@code{Context} and the ``external world'', and the corresponding @code{Context}
variable becomes undefined.

@item
@code{Asis.Implementation.Finalize (...);}
@cindex @code{Asis.Implementation.Finalize} procedure

This releases all the resources used by an ASIS implementation.
@end enumerate

@noindent
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 @code{Context} several times while an ASIS implementation remains
initialized, and it may open and close the same @code{Context} several times while
the @code{Context} keeps its association with the ``external world''.
@cindex @code{Context} type

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


@c **************************************************
@node Building the Executable for an ASIS application
@c **************************************************
@section Building the Executable for an ASIS application

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

To get the executable for the ASIS application from
@ref{An ASIS Application that Solves the Problem} (assuming
that it is located in your current directory as the Ada source file named
@file{example1.adb}), invoke @command{gnatmake} as follows@footnote{
The @file{.adb} is optional}:

@smallexample
$ gnatmake example1.adb -largs -lasis
@end smallexample

@noindent
For more details concerning compiling ASIS applications and building
executables for them with ASIS-for-GNAT see
@ref{Compiling Binding and Linking Applications with ASIS-for-GNAT}.


@c *****************************************************************
@node Preparing Data for an ASIS Application - Generating Tree Files
@c *****************************************************************
@section Preparing Data for an ASIS Application @minus{} Generating Tree Files

@noindent
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 @emph{tree output files} (or, in short, @emph{tree files})
to capture
@cindex Tree file
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 @option{-gnatc} and @option{-gnatt} compiler options.
@cindex @option{-gnatc} option
@cindex @option{-gnatt} option
If you want to apply
the program described in section
@ref{An ASIS Application that Solves the Problem} to itself,
compile the source of this application with the command:

@smallexample
$ gcc -c -gnatc -gnatt example1.adb
@end smallexample

@noindent
and as a result, GNAT will generate the tree file named @file{example1.adt} in the current
directory.

For more information on how to generate and deal with tree files, see
@ref{ASIS Context}, and @ref{ASIS Tutorials}.


@c ******************************
@node Running an ASIS Application
@c ******************************
@section Running an ASIS Application

@noindent
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 @file{example1}
(@file{example1.exe} on a Windows platform)
and the tree file @file{example1.adt}.
If we run
our application, it will process an ASIS @code{Context} defined by one tree file
@file{example1.adt} (for more details about defining an ASIS @code{Context} see
@ref{ASIS Context}, and the @cite{ASIS-for-GNAT Reference Manual}).
@cindex @code{Context} type
The result will be:

@smallexample
   A @code{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
@end smallexample

@noindent
Note that the tree file
@cindex Tree file
contains the full syntactic and semantic information not only
about the unit compiled by the given call to @command{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.


@c ****************
@node ASIS Overview
@c ****************
@chapter ASIS Overview

@noindent
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.
@cindex ASIS overview

For more details, please refer to the ASIS definition itself. To gain some initial
experience with ASIS, try the examples in @ref{ASIS Tutorials}.

@menu
* Main ASIS Abstractions::
* ASIS Package Hierarchy::
* Structural and Semantic Queries::
* ASIS Error Handling Policy::
* Dynamic Typing of ASIS Queries::
* ASIS Iterator::
* How to Navigate through the Asis Package Hierarchy::
@end menu


@c *************************
@node Main ASIS Abstractions
@c *************************
@section Main ASIS Abstractions

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

@table @code
@item Context
@cindex @code{Context} type
An ASIS @code{Context} is a logical handle to an Ada environment, as defined in the
@cite{Ada Reference Manual},
Chapter 10. An ASIS application developer may view an ASIS @code{Context} as a way
to define a set of compilation units available through the ASIS queries.
@cindex ASIS queries

@item Compilation_Unit
@cindex @code{Compilation_Unit} type
An ASIS @code{Compilation_Unit} is a logical handle to an Ada compilation unit. It
reflects practically all the properties of compilation units
defined by the @cite{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 @code{Compilation_Unit} provides the ``black-box'' view of a
compilation unit, considering the unit as a whole. It may be decomposed
into ASIS @code{Element}s
@cindex @code{Element} type
and then analyzed in ``white-box'' fashion.

@item Element
@cindex @code{Element} type
An ASIS @code{Element} is a logical handle to a syntactic component of an ASIS
@code{Compilation_Unit} (either explicit or implicit).
@end table

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

@table @code
@item Container
@cindex @code{Container} type
An ASIS @code{Container} (defined by the
@code{Asis.Ada_Environments.Containers} package)
@cindex @code{Asis.Ada_Environments.Containers} package
provides a means for
structuring the content of an ASIS @code{Context}; i.e., ASIS @code{Compilation_Unit}s
are grouped into @code{Container}s.

@item Line
@cindex @code{Line} type
An ASIS @code{Line} (defined by the @code{Asis.Text} package)
@cindex @code{Asis.Text} package
is the
abstraction of a line of code in an Ada source text. An ASIS @code{Line} has a length, a
string image and a number.

@item Span
@cindex @code{Span} type
An ASIS @code{Span} (defined by the @code{Asis.Text} package)
@cindex @code{Asis.Text} package
defines the
location of an @code{Element}, a @code{Compilation_Unit}, or a whole compilation in the
corresponding source text.

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


@c *************************
@node ASIS Package Hierarchy
@c *************************
@section ASIS Package Hierarchy
@cindex ASIS package hierarchy

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

@table @asis
@item @code{Asis}
@cindex @code{Asis} package
The root package of the hierarchy. It defines the main ASIS
 abstractions @minus{} @code{Context},
@cindex @code{Context} type
@code{Compilation_Unit}
@cindex @code{Compilation_Unit} type
and @code{Element}
@cindex @code{Element} type
@minus{} as Ada private types. It also contains a set of enumeration types that define
 the classification hierarchy for ASIS @code{Element}s (which closely reflects the
 Ada syntax defined in the @cite{Ada Reference Manual}) and the classification of
 ASIS @code{Compilation_Unit}s.
 This package does not contain any queries.

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

@item @code{Asis.Ada_Environments}
@cindex @code{Asis.Ada_Environments} package
Contains queries
@cindex ASIS queries
that deal with an ASIS @code{Context}: associating and dissociating,
 opening and closing a @code{Context}.
@cindex @code{Context} type

@item @code{Asis.Compilation_Units}
@cindex @code{Asis.Compilation_Units} package
Contains queries
@cindex ASIS queries
that work with ASIS @code{Compilation_Unit}s: obtaining units from a
 @code{Context}, getting semantic dependencies between units and ``black-box'' unit
 properties.

@item @code{Asis.Compilation_Units.Relations}
@cindex @code{Asis.Compilation_Units.Relations} package
Contains queries
@cindex ASIS queries
that return integrated semantic dependencies among ASIS
 @code{Compilation_Unit}s; e.g., all the units needed by a given unit to be included
 in a partition.

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

@item Packages working on specific @code{Element}s
This group contains the following packages: @code{Asis.Declarations},
@cindex @code{Asis.Declarations} package
 @code{Asis.Definitions},
@cindex @code{Asis.Definitions} package
 @code{Asis.Statements},
@cindex @code{Asis.Statements} package
@code{Asis.Expressions}
@cindex @code{Asis.Expressions} package
and
 @code{ASIS.Clauses}.
@cindex @code{ASIS.Clauses} package
Each of these packages contains queries working on
 @code{Element}s of the corresponding kind @minus{} that is, representing Ada declarations,
 definitions, statements, expressions and clauses respectively.

@item @code{Asis.Text}
@cindex @code{Asis.Text} package
Contains queries
@cindex ASIS queries
returning information about the source representation of ASIS
@code{Compilation_Unit}s and ASIS @code{Element}s.

@item @code{Asis.Exceptions}
@cindex @code{Asis.Exceptions} package
Defines ASIS exceptions.

@item @code{Asis.Errors}
@cindex @code{Asis.Errors} package
Defines possible ASIS error status values.
@end table


@c **********************************
@node Structural and Semantic Queries
@c **********************************
@section Structural and Semantic Queries

@noindent
@cindex ASIS queries
Queries working on @code{Element}s and returning @code{Element}s or @code{Element} lists
are divided into structural and semantic queries.
@cindex Structural ASIS queries
@cindex Semantic ASIS queries

Each structural query (except @code{Enclosing_Element})
@cindex @code{Enclosing_Element} query
implements one step of
the parent-to-child decomposition of an Ada program according to the ASIS
@code{Element} classification hierarchy. @code{Asis.Elements.Enclosing_Element} query
@cindex @code{Asis.Elements.Enclosing_Element} query
implements the reverse child-to-parent step. (For implicit @code{Element}s obtained
as results of semantic queries, @code{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
@code{Enclosing_Element} applied to its result).

A semantic query for a given @code{Element} returns the @code{Element} or the list of
@code{Element}s representing some semantic property @minus{} 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 @code{Element} @code{El} representing an assignment statement:

@smallexample @c ada
    X := A + B;
@end smallexample

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

@smallexample @c ada
   El_Var  := Asis.Statements.Assignment_Variable_Name (El); --  X
   El_Expr := Asis.Statements.Assignment_Expression    (El); --  A + B
@end smallexample

@noindent
Then we can analyze semantic properties of the variable name represented by
@code{El_Var} and of the expression represented by @code{El_Expr} by means of
appropriate semantic queries:

@smallexample @c ada
   El_Var_Def   :=
      Asis.Expressions.Corresponding_Name_Definition (El_Var);
   El_Expt_Type :=
      Asis.Expressions.Corresponding_Expression_Type (El_Expr);
@end smallexample

@noindent
As a result, @code{El_Var_Def} will be of @code{A_Defining_Identifier} kind
and will represent the defining occurrence of @code{X}, while
@code{El_Expt_Type} of a kind @code{An_Ordinary_Type_Declaration} will
represent the declaration of the type of the expression @code{A + B}.

If we apply @code{Asis.Elements.Enclosing_Element} to @code{El_Var} or to
@code{El_Expr}, we will get back to the @code{Element} representing the
assignment statement.

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


@c *****************************
@node ASIS Error Handling Policy
@c *****************************
@section ASIS Error Handling Policy
@cindex Error Handling

@noindent
Only ASIS-defined exceptions (and the Ada predefined @code{Storage_Error}
@cindex @code{Storage_Error} (propagated from ASIS queries)
exception) propagate out from ASIS queries. ASIS exceptions
are defined in the @code{Asis.Exceptions} package.
@cindex @code{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
@code{Asis.Errors.Error_Kinds} type)
@cindex @code{Asis.Errors.Error_Kinds} type
and forms the @code{Diagnosis} string.
@cindex @code{Diagnosis} string
An application can query the current value of the ASIS Error Status by the
@code{Asis.Implementation.Status} query,
@cindex @code{Asis.Implementation.Status} query
and the current content of the
@code{Diagnosis} string by @code{Asis.Implementation.Diagnosis} query.
@cindex @code{Asis.Implementation.Diagnosis} query
An application
can reset the Error Status and the @code{Diagnosis} string by
invoking the @code{Asis.Implementation.Set_Status} procedure.
@cindex @code{Asis.Implementation.Set_Status} procedure

@emph{Caution:} The ASIS way of providing error information is not tasking safe.
The @code{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.
@cindex Tasking and error information


@c *************************************
@node Dynamic Typing of ASIS Queries
@c *************************************
@section Dynamic Typing of ASIS Queries
@cindex ASIS queries (dynamic typing)

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

Many of the queries working on @code{Element}s and @code{Compilation_Unit}s can be applied
only to specific kinds of @code{Element}s and @code{Compilation_Unit}s respectively. For
example, it does not make sense to query
@code{Assignment_Variable_Name} for an @code{Element} of
@code{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 @code{Element} structural
or semantic query (that is, for a query having an @code{Element} as an argument and
returning either an @code{Element} or @code{Element} list as a result) a list of appropriate
@code{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 @code{Element}s being of the kinds from this list. If the kind of the
argument @code{Element} does not belong to this list, the corresponding call to this
query raises the @code{Asis.Exceptions.ASIS_Inappropriate_Element} exception
@cindex @code{Asis.Exceptions.ASIS_Inappropriate_Element} exception
with @code{Asis.Errors.Value_Error} error status set.
@cindex @code{Asis.Errors.Value_Error} error status

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

If a query has a list of expected @code{Element} kinds or expected @code{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
@code{Asis.Elements.Statement_Kind} query
@cindex @code{Asis.Elements.Statement_Kind} query
is called for an argument of
@code{A_Declaration} kind, it just returns @code{Not_A_Statement}, but without
raising any exception.


@c ****************
@node ASIS Iterator
@c ****************
@section ASIS Iterator
@cindex ASIS Iterator

@noindent
ASIS provides a powerful mechanism to traverse an Ada unit, the generic
procedure @code{Asis.Iterator.Traverse_Element}.
@cindex @code{Asis.Iterator.Traverse_Element} generic procedure
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
@code{Element}s). In the course of this traversal, it applies to each @code{Element} the
formal @code{Pre_Operation} procedure when visiting this @code{Element} for the first
time, and the formal @code{Post_Operation} procedure when leaving this @code{Element}.
By providing specific procedures for @code{Pre_Operation} and
@code{Post_Operation} when instantiating the generic unit, you
can automatically process all ASIS @code{Element}s found
in a given ASIS tree.

For example, suppose we have an assignment statement:

@smallexample @c ada
    X := F (Y);
@end smallexample

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

@smallexample
             (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)
@end smallexample

@noindent
To see in more detail how @code{Traverse_Element} may be used for rapid
development of a number of useful ASIS applications, try the examples in
@ref{ASIS Tutorials}.


@c *************************************************
@node How to Navigate through the Asis Package Hierarchy
@c *************************************************
@section How to Navigate through the @code{Asis} Package Hierarchy

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

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

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

@item
The names of all the semantic queries (and only ones) start from
 @code{Corresponding_...} or @code{Implicit_...}

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


@c ***************
@node ASIS Context
@c ***************
@chapter ASIS @code{Context}
@cindex @code{Context} type

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

@menu
* ASIS Context and Tree Files::
* Creating Tree Files for Use by ASIS::
* Different Ways to Define an ASIS Context in ASIS-for-GNAT::
* Consistency Problems::
* Processing Several Contexts at a Time::
* Using ASIS with a cross-compiler::
@end menu


@c *************************************
@node ASIS Context and Tree Files
@c *************************************
@section ASIS @code{Context} and Tree Files
@cindex Tree file

@noindent
The ASIS-for-GNAT
@cindex ASIS-for-GNAT
implementation is based on @emph{tree output files},
or, simply, @emph{tree files}. When called with the special option
@option{-gnatt},
@cindex @option{-gnatt} option
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))
@cindex AST (Abstract Syntax Tree)
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 '@file{.adt}'. For example, the tree
file for @file{foo.adb} is named @file{foo.adt}.
@cindex @file{adt} extension for tree files


@c **************************************
@node Creating Tree Files for Use by ASIS
@c **************************************
@section Creating Tree Files for Use by ASIS
@cindex Tree file

@menu
* Creating Trees for Data Decomposition Annex::
@end menu

@noindent
Neither @command{gcc} nor @command{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 @option{-gnatc} and @option{-gnatt} options (these may be combined
into the @option{-gnatct} option.  Thus
@cindex @option{-gnatc} option
@cindex @option{-gnatt} option
@cindex @option{-gnatct} option

@smallexample
$ gcc -c -gnatc -gnatt foo.adb
@end smallexample

@noindent
will produce @file{foo.adt}, provided that @file{foo.adb} contains the source
of a legal Ada compilation unit. The @option{-gnatt} option generates a tree file,
@cindex Tree file
and
@option{-gnatc} turns off AST expansion. ASIS needs tree files created without
AST expansion, whereas to create an object file, GNAT needs an expanded AST.
@cindex AST (Abstract Syntax Tree)
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:

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

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

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

@item
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 @code{Context}. See @ref{Consistency Problems}, for more details.

@item
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 @code{Context}, or you may get wrong results
 when querying the source or object file for a given ASIS
 @code{Compilation_Unit}.

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

@smallexample
$ gcc -c -gnatc -gnatt .\inner\foo.adb
@end smallexample

@noindent
but not as

@smallexample
$ gcc -c -gnatc -gnatt inner\foo.ads
@end smallexample

@noindent
Otherwise ASIS will not perform correctly.

@item
When reading in a tree file, ASIS checks that this tree file was created with
the @option{-gnatc} option, and it does not accept trees created without
this option.
@cindex @option{-gnatc} option

@item
If called to create a tree, GNAT does not destroy an @file{ALI} file if the @file{ALI} file
 already exists for the unit being compiled and if this @file{ALI} file is
 up-to-date. Moreover, GNAT may place some information from the existing @file{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.

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

@smallexample
$ gcc -c -gnatc -gnatt foo.adb
@end smallexample

@noindent
and then generate the tree for the corresponding spec:

@smallexample
$ gcc -c -gnatc -gnatt foo.ads
@end smallexample

@noindent
then the tree file @file{foo.adt}
@cindex Tree file
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 @code{gnatmake} whenever possible (see
 @ref{Using gnatmake to Create Tree Files} for more details).
 Otherwise, first create trees for specs and then for bodies:

@smallexample
$ gcc -c -gnatc -gnatt *.ads
$ gcc -c -gnatc -gnatt *.adb
@end smallexample

@item
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.
@cindex Tree swapping (ASIS performance issue)
 (See @ref{How to Build Efficient ASIS Applications}, for some
 tips).

@item
It is possible to create tree files ``on the fly'', as part of the
 processing of the ASIS queries that obtain units from a @code{Context}. In this
 case there is no need to create tree files before running an ASIS application
 using the corresponding @code{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 @code{Compilation_Unit} at a time. See the
 @cite{ASIS-for-GNAT Reference Manual} for more details.
@end itemize

@noindent
Note that between opening and closing a @code{Context}, an ASIS application should
not change its working directory; otherwise execution of the application is
erroneous.
@cindex Erroneous execution


@c **********************************************
@node Creating Trees for Data Decomposition Annex
@c **********************************************
@subsection Creating Trees for Data Decomposition Annex
@cindex Data Decomposition Annex (DDA)
@cindex Tree file

@noindent
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.
@cindex Subunits and the Data Decomposition Annex
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 @code{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 @command{gnatmake}: it will
never create separate trees for subunits.


@c ************************************************************
@node Different Ways to Define an ASIS Context in ASIS-for-GNAT
@c ************************************************************
@section Different Ways to Define an ASIS @code{Context} in ASIS-for-GNAT
@cindex @code{Context} type
@cindex ASIS-for-GNAT

@noindent
The @code{Asis.Ada_Environments.Associate} query
@cindex @code{Asis.Ada_Environments.Associate} query
that defines a @code{Context} has the following spec:

@smallexample @c ada
procedure Associate
             (The_Context : in out Asis.Context;
              Name        : in Wide_String;
              Parameters  : in Wide_String := Default_Parameters);
@end smallexample

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

@itemize @bullet
@item
How to define a set of tree files making up the @code{Context} (@option{-C} options);

@item
How to deal with tree files when opening a @code{Context} and when
 processing ASIS queries (@option{-F} options);

@item
How to process the source files during the consistency check when
opening the @code{Context} (@option{-S} options):

@item
The search path for tree files making up the @code{Context} (@option{-T} options);

@item
The search path for source files used for calling GNAT to create a tree
file ``on the fly'' (@option{-I} options);
@end itemize

@noindent
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 @code{Context} association parameters in
ASIS-for-GNAT; for full details refer to the @cite{ASIS-for-GNAT Reference Manual}.

@menu
* Defining a set of tree files making up a Context::
* Dealing with tree files when opening a Context and processing ASIS queries::
* Processing source files during the consistency check::
* Setting search paths::
@end menu


@c ***************************************************
@node Defining a set of tree files making up a Context
@c ***************************************************
@subsection Defining a set of tree files making up a @code{Context}

@noindent
The following options are available:

@table @option
@item -C1
``One tree'' @code{Context},
@cindex One-tree @code{Context}
defining a @code{Context} comprising a single tree file; this tree
 file name should be given explicitly in the @code{Parameters} string.

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

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

@noindent
The default option is @option{-CA}.

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



@c *****************************************************************************
@node Dealing with tree files when opening a Context and processing ASIS queries
@c *****************************************************************************
@subsection Dealing with tree files when opening a @code{Context} and processing ASIS queries

@noindent
The following options are available:

@table @option
@item -FT
Only pre-created trees are used, no tree file can be created by ASIS.

@item -FS
All the trees considered as making up a given @code{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 @code{Context} remains
 open. This option can be set only with @option{-CA} option.

@item -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 @option{-CA} option.
@end table

@noindent
The default option is @option{-FT}.

Note that the @option{-FT} and @option{-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 @code{Context},
but in each case the ramifications of using such non-standard options
should be carefully considered. See the @cite{ASIS-for-GNAT Reference Manual}
for a detailed description of these option.


@c *******************************************************
@node Processing source files during the consistency check
@c *******************************************************
@subsection Processing source files during the consistency check when opening a @code{Context}

@noindent
The following options are available:

@table @option
@item -SA
Source files for all the @code{Compilation_Unit}s belonging to the @code{Context} (except
  the predefined @code{Standard} package) have to be available, and all of them
  are taken into account for consistency checks when opening the @code{Context}.

@item -SE
Only existing source files for all the @code{Compilation_Unit}s belonging to the
 @code{Context} are taken into account for consistency checks when opening the @code{Context}.

@item -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
 @code{Context}.
@end table

@noindent
The default option is @option{-SA}.
See @ref{Consistency Problems}, concerning consistency issues in ASIS-for-GNAT.


@c ***********************
@node Setting search paths
@c ***********************
@subsection Setting search paths

@noindent
Using the @option{-I}, @option{-gnatec} and @option{-gnatA} options for defining
an ASIS @code{Context} is similar to using the same optionsfor @command{gcc}.
The @option{-T} option is used in the same way,
for tree files.  For full details about the @option{-T} and @option{-I}
options, refer to the @cite{ASIS-for-GNAT Reference Manual}. Note that the @option{-T}
option is used only to locate existing tree files, and it has no effect for
@option{-FS} @code{Context}s. On the other hand, the @option{-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 @option{-FT} @code{Context}s, and it cannot be used to
tell ASIS where it should look for source files for ASIS @code{Compilation_Unit}s.


@c ***********************
@node Consistency Problems
@c ***********************
@section Consistency Problems
@cindex Consistency problems

@menu
*   Inconsistent versions of ASIS and GNAT::
*   Consistency of a set of tree and source files::
@end menu

@noindent
There are two different kinds of consistency problems existing for
ASIS-for-GNAT, and both of them can show up when opening an ASIS @code{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.
@cindex Tree file
@cindex ASIS-for-GNAT

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


@c *****************************************
@node Inconsistent versions of ASIS and GNAT
@c *****************************************
@subsection Inconsistent versions of ASIS and GNAT

@noindent
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 @code{Program_Error}
@cindex @code{Program_Error} exception
with a corresponding exception message. In
this case, @code{Program_Error} is not caught by any ASIS query, and it propagates
outside ASIS.@footnote{This is not a violation of the requirement stated in
the ASIS definition that only ASIS-defined exceptions are allowed to propagate
outside ASIS queries, because in this case you do not have ASIS-for-GNAT
properly installed and therefore you do not have a valid ASIS implementation.}
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
@option{-vs} parameter for the ASIS @code{Initialize} procedure, see
@cite{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
@code{Program_Error} will be raised otherwise.

Be careful when using a @code{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.


@c ************************************************
@node Consistency of a set of tree and source files
@c ************************************************
@subsection Consistency of a set of tree and source files
@cindex Tree file

@noindent
When processing a set of more then one tree file making up the same @code{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 @code{Context} (via the @code{Asis.Ada_Environments.Open} query),
@cindex @code{Asis.Ada_Environments.Open} query
ASIS does the
following checks for all the tree files making up the @code{Context}:

@itemize @bullet
@item
If the @option{-SA} option is set for the @code{Context}, ASIS checks that for every
  @code{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).

@item
If the @option{-SE} option is set for the @code{Context}, then if for a @code{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
  @code{Compilation_Unit} belonging to a @code{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.

@item
If the @option{-SN} option is set for the @code{Context}, ASIS checks that all the trees
  were created from the same versions of the sources involved.
@end itemize

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


@c ****************************************
@node Processing Several Contexts at a Time
@c ****************************************
@section Processing Several @code{Context}s at a Time

@noindent
If your application processes more then one open @code{Context} at a time, and if
at least one of the @code{Context}s is defined with an @option{-FS} or @option{-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 @code{Context}s at a time, an ASIS application should
have at most one @code{Context} defined with an @option{-FS} or @option{-FM} option. If the
application has such a @code{Context}, all the other @code{Context}s should not use
tree files located in the current directory.


@c ****************************************
@node Using ASIS with a cross-compiler
@c ****************************************
@section Using ASIS with a cross-compiler

@noindent
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
@code{Context} defined with @option{-FS} option. If you would like to
use trees created on the fly (that is, to use a @code{Context} defined with the
@option{-FS} or @option{-FM} option), you have to tell ASIS which compiler should
be called to perform this function. There are two ways to do this.

@itemize @bullet
@item
You can use the @option{--GCC} option in the @code{Context} definition to specify
explicitly the name of the command to be called to create the trees on the fly
@cindex @option{-GCC} option

@item
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 ``@code{-}'',
  for example @code{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 @code{gcc}. For example, for @code{some_specific-foo},
  ASIS will try to call @code{some_specific-gcc} to create the tree file.
@end itemize

The algorithm for defining the name of the command to be used to create trees on the fly
is as follows. If the @option{--GCC} option is used in the @code{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 @code{gcc} installation is used.


@c ****************************
@node ASIS Interpreter asistant
@c ****************************
@chapter ASIS Interpreter @code{asistant}
@cindex @code{asistant}

@noindent
This chapter describes @code{asistant}, an interactive interface to ASIS queries.
@cindex ASIS queries

@menu
* asistant introduction::
* asistant commands::
* asistant variables::
* Browsing an ASIS tree::
* Example::
@end menu


@c ************************
@node asistant introduction
@c ************************
@section @code{asistant} Introduction

@noindent
The @code{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 @code{Element}); instead @code{asistant} reports an
error and lets you try again.

You can also use @code{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
@code{asistant} to reconstruct the situation that causes the problems,
and then experiment with ASIS queries.

Though primarily an interactive tool, @code{asistant} also can interpret
sequences of commands written to a file (called a ``script file''
@cindex Script file (for @code{asistant})
below). The @code{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 @code{asistant} may be found in the
@cite{@code{asistant} Users' Guide} (file @file{asistant.ug} in the @code{asistant} source directory).
Here is a brief overview of @code{asistant} usage.

The executable for @code{asistant} is created in the @code{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 @file{GNATPRO/bin}
directory when installing ASIS from the binary distribution). Put this
executable somewhere on your path@footnote{You do not have to do this if you have
installed ASIS from the binary distribution, because the executable for
@code{asistant} has been added to other GNAT executables},
and then type
``@code{asistant}'' to call @code{asistant} in an interactive mode. As a result,
the program will output brief information about itself and then the
@code{asistant} prompt ``@code{>}'' will appear:
@cindex ASIS-for-GNAT

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

>
@end smallexample

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

@smallexample
>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:

> ...
@end smallexample


@c ********************
@node asistant commands
@c ********************
@section @code{asistant} commands
@cindex @code{asistant} commands

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

@table @code
@item Help [(name)]
@cindex @code{Help} (@code{asistant} command)
Outputs the profile of the ASIS query ``@code{name}''; when called with no argument,
 generates general @code{asistant} help information.

@item Set (name)
@cindex @code{Set} (@code{asistant} command)
Creates a (non-initialized) variable ``@code{name}'' of the ASIS @code{Context} type.

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

@item Print (expr)
@cindex @code{Print} (@code{asistant} command)
Evaluates the expression ``@code{expr}'' and outputs its value (some information may be
 omitted depending on the level specified by the @command{PrintDetail} command).

@item Run (@file{filename})
@cindex @code{Run} (@code{asistant} command)
Launches the script from a file @file{filename}, reading further commands from it.
@cindex Script file (for @code{asistant})

@item Pause
@cindex @code{Pause} (@code{asistant} command)
Pauses the current script and turns @code{asistant} into interactive mode.

@item Run
Resumes a previously @code{Pause}d script.

@item Browse
@cindex @code{Browse} (@code{asistant} command)
Switches @code{asistant} into step-by-step ASIS tree browsing.

@item Log (@file{filename})
@cindex @code{Log} (@code{asistant} command)
Opens the file @file{filename} for session logging.

@item Log
Closes the current log file.

@item PrintDetail
@cindex @code{PrintDetail} (@code{asistant} command)
Toggles whether the @command{Print} command outputs additional information.

@item Quit [(exit-status)]
@cindex @code{Quit} (@code{asistant} command)
Quits @code{asistant}.
@end table


@c *********************
@node asistant variables
@c *********************
@section @code{asistant} variables
@cindex @code{asistant} variables

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

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


@c ************************
@node Browsing an ASIS tree
@c ************************
@section Browsing an ASIS tree
@cindex Browser (@code{asistant} utility)

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

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

@smallexample
> set (e0, Browse (e1))
@end smallexample

@noindent
you will start ASIS tree browsing from @code{e1}; when you finish
browsing, @code{e0} will represent the last @code{Element} visited during the
browsing.

If you type:

@smallexample
> Browse (e1)
@end smallexample

@noindent
you will be able to browse the ASIS tree, but the last @code{Element} of the
browsing will be discarded.

Browser displays the ASIS @code{Element} it currently points at and expects one of
the following commands:

@table @code
@item U
Go one step up the ASIS tree (equivalent to calling the ASIS
 @code{Enclosing_Element} query);
@cindex @code{Enclosing_Element} query

@item D
Go one step down the ASIS tree, to the left-most component of the current @code{Element}

@item N
Go to the right sibling (to the next @code{Element} in the ASIS tree hierarchy)

@item P
Go to the left sibling (to the previous @code{Element} in the ASIS tree hierarchy)

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

@item <SPACE><query>
Call the <query> for the current @code{Element}.

@item Q
Go back to the @code{asistant} environment; the Browser command interpreter is
disabled and the @code{asistant} command interpreter is enabled with the
current @code{Element} returned as a result of the call to @code{Browse}.
@end table

@noindent
Browser immediately interprets the keystroke and displays the new current
@code{Element}. If the message @code{"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 @code{Element} and it is not possible to go
down, or it is the leftmost or the rightmost component of some @code{Element}, and
it is not possible to go left or right, or it is the top @code{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 @code{Element} and return @code{Element} as a result.

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


@c **********
@node Example
@c **********
@section Example
@cindex ASIS Example

@noindent
Suppose we have an ASIS @code{Compilation_Unit} @code{Demo} in the source file @file{demo.adb}:

@smallexample @c ada
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;
@end smallexample

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

@smallexample @c ada
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
@end smallexample


@c *****************************
@node ASIS Application Templates
@c *****************************
@chapter ASIS Application Templates
@cindex ASIS application templates
@cindex Templates (for ASIS applications)

@noindent
The subdirectory @file{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 @file{README} file in the @file{templates}
subdirectory.


@c *****************
@node ASIS Tutorials
@c *****************
@chapter ASIS Tutorials
@cindex ASIS Tutorials

@noindent
The subdirectory @file{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 @code{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 @file{README} file in the @file{tutorial}
subdirectory.


@c *******************************************
@node How to Build Efficient ASIS Applications
@c *******************************************
@chapter How to Build Efficient ASIS Applications
@cindex ASIS Performance

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

@menu
* Tree Swapping as a Performance Issue::
* Queries That Can Cause Tree Swapping::
* How to Avoid Unnecessary Tree Swapping::
* Using gnatmake to Create Tree Files::
@end menu


@c ***************************************
@node Tree Swapping as a Performance Issue
@c ***************************************
@section Tree Swapping as a Performance Issue
@cindex Tree swapping (ASIS performance issue)

@noindent
If an ASIS @code{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:

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

@item
@emph{Processing of information from dependent units.}
A unit @code{U} may be present not only in the tree created for @code{U}, but also in
all the trees created for units which semantically depend upon @code{U}.
Suppose we have a library procedure @code{Proc} depending on a
 library package @code{Pack}, and in the set of trees making up our @code{Context} we
 have trees @file{pack.adt} and @file{proc.adt}. Suppose we have some
 @code{Element} representing a component of @code{Pack}, when @file{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 @file{proc.adt}.
 Suppose that now the application wants to do something with the @code{Element}
 representing some component of @code{Pack} and obtained from @file{pack.adt}. Even
 though the unit @code{Pack} is represented by the currently accessed tree
 @file{proc.adt}, ASIS has to switch back to @file{pack.adt}, because all the
 references into the tree structure kept as a part of the value of this
 @code{Element} are valid only for @file{pack.adt}.
@end itemize


@c ***************************************
@node Queries That Can Cause Tree Swapping
@c ***************************************
@section Queries That Can Cause Tree Swapping

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

@smallexample
Asis.Elements
Asis.Declarations
Asis.Definitions
Asis.Statements
Asis.Clauses
Asis.Expressions
Asis.Text
@end smallexample

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

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


@c *****************************************
@node How to Avoid Unnecessary Tree Swapping
@c *****************************************
@section How to Avoid Unnecessary Tree Swapping
@cindex Tree swapping (ASIS performance issue)

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

@itemize @bullet
@item
 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 @code{Context}. Try to use @command{gnatmake} to create
 a suitable set of tree files covering an Ada program for processing by
 an ASIS application.

@item
 Choose the @code{Context} definition appropriate to your application. For
 example, use ``one tree'' @code{Context} (@option{-C1}) for applications that are limited
 to processing single units (such as a pretty printer or @code{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'' @code{Context}
 definition, an application has only one tree file to read when
 opening a @code{Context}, and no other tree file will be read during the
 application run. An ``N-trees'' @code{Context} is a natural extension of ``one tree''
 @code{Context} for applications that know in advance which units will be
 processed, but opening a @code{Context} takes longer, and ASIS may switch among
 different tree files during an application run. Use ``all trees'' @code{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'' @code{Context}, use the approach for creating
 tree files described above to minimize a set of tree files to be
 processed.

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

@item
 If you are going to analyze a library unit having both a spec and a body,
 start by obtaining an @code{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.

@item
 To see a ``tree swapping profile'' of your application use the @option{-dt} debug flag
 when initializing ASIS (@code{Asis.Implementation.Initialize ("-dt")}).
@cindex @code{Asis.Implementation.Initialize} procedure
 The
 information returned may give you some hints on
 how to avoid tree swapping.
@end itemize


@c **************************************
@node Using gnatmake to Create Tree Files
@c **************************************
@section Using @code{gnatmake} to Create Tree Files
@cindex @code{gnatmake} (for creating tree files)

@noindent
To create a suitable set of tree files, you may use @code{gnatmake}. GNAT
creates an @file{ALI} file for every successful compilation, whether or not
code has been generated. Therefore, it is possible to run @code{gnatmake} with
the @option{-gnatc} and @option{-gnatt} options;
@cindex @option{-gnatc} option
@cindex @option{-gnatt} option
this will create the set of
tree files for all the compilation units needed in the resulting program.
Below we will use
@command{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 @command{gnatmake} to some of its
components.

Using @code{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 @code{gnatmake} to create a set of tree
files.

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

@smallexample
$ gnatmake -f -c ... main_subprogram.adb -cargs -gnatc -gnatt
@end smallexample

@noindent
or simply as

@smallexample
$ gnatmake -f -c -gnatc -gnatt ... main_subprogram.adb
@end smallexample

@noindent
this will create the trees representing the full program for which
@code{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 @command{gnatmake} is being called with the @option{-f} option
(which means ``force recompilation'').
Usng @command{gnatmake} without the @option{-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 @file{ALI} files.
If the
object files exist and are consistent with the @file{ALI} and source
files, the source will not be recompiled for creating a tree file unless the @option{-f}
option is set.

A different approach is to combine the tree files and the associated @file{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 @file{ALI} files should be in another directory.
In this case, by invoking @command{gnatmake} through:

@smallexample
$ gnatmake -c ... main_subprogram.adb -cargs -gnatc -gnatt
@end smallexample

@noindent
or simply:

@smallexample
$ gnatmake -c -gnatc -gnatt ... main_subprogram.adb
@end smallexample

@noindent
(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.


@c **************************************************
@node Processing an Ada Library by an ASIS-Based Tool
@c **************************************************
@chapter Processing an Ada Library by an ASIS-Based Tool
@cindex Ada predefined library (processing by an ASIS tool)

@noindent
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:

@itemize @bullet
@item
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 @command{gnatmake}
  (except in circumstances described below).
  For example, @code{Ada.Text_IO} is not recompiled
  when you invoke @command{gnatmake} on a unit that @code{with}s
  @code{Ada.Text_IO}.

@item
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 @command{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.

@item
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).

@item
In ASIS-for-GNAT, there is no standard way to define whether a given
  @code{Compilation_Unit} belongs to some precompiled Ada library other than
  the GNAT Run-Time Library (some heuristics may be added to @code{Asis.Extensions}).
@cindex @code{Asis.Extensions} package
  ASIS-for-GNAT classifies (by means of the
  @code{Asis.Compilation_Units.Unit_Origin} query)
@cindex @code{Asis.Compilation_Units.Unit_Origin} query
a unit as
  @code{A_Predefined_Unit}, if it is from the Run-Time Library
  and if it is mentioned in the @cite{Ada Reference Manual}, Annex A, Paragraph 2
  as an Ada 95 predefined unit;
  a unit is classified as
  @code{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 @code{An_Application_Unit};

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

@noindent
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:

@itemize @bullet
@item
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 @command{gnatmake}
   without the @option{-a} option (this is the usual way of using @command{gnatmake}).
   When the tool encounters a @code{Compilation_Unit} which represents a spec of some
   library unit, and for which @code{Asis.Compilation_Units.Is_Body_Required}
@cindex @code{Asis.Compilation_Units.Is_Body_Required} function
   returns @code{True}, but @code{Asis.Compilation_Units.Corresponding_Body}
@cindex @code{Asis.Compilation_Units.Corresponding_Body} function
yields a
   result of @code{A_Nonexistent_Body} kind, then the tool may conclude that
   this library unit belongs to some precompiled Ada library.

@item
 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 @command{gnatmake} with the @option{-a} option.
@end itemize

@noindent
You can use @code{Asis.Compilation_units.Unit_Origin}
@cindex @code{Asis.Compilation_units.Unit_Origin}
to filter out Run-Time Library components.


@c ****************************************************************
@node Compiling Binding and Linking Applications with ASIS-for-GNAT
@c ****************************************************************
@chapter Compiling, Binding and Linking Applications with ASIS-for-GNAT
@cindex ASIS-for-GNAT

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

@smallexample
$ gnatlink my_application -lasis
@end smallexample

@noindent
When using @command{gnatmake}, you also have to provide this linker parameter
whenever a call to @command{gnatmake} invokes @command{gnatlink}:

@smallexample
$ gnatmake ... my_application -largs -lasis
@end smallexample

@noindent
You do not need these linker parameters if a call to @command{gnatmake} is not
creating the executable:

@smallexample
$ gnatmake -c ... my_application
@end smallexample

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

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

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

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


@c *************************
@node ASIS-for-GNAT Warnings
@c *************************
@chapter ASIS-for-GNAT Warnings
@cindex Warnings (from ASIS-for-GNAT)

@noindent
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 @code{Initialize},
@code{Finalize} and @code{Associate} or opening a @code{Context}.

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

@table @emph
@item default
Warning messages are output to @code{Standard_Error}.

@item suppress
Warning messages are suppressed.

@item treat as error
A warning is treated as an error by ASIS-for-GNAT: instead of sending a
message to @code{Standard_Error}, ASIS-for-GNAT raises @code{Asis_Failed}
@cindex @code{Asis_Failed} exception
and converts the
warning message into the ASIS @code{Diagnosis} string.
@cindex @code{Diagnosis} string
ASIS Error Status depends on
the cause of the warning.
@end table

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

@c *************************************************
@node Exception Handling and Reporting Internal Bugs
@c *************************************************
@chapter Exception Handling and Reporting Internal Bugs

@noindent
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 @code{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 @code{Asis.Implementation.Initialize}. See
@cite{ASIS-for-GNAT Reference Manual}
for more details.

@c *****************************************************
@node File Naming Conventions and Application Name Space
@c *****************************************************
@chapter File Naming Conventions and Application Name Space

@noindent
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 @code{Asis} package:
@cindex @code{Asis} package

@itemize @bullet
@item
@code{Asis.Extensions} hierarchy (the source file names start with
  @file{asis-extensions}) defines some useful ASIS extensions, see ASIS
  Reference Manual for more details.
@cindex @code{Asis.Extensions} package

@item
@code{Asis.Set_Get} (the source files @file{asis-set_get.ad(b|s)}
  respectively) contains the access and update subprograms for the
  implementation of the main ASIS abstractions defined in @code{Asis}.
@cindex @code{Asis.Set_Get} package

@item
@code{Asis.Text.Set_Get} (the source files @file{asis-text-set_get.ad(b|s)}
  respectively) contains the access and update subprograms for the
  implementation of the ASIS abstractions defined in @code{Asis.Text};
@cindex @code{Asis.Text.Set_Get} package
@end itemize

@noindent
All other ASIS-for-GNAT Ada implementation components belong to the
hierarchy rooted at the package @code{A4G}
@cindex @code{A4G} package
(which comes from ``ASIS-for-GNAT'').

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

@smallexample
   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
@end smallexample

@noindent
Therefore, in your ASIS application you should not add children at any level of the @code{Asis}
or @code{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.


@c *************************************
@node Index
@c *************************************
@unnumbered Index
@printindex cp

@contents
@bye