File: asis_ug_4.html

package info (click to toggle)
asis 2008-5
links: PTS
area: main
in suites: squeeze
size: 9,724 kB
ctags: 615
sloc: ada: 95,867; makefile: 259; xml: 19
file content (647 lines) | stat: -rw-r--r-- 31,452 bytes
<HTML>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created on May, 22  2008 by texi2html 1.64-gnat-1 -->
<!-- 
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
            Karl Berry  <karl@freefriends.org>
            Olaf Bachmann <obachman@mathematik.uni-kl.de>
            and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
 
-->
<HEAD>
<TITLE>ASIS-for-GNAT User's Guide: ASIS Overview</TITLE>
<META NAME="description" CONTENT="ASIS-for-GNAT User's Guide: ASIS Overview">
<META NAME="keywords" CONTENT="ASIS-for-GNAT User's Guide: ASIS Overview">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64-gnat-1">

</HEAD>

<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">

<A NAME="SEC16"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_3.html#SEC15"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC17"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_15.html#SEC56">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 3. ASIS Overview </H1>
<!--docid::SEC16::-->
<P>

This chapter contains a short overview of the ASIS definition as given in
the ISO/IEC 15291:1999 ASIS Standard. This overview is aimed at helping an ASIS
newcomer find needed information in the ASIS definition.
<A NAME="IDX48"></A>
</P><P>

For more details, please refer to the ASIS definition itself. To gain some initial
experience with ASIS, try the examples in <A HREF="asis_ug_8.html#SEC45">7. ASIS Tutorials</A>.
</P><P>

<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0> 
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="asis_ug_4.html#SEC17">3.1 Main ASIS Abstractions</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="asis_ug_4.html#SEC18">3.2 ASIS Package Hierarchy</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="asis_ug_4.html#SEC19">3.3 Structural and Semantic Queries</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="asis_ug_4.html#SEC20">3.4 ASIS Error Handling Policy</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="asis_ug_4.html#SEC21">3.5 Dynamic Typing of ASIS Queries</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="asis_ug_4.html#SEC22">3.6 ASIS Iterator</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="asis_ug_4.html#SEC23">3.7 How to Navigate through the <CODE>Asis</CODE> Package Hierarchy</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
</TABLE></BLOCKQUOTE>
<P>

<A NAME="Main ASIS Abstractions"></A>
<HR SIZE="6">
<A NAME="SEC17"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC18"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_15.html#SEC56">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 3.1 Main ASIS Abstractions </H2>
<!--docid::SEC17::-->
<P>

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

<DL COMPACT>
<DT><CODE>Context</CODE>
<DD><A NAME="IDX49"></A>
An ASIS <CODE>Context</CODE> is a logical handle to an Ada environment, as defined in the
<CITE>Ada Reference Manual</CITE>,
Chapter 10. An ASIS application developer may view an ASIS <CODE>Context</CODE> as a way
to define a set of compilation units available through the ASIS queries.
<A NAME="IDX50"></A>
<P>

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

<DT><CODE>Element</CODE>
<DD><A NAME="IDX53"></A>
An ASIS <CODE>Element</CODE> is a logical handle to a syntactic component of an ASIS
<CODE>Compilation_Unit</CODE> (either explicit or implicit).
</DL>
<P>

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

<DL COMPACT>
<DT><CODE>Container</CODE>
<DD><A NAME="IDX54"></A>
An ASIS <CODE>Container</CODE> (defined by the
<CODE>Asis.Ada_Environments.Containers</CODE> package)
<A NAME="IDX55"></A>
provides a means for
structuring the content of an ASIS <CODE>Context</CODE>; i.e., ASIS <CODE>Compilation_Unit</CODE>s
are grouped into <CODE>Container</CODE>s.
<P>

<DT><CODE>Line</CODE>
<DD><A NAME="IDX56"></A>
An ASIS <CODE>Line</CODE> (defined by the <CODE>Asis.Text</CODE> package)
<A NAME="IDX57"></A>
is the
abstraction of a line of code in an Ada source text. An ASIS <CODE>Line</CODE> has a length, a
string image and a number.
<P>

<DT><CODE>Span</CODE>
<DD><A NAME="IDX58"></A>
An ASIS <CODE>Span</CODE> (defined by the <CODE>Asis.Text</CODE> package)
<A NAME="IDX59"></A>
defines the
location of an <CODE>Element</CODE>, a <CODE>Compilation_Unit</CODE>, or a whole compilation in the
corresponding source text.
<P>

