TOC PREV NEXT INDEX DOC LIST MASTER INDEX



ASIS Structures and Types

This chapter presents libraries, compilation units, elements, element-ids, lines, numerics, and strings as ASIS defines and uses them.

The following topics are covered in this chapter:


ASIS Basics

ASIS applications work mainly with three abstractions inspired by the Ada 83 LRM. These are:

In addition, ASIS defines several lower-level types to assist in processing semantic and syntactic information:


Libraries

An ASIS library is intended to exactly match the concept of an Ada program library from Ada83 LRM Section 10.4, Ada95 LRM 10.

Type for ASIS Libraries

Asis.Library is an undiscriminated limited private type. A vendor's implementation can declare Library as a type or as a subtype of an existing type. It will always be a limited private type or be derived from a limited private type.

This decreases the chances that an application would use Ada's built-in operations and thereby accidentally introduce vendor-specific dependencies —— for example, by inadvertently using ":=", "=", ">", "." (selection) or other built-in operations.

Note: An open ASIS library is always associated with a single, specific variable of type Library.

Program Libraries vs. ASIS Libraries

There are many ways in which an Ada vendor can implement Ada program libraries (Ada83 LRM 10.4, Ada95 LRM 10). These include, and are not limited to:

In addition, it is possible for an Ada implementation to provide any number of ways for combining individual physical program libraries into larger more complex logical program libraries that then can be used for compilations (Ada83 LRM 10.4, Ada95 LRM 10).

The ASIS library embraces this larger logical program-library concept. A single ASIS library may involve any number of vendor program libraries. The exact extent of an ASIS library is determined by the implementation, but ASIS libraries for a particular vendor are expected to be at least as flexible as the program library concept available to the vendor's Ada librarian for normal unit compilations and program construction.

This means that a single physical compilation unit (Ada83 LRM 10.1(3), Ada95 LRM 10.1.1) can belong to any number of logical program libraries (Ada83 LRM 10.4 (4), Ada95 LRM 10). Thus, wherever the ASIS specifications use phrases of the form ``a unit belonging to the library,'' the meaning is ``any physical compilation unit that can be reached by means of this logical program library."

An ASIS library includes all Ada compilation units that can be reached by any combination of queries on compilation units and elements. For example, if an element is reachable using some semantic query such as Expressions.Name_Definition, then the compilation unit containing that element is reachable by passing the simple ("ABC") or expanded ("ABC.DEF") name of the physical unit to the Compilation_Units.Library_Unit or Secondary_Unit functions (provided the unit is an eligible unit, the semantic reference could be obsolete). For some vendors, this implies that an ASIS library is a larger concept than program library normally would be for those vendors.

An ASIS library is what is sometimes referred to as the link-time closure of a program (or group of programs). Some vendors have separate concepts for what constitutes the compile-time library and what constitutes the link-time library. The compile-time library is often made up of a subset of the specifications for the complete run-time unit closure for a program. ASIS always works with the full link-time closure (all specs and all bodies for all units).


Compilation Units

ASIS compilation units are intended to exactly match the concept of the same name from Ada83 LRM 10.1, Ada95 LRM 10.1.1.

Kinds of Compilation Units

There are various kinds of compilation units. The possible ASIS kinds are represented by the enumeration Asis.Compilation_Unit_Kind and are shown in the following table:

Table 3 Kinds of Compilation Units
Kind
Description
A_Subprogram_Declaration
Declaration of a subprogram interface
A_Package_Declaration
Declaration of a package interface
A_Generic_Declaration
Declaration of a generic interface
A_Generic_Instantiation
Instantiation of a generic interface
A_Subprogram_Body
Declaration of a subprogram body
A_Package_Body
Declaration of a package body
A_Subunit
Declaration of a subprogram, task, or package subunit body
A_Nonexistent_Library_Unit
Returned only by the various relationship interfaces; represents a library-unit specification that is known to be required but that does not exist (or Is_Obsolete) in the library
A_Nonexistent_Secondary_Unit
Returned only by the various relationship interfaces; represents a secondary body unit that is known to be required but that does not exist (or Is_Obsolete) in the library
Unknown
Used for units where either the kind cannot be determined or the kind and the internal structure are purposely being hidden (e.g., for vendor-proprietary units)
Not_ A_Compilation_Unit
Reserved for uninitialized values (Nil_Compilation_Unit)

