\input texinfo   @c -*-texinfo-*-
@c %**start of header

@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c                                                                            o
@c                        ASIS-for-GNAT DOCUMENTATION                         o
@c                                                                            o
@c                              A S I S _ R M                                 o
@c                                                                            o
@c                            $Revision: 1.000
@c                                                                            o
@c             Copyright (C) 2000 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_RM 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 oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo

@setfilename asis_rm.info
@settitle ASIS-for-GNAT Reference Manual
@setchapternewpage odd
@syncodeindex fn cp
@c %**end of header

@titlepage

@title ASIS-for-GNAT Reference Manual

@author Ada Core Technologies, Inc.

@page
@vskip 0pt plus 1filll

@copyright{} Copyright 2000, Ada Core Technologies, Inc.

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 Manual, (dir), (dir)
@top ASIS-for-GNAT Reference Manual
@end ifinfo

ASIS-for-GNAT Reference Manual

@copyright{} Copyright 2000, Ada Core Technologies, Inc.

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.

ASIS-for-GNAT Reference Manual

@menu
* About This Manual::
* ASIS-for-GNAT and the ASIS Standard::
* ASIS Extensions::
* Implementation-Specific Features and Implementation Permissions::
* Debugging Information::

 --- The Detailed Node Listing ---

About This Manual

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

ASIS-for-GNAT and the ASIS Standard

ASIS Extensions

Implementation-Specific Features and Implementation Permissions

* Interacting with the Underlying Ada Implementation::
*   Format of the Parameters string::
*   Parameters of AsisImplementationInitialize Procedure::
*   Parameters of AsisImplementationFinalize Procedure::
*   Parameters of AsisAda_EnvironmentsAssociate Procedure::
* Implementation Permissions::
*   AsisImplementationPermissions Queries::
*   Processing Implicit Elements::
*   Processing Several Contexts at a Time::
*   Implementation-Defined Types and Values::
* ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results::
* Restrictions Specific to -FS and -FM Context options::

Debugging Information

* Interpreting Debug Images::
* ASIS Debug Flags::
@end menu


@node About This Manual
@unnumbered About This Manual

@noindent
This Manual contains useful information in writing tools and applications
using ASIS 95 implementation for the GNAT Ada 95 compiler (ASIS-for-GNAT). It
includes information on implementation dependent characteristics and the
current implementation limitations of ASIS-for-GNAT.

ASIS has been designed to be a portable basis for many useful Ada code
analysis tools. However, since ASIS is designed to be implemented for wide
variety of Ada compilers, it also contains a number of implementation specific
features to be used in interfacing with the underlying Ada implementation, as
well as implementation permissions for particular queries

Note: Any ASIS application that makes use of implementation-dependent features
may be non-portable. You should follow good programming practice and isolate
and clearly document any sections of your program that make use of these
features in a non-portable manner.

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

@node What This Manual Contains, What You Should Know Before Reading This Manual, , About This Manual
@unnumberedsec What This Manual Contains

@noindent
This guide contains the following chapters:

@itemize @minus
@item
@ref{ASIS-for-GNAT and the ASIS Standard} describes the relations
  between ASIS-for-GNAT and the existing ASIS International Standard;
@item
@ref{ASIS Extensions} describes the ASIS extensions implemented in
  ASIS-for-GNAT;
@item
@ref{Implementation-Specific Features and Implementation Permissions}
  goes through the aspects of the ASIS definition which are
  implementation-specific and describes their implementation in ASIS-for-GNAT;
@item
@ref{Debugging Information} describes the debugging information which
  can be produced by ASIS-for-GNAT
@end itemize


@node What You Should Know Before Reading This Manual
@unnumberedsec What You Should Know Before Reading This Manual

@noindent
This Reference Manual assumes, that you are familiar with Ada 95 language, as
described in the International Standard ANSI/ISO/IEC-8652:1995, Jan 1995, and
with ASIS 95, as described in the ASIS 95 International Standard
ISO/IEC 15291:1999.

This Manual relies on some important facts described in the ASIS-for-GNAT
User's Guide and uses the terminology introduced in the User's Guide.


@node Related Information
@unnumberedsec Related Information

@noindent
For more information, see the following documents:
@itemize @minus
@item
GNAT User's Guide;
@item
ASIS-for-GNAT User's Guide;
@item
Ada 95 Reference Manual, which contains all reference material for
the Ada 95 programming language;
@item
ASIS 95 definition, which contains all reference material for
  the Ada Semantic Interface Specification;
@end itemize

@noindent
@node ASIS-for-GNAT and the ASIS Standard
@chapter ASIS-for-GNAT and the ASIS Standard

@noindent
Now the ASIS definition for Ada 95 (ASIS 95) exists as ISO/IEC 15291:1999
International Standard. ASIS-for-GNAT supports the ASIS 95 interface as it is
defined in the ASIS Standard. ASIS-for-GNAT also contains some ASIS extensions
(see chapter @ref{ASIS Extensions}), as allowed by the ASIS Standard,
section 1.1.3.1.

Currently some queries in some situations may raise the Asis_Failed exception
with Not_Implemented_Error error status. This means, that some part of the
functionality of a given query is not implemented yet. If you encounter such a
situation, report it as an ordinary ASIS-for-GNAT bug. Our general goal is to
have the full implementation of ASIS 95 conforming to the ASIS Standard.

ASIS-for-GNAT contains the specifications of all the ASIS interface packages
as defined in the ASIS Standard, except the optional Data Decomposition
Annex, with no changes, except adding comments in the very beginning, adding
with clauses, adding declarations in package private parts and some
reformatting needed to follow the GNAT coding style. The only exception is
moving the Is_Dispatching_Operation query from Asis.Expressions into
Asis.Declarations.


@node ASIS Extensions
@chapter ASIS Extensions

@noindent
ASIS-for-GNAT provides some additional queries as ASIS extensions. All these
queries are defined and documented in the hierarchy headed by package
Asis.Extensions. They are referred as "ASIS extensions" or "ASIS extension
queries" below.

All the ASIS extensions obey all the general ASIS rules: when using ASIS
extensions, you have to follow the required sequiensing of calls, only
ASIS-defined exceptions are allowed to propagate outside the ASIS exception
queries. If the documentation of an ASIS exception query contains a list of
appropriate element kinds, then this query can be applied only to Elements
from this list and it raises ASIS_Inappropriate_Element with Value_Error
status otherwise. If the documentation of an ASIS exception query contains a
list of expected element kinds, then this query can be applied to an
Element having any kind, but it returns meaningful result only for Elements
from this list.

The current set of ASIS extensions originated from the ASIS implementation
needs and from the development of some ASIS tools inside the ASIS-for-GNAT
team. As it stands now, Asis.Extensions hierarchy is not supposed to be
stable - some queries may be removed from it, some new extension queries may
be added. We are very interested in ASIS application developers feedback to
implement a compact, but useful set of extension queries in ASIS-for-GNAT.

Currently Asis.Extensions hierarchy contains its top Asis.Extensions package
defining a set of various-purpose extensions, and its only child
Asis.Extensions.Flat_Kinds, which defines a "flat" Element classification.

Asis.Extensions package contains the following extension types and queries (see
the specification of Asis.Extensions in the file named
@code{asis-extensions.ads} for full details):

@enumerate
@item
 Types for dynamic Elements and Compilation Units lists:

@smallexample
   type Element_List_Access is access Element_List;
   type Compilation_Unit_List_Access is
      access Compilation_Unit_List;
@end smallexample

@noindent
    an application may use dynamic allocation to keep the results of queries
    returning lists (instead of declaring local list variables in block
    statements)

@item
 Placeholders for Traverse_Element instantiations:

@smallexample
   type No_State is (Not_Used);
   --  Placeholder for the State_Information formal type

   procedure No_Op
     (Element : Asis.Element;
      Control : in out Traverse_Control;
      State   : in out No_State);
   --  Placeholder for the formal Post_Operation procedure
@end smallexample

@noindent
    In many simple cases of instantiating Traverse_Element, the only needed
    actual is the actual for Pre_Operation, so these placeholders for
    traversal state and post-operation may be used to get the legal
    instantiation;

@item
 Test functions:

@smallexample
   function Is_Primitive_Operation (Declaration : Asis.Element)
     return Boolean;

   --  Checks if its argument is a declaration of a (user-defined)
   --  primitive operation of some type (both explicit and implicit
   --  declarations are expected).

   function Acts_As_Spec (Declaration : Asis.Element)
     return Boolean;

   --  Checks if there is no separate subprogram declaration for a
   --  given body declaration or body stub.

   function Is_Renaming_As_Body (Declaration : Asis.Element)
     return Boolean;
   --  Checks if its argument is a renaming-as-body declaration.

   function Is_Completed (Declaration : Asis.Element)
     return Boolean;
   --  Checks if its argument (which is expected to be a
   --  declaration requiring completion) has a completion in its
   --  enclosed ASIS Context.

   function Is_True_Expression (Expression : Asis.Expression)
     return Boolean;
   --  Checks if Expression is an expression in Ada sense, that is
   --  if it is an expression as defined in RM 4.4, and the type of
   --  this expression can be represented in ASIS. For cases of
   --  An_Expression Element for which Is_True_Expression is True,
   --  the Corresponding_Expression_Type query should yield non-Nil
   --  result

   function Is_Static (Expression : Asis.Expression)
     return Boolean;
   --  Checks if Expression is static in the GNAT sense, that is if
   --  the compiler computes its value during the compilation time.
   --  We believe that this notion of a static expression is close
   --  to the definition of static expression in RM 95, but we can
   --  not guarantee this.
@end smallexample

@item
Modified versions of the "primary" ASIS queries:

