[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
String3.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] | [ ? ] |
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
{
.
There may be 0 or more parameters in a <Space>
,<LF>
, <CR>
}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] | [ ? ] |
Asis.Implementation.Initialize
The allowed parameters for Asis.Implementation.Initialize
are as follows:
-d<flag>
<flag>
is set ON
-dall
-k
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
Standard_Error
the bug box
containing the description of the internal implementation bug. Implies -k
-vs
-we
ASIS_Failed
exception is raised;
the warning message is the ASIS Diagnosis
string.
-ws
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] | [ ? ] |
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] | [ ? ] |
Asis.Ada_Environments.Associate
The following parameters are allowed:
-C1
Context
comprises a single tree file,
whose name is given as the next parameter in the Parameters
string.
-CN
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
Context
comprises all the tree files in the tree search path.
-FS
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
-FM
-SA
Compilation_Unit
s belonging to the
Context
(except
the predefined Standard
package) are considered in the consistency
check when opening the Context
.
-SE
Compilation_Units
belonging to the
Context
are considered in the consistency check when opening the Context
.
-SN
Context
.
-I<dir>
--GCC=compiler_name
-gnatec<file>
-gnatA
-T<dir>
<file_name>
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 "..".
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 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_Unit
s contained in the Context
) to be changed while
the Context
is open. See 3.4 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] | [ ? ] |
This section describes how ASIS-for-GNAT deals with implementation permissions.
3.2.1 Asis.Implementation.Permissions
Queries3.2.2 Processing Implicit Element
s3.2.3 Processing Several Contexts at a Time 3.2.4 Implementation-Defined Types and Values
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 | False (*) |
Inherited_Subprograms_Supported | False (*) |
Generic_Macro_Expansion_Supported | True |
(*) See also 3.2.2 Processing Implicit Element
s.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Element
s
ASIS Element
s represent both explicit and implicit(4)
components of Ada programs.
Some ASIS queries can return implicit Element
s (that is,
Element
s 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 Element
s 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 Element
s are partially supported by ASIS-for-GNAT.
ASIS-for-GNAT supports implicit Element
s for the following constructs:
ASIS-for-GNAT does not
support implicit Element
s representing implicit declarations of predefined
type operations (such as "=
", or the "+
" operation for numeric types).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
According to the ASIS Standard, the number of ASIS Context
s that can be
associated and opened at a time, as well as the number of ASIS
Compilation_Unit
s that can be processed at a time, are implementation specific.
ASIS-for-GNAT does not impose any restriction on the number of Context
s
opened at the same time, or on the number of
Compilation_Unit
s that can be obtained from all the opened Context
s, 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_Unit
s 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 Context
s processed at the same time there is one that can create
trees "on the fly", then the other Context
s should not use tree files located in
the current directory.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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.
package Asis.Ada_Environments
ASIS 8.1 function Default_Name
ASIS 8.2 function Default_Parameters
Context
associated with the `-CA' option:
Context
are processed.
ASIS reads in each tree file and checks
that it was created with
the `-gnatc' option. Tree files that cannot be read in or
that were not created with the `-gnatc' option are ignored.
For each other tree ASIS collects some "black-box"
information about the Compilation_Unit
s that it represents,
and performs a consistency check
for every unit it encounters in the tree (see ASIS-for-GNAT
User's Guide for a discussion of the consistency
problem). If any consistency check fails, ASIS_Failed
is raised and the Context
remains closed.
Context
associated with a `-C1' or `-CN' option, ASIS
processes all the tree files associated with the Context
,
collecting "black-box" information and performing consistency
checks for all the encountered Compilation Units.
If for any reason a tree file cannot be
successfully read in for a Context
associated with a `-C1'
option, ASIS_Failed
is raised and the Context
remains
closed.
If a tree read fails for a Context
associated with a `-CN' option,
an ASIS warning
is generated and the Context
opening process continues.
If any consistency check fails, ASIS_Failed
is raised and the Context
remains closed.
package Asis.Ada_Environments.Containers
Container
model. Every Context
contains exactly one Container
, whose content and name
are the same as its enclosing Context
package Asis.Compilation_Units
ASIS 10.3 function Unit_Origin
A_Predefined_Unit
origin is returned for those compilation units
listed in RM95, Annex A(2), and only for these units.
An_Implementation_Unit
origin is returned for compilation
units that are the components of the GNAT Run-Time
Library, but that are not listed in RM95, Annex A(2).
An_Application_Unit
origin is returned for all other
compilation units.
ASIS 10.6 function Library_Unit_Declaration
and ASIS 10.7 function Compilation_Unit_Body
Context
associated with an `-FS' or `-FM' option,
if ASIS cannot find a needed unit in the tree files
that 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 for any reason, Nil_Compilation_Unit
is returned.
ASIS 10.13 function Corresponding_Declaration
Compilation_Unit
s
of An_Unknown_Unit
kind.
A_Public_Declaration_And_Body
class,
Nil_Compilation_Unit
is returned.
ASIS 10.14 function Corresponding_Body
Compilation_Unit
s
of An_Unknown_Unit
kind.
ASIS 10.22 function Can_Be_Main_Program
Compilation_Unit
s retrievable from a given ASIS Context
, both are considered as
Can_Be_Main_Program
.
Compilation_Unit
. This name may or may not contain a prefix denoting the
directory in the underlying file system. If present, the directory may be
given in absolute or relative form, depending on the command line options
that were used for the call to GNAT that created the corresponding tree
file.
Asis.Extensions.Source_File_Status
to get the information
about the current status of the source file for a Compilation_Unit
.
Nil_Asis_String
to indicate that Text_IO.Open
uses the default
options for manipulating Ada sources.
ASIS 10.26 function Object_Name
ASIS 10.27 function Object_Form
ASIS 10.29 function Has_Attribute
False
. ASIS-for-GNAT does not provide any additional attributes for
Compilation Units.
ASIS 10.30 function Attribute_Value_Delimiter
LF
wide
character.
ASIS 10.31 function Attribute_Values
package Asis.Compilation_Units.Times
ASIS 11.2 function Time_Of_Last_Update
Asis.Compilation_Units.Text_Name
.
ASIS 11.3 function Compilation_CPU_Duration
ASIS 11.4 function Attribute_Time
Nil_ASIS_Time
because
ASIS-for-GNAT does not provide any Compilation_Unit
attributes
package Asis.Elements
ASIS 13.3 function Context_Clause_Elements
Nil_Element_List
if the argument unit is of
A_Nonexistent_Declaration
, A_Nonexistent_Body
or
An_Unknown_Unit
kind
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.
ASIS 13.4 function Configuration_Pragmas
Nil_Element_List
, because in the GNAT
compilation environment "a list of pragmas that apply to all future
compilation_unit elements compiled into The_Context
" essentially depends
on the GNAT options set when compiling a unit (in particular the `-gnatA'
and `-gnatec' options), and this cannot be determined from the
content of the given Context
.
ASIS 13.5 function Compilation_Pragmas
Nil_Element_List
for the predefined package Standard
.
A_Configuration_Compilation
unit (or components thereof) are considered
as being equal only if they are created by the same compilation (belong
to the same tree).
ASIS 13.36 function Enclosing_Element
Element_Context
parameter.
The Enclosing_Element
function with two parameters just calls the
Enclosing_Element
function with one parameter for its Element
parameter.
package Asis.Declarations
ASIS 15.24 function Body_Block_Statement
Asis.Statements.Is_Declare_Block
returns False
.
package Asis.Statements
ASIS 18.14 function Is_Declare_Block
Asis.Declarations.Body_Block_Statement
function, the result will be
True
if and only if the corresponding body has declarative items.
package Asis.Text
ASIS 20.22 function Delimiter_Image
LF
wide character.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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_Unit
s.
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:
Context
.
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' Context
s, 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_Unit
s 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_Unit
s or returning lists of Compilation_Unit
s
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 |
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |