TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Package Asis

Package Asis contains all public ASIS resources. Portable ASIS applications should not reference any resources except those defined in this package.

For more information, click on a topic:


Resources in Package Asis

The resources in package Asis fall into several functional groups, as shown below.

To see detailed referenced information, click on the name of a resource:
Component packages:
Compilation_Units Elements Exceptions Ids Lines Representation_Clauses Strings Times
Declarations Environment Expressions Libraries Numerics Statements Text Type_Definitions
Package Numerics types:

Asis_Integer Asis_Positive
Asis_Natural List_Index
Package Strings types and constants:
Asis_Character Nil_Asis_String
Asis_String
Package Times types and constants:
Asis_Time
Nil_Asis_Time
Package Libraries type:
Library

Package Compilation_Units types and constants:
Compilation_Unit Nil_Compilation_Unit Relationship
Compilation_Unit_List Nil_Compilation_Unit_List

Package Elements types and constants:
Element Nil_Element
Element_List Nil_Element_List
Element and element-list subtypes1
Package Ids types and constants:
Id Id_Segment Nil_Id
Id_List Id_Segment_List Nil_Id_Segment
Package Text types and constants:
Character_Position Line Line_Number Maximum_Line_Length Nil_Line Nil_Span
Character_Position_Positive Line_List Line_Number_Positive Maximum_Line_Number Nil_Line_List Span
Package Exceptions:

Asis_Failed Asis_Inappropriate_Compilation_Unit Asis_Inappropriate_Element Asis_Inappropriate_Library Asis_Inappropriate_Line Asis_Inappropriate_Line_Number
1 A large number of element and element-list subtypes are defined. These are described in detail in "Package Elements Types and Constants."


Key Concepts for Package Asis

The principal interface to ASIS version 1.1 is composed of sixteen packages and a similar number of nested packages. These packages contain approximately 300 subprograms and 30 types and objects.

To simplify the development of applications, all packages, types, and objects are made visible in package Asis using renaming or subtype declarations or using initial declaration. The actual implementation is vendor-dependent; however, the implementation must guarantee certain naming and typing conventions as well as visibility rules.

All ASIS resources are available through naming expressions of the form Asis.Name. A close review of the ASIS package specifications will turn up additional kinds of naming expressions; these forms are historical and should not be used in applications.

The resources provided by package Asis are divided into a number of related declaration groups and are fully described in the following categories. To see more information, click on a topic:

Component Packages

The principal ASIS interfaces are contained within sixteen packages. Rational ASIS has implemented most of these in separate files; renaming declarations make them visible from package Asis. Your applications should use only the resources available in package Asis and those made visible through the renaming declarations.

Of the sixteen packages, five are small and contain low-level declarations that can be used by your application but are also used by the other ASIS packages. The packages are described briefly below. Click on the following topics for more information:

The remaining packages constitute the bulk of ASIS. Rational ASIS has implemented most of these in separate files; renaming declarations make them visible from package Asis. The packages are described briefly below. They are completely described in separate packages. Click on a topic to go directly to that package:

Package Numerics Types

Package Numerics defines numeric types and values and related operations for use with the ASIS interfaces. The purpose of the package is to:

The types made visible in package Asis are listed below and fully described in "Package Numerics":

Package Strings Types and Constants

Package Strings defines the character and string types and related operations for use with the ASIS interfaces. The purpose of the package is to:

The types and objects made visible in package Asis are listed below and fully described in "Package Strings":

Package Times Types and Constants

Package Times defines the time type and related operations for use by the ASIS interfaces. The package isolates ASIS from the implementation of package Calendar.

The types and objects made visible in package Asis are listed below and fully described in "Package Times":

Package Libraries Type

Package Libraries provides resources for accessing Ada program libraries.

The type made visible in package Asis that is related to package Libraries is described briefly below:

More detailed descriptions of the above type and the associated subprograms are provided in package Libraries, "Key Concepts in Package Libraries."

Package Compilation_Units Types and Constants

Package Compilation_Units accesses Ada compilation units, the pragmas that affect the units, and the elements that represent the declarations of the units.

The types and objects made visible in package Asis that are related to package Compilation_Units are described briefly below:

More detailed descriptions of the above types and constants and how they are used with their associated subprograms are provided in package Compilation_Units, "Key Concepts for Package Compilation_Units,"

Package Elements Types and Constants