@smallexample
   generic
      type State_Information is limited private;

      with procedure Pre_Operation
                       (Element : in     Asis.Element;
                        Control : in out Traverse_Control;
                        State   : in out State_Information) is <>;

      with procedure Post_Operation
                       (Element : in     Asis.Element;
                        Control : in out Traverse_Control;
                        State   : in out State_Information) is <>;

   procedure Traverse_Unit
     (Unit    : in     Asis.Compilation_Unit;
      Control : in out Traverse_Control;
      State   : in out State_Information);
   --  A generalized version of Asis.Iterator.Traverse_Element.
   --  Traverses the whole structure of the argument Compilation
   --  Unit

   function Formal_Subprogram_Default
     (Declaration : in Asis.Generic_Formal_Parameter)
      return Asis.Expression;
   --  This is a modified version of the
   --  Asis.Declarations.Formal_Subprogram_Default query. It returns
   --  Nil_Element instead of raising Asis_Inappropriate_Element if
   --  Subprogram_Default_Kinds of its argument is not
   --  A_Name_Default

   function Primary_Owner
     (Declaration : Asis.Declaration)
      return        Asis.Declaration;
   --  In the case that Declaration is Is_Primary_Operation for some
   --  tagged type, this function returns the tagged type definition
   --  for which it is a primary operation.

   function Corresponding_Called_Function_Unwinded
     (Expression : in Asis.Expression)
      return Asis.Declaration;
   --  This is the modification of
   --  Asis.Expressions.Corresponding_Called_Function which unwinds
   --  all the renamings in case if the function name in the
   --  argument function call is defined by a renaming declaration.
   --  This function returns the declaration of the called function
   --  *entity*.

   function Corresponding_Called_Entity_Unwinded
     (Statement : in Asis.Statement)
      return Asis.Declaration;
   --  This is the modification of
   --  Asis.Statements.Corresponding_Called_Entity which unwinds all
   --  the renamings in case if the procedure or entry name in the
   --  argument call is defined by a renaming declaration. This
   --  function returns the declaration of the callable *entity*.
@end smallexample

@item
Extensions of ASIS functionality:

@smallexample
   function Is_Obsolete (Right : Asis.Compilation_Unit)
     return Boolean;
   --  Checks if a unit is obsolete.

   type Source_File_Statuses is
     (No_File_Status, Absent, Older,  Newer, Up_To_Date);

   function Source_File_Status
     (Right : Asis.Compilation_Unit)
      return  Source_File_Statuses;
   --  Checks the status of the source file for the argument unit.

   function Is_Main_Unit_In_Tree
     (Right : Asis.Compilation_Unit)
      return  Boolean;
   --  Checks if a unit is a main unit from some compilation which
   --  has created a tree within the set of tree files making up the
   --  enclosing Context.

   function Compilation_Dependencies
     (Main_Unit : Asis.Compilation_Unit)
      return      Asis.Compilation_Unit_List;
   --  Provides the full list of units upon which Main_Unit depends
   --  in the GNAT compilation system.

   function Corresponding_First_Definition
     (Defining_Name : in Asis.Defining_Name)
      return Asis.Defining_Name;
   --  In case if there are more then one defining occurrence of an
   --  argument Defining_Name representing the same view of the same
   -- entity, this function returns the first defining occurrence
   --  which actually introduces the entity.

   function Corresponding_Body_Parameter_Definition
     (Defining_Name : Asis.Defining_Name)
      return          Asis.Defining_Name;
   --  When applying to a defining name which is a name of a formal
   --  parameter of a subprogram, this function returns the defining
   --  name of this parameter from a subprogram body.

   function Element_Span_In_Template
     (Element : Asis.Element)
      return    Asis.Text.Span;
   --  If Is_Part_Of_Instance is True for the argument Element, then
   --  this function returns the span of the corresponding piece of
   --  code in the generic template. Otherwise a Nil_Span is
   --  returned. Nil_Span is also returned if Is_Part_Of_Implicit
   --  Element is True for Element.

   function Element_Image_In_Template
     (Element : Asis.Element)
      return    Program_Text;
   --  If Is_Part_Of_Instancce is True for the argument Element,
   --  then this function returns the image of the corresponding
   --  piece of code in the generic template. Otherwise a null
   --  string is returned. A null string is also returned if
   --  Is_Part_Of_Implicit_ELement is true for Element
@end smallexample

@noindent
@item
General_Purpose Extensions:

@smallexample
   function Get_Last_Component (E : Asis.Element)
     return Asis.Element;
   --  Returns the right-most direct component of its argument.

   function Components (E : Asis.Element) return Asis.Element_List;
   --  Returns the list of all the first-level components of its
   --  argument.
@end smallexample
@end enumerate

