ASIS-for-GNAT Reference ManualAda Core Technologies, Inc.
Table of Contents
(C) Copyright 2000, Ada Core Technologies, Inc.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
ASIS-for-GNAT Reference Manual
(C) Copyright 2000, Ada Core Technologies, Inc.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
ASIS-for-GNAT Reference Manual
This Manual contains useful information in writing tools and applications using ASIS 95 implementation for the GNAT Ada 95 compiler (ASIS-for-GNAT). It includes information on implementation dependent characteristics and the current implementation limitations of ASIS-for-GNAT.
ASIS has been designed to be a portable basis for many useful Ada code analysis tools. However, since ASIS is designed to be implemented for wide variety of Ada compilers, it also contains a number of implementation specific features to be used in interfacing with the underlying Ada implementation, as well as implementation permissions for particular queries
Note: Any ASIS application that makes use of implementation-dependent features may be non-portable. You should follow good programming practice and isolate and clearly document any sections of your program that make use of these features in a non-portable manner.
This guide contains the following chapters:
This Reference Manual assumes, that you are familiar with Ada 95 language, as described in the International Standard ANSI/ISO/IEC-8652:1995, Jan 1995, and with ASIS 95, as described in the ASIS 95 International Standard ISO/IEC 15291:1999.
This Manual relies on some important facts described in the ASIS-for-GNAT User's Guide and uses the terminology introduced in the User's Guide.
For more information, see the following documents:
Now the ASIS definition for Ada 95 (ASIS 95) exists as ISO/IEC 15291:1999 International Standard. ASIS-for-GNAT supports the ASIS 95 interface as it is defined in the ASIS Standard. ASIS-for-GNAT also contains some ASIS extensions (see chapter section ASIS Extensions), as allowed by the ASIS Standard, section 188.8.131.52.
Currently some queries in some situations may raise the Asis_Failed exception with Not_Implemented_Error error status. This means, that some part of the functionality of a given query is not implemented yet. If you encounter such a situation, report it as an ordinary ASIS-for-GNAT bug. Our general goal is to have the full implementation of ASIS 95 conforming to the ASIS Standard.
ASIS-for-GNAT contains the specifications of all the ASIS interface packages as defined in the ASIS Standard, except the optional Data Decomposition Annex, with no changes, except adding comments in the very beginning, adding with clauses, adding declarations in package private parts and some reformatting needed to follow the GNAT coding style. The only exception is moving the Is_Dispatching_Operation query from Asis.Expressions into Asis.Declarations.
ASIS-for-GNAT provides some additional queries as ASIS extensions. All these queries are defined and documented in the hierarchy headed by package Asis.Extensions. They are referred as "ASIS extensions" or "ASIS extension queries" below.
All the ASIS extensions obey all the general ASIS rules: when using ASIS extensions, you have to follow the required sequiensing of calls, only ASIS-defined exceptions are allowed to propagate outside the ASIS exception queries. If the documentation of an ASIS exception query contains a list of appropriate element kinds, then this query can be applied only to Elements from this list and it raises ASIS_Inappropriate_Element with Value_Error status otherwise. If the documentation of an ASIS exception query contains a list of expected element kinds, then this query can be applied to an Element having any kind, but it returns meaningful result only for Elements from this list.
The current set of ASIS extensions originated from the ASIS implementation needs and from the development of some ASIS tools inside the ASIS-for-GNAT team. As it stands now, Asis.Extensions hierarchy is not supposed to be stable - some queries may be removed from it, some new extension queries may be added. We are very interested in ASIS application developers feedback to implement a compact, but useful set of extension queries in ASIS-for-GNAT.
Currently Asis.Extensions hierarchy contains its top Asis.Extensions package defining a set of various-purpose extensions, and its only child Asis.Extensions.Flat_Kinds, which defines a "flat" Element classification.
Asis.Extensions package contains the following extension types and queries (see
the specification of Asis.Extensions in the file named
Asis.Extensions.Flat_Kinds package contains the definition of the type Flat_Element_Kinds. This type defines a "flat" Element classification which is equivalent to the Element classification hierarchy defined in Asis package: each kind value of the original hierarchy having subordinate kinds is replaced by the corresponding subordinate range. Asis.Extensions.Flat_Kinds package also provides conversion functions from the "flat" classification into the original classification hierarchy.
There are three kinds of implementation dependencies in ASIS.
First, ASIS subprograms which define an interface between an ASIS implementation and the underlying Ada implementation have implementation-specific parameters. There are three queries of this kind - Asis.Implementation.Initialize, Asis.Implementation.Finalize and Asis.Ada_Enfironments.Associate, all of them have a string parameter named Parameters which has implementation-specific meaning. The meaning of Parameters string in ASIS-for-GNAT is discussed in section section Interacting with the Underlying Ada Implementation.
Second, some ASIS areas are considered as making problems for ASIS implementations. For such areas, the Asis Working Draft contains explicit implementation permissions which allow an ASIS implementation not to implement some part of the ASIS functionality or to implement it in a restricted way. Each of these permissions usually affects more, then one particular ASIS query. The ASIS package Asis.Implementation.Permissions contains boolean queries which tell you what choices are made for these implementation permission in a given ASIS implementation. The solutions taken in ASIS-for-GNAT for these general implementation permissions are discussed in section section Implementation Permissions.
Third, for some ASIS queries implementation permissions which are specific for a given query are given explicitly in the ASIS Working Draft. For some other queries, the result of a query may be implementation-specific because of the very nature of the query, even though it is not explicitly said so in the ASIS Standard. Such queries are discussed in section section ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results.
A Parameters string is a parameter of the three ASIS subprograms: Asis.Implementation. Initialize, Asis.Implementation.Finalize and Asis.Ada_Environments.Associate. The following requirements are common for all these subprograms:
The allowed parameters for Asis.Implementation.Initialize are:
Now <debug_flag> may be any lower case letter from 'a' to 'z' or any digit from 0 to 9 (not all of the corresponding options are implemented now).
ASIS debug flags are documented in the file
<warning_mode> could be either 's', which means "suppress all the warning messages" or 'e', which means "treat every warning as an error", and in this case every warning are converted in Asis_Failed raising with warning messages as ASIS Diagnosis strings.
If more then one parameter controlling the warning mode is set in the diagnosis string, each of them changes the warning mode in the place where it is given.
See also ASIS-for-GNAT Users' Guide for more information about warnings.
No parameter is allowed for Asis.Implementation.Finalize in the current ASIS-for-GNAT version.
When called, Asis.Implementation.Finalize resets all the general ASIS-for-GNAT parameters to the default values (that is, all the debug flags are set off, and the warning mode is set to the default warning mode).
The following parameters are allowed for this query:
For -I and -T parameters, <dir> should denote an existing directory in the underlying file system, notations as "." and ".." are allowed, as well as relative or absolute directory names. If <dir> does not denote an existing directory, Asis_Failed with Parameter_Error status is raised.
A tree file name given by a <file_name> parameter may or may not contain directory information.
The search path associated with an ASIS Context consists of the directories listed as parameters for the Asis.Ada_Environments.Associate query, in the same order as they are included in the actual Parameters string. The ASIS source search path consists only of the directories following '-I', and the ASIS tree search path consists only of the directories following '-T'. If no source (tree) directory presents in the value of the Parameters string, then the ASIS source (tree) search path consists of the current directory only, otherwise the current directory is included in the ASIS search path if amd only if it is set explicitly as -I. or -T. respectively.
If an ASIS Context is associated with -FS or -FM option, the Context source search path to locate sources of the units to create a tree file for, and to locate other source files needed when called GNAT to create tree files. For example, if we have:
Asis.Ada_Environments.Associate (My_Cont, "My_Cont_Name", "-CA -FS -I./dir -I.");
then, when processing a call:
My_Unit := Asis.Compilation_Units.Library_Unit_Declaration ("Foo", My_Cont);
ASIS first try to locate the source file foo.ads in ./dir, and if this attempt fails, it tries to locate it in the current directory. If the source file is found (let it be in the current directory), ASIS calls GNAT to create the tree file as
gcc -c -gnatc -gnatt -I./dir -I. -I- foo.ads
If an ASIS Context is associated with -CA option, then, when this Context is opened, ASIS processes all the tree files located in the tree search path associated with the Context.
The following restrictions are imposed on allowed combinations of parameters in the actual Parameters string of the Asis.Ada_Environments.Associate query:
In case if an incompatible combination is set, Asis_Failed with Parameter_Error status is raised
In case if the actual for the Parameters string in a call to the query
Note, that the definition of the parameters might change later on.
For the Name parameter of the Asis.Ada_Environments.Associate query any string can be passed as an actual. In the current ASIS-for-GNAT version no verification is performed for an actual and no semantic is associated with the Name parameter of the Asis.Ada_Environments.Associate query.
The Boolean queries defined in the
Is_Formal_Parameter_Named_Notation_Supported True Default_In_Mode_Supported True Generic_Actual_Part_Normalized False Record_Component_Associations_Normalized False Is_Prefix_Call_Supported True Function_Call_Parameters_Normalized False Call_Statement_Parameters_Normalized False Discriminant_Associations_Normalized False Is_Line_Number_Supported True Is_Span_Column_Position_Supported True Is_Commentary_Supported True Attributes_Are_Supported False Implicit_Components_Supported False + Object_Declarations_Normalized False Predefined_Operations_Supported False + Inherited_Declarations_Supported False + Inherited_Subprograms_Supported False + Generic_Macro_Expansion_Supported True
+ - See section section Processing Implicit Elements
ASIS Elements represent both explicit and implicit components of Ada programs. There are queries in ASIS which can return implicit Elements (that is, Elements representing implicit Ada constructs) or which can have implicit Elements as parameters.
The ASIS Standard gives the permission to ASIS implementation not to support implicit Elements at all or to support them only partially. If an implementation does not support implicit Element representing a particular kind of Ada implicit constructs, this means, that corresponding ASIS queries return Nil_Element in cases when, according to RM-defined Ada syntax and semantic, they should return implicit Elements representing these implicit constructs.
Now implicit Elements are partially supported by ASIS-for-GNAT. In case of
implicitly declared user-defined inherited subprograms, the queries
Our final goal is to have all the implicit Ada constructs fully implemented in ASIS-for-GNAT.
ASIS Standard says that the number of ASIS Context which can be associated and opened at a time, as well as the number of ASIS Compilation Units which can be processed at a time are implementation-specific. ASIS-for-GNAT does not impose any restrictions on the number of ASIS Context opened at a time in an ASIS application, as well as on the number of ASIS Compilation Units which can be obtained from all the opened Contexts, as long as the application does not go beyond the general system resource limitations.
Note, however, for a Context associated with -FS or -FM option, all the trees create don the fly during obtaining Compilation Units from this Context are placed in the current directory. If the current directory contains also some tree files belonging to another Context, they may be corrupted. To process more then one Context in a safe way, an application should have ot most one Context associated with -FS or -FM option. Moreover, if among Contexts processed at the same time there is a Context which can create trees on the fly, all the other Context should not use tree files located in the current directory.
All the implementation-defined types, subtypes and values depend on the subtype Implementation_Defined_Integer_Type and on the Implementation_Defined_Integer_Constant defined in package Asis. ASIS-for-GNAT does not change the definition given in the specification of package Asis as it stands in the ASIS Standard:
subtype Implementation_Defined_Integer_Type is Integer; Implementation_Defined_Integer_Constant : constant := 2**31-1;
All the ASIS (sub)types used as list indexes for the ASIS array types have this value of Implementation_Defined_Integer_Constant as an upper bound.
This section contains implementation-specific documentation items for the queries having implementation permissions (given under --|IP sentinel in the ASIS definition) or for the queries whose behavior may be implementation-specific for whatever reason. Such queries are ordered according to the presentation in the ASIS definition. We have preserved the clause and subclause numbers from the ASIS definition, putting these numbers between quotes to avoid confusion with section numbers in this manual.
The results returned by the ASIS Debug_Image queries are discussed in section section Interpreting Debug Images.
'8' package Asis.Ada_Environments '8.1' function Default_Name - null string is returned; '8.2' function Default_Parameters - null string is returned; '8.4' procedure Open - what happens during the Context opening is: - for a Context associated with -CA option: - if -FS is also set, nothing is doing; - if -FT or -FM is set, all the tree files (that is, files having .adt suffix) in the tree search path associated with the Context are processed. For every tree file an attempt to read it in is made, and then it is checked that this file was created with -gnatc option. Tree files which cannot be read in or which were not created with -gnatc option are ignored. For all the other trees ASIS collects some black-box information about Compilation Units represented by this tree file, and performs a consistency check for every unit it encounters in the tree (see ASIS-for-GNAT Users' Guide for discussion of the consistency problem). If any consistency check fails, Asis_Failed is raises and the Context remains closed. - for a Context associated with -C1 or -CN option: ASIS process all the tree files associated with the Context, collecting black-box information and doing consistency check for all the encountered Compilation Units. If, because of any reason, a tree file cannot be successfully read in, for a Context associated with -C1 option Asis_Failed is raised and the Context remains closed; and for a Context associated with -CN option, ASIS warning is generated and Context opening goes further. If any consistency check fails, Asis_Failed is raised and the Context remains closed. '10' package Asis.Compilation_Units '10.3' function Unit_Origin - A_Predefined_Unit origin is returned for compilation units listed in RM95, Annex A (2), and only for these units; - An_Implementation_Unit origin is returned for compilation units which are the components of the GNAT Run-Time Library, but which are not mentioned in RM95, Annex A (2); - An_Application_Unit origin is returned for all the other compilation units; '10.6' function Library_Unit_Declaration '10.7' function Compilation_Unit_Body - when processing a Context associated with -FS or -FM option, for both of these queries, if ASIS cannot find a needed unit in the tree files which have been already processed, it tries to create the needed tree by locating the source of the unit and compiling it on the fly. If this attempt fails by any reason, Nil_Compilation_Unit is returned; '10.13' function Corresponding_Declaration: - ASIS-for-GNAT does not make use of ASIS Compilation Units of An_Unknown_Unit kind; - if an argument is of A_Public_Declaration_And_Body class, Nil_Compilation_Unit is returned; '10.14' function Corresponding_Body - ASIS-for-GNAT does not make use of ASIS Compilation Units of An_Unknown_Unit kind; '10.22' function Can_Be_Main_Program - for GNAT, any parameterless library procedure and any parameterless library function returning the result of (any) integer type is classified by this query as a (possible) main subprogram for partition; - If for such a library subprogram both spec and body exist as ASIS Compilation Units retrievable form a given ASIS Context, both of them are considered as Can_Be_Main_Program '10.24' function Text_Name - this function returns the name of the source file containing the source of Compilation_Unit. This name may or may not contain a prefix indicating the directory in the underlying file system, the directory indication may be given in absolute or the relative form, depending on the command line options which were used for the call to GNAT that created the corresponding tree file; - this function does not check the existence of the corresponding source file in the underlying file system, it just reflects the situation which was in effect when the corresponding tree file was created. Thus, if you delete or move the corresponding source file after creating the tree, the full file name returned by this function will be incorrect; - in case of inconsistency (that is, when several versions of the unit's source were used for creating the tree files making up the given ASIS Context), the name of the latest version of the source is returned. '10.25' function Text_Form - In the GNAT compilation model all source files are ordinary text files in the underlying file system. Therefore this function always returns a Nil_Asis_String to indicate that Text_IO.Open uses the default options for manipulating Ada sources. '10.29' function Has_Attribute - Returns False. ASIS-for-GNAT does not provide any additional attributes for Compilation Units. '10.30' function Attribute_Value_Delimiter - Returns (wide) string of the length one and containing LF (wide) character. '10.31' function Attribute_Values - a null string is returned '11' package Asis.Compilation_Units.Times '11.2' function Time_Of_Last_Update - This function returns the time stamp of the corresponding source file. The corresponding source file is the source file whose name is returned by Asis.Compilation_Units. Text_Name. That is to say, this function returns the time of the latest change to the sources for the unit. '13' package Asis.Elements '13.3' function Context_Clause_Elements - this function returns exactly those clauses and pragmas which are in the source for the unit. - returns Nil_Element_List for Nonexistent or Unknown unit. - returns Nil_Element_List for the predefined package Standard. For all other predefined Ada compilation units, returns their context clauses as they appear in the sources held in the GNAT Run-Time Library. '13.5' function Compilation_Pragmas - this function returns exactly those pragmas which are in the source for the unit, both in the context clause and after the end of the text of the compilation unit proper. - returns Nil_Element_List for Nonexistent or Unknown unit. - returns Nil_Element_List for the predefined package Standard. For all the other predefined Ada compilation units, returns the pragmas found in the corresponding sources in the GNAT Run-Time Library. '13.36' function Enclosing_Element - ASIS-for-GNAT does not actually require the Element_Context parameter. The Enclosing_Element function with two parameters just calls the Enclosing_Element function with one parameter for its Element parameter. '15' package Asis.Declarations '15.24' function Body_Block_Statement - If the body passed as the actual has no declarative items on its own, Asis.Statements.Is_Declare_Block returns FALSE for the result of this function '17' package Asis.Expressions '17.6' function Corresponding_Name_Definition - if an argument Reference name is declared implicitly, then if it denotes a user-defined inherited subprogram, the corresponding non-nil defining name Element is returned. Otherwise the function returns Nil_Element. '17.8' function Corresponding_Name_Declaration - if an argument Reference name is declared implicitly, then if it denotes a user-defined inherited subprogram, the corresponding non-nil declaration Element is returned. Otherwise the function returns Nil_Element. '17.29' function Corresponding_Called_Function - For implicitly declared functions, if the actual is an expression that represents a call to an predefined operation, Nil_Element is returned. If it is a call to an implicitly declared user-defined inherited operation, the corresponding (implicit) function declaration is returned; '18' package Asis.Statements '18.14' function Is_Declare_Block - If the argument represents the dummy block statement created by Asis.Declarations.Body_Block_Statement function, the result will be True if and only if the corresponding body has declarative items on its own. '20' package Asis.Text '20.1' type Line - Lines in ASIS-for-GNAT do not contain any character which signify end of line according to RM95, 2.2(2) '20.22' function Delimiter_Image - Returns (wide) string of the length one and containing LF (wide) character.
The following queries from Asis.Compilation_Units are not implemented for a Context associated with -FS or -FM Context option:
Library_Unit_Declarations Compilation_Unit_Bodies Compilation_Units Corresponding_Children Corresponding_Body (formally, this function is implemented, but it may give wrong results) Subunits
There are two kinds of the debugging information available in ASIS-for-GNAT - debug images returned by the ASIS queries Debug_Image for Contexts, Compilation Units and Elements, and debug output generated by ASIS queries when the corresponding implementation debug flag is set ON during ASIS initialization (see section Parameters of Asis.Implementation.Initialize Procedure).
It is easy to interpret the debug images generated for the main ASIS abstractions, because most of the information being generated directly corresponds to ASIS notions. The following details of debug images are implementation-specific:
ASIS provides several internal debug flags which are described in a_debug.adb. Their setting generates (to stdout) useful internal debugging information. This information is not always user-oriented, but the following debug flags may be useful for the ASIS user:
This document was generated on 30 January 2001 using the texi2html translator version 1.51.