Package Elements provides access to the syntactic elements that make up program units. Functions are available that traverse the element tree, identify the kinds of elements encountered, and obtain the element logically enclosing an element.

The types and objects made visible in package Asis that are related to package Elements are described briefly below:

More detailed descriptions of the above types and constants and how they are used with their associated subprograms are provided in package Elements, "Key Concepts for Package Elements."

For more clarity in the definition of the subprograms that use Element and Element_List types, a number of subtypes have been defined. The following table shows the subtypes and the most applicable LRM references:
Subtype
LRM Section(s)
Argument_Association_List
Ada83 LRM 2.8 Ada95 LRM 2.8
Association Association_List
Ada83 LRM 2.8, 6.4 Ada95 LRM 2.8, 6.4
Case_Statement_Alternative Case_Statement_Alternative_List
Ada83 LRM 5.4 Ada95 LRM 5.4
Choice Choice_List
Ada83 LRM 3.7.3 Ada95 LRM 3.8.1

Subtype
LRM Section(s)
Component_Association Component_Association_List
Ada83 LRM 4.3 Ada95 LRM 4.3
Component_Clause Component_Clause_List
Ada83 LRM 13.4 Ada95 LRM 13.5.1
Component_Declaration
Ada83 LRM 3.7 Ada95 LRM 3.8
Constraint
Ada83 LRM 3.3.2 Ada95 LRM 3.2.2
Context_Clause Context_Clause_List
Ada83 LRM 8.4, 10.1.1 Ada95 LRM 8.4, 10.1.2
Declaration Declaration_List
Ada83 LRM 3 Ada95 LRM 3
Declarative_Item_List
Ada83 LRM 5.6, 7.4,
9.1 Ada95 LRM 5.6, 7.3, 9.1
Discrete_Range Discrete_Range_List
Ada83 LRM 3.6 Ada95 LRM 3.6
Discriminant_Association Discriminant_Association_List
Ada83 LRM 3.7.2 Ada95 LRM 3.7.1
Discriminant_Specification_List
Ada83 LRM 3.7.1 Ada95 LRM 3.7
Entity_Name_Definition Entity_Name_Definition_List
Ada83 LRM 3.1 Ada95 LRM 3.1
Entry_Declaration_List
Ada83 LRM 9.5 Ada95 LRM 9.5
Exception_Handler Exception_Handler_List
Ada83 LRM 11.2 Ada95 LRM 11.2
Expression Expression_List
Ada83 LRM 4.4 Ada95 LRM 4.4
Generic_Formal_Parameter Generic_Formal_Parameter_List
Ada83 LRM 12.3 Ada95 LRM 12.3

Subtype
LRM Section(s)
If_Statement_Arm If_Statement_Arm_List
Ada83 LRM 5.5 Ada95 LRM 5.5
Length_Clause_List
Ada83 LRM 13.2 Ada95 LRM 13.3
Name_List
Ada83 LRM 8.4,
10.1.1 Ada95 LRM 8.4, 10.1.2
Parameter_Specification Parameter_Specification_List
Ada83 LRM 6.1 Ada95 LRM 6.1
Pragma_Element Pragma_Element_List
Ada83 LRM 2.8 Ada95 LRM 2.8
Range_Constraint
Ada83 LRM 3.5 Ada95 LRM 3.5
Record_Component Record_Component_List
Ada83 LRM 3.7 Ada95 LRM 3.8
Representation_Clause
Ada83 LRM 3.4 Ada95 LRM 3.4
Select_Alternative
Ada83 LRM 9.7.1 Ada95 LRM 9.7.1
Select_Statement_Arm Select_Statement_Arm_List
Ada83 LRM 9.7 Ada95 LRM 9.7
Simple_Name Simple_Name_List
Ada83 LRM 3.7.2 Ada95 LRM 3.7.1
Statement Statement_List
Ada83 LRM 5.1 Ada95 LRM 5.1
Subtype_Indication
Ada83 LRM 3.3.2 Ada95 LRM 3.2.2
Variant Variant_List
Ada83 LRM 3.7.3 Ada95 LRM 3.8.1
Variant_Component_List
Ada83 LRM 3.7 Ada95 LRM 3.8

Package Ids Types and Constants

Package Ids provides resources that support persistent and unique names for elements.These are called element identifiers (element-ids) and are represented by the Id type.

An element-id identifies a particular element, from a particular physical compilation unit, from a particular library, at a particular time.