@noindent
Asis.Extensions.Flat_Kinds package contains the definition of the type
Flat_Element_Kinds. This type defines a "flat" Element classification which is
equivalent to the Element classification hierarchy defined in Asis package:
each kind value of the original hierarchy having subordinate kinds is replaced
by the corresponding subordinate range. Asis.Extensions.Flat_Kinds package
also provides conversion functions from the "flat" classification into the
original classification hierarchy.


@node Implementation-Specific Features and Implementation Permissions
@chapter Implementation-Specific Features and Implementation Permissions

@noindent
There are three kinds of implementation dependencies in ASIS.

First, ASIS subprograms which define an interface between an ASIS
implementation and the underlying Ada implementation have
implementation-specific parameters. There are three queries of this kind -
Asis.Implementation.Initialize, Asis.Implementation.Finalize and
Asis.Ada_Enfironments.Associate, all of them have a string parameter named
Parameters which has implementation-specific meaning. The meaning of
Parameters string in ASIS-for-GNAT is discussed in section
@ref{Interacting with the Underlying Ada Implementation}.

Second, some ASIS areas are considered as making problems for ASIS
implementations. For such areas, the Asis Working Draft contains explicit
implementation permissions which allow an ASIS implementation not to implement
some part of the ASIS functionality or to implement it in a restricted way.
Each of these permissions usually affects more, then one particular ASIS
query. The ASIS package Asis.Implementation.Permissions contains boolean
queries which tell you what choices are made for these implementation
permission in a given ASIS implementation. The solutions taken in
ASIS-for-GNAT for these general implementation permissions are discussed in
section @ref{Implementation Permissions}.

Third, for some ASIS queries implementation permissions which are specific for
a given query are given explicitly in the ASIS Working Draft. For some other
queries, the result of a query may be implementation-specific because of the
very nature of the query, even though it is not explicitly said so in the ASIS
Standard. Such queries are discussed in section
@ref{ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results}.

@menu
* Interacting with the Underlying Ada Implementation::
* Implementation Permissions::
* ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results::
* Restrictions Specific to -FS and -FM Context options::
@end menu


@node Interacting with the Underlying Ada Implementation
@section Interacting with the Underlying Ada Implementation

@menu
*   Format of the Parameters string::
*   Parameters of AsisImplementationInitialize Procedure::
*   Parameters of AsisImplementationFinalize Procedure::
*   Parameters of AsisAda_EnvironmentsAssociate Procedure::
@end menu


@node Format of the Parameters string
@subsection Format of the Parameters string

A Parameters string is a parameter of the three ASIS
subprograms: Asis.Implementation. Initialize,
Asis.Implementation.Finalize and Asis.Ada_Environments.Associate.
The following requirements are common for all these subprograms:

@itemize @minus
@item
 A Parameters string are considered as consisting on substrings bounded by
  the beginning of the string, the end of the string, space character, LF or
  CR and containing no space character, LF or CR inside. These substrings are
  called parameters (with low-case 'p') below;

@item
 any number of space character, CR and LF are allowed before the first
  parameter, after the last parameter and between any two parameters;

@item
 each of the queries Asis.Implementation.Initialize,
  Asis.Implementation.Finalize and Asis.Ada_Enfironments.Associate has its own
  requirements imposed on its parameters. For all of these queries, if some
  parameter does not match the rules for a given query, either an error
  message is generated or Asis_Failed with the Parameter_Error status is
  raised. In this manual, the situations when Asis_Failed is raised when
  processing the Parameters string are documented specially.
@end itemize

@node Parameters of AsisImplementationInitialize Procedure
@subsection Parameters of Asis.Implementation.Initialize Procedure

@noindent
The allowed parameters for Asis.Implementation.Initialize are:

@table @code
@item -d<debug_flag>
sets the ASIS-for-GNAT debug flag <debug_flag> ON
@item -dall
sets all the ASIS-for-GNAT debug flags ON.
@item -w<warning_mode>
sets the ASIS warning mode (This is under development at the moment).
@end table

Now <debug_flag> may be any lower case letter from 'a' to 'z' or any digit
from 0 to 9 (not all of the corresponding options are implemented now).

ASIS debug flags are documented in the file @code{a_debug.adb}.
(See also section @ref{ASIS Debug Flags} for some advices)

<warning_mode> could be either 's', which means "suppress all the warning
messages" or 'e', which means "treat every warning as an error", and in this
case every warning are converted in Asis_Failed raising with warning messages
as ASIS Diagnosis strings.

If more then one parameter controlling the warning mode is set in the
diagnosis string, each of them changes the warning mode in the place where it
is given.

See also ASIS-for-GNAT Users' Guide for more information about warnings.


@node Parameters of AsisImplementationFinalize Procedure
@subsection Parameters of Asis.Implementation.Finalize Procedure

@noindent
No parameter is allowed for Asis.Implementation.Finalize in the current
ASIS-for-GNAT version.

When called, Asis.Implementation.Finalize resets all the general ASIS-for-GNAT
parameters to the default values (that is, all the debug flags are set off,
and the warning mode is set to the default warning mode).