Types of Compilation Units

There are two main ASIS types for describing compilation units:

Compilation Units vs. Physical Units

An ASIS compilation unit is a logical entity that includes two pieces of information:

An implementation can treat two exact copies of the same unit information as the same physical entity. This is not required; separate copies can be treated as separate units that happen to be structurally and semantically identical. The intent is to allow for Ada librarian implementations that initialize all new libraries by installing copies of the Ada predefined packages, for example, Text_Io. Such implementations are allowed to treat all identical compiled units as if they were the same unit. This extends into the realm of element-ids for elements from these units. The implementation would be allowed to make it possible for tools to use any instance of the identical unit, from any open ASIS library, when converting an element-id to an element.

Using Compilation Units

An ASIS compilation unit is valid (is reusable, can be referenced) only as long as the ASIS library used to create it remains open. Closing an ASIS library has the side effect of rendering invalid all compilation units obtained from it. Use of an invalid compilation unit is erroneous in all cases. Implementations are encouraged, but not required, to detect the use of invalid compilation units.

Two ASIS compilation units are Compilation_Units.Is_Equal if they refer to the same physical compilation unit. Two compilation units are Compilation_Units.Is_Identical if they are Is_Equal and if they are derived from the same open ASIS library.

An uninitialized Compilation_Unit variable will always test True with Compilation_Units.Is_Nil.


Elements

ASIS elements represent the syntactic and semantic information available from most Ada program libraries. An element is one of:

Element Kinds

There are various kinds of elements. The possible ASIS kinds are enumerated in the various ASIS packages. The various kinds form a hierarchy with Element_Kinds at the top of the hierarchy. Below Element_Kinds, the hierarchy is:

Element Types

There are two main ASIS types for describing elements:

ASIS also defines a variety of element subtypes that are used to identify classes of elements. These subtypes classify elements into declarations, statements, expressions, type definitions, and several other classes.

For many element classes, ASIS provides enumeration types that further describe the kinds of the elements. For example, statements can be if statements, loop statements, raise statements, or any other kind of statement. ASIS includes functions that allow you to determine the kind for elements of a particular class.

ASIS offers many structural queries in the form of functions to decompose the various classes of composite elements into constituent component elements.

Other, nonstructural, ASIS functions return semantically related elements, such as the type of a given object or the specification of a given body.

Each ASIS element may also have attributes that provide information about that element. For example, all declaration elements have one or more names (Entity_Name_Definitions) associated with them. Static expressions may have a value associated with them. ASIS provides functions to provide this information for specific kinds of elements.

Some elements make reference to other elements. Declarations, for example, define named elements of the class An_Entity_Name_Definition. Other elements such as statements and expressions may make reference to named elements. These references are handled with elements of the class An_Expression and subclasses such as A_Simple_Name, An_Operator_Symbol, A_Character_Literal, A_Selected_Component, A_Function_Call, and so on.

Each ASIS element has a text image whose value is a series of characters that form the text span of the element. The text span covers all the characters from the first character of the element through the last character of the element over the range of lines.

ASIS Element vs. Physical Syntactic Element

An ASIS element is a logical entity that includes three pieces of information:

Querying Elements

ASIS provides two general classes of query functions that can be used to derive new elements from existing elements. Syntactic query functions obtain elements that are known to be part of the same enclosing compilation unit; for example, if statement arms are a part of an enclosing if statement.

Semantic query functions obtain elements that may or may not be part of the same compilation unit.

Semantic query functions are implementation-dependent. However, they all work as if they:

Semantic queries always raise Asis.Failed with a status code of Obsolete_Reference_Error if they would otherwise be forced to return an element whose Enclosing_Compilation_Unit would either:

Using Elements