The types and objects made visible in package Asis that are related to package Ids are described briefly below:

More detailed descriptions of the above types and constants and how they are used with their associated subprograms are provided in package Ids, "Key Concepts for Package Ids."

Package Text Types and Constants

Package Text provides access to the text of compilation units. Text is associated with elements and is defined in terms of:

The types and constants made visible in package Asis are listed below and fully described in "Package Lines":

In addition to the above types and constants, the following constant is defined in package Asis:

More detailed descriptions of all the above types and constants and how they are used with their associated subprograms are provided in package Text, "Key Concepts for Package Text."

Package Exceptions

Package Exceptions defines the exceptions used by the ASIS interfaces.

These exceptions are raised when:

Except for the Asis_Failed exception, each exception corresponds to a particular kind of parameter. For example, Asis-_Inappropriate_Library is raised if an Asis.Library type parameter is invalid.

The list of ASIS exceptions and brief descriptions of why each can be raised are provided below. See "Package Exceptions" for detailed information on the ASIS exception philosophy and each of the exceptions.


Package Exceptions

Expanded Name Asis.Exceptions

Defines all the exceptions used by ASIS interfaces.

Description

Whenever an ASIS implementation raises one of the ASIS exceptions, it will have previously set the values returned by Environment.Status and Environment.Diagnosis. The Status will not be Not_An_Error. The Diagnosis string may be Nil_Asis-_String; however, implementors are encouraged to return a detailed textual description of the cause of a failure.

All ASIS subprograms attempt to catch all exceptions and will do one of the following:

In some situations, ASIS cannot prevent a non-ASIS exception from being propagated to the application program. These situations include:

In addition to the ASIS exceptions, package Ids.Id_Io can raise the exceptions in the Ada predefined package Io_Exceptions.

In general, ASIS functions that return enumeration values (including Boolean values) do not raise exceptions when provided with inappropriately valued parameters. For example, the Elements.Is_Predefined function does not raise an exception if provided with an element that does not represent a pragma. Exceptions to this include:

Compilation units and elements can become invalid because of concurrent library updates or because their associated library is closed.

In the absence of concurrent library updates, all exceptions except Asis_Failed typically indicate an error in the ASIS application. For example, passing an uninitialized compilation-unit variable will cause Asis_Inappropriate_Compilation_Unit (or possibly Constraint_Error) to be raised.

The Asis_Failed exception indicates a failure in the ASIS implementation or attempted use of a capability that has not been implemented. In the case of a capability that has not been implemented, the Environment.Status function returns the value Not_Implemented_Error. For any other failure, you should attempt to identify the circumstances and forward a problem report to the vendor so that corrections can be made.

Exceptions

Asis_Failed

Raised when an ASIS subprogram cannot complete its operation correctly. This exception typically indicates a failure of, or a programmer error in, the underlying ASIS implementation. This is a catch-all exception that can be raised for different reasons in different ASIS implementations. The possible Environment.Status values and associated causes include:

Asis_Inappropriate_Compilation_Unit

Raised when ASIS is passed a compilation unit that is not appropriate. The compilation unit might be uninitialized, the corresponding library could be closed, or the kind of the unit may be inappropriate for the subprogram.

Asis_Inappropriate_Element

Raised when ASIS is passed an element that is not appropriate. The element might be uninitialized, the corresponding library could be closed, or the kind of the element may be inappropriate for the subprogram.

Asis_Inappropriate_Library

Raised when ASIS is passed a library that is not appropriate for the operation. The library might be uninitialized, nil, dissociated (see Libraries.Dissociate), or not open.

Asis_Inappropriate_Line

Raised when ASIS is passed a line that is not appropriate. The line might be uninitialized or the corresponding library could be closed.

Asis_Inappropriate_Line_Number

Raised when ASIS is passed a line number that is not appropriate. The line number might be uninitialized or out of the range of valid lines for an associated element or line.

Errors

None.

Examples

Cross-References

Related subprograms:

Related concepts:


Package Lines

Expanded Name Asis.Lines

Defines all types and related operations for obtaining and manipulating text images.

Description

Package Text contains subprograms that support the retrieval of the spans and text images of program elements, compilations, and compilation units. Package Lines defines the types required to interface with these subprograms.

Resources

Identifies the maximum line number within a compilation that ASIS can represent.

Indicates a type that represents the line numbers in a
compilation.

Indicates a type that represents the line numbers in a
compilation.