@node Parameters of AsisAda_EnvironmentsAssociate Procedure
@subsection Parameters of Asis.Ada_Environments.Associate Procedure

The following parameters are allowed for this query:

@table @code

@item -C1
a Context is made up by a single tree file, this tree file name should
      be given explicitly in the Parameters string;

@item -CN
a Context is made up by a set of tree files, the names of the tree files
      making up the Context should be given explicitly in the Parameters
      string;

@item -CA
a Context is made up by all the tree files in the tree search path;

@item -FS
   all the trees considered as making up a given Context are created on the
      fly, whether or not the corresponding tree file already exists; once
      created, a tree file may then be reused till the Context remains open;

@item -FT
 only pre-created trees are used, no tree file can be created by ASIS;

@item -FM
 mixed approach: if a needed tree does not exist, the attempt to create
      it on the fly is made;

@item -SA
 source files for all the Compilation Units belonging to the Context
      (except the predefined Standard package) are considered in the
      consistency check when opening the Context;

@item -SE
 only existing source files for all the Compilation Units belonging to the
      Context are considered in the consistency check when opening the Context

@item -SN
 no source file from the underlying file system is taken into account
      when checking the consistency of the set of tree files making up a
      Context;

@item -I<dir>
 defines the directory to look for a source file;

@item -T<dir>
 defines the directory to look for a tree file;

@item <file_name>
 defines the name of a tree file;
@end table

@noindent
For -I and -T parameters, <dir> should denote an existing directory in the
underlying file system, notations as "." and ".." are allowed, as well as
relative or absolute directory names. If <dir> does not denote an existing
directory, Asis_Failed with Parameter_Error status is raised.

A tree file name given by a <file_name> parameter may or may not contain
directory information.

The search path associated with an ASIS Context consists of the directories
listed as parameters for the Asis.Ada_Environments.Associate query, in the
same order as they are included in the actual Parameters string. The ASIS
source search path consists only of the directories following '-I', and the
ASIS tree search path consists only of the directories following '-T'. If no
source (tree) directory presents in the value of the Parameters string, then
the ASIS source (tree) search path consists of the current directory only,
otherwise the current directory is included in the ASIS search path if amd only
if it is set explicitly as -I. or -T. respectively.

If an ASIS Context is associated with -FS or -FM option, the Context source
search path to locate sources of the units to create a tree file for, and to
locate other source files needed when called GNAT to create tree files. For
example, if we have:

@smallexample
   Asis.Ada_Environments.Associate
     (My_Cont,
     "My_Cont_Name",
     "-CA -FS -I./dir -I.");
@end smallexample

then, when processing a call:

@smallexample
   My_Unit := Asis.Compilation_Units.Library_Unit_Declaration
     ("Foo", My_Cont);
@end smallexample

ASIS first try to locate the source file foo.ads in ./dir, and if this attempt
fails, it tries to locate it in the current directory. If the source file is
found (let it be in the current directory), ASIS calls GNAT to create the tree
file as

@smallexample
   gcc -c -gnatc -gnatt -I./dir -I. -I- foo.ads
@end smallexample

If an ASIS Context is associated with -CA option, then, when this Context is
opened, ASIS processes all the tree files located in the tree search path
associated with the Context.

The following restrictions are imposed on allowed combinations of parameters
in the actual Parameters string of the Asis.Ada_Environments.Associate query:

@itemize @bullet

@item
-C1 and -CN require FT

@item
-C1 requires exactly one tree file to be set

@item
-CN requires at least one tree file to be set

@item
-CA does not allow a tree file name

@item
-FS and -FM require -SA
@end itemize

In case if an incompatible combination is set, Asis_Failed
with Parameter_Error status is raised

In case if the actual for the Parameters string in a call to the query
@code{Associate} is an empty string, the default parameters
are: "-CA -FT -SA"

Note, that the definition of the parameters might change later on.

For the Name parameter of the Asis.Ada_Environments.Associate query any string
can be passed as an actual. In the current ASIS-for-GNAT version no
verification is performed for an actual and no semantic is associated with the
Name parameter of the Asis.Ada_Environments.Associate query.

@node Implementation Permissions
@section Implementation Permissions

@menu
*   AsisImplementationPermissions Queries::
*   Processing Implicit Elements::
*   Processing Several Contexts at a Time::
*   Implementation-Defined Types and Values::
@end menu

@node AsisImplementationPermissions Queries
@subsection Asis.Implementation.Permissions Queries

@noindent
The Boolean queries defined in the @code{Asis.Implementation.Permissions}
package return the following results under ASIS-for-GNAT:

