[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. Implementation-Specific Features and Implementation Permissions

ASIS permits four kinds of implementation-specific behavior.

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

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

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

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

3.1 Interacting with the Underlying Ada Implementation  
3.2 Implementation Permissions  
3.3 ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results  
3.4 Processing of Predefined Input-Output Packages  
3.5 Representation clauses and `-gnatI' GNAT option  
3.6 Dynamic Context Modes  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 Interacting with the Underlying Ada Implementation

This section describes how to use the Parameters string to pass implementation-specific information to several ASIS subprograms.

3.1.1 Format of the Parameters String  
3.1.2 Parameters of Asis.Implementation.Initialize  
3.1.3 Parameters of Asis.Implementation.Finalize  
3.1.4 Parameters of Asis.Ada_Environments.Associate  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.1 Format of the Parameters String

A Parameters string is passed to three ASIS subprograms: Asis.Implementation.Initialize, Asis.Implementation.Finalize, and Asis.Ada_Environments.Associate.

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

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.2 Parameters of Asis.Implementation.Initialize

The allowed parameters for Asis.Implementation.Initialize are as follows:

-d<flag>
The specific ASIS-for-GNAT debug flag named <flag> is set ON

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

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

-nbb
No bug box. Do not output to Standard_Error the bug box containing the description of the internal implementation bug. Implies -k

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

-we
All ASIS warnings are treated as errors. When execution reaches the point where the warning would occur, the ASIS_Failed exception is raised; the warning message is the ASIS Diagnosis string.

-ws
All ASIS warning messages are suppressed.

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

If more then one parameter controlling the warning mode is set in the Parameters string, all but the last one are ignored.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.3 Parameters of Asis.Implementation.Finalize

No parameters are allowed for Asis.Implementation.Finalize.

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.4 Parameters of Asis.Ada_Environments.Associate

The following parameters are allowed:

-C1
The Context comprises a single tree file, whose name is given as the next parameter in the Parameters string.

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

-CA
The Context comprises all the tree files in the tree search path.

-FS
All the trees considered as making up a given Context are created "on the fly", whether or not the corresponding tree file already exists. Once created, a tree file then is reused as long as the Context remains open.

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

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

-SA
Source files for all the Compilation_Units belonging to the Context (except the predefined Standard package) are considered in the consistency check when opening the Context.

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

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

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

--GCC=compiler_name
Defines the program to be called to create the tree on the fly

-gnatec<file>
Defines the additional configuration file to be used when calling GNAT to create the tree on the fly for `-FS' or `-FM' Context

-gnatA
Avoid processing `gnat.adc' when calling GNAT to create the tree on the fly for `-FS' or `-FM' Context

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

<file_name>
Defines the name of a tree file (used in conjunction with `-C1' or `-CN').

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

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

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

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

If a directory or a file name used as a part of some Context parameter contains space characters, this name should be quoted.

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) directories are present 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 and only if it is set explicitly as `-I.' or `-T.' respectively.

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

 
Asis.Ada_Environments.Associate
  (My_Context,
  "My_Context_Name",
  "-CA -FS -I./dir -I.");

then, when processing a call:

 
My_Unit := Asis.Compilation_Units.Library_Unit_Declaration
            ("Foo", My_Context);

ASIS first tries to locate the source file `foo.ads' in `./dir', and if this attempt fails, it tries to locate it in the current directory. If there is no such file in the current directory, ASIS continues the search by looking into the directories listed in the value of ADA_INCLUDE_PATH environment variable. If the source file is found (say in the current directory), ASIS creates the tree file by calling the compiler:

 
$ 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 further rules define the required combinations of parameters in the actual Parameters string:

In case an incompatible combination is set, ASIS_Failed with Parameter_Error status is raised.

If the actual Parameters string passed to Associate contains no parameters, the default parameters are `-CA', `-FT', and `-SA'.

The `-FS' and `-FM' options define dynamic Context modes; they allow the content of a Context (that is, the set of ASIS Compilation_Units contained in the Context) to be changed while the Context is open. See 3.6 Dynamic Context Modes for more details.

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 Implementation Permissions

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

3.2.1 Asis.Implementation.Permissions Queries  
3.2.2 Processing Implicit Elements  
3.2.3 Processing Several Contexts at a Time  
3.2.4 Implementation-Defined Types and Values  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.1 Asis.Implementation.Permissions Queries

The Boolean queries defined in the Asis.Implementation.Permissions package return the following results:

Query Value
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 True (*)
Inherited_Subprograms_Supported True (*)
Generic_Macro_Expansion_Supported True

(*) See also 3.2.2 Processing Implicit Elements.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.2 Processing Implicit Elements

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

Implicit Elements are partially supported by ASIS-for-GNAT.

ASIS-for-GNAT supports implicit Elements for the following constructs:

ASIS-for-GNAT does not support implicit Elements representing implicit declarations of predefined type operations (such as "=", or the "+" operation for numeric types).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.3 Processing Several Contexts at a Time

According to the ASIS Standard, the number of ASIS Contexts that can be associated and opened at a time, as well as the number of ASIS Compilation_Units that can be processed at a time, are implementation specific. ASIS-for-GNAT does not impose any restriction on the number of Contexts opened at the same time, or on the number of Compilation_Units that can be obtained from all the opened Contexts, as long as the application does not go beyond general system resource limitations.

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.4 Implementation-Defined Types and Values

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's declarations for these entities are the same as 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 ASIS array types have Implementation_Defined_Integer_Constant as an upper bound.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results

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

The results returned by the ASIS Debug_Image queries are discussed in 4.1 Interpreting Debug Images.

ASIS 8 package Asis.Ada_Environments

ASIS 8.1 function Default_Name

ASIS 8.2 function Default_Parameters

ASIS 8.4 procedure Open

ASIS 9 package Asis.Ada_Environments.Containers

ASIS 10 package Asis.Compilation_Units

ASIS 10.3 function Unit_Origin

ASIS 10.6 function Library_Unit_Declaration and ASIS 10.7 function Compilation_Unit_Body

ASIS 10.13 function Corresponding_Declaration

ASIS 10.14 function Corresponding_Body

ASIS 10.22 function Can_Be_Main_Program

ASIS 10.24 function Text_Name

ASIS 10.25 function Text_Form

ASIS 10.26 function Object_Name

ASIS 10.27 function Object_Form

ASIS 10.29 function Has_Attribute

ASIS 10.30 function Attribute_Value_Delimiter

ASIS 10.31 function Attribute_Values

ASIS 11 package Asis.Compilation_Units.Times

ASIS 11.2 function Time_Of_Last_Update

ASIS 11.3 function Compilation_CPU_Duration

ASIS 11.4 function Attribute_Time

ASIS 13 package Asis.Elements

ASIS 13.3 function Context_Clause_Elements

ASIS 13.4 function Configuration_Pragmas

ASIS 13.5 function Compilation_Pragmas

ASIS 13.31 function Is_Equal

ASIS 13.36 function Enclosing_Element

ASIS 15 package Asis.Declarations

ASIS 15.24 function Body_Block_Statement

ASIS 18 package Asis.Statements

ASIS 18.14 function Is_Declare_Block

ASIS 20 package Asis.Text

ASIS 20.1 type Line

ASIS 20.22 function Delimiter_Image


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 Processing of Predefined Input-Output Packages

The GNAT compiler transforms the structure of the predefined input-output packages (Ada.Text_IO, Ada.Wide_Text_IO and Ada.Wide_Wide_Text_IO) to optimize compilations of their clients. The documentation of Ada.Text_IO says:

 
--  Note: the generic subpackages of Text_IO (Integer_IO, Float_IO, Fixed_IO,
--  Modular_IO, Decimal_IO and Enumeration_IO) appear as private children in
--  GNAT. These children are with'ed automatically if they are referenced, so
--  this rearrangement is invisible to user programs, but has the advantage
--  that only the needed parts of Text_IO are processed and loaded.

The same happens for Ada.Wide_Text_IO and Ada.Wide_Wide_Text_IO. In this situation ASIS follows not the Ada Standard, but the actual code contained in the GNAT Run-Time Library. That is, the Anclosing_Compilation_Unit for an ASIS Element representing Ada.Text_IO.Inreger_IO will be not the Compilation_Unit that contains the whole package Ada.Text_IO, but the Compilation_Unit representing its private child as it is described above.

The Asis.Extensions package contains a query named Is_Sub_Package_Implemented_As_Child_Unit that allows to detect such private children of predefined Ada text input-output packages.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5 Representation clauses and `-gnatI' GNAT option

GNAT `-gnatI' allows to ignore all the representation clauses in the code being compiled. This allows to compile the code if it contains representation clauses that are illegal in the given compilation environment. ASIS can process tree files created with `-gnatI', and for the ASIS Context that is based on such trees, ASIS does not yield Elements that correspond to representation clauses.

Node, that you will see these representation clauses in the text images of the enclosing Elements, but nevertheless you will not be able to get them as subcomponents of such Elements.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6 Dynamic Context Modes

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

The difference between the two modes is as follows:

`-FS'
ASIS does not take into account any existing tree file when opening a Context.

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

For both `-FS' and `-FM' Contexts, once a tree file is created it is added to the set of tree files making up the Context and then it is reused (without recreating it from sources again) for the queries dealing with Compilation_Units represented by this tree.

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

 
Asis.Compilation_Units:
     Library_Unit_Declarations
     Compilation_Unit_Bodies
     Compilation_Units
     Corresponding_Children

Another limitation of the dynamic Context mode is that ASIS uses the standard GNAT naming scheme to compute the name of the source to be compiled from the name of the corresponding Ada compilation unit. That is, if the name of the source containing the code of some unit does not follow the GNAT naming scheme, then ASIS will not locate this source, and it will treat this unit as Nil_Compilation_Unit.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by GNAT Mailserver on April, 23 2014 using texi2html