Identifies the maximum column position within a line in a compilation, that ASIS can represent.

Indicates a type that represents a character position within a line in a compilation.

Indicates a type that represents a character position within a line in a compilation.

Indicates a record that contains the textual bounds of an element or line. The span identifies the first and last columns and line numbers.

Indicates a span containing no lines and no characters.

Identifies a specific line of text, or a portion of a line of text, from a specific compilation unit. The applicable portion of a line of text is identified by a span. A newly created variable of this type is equal to Nil_Line.

Indicates a line that does not reference a line from a compilation unit.

Identifies an array of lines. The index values of the array represent the line numbers on which the text from the compilation unit exists.

Errors

None.

Examples

Cross-References

Related package:

Related concepts:


Package Numerics

Expanded Name Asis.Numerics

Defines numeric types and values and related operations for use with the ASIS interfaces.

Description

The purpose of the package is to:

Resources

Defines the lower bound on ASIS integers.

Defines the upper bound on ASIS integers.

Defines an ASIS specific integer type. This type is analogous to Standard.Integer.

Defines an ASIS specific natural type. This type is analogous to Standard.Natural.

Defines an ASIS specific positive type. This type is analogous to Standard.Positive.

Defines the upper index limit for all lists (arrays) used by ASIS except the Line_List type.

Defines the index type of all lists (arrays) used by ASIS except the Line_List type.

package Operations

Defines the operators for types used in package Strings. The package typically is referenced in a use clause by an application. See "Package Numerics.Operations" for a description of the operators available.

Errors

None.

Examples

Cross-References

Related package:

Related concept:


Package Numerics.Operations

Expanded Name Asis.Numerics.Operations

Package Operations provides a simple way to obtain visibility to operators for types used in package Numerics. The package typically is referenced in a use clause by an application.

Cross-References

Related package:

Related concept:


Package Strings

Expanded Name Asis.Strings

Defines all character and string types and related operations for use with ASIS.

Description

The purpose of the package is to:

Resources

Defines an 8-bit character set. The first 128 elements correspond to the values of Standard.Character. The set is intended to be implemented as the 8-bit ASCII Latin-1 character set.

If an implementation has an existing type that implements this character set, that type can be used. The interface presented here, including all operations and literal names, must be preserved.

Converts a standard character to an Asis_Character.

Converts an Asis_Character to a standard character. High-order bits of the Asis_Character are removed during conversion so that neither a constraint nor numeric error can result.

Defines an array of Asis_Characters. Overloaded functions are provided so that the type and operators available for the type are analogous to Standard.String.

Defines an empty Asis_String.

Converts a standard string to an Asis_String. Each character in the string is converted as if the To_Asis_Character function had been used.

The resulting Asis_String may not have the same 'First or 'Last as the argument. If the standard string has a wider index range than Asis_String, the result may be truncated and the 'Length will be shorter.

Converts an Asis_String to a standard string. Each Asis_Character in the string is converted as if the To_Standard_Character function had been used.

The resulting string may not have the same 'First or 'Last as the argument. If the Asis_String has a wider index range than string, the result may be truncated and the 'Length will be shorter.

package Operations

Defines operators for types used in package Strings. The package typically is referenced in a use clause by an application. See "Package Strings.Operations" for a description of the operators available.

Errors

None.

Examples

Cross-References

Related package:

Related concept:


Package Strings.Operations

Expanded Name Asis.Strings.Operations

Package Operations provides a simple way to obtain visibility to operators for types used in package Strings. The package typically is referenced in a use clause by an application.

Cross-References

Related package:

Relates concept:


Package Times

Expanded Name Asis.Times

Defines the time type and related operations for use by the ASIS interfaces.

Description

Package Times isolates ASIS from the definitions in package Calendar (Ada83 LRM 9.6, Ada95 LRM 9.6).

A portable ASIS application should use only the resources presented in package Times and should not use the package Calendar resources directly.

Resources

subtype Asis_Time is Calendar.Time;

Identifies a time.

Nil_Asis_Time : constant Calendar.Time;

Defines a time that indicates that an actual time is not available.

package Operations renames Calendar;

Makes the operations of package Calendar available to applications that reference package Times in a with clause.

Errors

Calendar.Time_Error is raised if actual parameters to the subprograms available from package Operations do not form a proper date or if arithmetic operations on dates yield a date whose year number or Duration is out of range.

Examples

Cross-References

Related concepts:


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