@smallexample
   Is_Formal_Parameter_Named_Notation_Supported   True
   Default_In_Mode_Supported                      True
   Generic_Actual_Part_Normalized                 False
   Record_Component_Associations_Normalized       False
   Is_Prefix_Call_Supported                       True
   Function_Call_Parameters_Normalized            False
   Call_Statement_Parameters_Normalized           False
   Discriminant_Associations_Normalized           False
   Is_Line_Number_Supported                       True
   Is_Span_Column_Position_Supported              True
   Is_Commentary_Supported                        True
   Attributes_Are_Supported                       False
   Implicit_Components_Supported                  False +
   Object_Declarations_Normalized                 False
   Predefined_Operations_Supported                False +
   Inherited_Declarations_Supported               False +
   Inherited_Subprograms_Supported                False +
   Generic_Macro_Expansion_Supported              True
@end smallexample

@noindent
+  - See section @ref{Processing Implicit Elements}


@node Processing Implicit Elements
@subsection Processing Implicit Elements

@noindent
ASIS Elements represent both explicit and implicit components of Ada programs.
There are queries in ASIS which can return implicit Elements (that is,
Elements representing implicit Ada constructs) or which can have implicit
Elements as parameters.

The ASIS Standard gives the permission to ASIS implementation not to
support implicit Elements at all or to support them only partially. If an
implementation does not support implicit Element representing a particular
kind of Ada implicit constructs, this means, that corresponding ASIS queries
return Nil_Element in cases when, according to RM-defined Ada syntax and
semantic, they should return implicit Elements representing these implicit
constructs.

Now implicit Elements are partially supported by ASIS-for-GNAT. In case of
implicitly declared user-defined inherited subprograms, the queries
@code{Asis.Expressions.@-Corresponding_Name_Definition},
Asis.Expressions.Corresponding_Called_Function and
@code{Asis.Statements.Corresponding_Called_Entity} return non-nil result
representing the corresponding entity. In case of implicitly declared
predefined operations, @code{Nil_Element} is returned.

Our final goal is to have all the implicit Ada constructs fully implemented in
ASIS-for-GNAT.


@node Processing Several Contexts at a Time
@subsection Processing Several Contexts at a Time

@noindent
ASIS Standard says that the number of ASIS Context which can be
associated and opened at a time, as well as the number of ASIS Compilation
Units which can be processed at a time are implementation-specific.
ASIS-for-GNAT does not impose any restrictions on the number of ASIS Context
opened at a time in an ASIS application, as well as on the number of ASIS
Compilation Units which can be obtained from all the opened Contexts, as long
as the application does not go beyond the general system resource limitations.

Note, however, for a Context associated with -FS or -FM option, all the trees
create don the fly during obtaining Compilation Units from this Context are
placed in the current directory. If the current directory contains also some
tree files belonging to another Context, they may be corrupted. To process
more then one Context in a safe way, an application should have ot most one
Context associated with -FS or -FM option. Moreover, if among Contexts
processed at the same time there is a Context which can create trees on the
fly, all the other Context should not use tree files located in the current
directory.


@node Implementation-Defined Types and Values
@subsection Implementation-Defined Types and Values

@noindent
All the implementation-defined types, subtypes and values depend on the
subtype Implementation_Defined_Integer_Type and on the
Implementation_Defined_Integer_Constant defined in package Asis. ASIS-for-GNAT
does not change the definition given in the specification of package Asis as
it stands in the ASIS Standard:

@smallexample
    subtype Implementation_Defined_Integer_Type is Integer;
    Implementation_Defined_Integer_Constant : constant := 2**31-1;
@end smallexample

@noindent
All the ASIS (sub)types used as list indexes for the ASIS array types have this
value of Implementation_Defined_Integer_Constant as an upper bound.


@node ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results
@section ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results

@noindent
This section contains implementation-specific documentation items for the
queries having implementation permissions (given under --|IP sentinel in the
ASIS definition) or for the queries whose behavior may be
implementation-specific for whatever reason. Such queries are ordered
according to the presentation in the ASIS definition. We have preserved the
clause and subclause numbers from the ASIS definition, putting these numbers
between quotes to avoid confusion with section numbers in this manual.

The results returned by the ASIS Debug_Image queries are discussed in
section @ref{Interpreting Debug Images}.

@smallexample
'8'  package Asis.Ada_Environments

'8.1'  function Default_Name
       - null string is returned;

'8.2'  function Default_Parameters
       - null string is returned;

'8.4'  procedure Open
       - what happens during the Context opening is:

         - for a Context associated with -CA option:
           - if -FS is also set, nothing is doing;
           - if -FT or -FM is set, all the tree files (that is,
             files having .adt suffix) in the tree search path
             associated with the Context are processed. For every
             tree file an attempt to read it in is made, and then
             it is checked that this file was created with
             -gnatc option. Tree files which cannot be read in or
             which were not created with -gnatc option are ignored.
             For all the other trees ASIS collects some black-box
             information about Compilation Units represented by
             this tree file, and performs a consistency check for
             every unit it encounters in the tree (see ASIS-for-GNAT
             Users' Guide for discussion of the consistency
             problem). If any consistency check fails, Asis_Failed
             is raises and the Context remains closed.

         - for a Context associated with -C1 or -CN option: ASIS
           process all the tree files associated with the Context,
           collecting black-box information and doing consistency
           check for all the encountered Compilation Units. If,
           because of any reason, a tree file cannot be
           successfully read in, for a Context associated with -C1
           option Asis_Failed is raised and the Context remains
           closed; and for a Context associated with -CN option,
           ASIS warning is generated and Context opening goes
           further. If any consistency check fails, Asis_Failed is
           raised and the Context remains closed.