<DT><CODE>Id</CODE>
<DD><A NAME="IDX60"></A>
An ASIS <CODE>Id</CODE> (defined by the <CODE>Asis.Ids</CODE>
<A NAME="IDX61"></A>
package)  provides a way to
store some "image" of an ASIS <CODE>Element</CODE> outside an ASIS application. An
application may create an <CODE>Id</CODE> value from an <CODE>Element</CODE> and store it in a
file. Subsequently the same or another application may read this <CODE>Id</CODE> value
and convert it back into the corresponding <CODE>Element</CODE> value.
</DL>
<P>

<A NAME="ASIS Package Hierarchy"></A>
<HR SIZE="6">
<A NAME="SEC18"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC17"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC19"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC19"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_15.html#SEC56">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 3.2 ASIS Package Hierarchy </H2>
<!--docid::SEC18::-->
<P>

ASIS is defined as a hierarchy of Ada packages. Below is a
short description of this hierarchy.
</P><P>

<DL COMPACT>
<DT><CODE>Asis</CODE>
<DD><A NAME="IDX62"></A>
The root package of the hierarchy. It defines the main ASIS
 abstractions - <CODE>Context</CODE>,
<A NAME="IDX63"></A>
<CODE>Compilation_Unit</CODE>
<A NAME="IDX64"></A>
and <CODE>Element</CODE>
<A NAME="IDX65"></A>
- as Ada private types. It also contains a set of enumeration types that define
 the classification hierarchy for ASIS <CODE>Element</CODE>s (which closely reflects the
 Ada syntax defined in the <CITE>Ada Reference Manual</CITE>) and the classification of
 ASIS <CODE>Compilation_Unit</CODE>s.
 This package does not contain any queries.
<P>

<DT><CODE>Asis.Implementation</CODE>
<DD><A NAME="IDX66"></A>
Contains subprograms that control an ASIS implementation: initializing and
 finalizing it, retrieving and resetting diagnosis information. Its child
 package <CODE>Asis.Implementation.Permissions</CODE>
<A NAME="IDX67"></A>
contains boolean queries that
 reflect how ASIS implementation-specific features are implemented.
<P>

<DT><CODE>Asis.Ada_Environments</CODE>
<DD><A NAME="IDX68"></A>
Contains queries
<A NAME="IDX69"></A>
that deal with an ASIS <CODE>Context</CODE>: associating and dissociating,
 opening and closing a <CODE>Context</CODE>.
<A NAME="IDX70"></A>
<P>

<DT><CODE>Asis.Compilation_Units</CODE>
<DD><A NAME="IDX71"></A>
Contains queries
<A NAME="IDX72"></A>
that work with ASIS <CODE>Compilation_Unit</CODE>s: obtaining units from a
 <CODE>Context</CODE>, getting semantic dependencies between units and "black-box" unit
 properties.
<P>

<DT><CODE>Asis.Compilation_Units.Relations</CODE>
<DD><A NAME="IDX73"></A>
Contains queries
<A NAME="IDX74"></A>
that return integrated semantic dependencies among ASIS
 <CODE>Compilation_Unit</CODE>s; e.g., all the units needed by a given unit to be included
 in a partition.
<P>

<DT><CODE>Asis.Elements</CODE>
<DD><A NAME="IDX75"></A>
Contains queries
<A NAME="IDX76"></A>
working on <CODE>Element</CODE>s and implementing general <CODE>Element</CODE>
 properties: gateway queries from ASIS Compilation Units to ASIS <CODE>Element</CODE>s,
 queries defining the position of an <CODE>Element</CODE> in the <CODE>Element</CODE> classification
 hierarchy, queries which define for a given <CODE>Element</CODE> its enclosing
 <CODE>Compilation_Unit</CODE> and its enclosing <CODE>Element</CODE>.
 It also contains queries for processing pragmas.
<P>

<DT>Packages working on specific <CODE>Element</CODE>s
<DD>This group contains the following packages: <CODE>Asis.Declarations</CODE>,
<A NAME="IDX77"></A>
 <CODE>Asis.Definitions</CODE>,
<A NAME="IDX78"></A>
 <CODE>Asis.Statements</CODE>,
<A NAME="IDX79"></A>
<CODE>Asis.Expressions</CODE>
<A NAME="IDX80"></A>
and
 <CODE>ASIS.Clauses</CODE>.
<A NAME="IDX81"></A>
Each of these packages contains queries working on
 <CODE>Element</CODE>s of the corresponding kind - that is, representing Ada declarations,
 definitions, statements, expressions and clauses respectively.
