1
ASIS-for-GNAT Reference Manual
2
******************************
4
ASIS-for-GNAT Reference Manual
6
(C) Copyright 2000, Ada Core Technologies, Inc.
8
Permission is granted to make and distribute verbatim copies of this
9
manual provided the copyright notice and this permission notice are
10
preserved on all copies.
12
ASIS-for-GNAT Reference Manual
17
This Manual contains useful information in writing tools and
18
applications using ASIS 95 implementation for the GNAT Ada 95 compiler
19
(ASIS-for-GNAT). It includes information on implementation dependent
20
characteristics and the current implementation limitations of
23
ASIS has been designed to be a portable basis for many useful Ada
24
code analysis tools. However, since ASIS is designed to be implemented
25
for wide variety of Ada compilers, it also contains a number of
26
implementation specific features to be used in interfacing with the
27
underlying Ada implementation, as well as implementation permissions
28
for particular queries
30
Note: Any ASIS application that makes use of
31
implementation-dependent features may be non-portable. You should
32
follow good programming practice and isolate and clearly document any
33
sections of your program that make use of these features in a
36
What This Manual Contains
37
=========================
39
This guide contains the following chapters:
41
- *Note ASIS-for-GNAT and the ASIS Standard:: describes the relations
42
between ASIS-for-GNAT and the existing ASIS International
45
- *Note ASIS Extensions:: describes the ASIS extensions implemented
48
- *Note Implementation-Specific Features and Implementation
49
Permissions:: goes through the aspects of the ASIS definition
50
which are implementation-specific and describes their
51
implementation in ASIS-for-GNAT;
53
- *Note Debugging Information:: describes the debugging information
54
which can be produced by ASIS-for-GNAT
56
What You Should Know Before Reading This Manual
57
===============================================
59
This Reference Manual assumes, that you are familiar with Ada 95
60
language, as described in the International Standard
61
ANSI/ISO/IEC-8652:1995, Jan 1995, and with ASIS 95, as described in the
62
ASIS 95 International Standard ISO/IEC 15291:1999.
64
This Manual relies on some important facts described in the
65
ASIS-for-GNAT User's Guide and uses the terminology introduced in the
71
For more information, see the following documents:
74
- ASIS-for-GNAT User's Guide;
76
- Ada 95 Reference Manual, which contains all reference material for
77
the Ada 95 programming language;
79
- ASIS 95 definition, which contains all reference material for
80
the Ada Semantic Interface Specification;
82
ASIS-for-GNAT and the ASIS Standard
83
***********************************
85
Now the ASIS definition for Ada 95 (ASIS 95) exists as ISO/IEC
86
15291:1999 International Standard. ASIS-for-GNAT supports the ASIS 95
87
interface as it is defined in the ASIS Standard. ASIS-for-GNAT also
88
contains some ASIS extensions (see chapter *Note ASIS Extensions::), as
89
allowed by the ASIS Standard, section 1.1.3.1.
91
Currently some queries in some situations may raise the Asis_Failed
92
exception with Not_Implemented_Error error status. This means, that
93
some part of the functionality of a given query is not implemented yet.
94
If you encounter such a situation, report it as an ordinary
95
ASIS-for-GNAT bug. Our general goal is to have the full implementation
96
of ASIS 95 conforming to the ASIS Standard.
98
ASIS-for-GNAT contains the specifications of all the ASIS interface
99
packages as defined in the ASIS Standard, except the optional Data
100
Decomposition Annex, with no changes, except adding comments in the
101
very beginning, adding with clauses, adding declarations in package
102
private parts and some reformatting needed to follow the GNAT coding
103
style. The only exception is moving the Is_Dispatching_Operation query
104
from Asis.Expressions into Asis.Declarations.
109
ASIS-for-GNAT provides some additional queries as ASIS extensions. All
110
these queries are defined and documented in the hierarchy headed by
111
package Asis.Extensions. They are referred as "ASIS extensions" or
112
"ASIS extension queries" below.
114
All the ASIS extensions obey all the general ASIS rules: when using
115
ASIS extensions, you have to follow the required sequiensing of calls,
116
only ASIS-defined exceptions are allowed to propagate outside the ASIS
117
exception queries. If the documentation of an ASIS exception query
118
contains a list of appropriate element kinds, then this query can be
119
applied only to Elements from this list and it raises
120
ASIS_Inappropriate_Element with Value_Error status otherwise. If the
121
documentation of an ASIS exception query contains a list of expected
122
element kinds, then this query can be applied to an Element having any
123
kind, but it returns meaningful result only for Elements from this list.
125
The current set of ASIS extensions originated from the ASIS
126
implementation needs and from the development of some ASIS tools inside
127
the ASIS-for-GNAT team. As it stands now, Asis.Extensions hierarchy is
128
not supposed to be stable - some queries may be removed from it, some
129
new extension queries may be added. We are very interested in ASIS
130
application developers feedback to implement a compact, but useful set
131
of extension queries in ASIS-for-GNAT.
133
Currently Asis.Extensions hierarchy contains its top Asis.Extensions
134
package defining a set of various-purpose extensions, and its only child
135
Asis.Extensions.Flat_Kinds, which defines a "flat" Element
138
Asis.Extensions package contains the following extension types and
139
queries (see the specification of Asis.Extensions in the file named
140
`asis-extensions.ads' for full details):
142
1. Types for dynamic Elements and Compilation Units lists:
144
type Element_List_Access is access Element_List;
145
type Compilation_Unit_List_Access is
146
access Compilation_Unit_List;
148
an application may use dynamic allocation to keep the results of
149
queries returning lists (instead of declaring local list
150
variables in block statements)
152
2. Placeholders for Traverse_Element instantiations:
154
type No_State is (Not_Used);
155
-- Placeholder for the State_Information formal type
158
(Element : Asis.Element;
159
Control : in out Traverse_Control;
160
State : in out No_State);
161
-- Placeholder for the formal Post_Operation procedure
163
In many simple cases of instantiating Traverse_Element, the only
164
needed actual is the actual for Pre_Operation, so these
165
placeholders for traversal state and post-operation may be
166
used to get the legal instantiation;
170
function Is_Primitive_Operation (Declaration : Asis.Element)
173
-- Checks if its argument is a declaration of a (user-defined)
174
-- primitive operation of some type (both explicit and implicit
175
-- declarations are expected).
177
function Acts_As_Spec (Declaration : Asis.Element)
180
-- Checks if there is no separate subprogram declaration for a
181
-- given body declaration or body stub.
183
function Is_Renaming_As_Body (Declaration : Asis.Element)
185
-- Checks if its argument is a renaming-as-body declaration.
187
function Is_Completed (Declaration : Asis.Element)
189
-- Checks if its argument (which is expected to be a
190
-- declaration requiring completion) has a completion in its
191
-- enclosed ASIS Context.
193
function Is_True_Expression (Expression : Asis.Expression)
195
-- Checks if Expression is an expression in Ada sense, that is
196
-- if it is an expression as defined in RM 4.4, and the type of
197
-- this expression can be represented in ASIS. For cases of
198
-- An_Expression Element for which Is_True_Expression is True,
199
-- the Corresponding_Expression_Type query should yield non-Nil
202
function Is_Static (Expression : Asis.Expression)
204
-- Checks if Expression is static in the GNAT sense, that is if
205
-- the compiler computes its value during the compilation time.
206
-- We believe that this notion of a static expression is close
207
-- to the definition of static expression in RM 95, but we can
208
-- not guarantee this.
210
4. Modified versions of the "primary" ASIS queries:
213
type State_Information is limited private;
215
with procedure Pre_Operation
216
(Element : in Asis.Element;
217
Control : in out Traverse_Control;
218
State : in out State_Information) is <>;
220
with procedure Post_Operation
221
(Element : in Asis.Element;
222
Control : in out Traverse_Control;
223
State : in out State_Information) is <>;
225
procedure Traverse_Unit
226
(Unit : in Asis.Compilation_Unit;
227
Control : in out Traverse_Control;
228
State : in out State_Information);
229
-- A generalized version of Asis.Iterator.Traverse_Element.
230
-- Traverses the whole structure of the argument Compilation
233
function Formal_Subprogram_Default
234
(Declaration : in Asis.Generic_Formal_Parameter)
235
return Asis.Expression;
236
-- This is a modified version of the
237
-- Asis.Declarations.Formal_Subprogram_Default query. It returns
238
-- Nil_Element instead of raising Asis_Inappropriate_Element if
239
-- Subprogram_Default_Kinds of its argument is not
242
function Primary_Owner
243
(Declaration : Asis.Declaration)
244
return Asis.Declaration;
245
-- In the case that Declaration is Is_Primary_Operation for some
246
-- tagged type, this function returns the tagged type definition
247
-- for which it is a primary operation.
249
function Corresponding_Called_Function_Unwinded
250
(Expression : in Asis.Expression)
251
return Asis.Declaration;
252
-- This is the modification of
253
-- Asis.Expressions.Corresponding_Called_Function which unwinds
254
-- all the renamings in case if the function name in the
255
-- argument function call is defined by a renaming declaration.
256
-- This function returns the declaration of the called function
259
function Corresponding_Called_Entity_Unwinded
260
(Statement : in Asis.Statement)
261
return Asis.Declaration;
262
-- This is the modification of
263
-- Asis.Statements.Corresponding_Called_Entity which unwinds all
264
-- the renamings in case if the procedure or entry name in the
265
-- argument call is defined by a renaming declaration. This
266
-- function returns the declaration of the callable *entity*.
268
5. Extensions of ASIS functionality:
270
function Is_Obsolete (Right : Asis.Compilation_Unit)
272
-- Checks if a unit is obsolete.
274
type Source_File_Statuses is
275
(No_File_Status, Absent, Older, Newer, Up_To_Date);
277
function Source_File_Status
278
(Right : Asis.Compilation_Unit)
279
return Source_File_Statuses;
280
-- Checks the status of the source file for the argument unit.
282
function Is_Main_Unit_In_Tree
283
(Right : Asis.Compilation_Unit)
285
-- Checks if a unit is a main unit from some compilation which
286
-- has created a tree within the set of tree files making up the
287
-- enclosing Context.
289
function Compilation_Dependencies
290
(Main_Unit : Asis.Compilation_Unit)
291
return Asis.Compilation_Unit_List;
292
-- Provides the full list of units upon which Main_Unit depends
293
-- in the GNAT compilation system.
295
function Corresponding_First_Definition
296
(Defining_Name : in Asis.Defining_Name)
297
return Asis.Defining_Name;
298
-- In case if there are more then one defining occurrence of an
299
-- argument Defining_Name representing the same view of the same
300
-- entity, this function returns the first defining occurrence
301
-- which actually introduces the entity.
303
function Corresponding_Body_Parameter_Definition
304
(Defining_Name : Asis.Defining_Name)
305
return Asis.Defining_Name;
306
-- When applying to a defining name which is a name of a formal
307
-- parameter of a subprogram, this function returns the defining
308
-- name of this parameter from a subprogram body.
310
function Element_Span_In_Template
311
(Element : Asis.Element)
312
return Asis.Text.Span;
313
-- If Is_Part_Of_Instance is True for the argument Element, then
314
-- this function returns the span of the corresponding piece of
315
-- code in the generic template. Otherwise a Nil_Span is
316
-- returned. Nil_Span is also returned if Is_Part_Of_Implicit
317
-- Element is True for Element.
319
function Element_Image_In_Template
320
(Element : Asis.Element)
322
-- If Is_Part_Of_Instancce is True for the argument Element,
323
-- then this function returns the image of the corresponding
324
-- piece of code in the generic template. Otherwise a null
325
-- string is returned. A null string is also returned if
326
-- Is_Part_Of_Implicit_ELement is true for Element
328
6. General_Purpose Extensions:
330
function Get_Last_Component (E : Asis.Element)
332
-- Returns the right-most direct component of its argument.
334
function Components (E : Asis.Element) return Asis.Element_List;
335
-- Returns the list of all the first-level components of its
338
Asis.Extensions.Flat_Kinds package contains the definition of the type
339
Flat_Element_Kinds. This type defines a "flat" Element classification
340
which is equivalent to the Element classification hierarchy defined in
341
Asis package: each kind value of the original hierarchy having
342
subordinate kinds is replaced by the corresponding subordinate range.
343
Asis.Extensions.Flat_Kinds package also provides conversion functions
344
from the "flat" classification into the original classification
347
Implementation-Specific Features and Implementation Permissions
348
***************************************************************
350
There are three kinds of implementation dependencies in ASIS.
352
First, ASIS subprograms which define an interface between an ASIS
353
implementation and the underlying Ada implementation have
354
implementation-specific parameters. There are three queries of this
355
kind - Asis.Implementation.Initialize, Asis.Implementation.Finalize and
356
Asis.Ada_Enfironments.Associate, all of them have a string parameter
357
named Parameters which has implementation-specific meaning. The meaning
358
of Parameters string in ASIS-for-GNAT is discussed in section *Note
359
Interacting with the Underlying Ada Implementation::.
361
Second, some ASIS areas are considered as making problems for ASIS
362
implementations. For such areas, the Asis Working Draft contains
363
explicit implementation permissions which allow an ASIS implementation
364
not to implement some part of the ASIS functionality or to implement it
365
in a restricted way. Each of these permissions usually affects more,
366
then one particular ASIS query. The ASIS package
367
Asis.Implementation.Permissions contains boolean queries which tell you
368
what choices are made for these implementation permission in a given
369
ASIS implementation. The solutions taken in ASIS-for-GNAT for these
370
general implementation permissions are discussed in section *Note
371
Implementation Permissions::.
373
Third, for some ASIS queries implementation permissions which are
374
specific for a given query are given explicitly in the ASIS Working
375
Draft. For some other queries, the result of a query may be
376
implementation-specific because of the very nature of the query, even
377
though it is not explicitly said so in the ASIS Standard. Such queries
378
are discussed in section *Note ASIS Queries Having Specific
379
Implementation Permissions or Implementation-Specific Results::.
381
Interacting with the Underlying Ada Implementation
382
==================================================
384
Format of the Parameters string
385
-------------------------------
387
A Parameters string is a parameter of the three ASIS subprograms:
388
Asis.Implementation. Initialize, Asis.Implementation.Finalize and
389
Asis.Ada_Environments.Associate. The following requirements are common
390
for all these subprograms:
392
- A Parameters string are considered as consisting on substrings
393
bounded by the beginning of the string, the end of the string,
394
space character, LF or CR and containing no space character, LF
395
or CR inside. These substrings are called parameters (with
398
- any number of space character, CR and LF are allowed before the
399
first parameter, after the last parameter and between any two
402
- each of the queries Asis.Implementation.Initialize,
403
Asis.Implementation.Finalize and Asis.Ada_Enfironments.Associate
404
has its own requirements imposed on its parameters. For all of
405
these queries, if some parameter does not match the rules for a
406
given query, either an error message is generated or Asis_Failed
407
with the Parameter_Error status is raised. In this manual, the
408
situations when Asis_Failed is raised when processing the
409
Parameters string are documented specially.
411
Parameters of Asis.Implementation.Initialize Procedure
412
------------------------------------------------------
414
The allowed parameters for Asis.Implementation.Initialize are:
417
sets the ASIS-for-GNAT debug flag <debug_flag> ON
420
sets all the ASIS-for-GNAT debug flags ON.
423
sets the ASIS warning mode (This is under development at the
426
Now <debug_flag> may be any lower case letter from 'a' to 'z' or any
427
digit from 0 to 9 (not all of the corresponding options are implemented
430
ASIS debug flags are documented in the file `a_debug.adb'. (See
431
also section *Note ASIS Debug Flags:: for some advices)
433
<warning_mode> could be either 's', which means "suppress all the
434
warning messages" or 'e', which means "treat every warning as an
435
error", and in this case every warning are converted in Asis_Failed
436
raising with warning messages as ASIS Diagnosis strings.
438
If more then one parameter controlling the warning mode is set in the
439
diagnosis string, each of them changes the warning mode in the place
442
See also ASIS-for-GNAT Users' Guide for more information about
445
Parameters of Asis.Implementation.Finalize Procedure
446
----------------------------------------------------
448
No parameter is allowed for Asis.Implementation.Finalize in the current
449
ASIS-for-GNAT version.
451
When called, Asis.Implementation.Finalize resets all the general
452
ASIS-for-GNAT parameters to the default values (that is, all the debug
453
flags are set off, and the warning mode is set to the default warning
456
Parameters of Asis.Ada_Environments.Associate Procedure
457
-------------------------------------------------------
459
The following parameters are allowed for this query:
462
a Context is made up by a single tree file, this tree file name
463
should be given explicitly in the Parameters string;
466
a Context is made up by a set of tree files, the names of the tree
467
files making up the Context should be given explicitly in
468
the Parameters string;
471
a Context is made up by all the tree files in the tree search path;
474
all the trees considered as making up a given Context are created
475
on the fly, whether or not the corresponding tree file
476
already exists; once created, a tree file may then be reused
477
till the Context remains open;
480
only pre-created trees are used, no tree file can be created by
484
mixed approach: if a needed tree does not exist, the attempt to
485
create it on the fly is made;
488
source files for all the Compilation Units belonging to the Context
489
(except the predefined Standard package) are considered in
490
the consistency check when opening the Context;
493
only existing source files for all the Compilation Units belonging
494
to the Context are considered in the consistency check when
498
no source file from the underlying file system is taken into
499
account when checking the consistency of the set of tree
500
files making up a Context;
503
defines the directory to look for a source file;
506
defines the directory to look for a tree file;
509
defines the name of a tree file;
511
For -I and -T parameters, <dir> should denote an existing directory in
512
the underlying file system, notations as "." and ".." are allowed, as
513
well as relative or absolute directory names. If <dir> does not denote
514
an existing directory, Asis_Failed with Parameter_Error status is
517
A tree file name given by a <file_name> parameter may or may not
518
contain directory information.
520
The search path associated with an ASIS Context consists of the
521
directories listed as parameters for the
522
Asis.Ada_Environments.Associate query, in the same order as they are
523
included in the actual Parameters string. The ASIS source search path
524
consists only of the directories following '-I', and the ASIS tree
525
search path consists only of the directories following '-T'. If no
526
source (tree) directory presents in the value of the Parameters string,
527
then the ASIS source (tree) search path consists of the current
528
directory only, otherwise the current directory is included in the ASIS
529
search path if amd only if it is set explicitly as -I. or -T.
532
If an ASIS Context is associated with -FS or -FM option, the Context
533
source search path to locate sources of the units to create a tree file
534
for, and to locate other source files needed when called GNAT to create
535
tree files. For example, if we have:
537
Asis.Ada_Environments.Associate
540
"-CA -FS -I./dir -I.");
542
then, when processing a call:
544
My_Unit := Asis.Compilation_Units.Library_Unit_Declaration
547
ASIS first try to locate the source file foo.ads in ./dir, and if
548
this attempt fails, it tries to locate it in the current directory. If
549
the source file is found (let it be in the current directory), ASIS
550
calls GNAT to create the tree file as
552
gcc -c -gnatc -gnatt -I./dir -I. -I- foo.ads
554
If an ASIS Context is associated with -CA option, then, when this
555
Context is opened, ASIS processes all the tree files located in the
556
tree search path associated with the Context.
558
The following restrictions are imposed on allowed combinations of
559
parameters in the actual Parameters string of the
560
Asis.Ada_Environments.Associate query:
562
* -C1 and -CN require FT
564
* -C1 requires exactly one tree file to be set
566
* -CN requires at least one tree file to be set
568
* -CA does not allow a tree file name
570
* -FS and -FM require -SA
572
In case if an incompatible combination is set, Asis_Failed with
573
Parameter_Error status is raised
575
In case if the actual for the Parameters string in a call to the
576
query `Associate' is an empty string, the default parameters are: "-CA
579
Note, that the definition of the parameters might change later on.
581
For the Name parameter of the Asis.Ada_Environments.Associate query
582
any string can be passed as an actual. In the current ASIS-for-GNAT
583
version no verification is performed for an actual and no semantic is
584
associated with the Name parameter of the
585
Asis.Ada_Environments.Associate query.
587
Implementation Permissions
588
==========================
590
Asis.Implementation.Permissions Queries
591
---------------------------------------
593
The Boolean queries defined in the `Asis.Implementation.Permissions'
594
package return the following results under ASIS-for-GNAT:
596
Is_Formal_Parameter_Named_Notation_Supported True
597
Default_In_Mode_Supported True
598
Generic_Actual_Part_Normalized False
599
Record_Component_Associations_Normalized False
600
Is_Prefix_Call_Supported True
601
Function_Call_Parameters_Normalized False
602
Call_Statement_Parameters_Normalized False
603
Discriminant_Associations_Normalized False
604
Is_Line_Number_Supported True
605
Is_Span_Column_Position_Supported True
606
Is_Commentary_Supported True
607
Attributes_Are_Supported False
608
Implicit_Components_Supported False +
609
Object_Declarations_Normalized False
610
Predefined_Operations_Supported False +
611
Inherited_Declarations_Supported False +
612
Inherited_Subprograms_Supported False +
613
Generic_Macro_Expansion_Supported True
615
+ - See section *Note Processing Implicit Elements::
617
Processing Implicit Elements
618
----------------------------
620
ASIS Elements represent both explicit and implicit components of Ada
621
programs. There are queries in ASIS which can return implicit Elements
622
(that is, Elements representing implicit Ada constructs) or which can
623
have implicit Elements as parameters.
625
The ASIS Standard gives the permission to ASIS implementation not to
626
support implicit Elements at all or to support them only partially. If
627
an implementation does not support implicit Element representing a
628
particular kind of Ada implicit constructs, this means, that
629
corresponding ASIS queries return Nil_Element in cases when, according
630
to RM-defined Ada syntax and semantic, they should return implicit
631
Elements representing these implicit constructs.
633
Now implicit Elements are partially supported by ASIS-for-GNAT. In
634
case of implicitly declared user-defined inherited subprograms, the
635
queries `Asis.Expressions.Corresponding_Name_Definition',
636
Asis.Expressions.Corresponding_Called_Function and
637
`Asis.Statements.Corresponding_Called_Entity' return non-nil result
638
representing the corresponding entity. In case of implicitly declared
639
predefined operations, `Nil_Element' is returned.
641
Our final goal is to have all the implicit Ada constructs fully
642
implemented in ASIS-for-GNAT.
644
Processing Several Contexts at a Time
645
-------------------------------------
647
ASIS Standard says that the number of ASIS Context which can be
648
associated and opened at a time, as well as the number of ASIS
649
Compilation Units which can be processed at a time are
650
implementation-specific. ASIS-for-GNAT does not impose any
651
restrictions on the number of ASIS Context opened at a time in an ASIS
652
application, as well as on the number of ASIS Compilation Units which
653
can be obtained from all the opened Contexts, as long as the
654
application does not go beyond the general system resource limitations.
656
Note, however, for a Context associated with -FS or -FM option, all
657
the trees create don the fly during obtaining Compilation Units from
658
this Context are placed in the current directory. If the current
659
directory contains also some tree files belonging to another Context,
660
they may be corrupted. To process more then one Context in a safe way,
661
an application should have ot most one Context associated with -FS or
662
-FM option. Moreover, if among Contexts processed at the same time
663
there is a Context which can create trees on the fly, all the other
664
Context should not use tree files located in the current directory.
666
Implementation-Defined Types and Values
667
---------------------------------------
669
All the implementation-defined types, subtypes and values depend on the
670
subtype Implementation_Defined_Integer_Type and on the
671
Implementation_Defined_Integer_Constant defined in package Asis.
672
ASIS-for-GNAT does not change the definition given in the specification
673
of package Asis as it stands in the ASIS Standard:
675
subtype Implementation_Defined_Integer_Type is Integer;
676
Implementation_Defined_Integer_Constant : constant := 2**31-1;
678
All the ASIS (sub)types used as list indexes for the ASIS array types
679
have this value of Implementation_Defined_Integer_Constant as an upper
682
ASIS Queries Having Specific Implementation Permissions or Implementation-Specific Results
683
==========================================================================================
685
This section contains implementation-specific documentation items for
686
the queries having implementation permissions (given under -|IP
687
sentinel in the ASIS definition) or for the queries whose behavior may
688
be implementation-specific for whatever reason. Such queries are ordered
689
according to the presentation in the ASIS definition. We have preserved
690
the clause and subclause numbers from the ASIS definition, putting
691
these numbers between quotes to avoid confusion with section numbers in
694
The results returned by the ASIS Debug_Image queries are discussed in
695
section *Note Interpreting Debug Images::.
697
'8' package Asis.Ada_Environments
699
'8.1' function Default_Name
700
- null string is returned;
702
'8.2' function Default_Parameters
703
- null string is returned;
706
- what happens during the Context opening is:
708
- for a Context associated with -CA option:
709
- if -FS is also set, nothing is doing;
710
- if -FT or -FM is set, all the tree files (that is,
711
files having .adt suffix) in the tree search path
712
associated with the Context are processed. For every
713
tree file an attempt to read it in is made, and then
714
it is checked that this file was created with
715
-gnatc option. Tree files which cannot be read in or
716
which were not created with -gnatc option are ignored.
717
For all the other trees ASIS collects some black-box
718
information about Compilation Units represented by
719
this tree file, and performs a consistency check for
720
every unit it encounters in the tree (see ASIS-for-GNAT
721
Users' Guide for discussion of the consistency
722
problem). If any consistency check fails, Asis_Failed
723
is raises and the Context remains closed.
725
- for a Context associated with -C1 or -CN option: ASIS
726
process all the tree files associated with the Context,
727
collecting black-box information and doing consistency
728
check for all the encountered Compilation Units. If,
729
because of any reason, a tree file cannot be
730
successfully read in, for a Context associated with -C1
731
option Asis_Failed is raised and the Context remains
732
closed; and for a Context associated with -CN option,
733
ASIS warning is generated and Context opening goes
734
further. If any consistency check fails, Asis_Failed is
735
raised and the Context remains closed.
737
'10' package Asis.Compilation_Units
739
'10.3' function Unit_Origin
740
- A_Predefined_Unit origin is returned for compilation units
741
listed in RM95, Annex A (2), and only for these units;
743
- An_Implementation_Unit origin is returned for compilation
744
units which are the components of the GNAT Run-Time
745
Library, but which are not mentioned in RM95, Annex A (2);
747
- An_Application_Unit origin is returned for all the other
751
'10.6' function Library_Unit_Declaration
752
'10.7' function Compilation_Unit_Body
753
- when processing a Context associated with -FS or -FM
754
option, for both of these queries, if ASIS cannot find a
755
needed unit in the tree files which have been already
756
processed, it tries to create the needed tree by locating
757
the source of the unit and compiling it on the fly. If
758
this attempt fails by any reason, Nil_Compilation_Unit
761
'10.13' function Corresponding_Declaration:
762
- ASIS-for-GNAT does not make use of ASIS Compilation Units
763
of An_Unknown_Unit kind;
764
- if an argument is of A_Public_Declaration_And_Body class,
765
Nil_Compilation_Unit is returned;
767
'10.14' function Corresponding_Body
768
- ASIS-for-GNAT does not make use of ASIS Compilation Units
769
of An_Unknown_Unit kind;
771
'10.22' function Can_Be_Main_Program
772
- for GNAT, any parameterless library procedure and any
773
parameterless library function returning the result of
774
(any) integer type is classified by this query as a
775
(possible) main subprogram for partition;
777
- If for such a library subprogram both spec and body exist
778
as ASIS Compilation Units retrievable form a given ASIS
779
Context, both of them are considered as
782
'10.24' function Text_Name
783
- this function returns the name of the source file
784
containing the source of Compilation_Unit. This name may
785
or may not contain a prefix indicating the directory in
786
the underlying file system, the directory indication may
787
be given in absolute or the relative form, depending on
788
the command line options which were used for the call
789
to GNAT that created the corresponding tree file;
790
- this function does not check the existence of the
791
corresponding source file in the underlying file system,
792
it just reflects the situation which was in effect when
793
the corresponding tree file was created. Thus, if you
794
delete or move the corresponding source file after
795
creating the tree, the full file name returned by this
796
function will be incorrect;
797
- in case of inconsistency (that is, when several versions
798
of the unit's source were used for creating the tree files
799
making up the given ASIS Context), the name of the latest
800
version of the source is returned.
802
'10.25' function Text_Form
803
- In the GNAT compilation model all source files are
804
ordinary text files in the underlying file system.
805
Therefore this function always returns a Nil_Asis_String
806
to indicate that Text_IO.Open uses the default options for
807
manipulating Ada sources.
808
'10.29' function Has_Attribute
809
- Returns False. ASIS-for-GNAT does not provide any
810
additional attributes for Compilation Units.
812
'10.30' function Attribute_Value_Delimiter
813
- Returns (wide) string of the length one and containing LF
816
'10.31' function Attribute_Values
817
- a null string is returned
820
'11' package Asis.Compilation_Units.Times
822
'11.2' function Time_Of_Last_Update
823
- This function returns the time stamp of the corresponding
824
source file. The corresponding source file is the source
825
file whose name is returned by Asis.Compilation_Units.
826
Text_Name. That is to say, this function returns the time
827
of the latest change to the sources for the unit.
829
'13' package Asis.Elements
831
'13.3' function Context_Clause_Elements
832
- this function returns exactly those clauses and pragmas
833
which are in the source for the unit.
834
- returns Nil_Element_List for Nonexistent or Unknown unit.
835
- returns Nil_Element_List for the predefined package
836
Standard. For all other predefined Ada compilation units,
837
returns their context clauses as they appear in the
838
sources held in the GNAT Run-Time Library.
840
'13.5' function Compilation_Pragmas
841
- this function returns exactly those pragmas which are in
842
the source for the unit, both in the context clause and
843
after the end of the text of the compilation unit proper.
844
- returns Nil_Element_List for Nonexistent or Unknown unit.
846
- returns Nil_Element_List for the predefined package
847
Standard. For all the other predefined Ada compilation
848
units, returns the pragmas found in the corresponding
849
sources in the GNAT Run-Time Library.
851
'13.36' function Enclosing_Element
852
- ASIS-for-GNAT does not actually require the
853
Element_Context parameter. The Enclosing_Element function
854
with two parameters just calls the Enclosing_Element
855
function with one parameter for its Element parameter.
858
'15' package Asis.Declarations
860
'15.24' function Body_Block_Statement
861
- If the body passed as the actual has no declarative items
862
on its own, Asis.Statements.Is_Declare_Block returns FALSE
863
for the result of this function
865
'17' package Asis.Expressions
867
'17.6' function Corresponding_Name_Definition
868
- if an argument Reference name is declared implicitly, then
869
if it denotes a user-defined inherited subprogram, the
870
corresponding non-nil defining name Element is returned.
871
Otherwise the function returns Nil_Element.
873
'17.8' function Corresponding_Name_Declaration
874
- if an argument Reference name is declared implicitly, then
875
if it denotes a user-defined inherited subprogram, the
876
corresponding non-nil declaration Element is returned.
877
Otherwise the function returns Nil_Element.
879
'17.29' function Corresponding_Called_Function
880
- For implicitly declared functions, if the actual is an
881
expression that represents a call to an predefined
882
operation, Nil_Element is returned. If it is a call to an
883
implicitly declared user-defined inherited operation, the
884
corresponding (implicit) function declaration is returned;
886
'18' package Asis.Statements
888
'18.14' function Is_Declare_Block
889
- If the argument represents the dummy block statement
890
created by Asis.Declarations.Body_Block_Statement
891
function, the result will be True if and only if the
892
corresponding body has declarative items on its own.
895
'20' package Asis.Text
898
- Lines in ASIS-for-GNAT do not contain any character which
899
signify end of line according to RM95, 2.2(2)
901
'20.22' function Delimiter_Image
902
- Returns (wide) string of the length one and containing LF
905
Restrictions Specific to -FS and -FM Context options
906
====================================================
908
The following queries from Asis.Compilation_Units are not implemented
909
for a Context associated with -FS or -FM Context option:
911
Library_Unit_Declarations
912
Compilation_Unit_Bodies
914
Corresponding_Children
915
Corresponding_Body (formally, this function is implemented, but
916
it may give wrong results)
919
Debugging Information
920
*********************
922
There are two kinds of the debugging information available in
923
ASIS-for-GNAT - debug images returned by the ASIS queries Debug_Image
924
for Contexts, Compilation Units and Elements, and debug output
925
generated by ASIS queries when the corresponding implementation debug
926
flag is set ON during ASIS initialization (see *Note Parameters of
927
AsisImplementationInitialize Procedure::).
929
Interpreting Debug Images
930
=========================
932
It is easy to interpret the debug images generated for the main ASIS
933
abstractions, because most of the information being generated directly
934
corresponds to ASIS notions. The following details of debug images are
935
implementation-specific:
940
this is the internal Context Id used in the internal
941
implementation data structures. This Id is assigned to a
942
Context when it is associated for the first time, and it
943
remains unchanged and unique unlit ASIS is finalized.
946
the number of the tree files making up the given Context
951
this is the internal Compilation_Unit Id used in the internal
952
implementation data structures. This Id remains unchanged and
953
unique unlit the unit's enclosed Context is closed.
956
TRUE if the same version of the unit's source was used for
957
all the tree files making up the enclosed unit's context, and
962
`Node, R_Node, Node_Field_1'
963
tree nodes on which the internal representation of a given
964
Element is based. They are meaningful only in the tree file
965
indicated in the Enclosing_Tree field of the debug image
968
implementation-specific indication of the cases when the
969
element needs some special processing
971
`"obtained from the tree"'
972
the Id and the name of the tree file from which the
973
tree-specific fields of the internal representation of given
974
Element were obtained
977
indicates the (relative) position of the source text of the
978
Element, counting from the beginning of the source of its
979
enclosing compilation unit. Makes sense for implicit Elements
986
ASIS provides several internal debug flags which are described in
987
a_debug.adb. Their setting generates (to stdout) useful internal
988
debugging information. This information is not always user-oriented,
989
but the following debug flags may be useful for the ASIS user:
992
outputs the content of the internal data structures for a Context,
993
when the Context is closed and dissociated. By analyzing
994
this information, you may map other debug information onto
998
turns off including the location of an Element into its
999
Debug_Image. It may be useful if an ASIS program crashes
1000
because of some problem with ASIS structural queries
1001
(structural queries are used by Element's Debug_Image
1002
query to compute the source location of the argument).
1005
when the Context is opened, lists the tree files being processed,
1006
and the ones selected to represent a given Context
1009
outputs a message every time when a tree file is read in. This
1010
information may be useful to analyze the "tree swapping
1011
profile of your application to cut down the number of tree
added
removed
documentation/asis_rm.txt
