\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 _ R M                                 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_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
@include version.texi

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

@titlepage

@title ASIS-for-GNAT Reference Manual
@sp 2
@subtitle Document revision level 1.22
@subtitle Date: 2004/04/13 08:36:32
@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 Manual, (dir), (dir)
@top ASIS-for-GNAT Reference Manual
@noindent
ASIS-for-GNAT Reference Manual

@noindent
Document revision level 1.22
@*
Date: 2004/04/13 08:36:32
@*
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 Manual::
* ASIS-for-GNAT and the ASIS Standard::
* ASIS Extensions::
* Implementation-Specific Features and Implementation Permissions::
* Debugging Information::
* Index::

@detailmenu
 --- 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

* Asis.Extensions::
* Asis.Extensions.Flat_Kinds::
* Asis.Extensions.Iterator::

Implementation-Specific Features and Implementation Permissions

* Interacting with the Underlying Ada Implementation::
*   Format of the Parameters String::
*   Parameters of Asis.Implementation.Initialize::
*   Parameters of Asis.Implementation.Finalize::
*   Parameters of Asis.Ada_Environments.Associate::
* Implementation Permissions::
*   Asis.Implementation.Permissions 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::
* Dynamic Context Modes::

Debugging Information

* Interpreting Debug Images::
* ASIS Debug Flags::

Index
@end detailmenu
@end menu
@end ifinfo

@c ********************
@node About This Manual
@c ********************
@unnumbered About This Manual

@noindent
This Manual contains reference material for developers
using ASIS-for-GNAT --- GNAT's implementation of
the Ada Semantic Interface Specification (ASIS 95).
It provides information about ASIS-for-GNAT's implementation-specific@footnote{
The term ``implementation-specific'' in ASIS means what is
called ``implementation-defined'' in the Ada Reference Manual.
}
characteristics and
current implementation limitations.

ASIS has been designed as a portable basis for many kinds of Ada code
analysis tools. However, for situations where a developer may need to
exploit the characteristics of a particular Ada compiler,
ASIS also contains a number of implementation-specific
features.  These allow interfacing with the underlying Ada implementation, as
well as exploiting the implementation permissions for particular queries.

Of course, any ASIS application that uses implementation-specific features
may be nonportable. You should follow good programming practice and isolate
and clearly document any sections of your program that make use of such
features in a nonportable manner.

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

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

@noindent
This manual contains the following chapters:

@itemize @bullet
@item
@ref{ASIS-for-GNAT and the ASIS Standard}, describes the relationship
between ASIS-for-GNAT and the existing ASIS International Standard.

@item
@ref{ASIS Extensions}, describes the contents of the packages
@code{Asis.Extensions}, @code{Asis.Extensions.Flat_Kinds} and
@code{Asis.Extensions.Iterator}.

@item
@ref{Implementation-Specific Features and Implementation Permissions},
presents the aspects of the ASIS definition that are
implementation specific and describes their treatment in ASIS-for-GNAT.

@item
@ref{Debugging Information}, describes the kinds of debugging information that
you can generate with ASIS-for-GNAT.
@end itemize


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

@noindent
This Reference Manual assumes that you are familiar with Ada 95 language as
defined by the @cite{International Standard ISO/IEC-8652:1995}, and
with ASIS 95 as defined by the
@cite{ASIS 95 International Standard ISO/IEC 15291:1999}.