<P>

<DT><CODE>Asis.Text</CODE>
<DD><A NAME="IDX82"></A>
Contains queries
<A NAME="IDX83"></A>
returning information about the source representation of ASIS
<CODE>Compilation_Unit</CODE>s and ASIS <CODE>Element</CODE>s.
<P>

<DT><CODE>Asis.Exceptions</CODE>
<DD><A NAME="IDX84"></A>
Defines ASIS exceptions.
<P>

<DT><CODE>Asis.Errors</CODE>
<DD><A NAME="IDX85"></A>
Defines possible ASIS error status values.
</DL>
<P>

<A NAME="Structural and Semantic Queries"></A>
<HR SIZE="6">
<A NAME="SEC19"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC18"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC20"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC20"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_15.html#SEC56">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 3.3 Structural and Semantic Queries </H2>
<!--docid::SEC19::-->
<P>

<A NAME="IDX86"></A>
Queries working on <CODE>Element</CODE>s and returning <CODE>Element</CODE>s or <CODE>Element</CODE> lists
are divided into structural and semantic queries.
<A NAME="IDX87"></A>
<A NAME="IDX88"></A>
</P><P>

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

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

For example, if we have <CODE>Element</CODE> <CODE>El</CODE> representing an assignment statement:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=+0><pre>    X := A + B;
</FONT></pre></td></tr></table></P><P>

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

<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=+0><pre>   El_Var  := Asis.Statements.Assignment_Variable_Name (El); --  X
   El_Expr := Asis.Statements.Assignment_Expression    (El); --  A + B
</FONT></pre></td></tr></table></P><P>

Then we can analyze semantic properties of the variable name represented by
<CODE>El_Var</CODE> and of the expression represented by <CODE>El_Expr</CODE> by means of
appropriate semantic queries:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=+0><pre>   El_Var_Def   :=
      Asis.Expressions.Corresponding_Name_Definition (El_Var);
   El_Expt_Type :=
      Asis.Expressions.Corresponding_Expression_Type (El_Expr);
</FONT></pre></td></tr></table></P><P>

As a result, <CODE>El_Var_Def</CODE> will be of <CODE>A_Defining_Identifier</CODE> kind
and will represent the defining occurrence of <CODE>X</CODE>, while
<CODE>El_Expt_Type</CODE> of a kind <CODE>An_Ordinary_Type_Declaration</CODE> will
represent the declaration of the type of the expression <CODE>A + B</CODE>.
</P><P>

If we apply <CODE>Asis.Elements.Enclosing_Element</CODE> to <CODE>El_Var</CODE> or to
<CODE>El_Expr</CODE>, we will get back to the <CODE>Element</CODE> representing the
assignment statement.
</P><P>

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

<A NAME="ASIS Error Handling Policy"></A>
<HR SIZE="6">
<A NAME="SEC20"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC19"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC21"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC21"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_15.html#SEC56">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 3.4 ASIS Error Handling Policy </H2>
<!--docid::SEC20::-->
<P>

Only ASIS-defined exceptions (and the Ada predefined <CODE>Storage_Error</CODE>
<A NAME="IDX91"></A>
exception) propagate out from ASIS queries. ASIS exceptions
are defined in the <CODE>Asis.Exceptions</CODE> package.
<A NAME="IDX92"></A>
</P><P>

When an ASIS exception is raised, ASIS sets the Error Status (the possible
ASIS error conditions are defined as the values of the
<CODE>Asis.Errors.Error_Kinds</CODE> type)
<A NAME="IDX93"></A>
and forms the <CODE>Diagnosis</CODE> string.
<A NAME="IDX94"></A>
An application can query the current value of the ASIS Error Status by the
<CODE>Asis.Implementation.Status</CODE> query,
<A NAME="IDX95"></A>
and the current content of the
<CODE>Diagnosis</CODE> string by <CODE>Asis.Implementation.Diagnosis</CODE> query.
<A NAME="IDX96"></A>
An application
can reset the Error Status and the <CODE>Diagnosis</CODE> string by
invoking the <CODE>Asis.Implementation.Set_Status</CODE> procedure.
<A NAME="IDX97"></A>
</P><P>

<EM>Caution:</EM> The ASIS way of providing error information is not tasking safe.
The <CODE>Diagnosis</CODE> string and Error Kind are global to an entire partition,
and are not "per task".
If ASIS exceptions are raised in more then
one task of a multi-tasking ASIS application, the result of
querying the error information in a particular task may be incorrect.
<A NAME="IDX98"></A>
</P><P>