An element is valid (is reusable, may be referenced) only as long as the ASIS library used to create the enclosing compilation unit remains open. Closing an ASIS library has the side effect of rendering invalid all elements obtained from it. Use of an invalid element is erroneous in all cases. Implementations are encouraged, but not required, to detect the use of invalid elements.

Two elements are Elements.Is_Equal if they refer to the same physical semantic element within the same physical compilation unit. Two elements are Elements.Is_Identical if they are Is_Equal and if they are derived from the same open ASIS library.

An uninitialized variable of type Element will always test True with Elements.Is_Nil.

It is possible to create a unique element-id for any element. The purpose of an element-id is to allow the direct retrieval of a specific element without having to duplicate the syntactic and semantic traversals that were originally used to locate it. See the Asis.Ids package.

Some vendors do not maintain all desired syntactic and semantic information in their program libraries. Those vendors are required to simulate the appropriate elements in order to exhibit conforming ASIS behavior.


Element-Ids

ASIS element-ids are a means of identifying particular elements obtained from a particular physical compilation unit. All elements have (can be assigned, can have generated for them) a unique element-id value.

Element-ids are relative names. Each element-id is valid (makes sense, can be interpreted) only in the context of an appropriate open ASIS library.

Element-ids can be saved and used at a later date.

Element-ids become invalid (cannot be reconverted to elements) when their associated compilation unit is destroyed or is otherwise rendered unavailable. Individual implementations may have various avenues for rendering element-ids invalid. Some possible examples are: unit recompilation, physical library restructuring, and changes made to library/unit pathnames.

Element-Id Type

The Asis.Id type is an undiscriminated private type. A vendor's implementation can declare it as a type or as a subtype of an existing type. It will always be an undiscriminated private type or be derived from an undiscriminated private type.

The intent is that only the "=", "<", ">", and ":=" basic Ada operations are to be available to applications. The built-in "=" operation is intended to be meaningful for element-ids generated from elements from the same open ASIS library. "=" may or may not be meaningful for element-ids obtained from separate libraries (see Maximal Conformance). The "<" and ">" operations are included so that it is possible to place element-ids into symbol tables or other mapping data structures that require these operations to function. Their operation is deterministic and two element-ids are either "<" or ">", but not both.

Using Element-Ids

The Asis.Id type is not guaranteed to be suitable for use with Direct_Io or any other predefined Ada I/O package. It may or may not contain access or other values that cannot be written to a file in a meaningful manner. All portable application I/O dealing with element-ids must be performed through the Asis.Ids.Id_Io package or with the Id_Segment data type.

Nil_Element has an element-id of Nil_Id, and Nil_Id always converts to Nil_Element.

An uninitialized variable of type Id always tests True with Ids.Is_Nil.

The ASIS element-id concept is a difficult one to implement. Not all vendors will be able to implement it in the fullest sense that applications might prefer. The discussion that follows will separately discuss the properties of a minimally conforming implementation and those of a maximally conforming implementation.

Saving Element-Ids

To be saved for later use, element-ids can be written to files, read at a later time, and used to locate the original element, if that element still exists.

It is the responsibility of the ASIS application to remember which ASIS library, as specified by a name and parameter association, was used to locate an element for which an element-id has been recorded. Those same name and parameter associations (or vendor-specific equivalents) must be used when opening a library that is to be used to convert the recorded element-ids back to elements.

If an implementation cannot convert an element-id into a current element, it will raise Asis_Inappropriate_Element with a Status of Value_Error (and, preferably, an informative Diagnosis string).

Minimal Conformance

The following discussion of element-id properties assumes that:

Assuming those three points, the following properties for element-ids are guaranteed by all ASIS implementations:

Maximal Conformance

The following does not assume identical name and parameter associations, nor does it assume the absence of modifications to the units or the library.

An implementation of element-ids should attempt to achieve the following desired properties:

Implementation Notes

The requirement that "=" be meaningful across element-ids has certain ramifications. An element-id may contain access values. This implies that an implementation that uses internal access values will cache these values and reuse them as appropriate. This caching is in effect independent of, and across, libraries. Heap storage utilized in the containment of element-ids cannot be reclaimed or reused (except for sharing) except when the ASIS environment is finalized. This implies that creation of element-ids by an application can be regarded as generating garbage. That garbage is not reclaimable until the Environment.Finalize procedure is called.