This Manual supplements the information presented in the
@cite{ASIS-for-GNAT User's Guide} and uses the terminology introduced there.


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

@noindent
For more information, please refer to the following documents:

@itemize @bullet
@item
@cite{GNAT User's Guide}

@item
@cite{ASIS-for-GNAT User's Guide}

@item
@cite{Ada 95 Reference Manual}

@item
@cite{ASIS 95 Standard}
@end itemize


@c **************************************
@node ASIS-for-GNAT and the ASIS Standard
@c **************************************
@chapter ASIS-for-GNAT and the ASIS Standard

@noindent
ASIS-for-GNAT implements ASIS 95@footnote{
If a query raises the @code{ASIS_Failed}
@cindex @code{ASIS_Failed} exception
exception with @code{Not_Implemented_Error}
@cindex @code{Not_Implemented_Error} error status
error status, this means that
some part of the functionality of the query is not implemented yet. If you
encounter such a situation, report it as an ordinary ASIS-for-GNAT bug. Our
goal is to have the full implementation of ASIS 95 conforming to the
ASIS Standard.}
and contains several extensions
(see @ref{ASIS Extensions}) as allowed by the @cite{ASIS Standard},
Section 1.1.3.1.

ASIS-for-GNAT declares all of the required@footnote{
The optional Data Decomposition Annex is not provided}
ASIS interface packages defined in the ASIS Standard.
The only differences between the GNAT and the standard ASIS versions of the packages are
that GNAT-for-ASIS:

@itemize @bullet
@item
includes GNAT-specific comment headers at the beginning of each source file;

@item
supplies additional context clauses;

@item
defines the packages' private parts;

@item
is formatted to comply with GNAT coding style;

@item
declares the @code{Is_Dispatching_Operation} query
@cindex @code{Is_Dispatching_Operation} query
in @code{Asis.Declarations}.
@cindex @code{Asis.Declarations} package
rather than in @code{Asis.Expressions}.
@cindex @code{Asis.Expressions} package
This query has @code{A_Declaration} @code{Element} as
 its argument and, according to the general principles of the ASIS package
 hierarchy, it should be in the @code{Asis.Declarations} spec.
@end itemize


@c ******************
@node ASIS Extensions
@c ******************
@chapter ASIS Extensions
@cindex ASIS Extensions

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

All the ASIS extensions obey the general ASIS rules:

@itemize @bullet
@item
When using ASIS
extensions, you have to follow the required sequencing of calls

@item
Only ASIS-defined exceptions propagate outside ASIS extension
queries
@end itemize

@noindent
If the documentation of an ASIS extension query contains a list of
``appropriate'' @code{Element} kinds, then the query can be applied only to @code{Element}s
from this list, and it raises @code{ASIS_Inappropriate_Element}
@cindex @code{ASIS_Inappropriate_Element} exception
with
@code{Value_Error}
@cindex @code{Value_Error} error status
status otherwise. If the documentation of an ASIS extension
query contains a list of ``expected'' element kinds, then the query can be
applied to an @code{Element} having any kind, but it returns a meaningful result only
for @code{Element}s 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. The @code{Asis.Extensions} hierarchy is not necessarily
frozen: some further extension queries may be added,
and suggestions from ASIS application developers are welcome.

Note that some of the ASIS extensions are implemented as ASIS @emph{secondary
queries} --- that is, the implementation of such a query is a sequence of primary
ASIS queries. Some other extensions are @emph{pure extensions}; that is, their
implementation is based on direct access to GNAT's internal data structures.

@menu
* Asis.Extensions::
* Asis.Extensions.Flat_Kinds::
* Asis.Extensions.Iterator::
@end menu


@c ******************
@node Asis.Extensions
@c ******************
@section @code{Asis.Extensions}
@cindex @code{Asis.Extensions} package

@noindent
This package, whose spec is located in the file
@file{asis-extensions.ads},
contains the declarations of various ASIS extensions, including
dynamic @code{Element} and @code{Compilation_Unit} list types, placeholder actual parameters
for @code{Asis.Iterator.Traverse_Element},
additional @code{Element} structural and
semantic queries, queries that return information about the status of the
source file for a @code{Compilation_Unit}, queries returning the (images
of the) values of static expressions, etc.


@c *****************************
@node Asis.Extensions.Flat_Kinds
@c *****************************
@section @code{Asis.Extensions.Flat_Kinds}
@cindex @code{Asis.Extensions.Flat_Kinds} package

@noindent
The ASIS @code{Element} classification hierarchy
is based on a set of Ada enumeration types,
each corresponding to a ``level'' in the hierarchy.
The package @code{Asis.Extensions.Flat_Kinds}, whose spec is located in the file
@file{asis-extensions-flat_kinds.ads},
defines the enumeration type @code{Flat_Element_Kinds};
@cindex @code{Flat_Element_Kinds} type
this type combines the values of all these types and thus provides
a ``flat'' view onto the syntactic @code{Element} classification.

@c *****************************
@node Asis.Extensions.Iterator
@c *****************************
@section @code{Asis.Extensions.Iterator}
@cindex @code{Asis.Extensions.Iterator} package

@noindent
This package, whose spec is located in the file
@file{asis-extensions-iterator.ads},
contains the declarations of @code{Traverse_Unit} generic procedure that
is a generalization of the standard ASIS @code{Asis.Iterator.Traverse_Element}
iterator. @code{Traverse_Unit} provides the depth-first traversal of the
whole syntactical structure of the ASIS Compilation Unit.

@c ******************************************************************
@node Implementation-Specific Features and Implementation Permissions
@c ******************************************************************
@chapter Implementation-Specific Features and Implementation Permissions
@cindex Implementation-specific features
@cindex Implementation permissions

@noindent
ASIS permits four kinds of implementation-specific behavior.

First, ASIS subprograms that define an interface between an ASIS
implementation and the underlying Ada implementation have
implementation-specific parameters. There are three such queries ---
@code{Asis.Implementation.Initialize},
@cindex @code{Asis.Implementation.Initialize} procedure
@code{Asis.Implementation.Finalize} and
@cindex @code{Asis.Implementation.Finalize} procedure
@code{Asis.Ada_Environments.Associate}.
@cindex @code{Asis.Ada_Environments.Associate} procedure
Each has a string parameter
named @code{Parameters} with an implementation-specific meaning. The meaning
of the @code{Parameters} string in ASIS-for-GNAT is discussed in
@ref{Interacting with the Underlying Ada Implementation}.

Second, in some areas the ASIS standard explicitly grants the
implementation permission to provide restricted functionality;
generally this allows omitting features that could present
considerable implementation difficulty.
Such permissions usually affect more than one ASIS query.
The ASIS package @code{Asis.Implementation.Permissions}
@cindex @code{Asis.Implementation.Permissions} package
contains boolean
queries identifying the choices made by a given ASIS implementation.
The ASIS-for-GNAT approach to these implementation permissions is discussed in
@ref{Implementation Permissions}.

Third, the ASIS standard defines specific implementation permissions
for some queries.
Also, the result of a query may be implementation specific because of the
nature of the query.
See
@ref{ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results}.

Finally, ASIS-for-GNAT provides special @code{Context} manipulation mechanisms that
supplement those defined in the ASIS standard.
These additional @code{Context} modes may be useful for
some ASIS applications.

@ifinfo
@menu
* Interacting with the Underlying Ada Implementation::
* Implementation Permissions::
* ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results::
* Dynamic Context Modes::
@end menu
@end ifinfo


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

@noindent
This section describes how to use the @code{Parameters} string to
pass implementation-specific information to several ASIS subprograms.

@ifinfo
@menu
* Format of the Parameters String::
* Parameters of Asis.Implementation.Initialize::
* Parameters of Asis.Implementation.Finalize::
* Parameters of Asis.Ada_Environments.Associate::
@end menu
@end ifinfo

@node Format of the Parameters String
@subsection Format of the @code{Parameters} String
@cindex @code{Parameters} string format

@noindent
A @code{Parameters} string is passed to three ASIS
subprograms: @code{Asis.Implementation.Initialize},
@cindex @code{Asis.Implementation.Initialize} procedure
@code{Asis.Implementation.Finalize},
@cindex @code{Asis.Implementation.Finalize} procedure
and @code{Asis.Ada_Environments.Associate}.
@cindex @code{Asis.Ada_Environments.Associate} procedure

The @code{Parameters} string comprises substrings delimited by separators.
The substrings are called @emph{parameters} (with lower-case 'p') below.
A separator is a non-empty string comprising characters from the set
@w{@code{@{ @code{<Space>},@code{<LF>}, @code{<CR>}@}}}.
There may be 0 or more parameters in a @code{Parameters} string, and there
may be separators before the first and/or after the last parameter.

Each of the queries @code{Asis.Implementation.Initialize},
@code{Asis.Implementation.Finalize}, and
@code{Asis.Ada_Environments.Associate} has specific rules for the
format of its parameters.
If some parameter is not well-formed,
then either a warning message is generated or else
the @code{ASIS_Failed}
@cindex @code{ASIS_Failed} exception
exception is raised with the @code{Parameter_Error} status.
@cindex @code{Parameter_Error} error status
The descriptions below explain the situations where
@code{ASIS_Failed} is raised.


@c ***********************************************
@node Parameters of Asis.Implementation.Initialize
@c ***********************************************
@subsection Parameters of @code{Asis.Implementation.Initialize}
@cindex @code{Asis.Implementation.Initialize} procedure

@noindent
The allowed parameters for @code{Asis.Implementation.Initialize} are as follows:

@table @code
@item -d<flag>
The specific ASIS-for-GNAT debug flag named @code{<flag>} is set ON
@cindex Debug flag parameter (to @code{Asis.Implementation.Initialize})

@item -dall
All the ASIS-for-GNAT debug flags are set ON

@item -k
Keep going even if an internal implementation error is detected.
When a non-ASIS exception is raised, it is replaced by
raising @code{ASIS_Failed} with @code{Unhandled_Exception_Error} status (this is
the only case when @code{Unhandled_Exception_Error} is set) and the
@code{Diagnosis} string containing the name and the message from the
non-ASIS exception originally raised

@item -nbb
No bug box. Do not output to @code{Standard_Error} the bug box
containing the description of the internal implementation bug. Implies @code{-k}

@item -vs
Set the strong GNAT/ASIS version check when reading the tree files

@item -we
All ASIS warnings are treated as errors.
@cindex Warning messages
When execution reaches the point where the warning would occur,
the @code{ASIS_Failed}
@cindex @code{ASIS_Failed} exception
exception is raised;
the warning message is the ASIS @code{Diagnosis} string.
@cindex @code{Diagnosis} string

@item -ws
All ASIS warning messages are suppressed.
@end table

@noindent
The @code{<flag>} value for the @option{-d} parameter
may be any lower case letter from @code{a} through @code{z} or any digit
from @code{0} through @code{9}, although
not all of the 36 possible flags are implemented.
For more information,
refer to the documentation in the source file @file{a4g-a_debug.adb}.
See also @ref{ASIS Debug Flags}.

If more then one parameter controlling the warning mode
@cindex Warning messages
is set in the @code{Parameters} string, all but the last one are ignored.


@c *********************************************
@node Parameters of Asis.Implementation.Finalize
@c *********************************************
@subsection Parameters of @code{Asis.Implementation.Finalize}
@cindex @code{Asis.Implementation.Finalize} procedure

@noindent
No parameters are allowed for @code{Asis.Implementation.Finalize}.

@code{Asis.Implementation.Finalize} resets all the general
ASIS-for-GNAT parameters to their default values (that is, all the debug flags
are set OFF, and the warning mode is set to the default warning mode).


@c ************************************************
@node Parameters of Asis.Ada_Environments.Associate
@c ************************************************
@subsection Parameters of @code{Asis.Ada_Environments.Associate}
@cindex @code{Asis.Ada_Environments.Associate} procedure

@noindent
The following parameters are allowed:

@table @code
@item -C1
The @code{Context} comprises a single tree file,
@cindex Tree file
whose name is given as the next parameter in the @code{Parameters} string.

@item -CN
The @code{Context} comprises a set of one or more tree files, whose names are
given as the next set of parameters in the @code{Parameters} string.

@item -CA
The @code{Context} comprises all the tree files in the tree search path.

@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 then is reused as long as the @code{Context} remains open.

@item -FT
Only pre-created trees are used; no tree files are created by ASIS.

@item -FM
Mixed approach: if a needed tree does not exist, an attempt is made to create
 it ``on the fly''.

@item -SA
Source files for all the @code{Compilation_Unit}s belonging to the
@code{Context} (except
 the predefined @code{Standard} package) are considered in the consistency
 check when opening the @code{Context}.
@cindex Consistency checking

@item -SE
Only existing source files for all the @code{Compilation_Units} belonging to the
@code{Context} are considered in the consistency check when opening the @code{Context}.

@item -SN
No source files from the underlying file system are taken into account when
checking the consistency of the set of tree files making up the @code{Context}.

@item -I<dir>
Defines the directory in which to search for source files when compiling sources to
 create a tree ``on the fly''.

@item --GCC=@var{compiler_name}
Defines the program to be called to create the tree on the fly

@item -gnatec<file>
Defines the additional configuration file to be used when calling GNAT to create
 the tree on the fly for @option{-FS} or @option{-FM} Context

@item -gnatA
Avoid processing @file{gnat.adc} when calling GNAT to create
 the tree on the fly for @option{-FS} or @option{-FM} Context

@item -T<dir>
Defines the directory in which to search for a tree file.

@item <file_name>
Defines the name of a tree file (used in conjunction with @option{-C1} or @option{-CN}).
@end table

@noindent
For the @option{-I} and @option{-T} parameters, @code{<dir>} should denote an existing
directory in the underlying file system. The ``.'' and ``..'' notations are
allowed, as well as relative or absolute directory names.
If @code{<dir>} does not denote an existing directory, @code{ASIS_Failed}
@cindex @code{ASIS_Failed} exception
with @code{Parameter_Error} status is raised.

For ASIS @option{-FS} or @option{-FM} Context, Context parameters @option{-I},
@option{-gnatec} and @option{-gnatA} are passed to the GNAT call to create
the tree on the fly and these parameters have exactly the same meaning as they
have for GNAT.

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

Any relative directory name or file name containing relative directory
information should start from ``.'' or ``..''.

The search path
@cindex Search path
associated with an ASIS @code{Context} consists of the directories
listed as parameters for the @code{Asis.Ada_Environments.Associate} query, in
the same order as they are included in the actual @code{Parameters} string.
The ASIS source search path consists only of the directories following
@option{-I}, and the ASIS tree search path consists only of the directories
following @option{-T}. If no source (tree) directories are present in the value of
the @code{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 and only if it is set explicitly as @option{-I.} or
@option{-T.} respectively.

If an ASIS @code{Context} is associated with an @option{-FS} or @option{-FM} option, the
@code{Context} source search path is used to locate sources of the units for which
tree files need to be created, and to locate other source files needed during compilation.
For example, if we have:

@smallexample @c ada
Asis.Ada_Environments.Associate
  (My_Context,
  "My_Context_Name",
  "-CA -FS -I./dir -I.");
@end smallexample

@noindent
then, when processing a call:

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

@noindent
ASIS first tries to locate the source file @file{foo.ads} in @file{./dir}, and
if this attempt fails, it tries to locate it in the current directory. If the
source file is found (say in the current directory), ASIS
creates the tree file by calling the compiler:

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

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

The following further rules define the required combinations of parameters
in the actual @code{Parameters} string:

@itemize @bullet
@item
@option{-C1} and @option{-CN} require @option{-FT}

@item
@option{-FS} and @option{-FM} require @option{-SA}
@end itemize

@noindent
In case an incompatible combination is set, @code{ASIS_Failed}
@cindex @code{ASIS_Failed} exception
with @code{Parameter_Error}
@cindex @code{Parameter_Error} error status
status is raised.

If the actual @code{Parameters} string passed to
@code{Associate} contains no parameters, the default parameters
are @option{-CA}, @option{-FT}, and @option{-SA}.

The @option{-FS} and @option{-FM} options define @emph{dynamic Context modes};
@cindex Dynamic @code{Context} modes
they allow the content of a @code{Context} (that is, the set
of ASIS @code{Compilation_Unit}s contained in the @code{Context}) to be changed while
the @code{Context} is open. See @ref{Dynamic Context Modes} for
more details.

For the @code{Name} parameter
@cindex @code{Name} parameter (to @code{Asis.Ada_Environments.Associate})
of the @code{Asis.Ada_Environments.Associate}
query, any string can be passed as an actual parameter.
No verification is performed on the contents, and no semantics are
associated with this parameter.


@c *****************************
@node Implementation Permissions
@c *****************************
@section Implementation Permissions
@cindex Implementation permissions

@noindent
This section describes how ASIS-for-GNAT deals with
implementation permissions.

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


@c ******************************************
@node Asis.Implementation.Permissions Queries
@c ******************************************
@subsection @code{Asis.Implementation.Permissions} Queries
@cindex @code{Asis.Implementation.Permissions} queries

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

@multitable {@code{Is_Formal_Parameter_Named_Notation_Supported}} {@code{False} (*)}
@item @emph{Query} @tab @emph{Value}
@item @code{Is_Formal_Parameter_Named_Notation_Supported} @tab @code{True}
@item @code{Default_In_Mode_Supported}                    @tab @code{True}
@item @code{Generic_Actual_Part_Normalized}               @tab @code{False}
@item @code{Record_Component_Associations_Normalized}     @tab @code{False}
@item @code{Is_Prefix_Call_Supported}                     @tab @code{True}
@item @code{Function_Call_Parameters_Normalized}          @tab @code{False}
@item @code{Call_Statement_Parameters_Normalized}         @tab @code{False}
@item @code{Discriminant_Associations_Normalized}         @tab @code{False}
@item @code{Is_Line_Number_Supported}                     @tab @code{True}
@item @code{Is_Span_Column_Position_Supported}            @tab @code{True}
@item @code{Is_Commentary_Supported}                      @tab @code{True}
@item @code{Attributes_Are_Supported}                     @tab @code{False}
@item @code{Implicit_Components_Supported}                @tab @code{False} (*)
@item @code{Object_Declarations_Normalized}               @tab @code{False}
@item @code{Predefined_Operations_Supported}              @tab @code{False} (*)
@item @code{Inherited_Declarations_Supported}             @tab @code{False} (*)
@item @code{Inherited_Subprograms_Supported}              @tab @code{False} (*)
@item @code{Generic_Macro_Expansion_Supported}            @tab @code{True}
@end multitable

@noindent
(*) See also @ref{Processing Implicit Elements}.


@c *******************************
@node Processing Implicit Elements
@c *******************************
@subsection Processing Implicit @code{Element}s
@cindex Implicit @code{Element}s

@noindent
ASIS @code{Element}s represent both explicit and implicit@footnote{
An example of an implicit construct is a derived subprogram.}
components of Ada programs.
Some ASIS queries can return implicit @code{Element}s (that is,
@code{Element}s representing implicit Ada constructs). Any syntactic or semantic query
should accept an implicit @code{Element} as an @code{Element} parameter, but
the ASIS Standard allows an implementation not to support
implicit @code{Element}s at all, or to support them only partially. If an
implementation does not support the implicit @code{Element} representing a particular
kind of construct, then an ASIS query that is supposed to process
this implicit @code{Element} should
return either a @code{Nil_Element} or a @code{Nil_Element_List}
depending on whether the query returns a single @code{Element} or an @code{Element_List}.

Implicit @code{Element}s are partially supported by ASIS-for-GNAT.

ASIS-for-GNAT supports implicit @code{Element}s for the following constructs:

@itemize @bullet
@item Derived user-defined subprograms
@item Derived enumeration literals
@item Derived record components
@end itemize

@noindent
ASIS-for-GNAT does not
support implicit @code{Element}s representing implicit declarations of predefined
type operations (such as ``@code{=}'', or the ``@code{+}'' operation for numeric types).


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

@noindent
According to the ASIS Standard, the number of ASIS @code{Context}s that can be
associated and opened at a time, as well as the number of ASIS
@code{Compilation_Unit}s that can be processed at a time, are implementation specific.
ASIS-for-GNAT does not impose any restriction on the number of @code{Context}s
opened at the same time, or on the number of
@code{Compilation_Unit}s that can be obtained from all the opened @code{Context}s, as long
as the application does not go beyond general system resource limitations.
@cindex Implementation limits

However, for a @code{Context} associated with an @option{-FS} or @option{-FM} option,
all the trees created ``on the fly'' while obtaining @code{Compilation_Unit}s from this
@code{Context} are placed in the current directory. If the current directory also contains
some tree files belonging to another @code{Context}, the latter may become corrupted. To
process more than one @code{Context} safely, an application should have at
most one @code{Context} associated with the @option{-FS} or @option{-FM} option. Moreover, if
among @code{Context}s processed at the same time there is one that can create
trees ``on the fly'', then the other @code{Context}s should not use tree files located in
the current directory.


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

@noindent
All the implementation-defined types, subtypes and values depend on the
subtype @code{Implementation_Defined_Integer_Type}
@cindex @code{Implementation_Defined_Integer_Type} subtype
and on the
@code{Implementation_Defined_Integer_Constant}
@cindex @code{Implementation_Defined_Integer_Constant}  named number
defined in package @code{Asis}.
ASIS-for-GNAT's declarations for these entities are the same as in the ASIS Standard:

@smallexample @c ada
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 ASIS array types have
@code{Implementation_Defined_Integer_Constant} as an upper bound.


@c *********************************************************************************************
@node ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results
@c *********************************************************************************************
@section ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results
@cindex Implementation permissions

@noindent
This section documents
queries having implementation permissions (given under @code{--|IP} sentinel
in the ASIS definition) and queries whose behavior is otherwise
implementation specific. Such queries are presented below
in their order of appearance in the ASIS Standard.
The clause and subclause numbers shown are those from the ASIS Standard.

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

@subheading @cite{ASIS 8} @code{package Asis.Ada_Environments}
@cindex @code{Asis.Ada_Environments} implementation permissions

@noindent
@cite{ASIS 8.1} @code{function Default_Name}
@cindex @code{Default_Name} function (implementation permissions)
@itemize @bullet
@item
Null string is returned.
@end itemize

@noindent
@cite{ASIS 8.2}  @code{function Default_Parameters}
@cindex @code{Default_Parameters} function (implementation permissions)
@itemize @bullet
@item
Null string is returned;.
@end itemize

@noindent
@cite{ASIS 8.4}  @code{procedure Open}
@cindex @code{Open} procedure  (implementation permissions)
@itemize @bullet
@item
For a @code{Context} associated with the @option{-CA} option:

@itemize @bullet
@item
If @option{-FS} is also set, nothing is done.

@item
If the @option{-FT} or @option{-FM} is set, all the tree files (that is,
  files having @file{.adt} suffix) in the tree search path
  associated with the @code{Context} are processed.
  ASIS reads in each tree file and checks
  that it was created with
  the @option{-gnatc} option. Tree files that cannot be read in or
  that were not created with the @option{-gnatc} option are ignored.
  For each other tree ASIS collects some ``black-box''
  information about the @code{Compilation_Unit}s that it represents,
  and performs a consistency check
@cindex Consistency checking
  for every unit it encounters in the tree (see @cite{ASIS-for-GNAT
  User's Guide} for a discussion of the consistency
  problem). If any consistency check fails, @code{ASIS_Failed}
@cindex @code{ASIS_Failed} exception
  is raised and the @code{Context} remains closed.
@end itemize

@item
For a @code{Context} associated with a @option{-C1} or @option{-CN} option, ASIS
  processes all the tree files associated with the @code{Context},
  collecting ``black-box'' information and performing consistency
  checks for all the encountered Compilation Units.
  If for any reason a tree file cannot be
  successfully read in for a @code{Context} associated with a @option{-C1}
  option, @code{ASIS_Failed} is raised and the @code{Context} remains
  closed.
  If a tree read fails for a @code{Context} associated with a @option{-CN} option,
  an ASIS warning
@cindex Warning messages
  is generated and the @code{Context} opening process continues.
  If any consistency check fails, @code{ASIS_Failed}
@cindex @code{ASIS_Failed} exception
  is raised and the @code{Context} remains closed.
@end itemize

@subheading @cite{ASIS 9} @code{package Asis.Ada_Environments.Containers}
@cindex @code{Asis.Ada_Environments.Containers} implementation permissions

@itemize @bullet
@item
 ASIS-for-GNAT supports the trivial @code{Container} model. Every @code{Context}
 contains exactly one @code{Container}, whose content and name
 are the same as its enclosing @code{Context}
@end itemize

@subheading @cite{ASIS 10} @code{package Asis.Compilation_Units}
@cindex @code{Asis.Compilation_Units} implementation permissions

@noindent
@cite{ASIS 10.3}  @code{function Unit_Origin}
@cindex @code{Unit_Origin} function (implementation permissions)

@itemize @bullet
@item
@code{A_Predefined_Unit} origin is returned for those compilation units
@cindex @code{A_Predefined_Unit}
listed in RM95, Annex A(2), and only for these units.

@item
@code{An_Implementation_Unit} origin is returned for compilation
@cindex @code{An_Implementation_Unit}
units that are the components of the GNAT Run-Time
Library, but that are not listed in RM95, Annex A(2).

@item
@code{An_Application_Unit} origin is returned for all other
@cindex @code{An_Application_Unit}
compilation units.
@end itemize

@noindent
@cite{ASIS 10.6} @code{function Library_Unit_Declaration} and @cite{ASIS 10.7} @code{function Compilation_Unit_Body}
@cindex @code{Library_Unit_Declaration} function (implementation permissions)
@cindex @code{Compilation_Unit_Body} function (implementation permissions)

@itemize @bullet
@item
When processing a @code{Context} associated with an @option{-FS} or @option{-FM} option,
if ASIS cannot find a needed unit in the tree files
that 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 for any reason, @code{Nil_Compilation_Unit} is returned.
@end itemize

@noindent
@cite{ASIS 10.13} @code{function Corresponding_Declaration}
@cindex @code{Corresponding_Declaration} function (implementation permissions)

@itemize @bullet
@item
ASIS-for-GNAT does not make use of ASIS @code{Compilation_Unit}s
of @code{An_Unknown_Unit} kind.
@cindex @code{An_Unknown_Unit}

@item
If an argument is of @code{A_Public_Declaration_And_Body} class,
@code{Nil_Compilation_Unit} is returned.
@end itemize

@noindent
@cite{ASIS 10.14} @code{function Corresponding_Body}
@cindex @code{Corresponding_Body} function (implementation permissions)

@itemize @bullet
@item
ASIS-for-GNAT does not make use of ASIS @code{Compilation_Unit}s
of @code{An_Unknown_Unit} kind.
@end itemize

@noindent
@cite{ASIS 10.22} @code{function Can_Be_Main_Program}
@cindex @code{Can_Be_Main_Program} function (implementation permissions)

@itemize @bullet
@item
For GNAT, any parameterless library procedure and any parameterless library
function returning a result of an integer type is classified by this
 query as a (possible) main subprogram for a partition.

@item
If for such a library subprogram both spec and body exist as ASIS
@code{Compilation_Unit}s retrievable from a given ASIS @code{Context}, both are considered as
 @code{Can_Be_Main_Program}.
@end itemize

@noindent
@cite{ASIS 10.24} @code{function Text_Name}
@cindex @code{Text_Name} function (implementation permissions)

@itemize @bullet
@item
This function returns the name of the source file containing the source of
 @code{Compilation_Unit}. This name may or may not contain a prefix denoting the
 directory in the underlying file system.  If present, the directory may be
 given in absolute or relative form, depending on the command line options
 that were used for the call to GNAT that created the corresponding tree
 file.

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

@item
Use the query @code{Asis.Extensions.Source_File_Status} to get the information
 about the current status of the source file for a @code{Compilation_Unit}.
@end itemize

@noindent
@cite{ASIS 10.25} @code{function Text_Form}
@cindex @code{Text_Form} function (implementation permissions)

@itemize @bullet
@item
In the GNAT compilation model all source files are ordinary text files in the
 underlying file system. Therefore this function always returns a
 @code{Nil_Asis_String} to indicate that @code{Text_IO.Open} uses the default
 options for manipulating Ada sources.
@end itemize

@noindent
@cite{ASIS 10.26} @code{function Object_Name}
@cindex @code{Object_Name} function (implementation permissions)

@itemize @bullet
@item
Returns a null string. In the GNAT environment, creating an object file has
no connection with creating trees for ASIS.
@end itemize

@noindent
@cite{ASIS 10.27} @code{function Object_Form}
@cindex @code{Object_Form} function (implementation permissions)

@itemize @bullet
@item
Returns a null string.
@end itemize

@noindent
@cite{ASIS 10.29} @code{function Has_Attribute}
@cindex @code{Has_Attribute} function (implementation permissions)

@itemize @bullet
@item
Returns @code{False}. ASIS-for-GNAT does not provide any additional attributes for
 Compilation Units.
@end itemize

@noindent
@cite{ASIS 10.30} @code{function Attribute_Value_Delimiter}
@cindex @code{Attribute_Value_Delimiter} function (implementation permissions)

@itemize @bullet
@item
 Returns a wide string of length one containing the @code{LF} wide
  character.
@end itemize

@noindent
@cite{ASIS 10.31} @code{function Attribute_Values}
@cindex @code{Attribute_Values} function (implementation permissions)

@itemize @bullet
@item
A null string is returned.
@end itemize

@subheading @cite{ASIS 11} @code{package Asis.Compilation_Units.Times}
@cindex @code{Asis.Compilation_Units.Times} implementation permissions

@noindent
@cite{ASIS 11.2}  @code{function Time_Of_Last_Update}
@cindex @code{Time_Of_Last_Update} function (implementation permissions)

@itemize @bullet
@item
This function returns the time stamp (the time of the latest change)
of the corresponding
 source file. The corresponding source file is the source file whose name is
 returned by @code{Asis.Compilation_Units.Text_Name}.
@end itemize

@noindent
@cite{ASIS 11.3}  @code{function Compilation_CPU_Duration}
@cindex @code{Compilation_CPU_Duration} function (implementation permissions)

@itemize @bullet
@item
This function always returns zero duration, because the CPU compilation
 duration concept does not apply to ASIS-for-GNAT
@end itemize

@noindent
@cite{ASIS 11.4}  @code{function Attribute_Time}
@cindex @code{Attribute_Time} function (implementation permissions)

@itemize @bullet
@item
This function always returns @code{Nil_ASIS_Time} because
 ASIS-for-GNAT does not provide any @code{Compilation_Unit} attributes
@end itemize


@subheading @cite{ASIS 13} @code{package Asis.Elements}
@cindex @code{Asis.Elements} implementation permissions

@noindent
@cite{ASIS 13.3}  @code{function Context_Clause_Elements}
@cindex @code{Context_Clause_Elements} function (implementation permissions)

@itemize @bullet
@item
This function returns exactly those clauses and pragmas that are in the
 source for the unit.

@item
Returns @code{Nil_Element_List} if the argument unit is of
@code{A_Nonexistent_Declaration}, @code{A_Nonexistent_Body} or
@code{An_Unknown_Unit} kind

@item
Returns @code{Nil_Element_List} for the predefined package @code{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.
@end itemize

@noindent
@cite{ASIS 13.4}  @code{function Configuration_Pragmas}
@cindex @code{Configuration_Pragmas} function (implementation permissions)

@itemize @bullet
@item
This function always returns @code{Nil_Element_List}, because in the GNAT
compilation environment ``a list of pragmas that apply to all future
 compilation_unit elements compiled into @code{The_Context}'' essentially depends
on the GNAT options set when compiling a unit (in particular the @option{-gnatA}
and @option{-gnatec} options), and this cannot be determined from the
content of the given @code{Context}.
@end itemize

@noindent
@cite{ASIS 13.5}  @code{function Compilation_Pragmas}
@cindex @code{Compilation_Pragmas} function (implementation permissions)

@itemize @bullet
@item
If the argument unit has been compiled on its own to produce a corresponding
tree file, then the result contains the configuration pragmas from the
GNAT configuration file(s) involved in this compilation. Otherwise  (that is, if
the argument unit has been compiled only as an effect of compiling some other
unit), the result contains only those pragmas that belong to
the unit's source file.

@item
A pragma that appears in the unit's context clause is included in the result
 list only if it is a configuration pragma.

@item
Returns @code{Nil_Element_List} for the predefined package @code{Standard}.
@end itemize

@noindent
@cite{ASIS 13.31} @code{function Is_Equal}
@cindex @code{Is_Equal} function (implementation permissions)

@itemize @bullet
@item
Two elements representing configuration pragmas belonging to
@code{A_Configuration_Compilation} unit (or components thereof) are considered
as being equal only if they are created by the same compilation (belong
to the same tree).
@end itemize

@noindent
@cite{ASIS 13.36} @code{function Enclosing_Element}
@cindex @code{Enclosing_Element} function (implementation permissions)

@itemize @bullet
@item
ASIS-for-GNAT does not require the @code{Element_Context} parameter.
 The @code{Enclosing_Element} function with two parameters just calls the
 @code{Enclosing_Element} function with one parameter for its @code{Element}
 parameter.
@end itemize


@subheading @cite{ASIS 15} @code{package Asis.Declarations}
@cindex @code{Asis.Declarations} implementation permissions

@noindent
@cite{ASIS 15.24} @code{function Body_Block_Statement}
@cindex @code{Body_Block_Statement} function (implementation permissions)

@itemize @bullet
@item
If the body passed as the actual parameter has no declarative items of its own,
 @code{Asis.Statements.Is_Declare_Block} returns @code{False}.
@end itemize


@subheading @cite{ASIS 18} @code{package Asis.Statements}
@cindex @code{Asis.Statements} implementation permissions

@noindent
@cite{ASIS 18.14} @code{function Is_Declare_Block}
@cindex @code{Is_Declare_Block} function (implementation permissions)

@itemize @bullet
@item
If the argument represents the dummy block statement created by
 @code{Asis.Declarations.Body_Block_Statement} function, the result will be
 @code{True} if and only if the corresponding body has declarative items.
@end itemize


@subheading @cite{ASIS 20} @code{package Asis.Text}
@cindex @code{Asis.Text} implementation permissions

@noindent
@cite{ASIS 20.1} @code{type Line}
@cindex @code{Line} type (implementation permissions)

@itemize @bullet
@item
Lines in ASIS-for-GNAT do not contain any end-of-line characters
 (see RM95, 2.2(2)).
@end itemize

@noindent
@cite{ASIS 20.22} @code{function Delimiter_Image}
@cindex @code{Delimiter_Image} function (implementation permissions)

@itemize @bullet
@item
Returns a wide string of length one, containing the @code{LF} wide character.
@end itemize


@c ************************
@node Dynamic Context Modes
@c ************************
@section Dynamic @code{Context} Modes
@cindex Dynamic @code{Context} modes

@noindent
If an ASIS @code{Context} is defined with an @option{-FS} or @option{-FM} option, then ASIS
may compile sources ``on the fly'' to obtain @code{Compilation_Unit}s.
Thus the content of the @code{Context} will not necessarily remain frozen when the @code{Context}
is open --- when ASIS gets a new @code{Compilation_Unit}, it
``adds'' it to the @code{Context}.  The @option{-FS} and @option{-FM} options are referred
to as @emph{dynamic Context modes}.

The difference between the two modes is as follows:

@table @option
@item -FS
ASIS does not take into account any existing tree file when opening a @code{Context}.

@item -FM
ASIS first processes the tree files in the tree search
path.  If a given @code{Compilation_Unit} is present in the existing set of
tree files, these tree files are used; otherwise ASIS tries to locate the source of the unit
and to compile it to produce a tree file.
@end table

@noindent
For both @option{-FS} and
@option{-FM} @code{Context}s, once a tree file
@cindex Tree file
is created it is added to the set of tree
files making up the @code{Context} and then it is reused (without recreating it from
sources again) for the queries dealing with @code{Compilation_Unit}s represented by
this tree.

An advantage of these dynamic @code{Context} modes is that you do not have to
create the tree files explicitly; to users of an ASIS application based on
such @code{Context} modes the application appears to operate directly from source files. But
there is also a
drawback, a consequence of the fact that the content of a @code{Context} may change while
the @code{Context} is open: some ASIS queries dealing
with @code{Compilation_Unit}s or returning lists of @code{Compilation_Unit}s
raise the @code{ASIS_Failed}
@cindex @code{ASIS_Failed} exception
exception (with @code{Use_Error}
@cindex @code{Use_Error} error status
status).
These queries are as follows:

@smallexample
Asis.Compilation_Units:
     Library_Unit_Declarations
     Compilation_Unit_Bodies
     Compilation_Units
     Corresponding_Children
@end smallexample


@c ************************
@node Debugging Information
@c ************************
@chapter Debugging Information
@cindex Debugging information

@noindent
There are two kinds of the debugging information available in ASIS-for-GNAT ---
debug images returned by the ASIS query @code{Debug_Image}
@cindex @code{Debug_Image} query
(for @code{Context}s,
@code{Compilation_Unit}s and @code{Element}s); and debug output generated by ASIS queries
when the corresponding implementation debug flag is set ON during ASIS
initialization (see @ref{Parameters of Asis.Implementation.Initialize}).

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

@c ****************************
@node Interpreting Debug Images
@c ****************************
@section Interpreting Debug Images
@cindex Debug images

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

@table @code
@item Context

@table @asis
@item @code{Context} Id

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

@item All tree files

The number of tree files making up the given @code{Context}.
@end table

@item Compilation_Unit

@table @asis
@item @code{Compilation_Unit} Id

This is the internal @code{Compilation_Unit} Id used in the
 implementation data structures. This Id remains
 unchanged and unique until the unit's enclosed @code{Context} is closed.

@item Is consistent

@code{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 @code{False} otherwise
@end table

@item Element

@table @asis
@item Node, R_Node, Node_Field_1

Tree nodes on which the internal representation of a given @code{Element}
 is based. They are meaningful only in the tree file indicated in
 the @code{Enclosing_Tree} field of the debug image

@item Special Case

Implementation-specific indication of the cases when the
 @code{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 @code{Element} were obtained

@item @code{Rel_Sloc}

Indicates the (relative) position of the source text of the
 @code{Element}, counting from the beginning of the source of its
 enclosing compilation unit. Applies to implicit
 @code{Element}s also.

@end table

@end table

@c *******************
@node ASIS Debug Flags
@c *******************
@section ASIS Debug Flags
@cindex Debug flags

@noindent
ASIS provides several internal debug flags, which are described in
@file{a_debug.adb}. When one or more of these flags is set,
useful internal debugging information is directed to @code{Standard_Output}.
Although this information is not always user-oriented, you
may find the following debug flags helpful when you are developing an ASIS
application:

@table @code
@item -dc
Outputs the content of the internal data structures for a @code{Context}, when
        the @code{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 @code{Element} into the result generated by
        @code{Debug_Image}. This may be useful if an ASIS program crashes
        because of some problem with ASIS structural queries (structural
        queries are used by @code{Element}'s @code{Debug_Image} query to compute the
        source location of the argument).

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

@item -dt
Outputs a message whenever a tree file is read in. This
        information may be useful for analyzing and reducing the ``tree swapping profile''
@cindex Tree swapping profile
        of your application.

@end table


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

@contents
@bye