<A NAME="Dynamic Typing of ASIS Queries"></A>
<HR SIZE="6">
<A NAME="SEC21"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC20"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC22"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC22"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_15.html#SEC56">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 3.5 Dynamic Typing of ASIS Queries </H2>
<!--docid::SEC21::-->
<P>

The ASIS type <CODE>Element</CODE>
<A NAME="IDX99"></A>
covers all Ada syntactic constructs,
and <CODE>Compilation_Unit</CODE>
<A NAME="IDX100"></A>
covers all Ada compilation
units. ASIS defines an <CODE>Element</CODE> classification hierarchy (which reflects
very closely the hierarchy of Ada syntactic categories defined in the
<CITE>Ada Reference Manual</CITE>,
and ASIS similarly defines a classification scheme for ASIS <CODE>Compilation_Unit</CODE>s.
For
any <CODE>Element</CODE> you can get its position in the <CODE>Element</CODE>
classification hierarchy by means of classification queries defined in the
package <CODE>Asis.Elements</CODE>.
<A NAME="IDX101"></A>
The classification queries for <CODE>Compilation_Unit</CODE>s
are defined in the package <CODE>Asis.Compilation_Units</CODE>.
<A NAME="IDX102"></A>
</P><P>

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

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

The situation for the queries working on <CODE>Compilation_Unit</CODE>s is similar. If a
query lists appropriate unit kinds in its documentation, then this query can
work only on <CODE>Compilation_Unit</CODE>s of the kinds from this list. The query should
raise <CODE>Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit</CODE>
<A NAME="IDX105"></A>
with <CODE>Asis.Errors.Value_Error</CODE> error status set when called for any
<CODE>Compilation_Unit</CODE> with a kind not from the list of the appropriate unit kinds.
</P><P>

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

<A NAME="ASIS Iterator"></A>
<HR SIZE="6">
<A NAME="SEC22"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC21"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC23"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC23"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_15.html#SEC56">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 3.6 ASIS Iterator </H2>
<!--docid::SEC22::-->
<P>

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

For example, suppose we have an assignment statement:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=+0><pre>    X := F (Y);
</FONT></pre></td></tr></table></P><P>

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

<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=+0><pre>             (1 Pre_Op)  X := F (Y) (10 Post_Op)
                             |
                             |
           -----------------------------------
           |                                 |
(2 Pre_Op) X (3 Post_Op)                     |
                                             |
                                (4 Pre_Op) F(Y) (9 Post_Op)
                                             |
                                             |
                                ---------------------------
                                |                         |
                    (5 Pre_Op)  F (6 Post_Op)  (7 Pre_Op) Y (8 Post_Op)
</FONT></pre></td></tr></table></P><P>

To see in more detail how <CODE>Traverse_Element</CODE> may be used for rapid
development of a number of useful ASIS applications, try the examples in
<A HREF="asis_ug_8.html#SEC45">7. ASIS Tutorials</A>.
</P><P>

<A NAME="How to Navigate through the Asis Package Hierarchy"></A>
<HR SIZE="6">
<A NAME="SEC23"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC22"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_15.html#SEC56">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 3.7 How to Navigate through the <CODE>Asis</CODE> Package Hierarchy </H2>
<!--docid::SEC23::-->
<P>

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

<UL>
<LI>
Use the short overview of the ASIS packages given in
<A HREF="asis_ug_4.html#SEC18">3.2 ASIS Package Hierarchy</A>, to limit your browsing to a smaller set
of ASIS packages (e.g., if
 you are interested in what can be done with <CODE>Compilation_Unit</CODE>s then look only in
 <CODE>Asis.Compilation_Units</CODE>; if you are looking for queries that can be
 used to decompose and analyze declarations, limit your search to
 <CODE>Asis.Declarations</CODE>).
<P>

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

<LI>
The names of all the semantic queries (and only ones) start from
 <CODE>Corresponding_...</CODE> or <CODE>Implicit_...</CODE>
<P>

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

<A NAME="ASIS Context"></A>
<HR SIZE="6">
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_4.html#SEC16"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_5.html#SEC24"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_15.html#SEC56">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="asis_ug_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>  
<FONT SIZE="-1">
This document was generated
by <I>Mail Server</I> on <I>May, 22  2008</I>
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html/"><I>texi2html</I></A>

</BODY>
</HTML>