'10' package Asis.Compilation_Units

'10.3'  function Unit_Origin
        - A_Predefined_Unit origin is returned for compilation units
          listed in RM95, Annex A (2), and only for these units;

        - An_Implementation_Unit origin is returned for compilation
          units which are the components of the GNAT Run-Time
          Library, but which are not mentioned in RM95, Annex A (2);

        - An_Application_Unit origin is returned for all the other
          compilation units;


'10.6'  function Library_Unit_Declaration
'10.7'  function Compilation_Unit_Body
        - when processing a Context associated with -FS or -FM
          option, for both of these queries, if ASIS cannot find a
          needed unit in the tree files which have been already
          processed, it tries to create the needed tree by locating
          the source of the unit and compiling it on the fly. If
          this attempt fails by any reason, Nil_Compilation_Unit
          is returned;

'10.13' function Corresponding_Declaration:
        - ASIS-for-GNAT does not make use of ASIS Compilation Units
          of An_Unknown_Unit kind;
        - if an argument is of A_Public_Declaration_And_Body class,
          Nil_Compilation_Unit is returned;

'10.14' function Corresponding_Body
        - ASIS-for-GNAT does not make use of ASIS Compilation Units
          of An_Unknown_Unit kind;

'10.22' function Can_Be_Main_Program
        - for GNAT, any parameterless library procedure and any
          parameterless library function returning the result of
          (any) integer type is classified by this query as a
          (possible) main subprogram for partition;

        - If for such a library subprogram both spec and body exist
          as ASIS Compilation Units retrievable form a given ASIS
          Context, both of them are considered as
          Can_Be_Main_Program

'10.24' function Text_Name
        - this function returns the name of the source file
          containing the source of Compilation_Unit. This name may
          or may not contain a prefix indicating the directory in
          the underlying file system, the directory indication may
          be given in absolute or the relative form, depending on
          the command line options which were used for the call
          to GNAT that created the corresponding tree file;
        - this function does not check the existence of the
          corresponding source file in the underlying file system,
          it just reflects the situation which was in effect when
          the corresponding tree file was created. Thus, if you
          delete or move the corresponding source file after
          creating the tree, the full file name returned by this
          function will be incorrect;
        - in case of inconsistency (that is, when several versions
          of the unit's source were used for creating the tree files
          making up the given ASIS Context), the name of the latest
          version of the source is returned.

'10.25' function Text_Form
        - In the GNAT compilation model all source files are
          ordinary text files in the underlying file system.
          Therefore this function always returns a Nil_Asis_String
          to indicate that Text_IO.Open uses the default options for
          manipulating Ada sources.
'10.29' function Has_Attribute
        - Returns False. ASIS-for-GNAT does not provide any
          additional attributes for Compilation Units.

'10.30' function Attribute_Value_Delimiter
        - Returns (wide) string of the length one and containing LF
          (wide) character.

'10.31' function Attribute_Values
        - a null string is returned


'11' package Asis.Compilation_Units.Times

'11.2'  function Time_Of_Last_Update
        - This function returns the time stamp of the corresponding
          source file. The corresponding source file is the source
          file whose name is returned by Asis.Compilation_Units.
          Text_Name. That is to say, this function returns the time
          of the latest change to the sources for the unit.

'13' package Asis.Elements

'13.3'  function Context_Clause_Elements
        - this function returns exactly those clauses and pragmas
          which are in the source for the unit.
        - returns Nil_Element_List for Nonexistent or Unknown unit.
        - returns Nil_Element_List for the predefined package
          Standard. For all other predefined Ada compilation units,
          returns their context clauses as they appear in the
          sources held in the GNAT Run-Time Library.

'13.5'  function Compilation_Pragmas
        - this function returns exactly those pragmas which are in
          the source for the unit, both in the context clause and
          after the end of the text of the compilation unit proper.
        - returns Nil_Element_List for Nonexistent or Unknown unit.

        - returns Nil_Element_List for the predefined package
          Standard. For all the other predefined Ada compilation
          units, returns the pragmas found in the corresponding
          sources in the GNAT Run-Time Library.

'13.36' function Enclosing_Element
        - ASIS-for-GNAT does not actually require the
          Element_Context parameter. The Enclosing_Element function
          with two parameters just calls the Enclosing_Element
          function with one parameter for its Element parameter.


'15' package Asis.Declarations

'15.24' function Body_Block_Statement
        - If the body passed as the actual has no declarative items
          on its own, Asis.Statements.Is_Declare_Block returns FALSE
          for the result of this function

'17' package Asis.Expressions

'17.6'  function Corresponding_Name_Definition
        - if an argument Reference name is declared implicitly, then
          if it denotes a user-defined inherited subprogram, the
          corresponding non-nil defining name Element is returned.
          Otherwise the function returns Nil_Element.

'17.8'  function Corresponding_Name_Declaration
        - if an argument Reference name is declared implicitly, then
          if it denotes a user-defined inherited subprogram, the
          corresponding non-nil declaration Element is returned.
          Otherwise the function returns Nil_Element.

'17.29' function Corresponding_Called_Function
        - For implicitly declared functions, if the actual is an
          expression that represents a call to an predefined
          operation, Nil_Element is returned. If it is a call to an
          implicitly declared user-defined inherited operation, the
          corresponding (implicit) function declaration is returned;

'18' package Asis.Statements

'18.14' function Is_Declare_Block
        - If the argument represents the dummy block statement
          created by Asis.Declarations.Body_Block_Statement
          function, the result will be True if and only if the
          corresponding body has declarative items on its own.


'20' package Asis.Text

'20.1'  type Line
        - Lines in ASIS-for-GNAT do not contain any character which
          signify end of line according to RM95, 2.2(2)

'20.22' function Delimiter_Image
        - Returns (wide) string of the length one and containing LF
         (wide) character.
@end smallexample


@node Restrictions Specific to -FS and -FM Context options
@section Restrictions Specific to -FS and -FM Context options

@noindent
The following queries from Asis.Compilation_Units are not implemented for a
Context associated with -FS or -FM Context option:

@smallexample
   Library_Unit_Declarations
   Compilation_Unit_Bodies
   Compilation_Units
   Corresponding_Children
   Corresponding_Body (formally, this function is implemented, but
                       it may give wrong results)
   Subunits
@end smallexample


@node Debugging Information, , Implementation-Specific Features and Implementation Permissions, Top
@chapter Debugging Information

@noindent
There are two kinds of the debugging information available in ASIS-for-GNAT -
debug images returned by the ASIS queries Debug_Image for Contexts,
Compilation Units and Elements, and debug output generated by ASIS queries
when the corresponding implementation debug flag is set ON during ASIS
initialization (see @ref{Parameters of AsisImplementationInitialize Procedure}).

@menu
* Interpreting Debug Images::
* ASIS Debug Flags::
@end menu

@node Interpreting Debug Images
@section Interpreting Debug Images

@noindent
It is easy to interpret the debug images generated for the main ASIS
abstractions, because most of the information being generated directly
corresponds to ASIS notions. The following details of debug images are
implementation-specific:

@itemize @bullet

@item Context

@table @code

@item Context Id
this is the internal Context Id used in the internal
implementation data structures. This Id is assigned to a
Context when it is associated for the first time, and it
remains unchanged and unique unlit ASIS is finalized.

@item All tree files
the number of the tree files making up the given Context

@end table

@item Compilation_Unit

@table @code

@item Unit Id
this is the internal Compilation_Unit Id used in the
internal implementation data structures. This Id remains
unchanged and unique unlit the unit's enclosed Context is closed.

@item Is consistent
TRUE if the same version of the unit's source was used for
all the tree files making up the enclosed unit's context,
and FALSE otherwise

@end table

@item Element

@table @code

@item Node, R_Node, Node_Field_1
tree nodes on which the internal representation of a given Element
is based. They are meaningful only in the tree file indicated in
the Enclosing_Tree field of the debug image

@item Special Case
implementation-specific indication of the cases when the
element needs some special processing

@item "obtained from the tree"
the Id and the name of the tree file from which
the tree-specific fields of the internal representation of
given Element were obtained

@item Rel_Sloc
indicates the (relative) position of the source text of the
Element, counting from the beginning of the source of its
enclosing compilation unit. Makes sense for implicit
Elements also.

@end table

@end itemize

@node ASIS Debug Flags, ,Interpreting Debug Images, Debugging Information
@section ASIS Debug Flags

ASIS provides several internal debug flags which are described in a_debug.adb.
Their setting generates (to stdout) useful internal debugging information.
This information is not always user-oriented, but the following debug flags
may be useful for the ASIS user:

@table @code
@item -dc
outputs the content of the internal data structures for a Context, when
        the Context is closed and dissociated. By analyzing this information,
        you may map other debug information onto unit and tree Ids.

@item -di
turns off including the location of an Element into its Debug_Image.
        It may be useful if an ASIS program crashes because of some problem
        with ASIS structural queries (structural queries are used by
        Element's Debug_Image query to compute the source location of the
        argument).

@item -do
when the Context is opened, lists the tree files being processed, and
        the ones selected to represent a given Context

@item -dt
outputs a message every time when a tree file is read in. This
        information may be useful to analyze the "tree swapping profile of
       your application to cut down the number of tree swapping.
@end table

@bye