Applications that do not choose to generate garbage are encouraged to use Id_Segment_List values instead, or to use the Asis.Ids.Id_Io interfaces that read and write elements, and to use the stored file position for an element-id as its unique hash value.


Lines

ASIS lines are representations for compilation text available from many Ada program libraries.

Line Types

There are two main types used for ASIS lines:

Related Subtypes

ASIS provides three subtypes to help process ASIS lines:

Line_Number

Line_Number is a numeric subtype that allows each ASIS implementation to place constraints on the upper bound for Line_List arrays and thus implicitly for unit text line numbers.

The actual upper bound of Line_Number (Maximum_Line_Number) is the only allowed variation between vendors.

Line_Number = 0 is reserved to act as an ``invalid'' Line_Number value. No unit text line will ever have a Line_Number of 0.

Character_Position

Character_Position is a numeric subtype that allows each ASIS implementation to place constraints on the upper bound for Character_Position and for unit text line lengths.

The actual upper bound of Character_Position (Maximum_Line_Length) is the only allowed variation between vendors.

Character_Position = 0 is reserved to act as an ``invalid'' Character_Position value. No unit text line will ever have a character in position 0.

Span

A text span is a means of designating a particular region of unit text. A single text position is identified by a line number and a column number that specifies the character position within the line. A text span is a pair of Line_Numbers with a starting and ending column, represented by the type Asis.Span.

An implementation may choose to ignore (not support) text character-position values in which case, the function Environment.Is_Span_Column_Position_Supported will return False.

The text of an element may span one or more lines. The text span of an element identifies the lower and upper bound of a span of text positions.

Text spans and positions give client tools the flexibility to access text through the ASIS interface or, more directly, through the external text file, if any.

Using Lines

A line is valid (is reusable, may be referenced) only as long as the ASIS library, used to create the enclosing compilation unit, remains open. Closing an ASIS library has the side effect of rendering invalid all lines obtained from it.

Use of an invalid line is erroneous in all cases. Implementations are encouraged, but not required, to detect the use of invalid lines.

An uninitialized variable of type Line always tests True with Is_Nil.


Numerics

The purpose of ASIS package Numerics is to:

The types provided are:

Asis_Integer

Asis_Integer is a numeric type that allows each ASIS implementation to place constraints on the lower and upper bounds. When possible, the range of this type should meet or exceed –(2**31𔂿) .. 2**31𔂿.

The actual range of Asis_Integer is the only allowed vendor variation.

List_Index

List_Index is a numeric subtype that, if possible, should have the same range as Asis_Positive. However, some implementations may need to enforce a smaller upper bound on the range of list values.

The actual upper bound on the range of List_Index is the only allowed vendor variation:


Strings

The purpose of ASIS package Strings is to:

Ada 83 has been officially redefined so that Standard.Character uses the 8-bit ASCII (Latin-1) character set. However, only a few compilers actually allow such a character set to be used in programs or at run time. Many are still validated against the older 7-bit ASCII standard. Consequently, until Ada 9x, ASIS will define its own string types:

Asis_Character

Asis_Character is an 8-bit character set that is intended to be implemented as the 8-bit ASCII (Latin-1) character set.

If an implementation has an existing Character type that implements this character set, it may use that character set in defining this type. In doing so, however, it must preserve the interface presented here (the operations and the literal names). It may do this by subtypes, function renames, and literal renames if it chooses.

ASIS provides conversions to and from Standard.Character:

Asis_String

Asis_String is an 8-bit character string that is intended to have a large enough index range so that all ASIS applications will be able to manipulate Ada program image fragments in a portable manner.

Conversions are provided to and from Standard.String:


Times

The purpose of the Asis.Times package is to provide a way to represent compilation times and time of last update for compilation units.

Asis_Time

Asis_Time is simply a rename of Calendar.Time. Operations for Asis_Time are those of Calendar.Time.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS