| blob | 075684353fa8e118096221e2be9e54c62f1625a1 |
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- L I B . X R E F --
6 -- --
7 -- S p e c --
8 -- --
9 -- $Revision: 1.4 $
10 -- --
11 -- Copyright (C) 1998-2001, Free Software Foundation, Inc. --
12 -- --
13 -- GNAT is free software; you can redistribute it and/or modify it under --
14 -- terms of the GNU General Public License as published by the Free Soft- --
15 -- ware Foundation; either version 2, or (at your option) any later ver- --
16 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
17 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
18 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
19 -- for more details. You should have received a copy of the GNU General --
20 -- Public License distributed with GNAT; see file COPYING. If not, write --
21 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
22 -- MA 02111-1307, USA. --
23 -- --
24 -- GNAT was originally developed by the GNAT team at New York University. --
25 -- Extensive contributions were provided by Ada Core Technologies Inc. --
26 -- --
27 ------------------------------------------------------------------------------
29 -- This package contains for collecting and outputting cross-reference
30 -- information.
37 -------------------------------------------------------
38 -- Format of Cross-Reference Information in ALI File --
39 -------------------------------------------------------
41 -- Cross-reference sections follow the dependency section (D lines) in
42 -- an ALI file, so that they need not be read by gnatbind, gnatmake etc.
43 --
44 -- A cross reference section has a header of the form
45 --
46 -- X dependency-number filename
47 --
48 -- This header precedes xref information (entities/references from
49 -- the unit, identified by dependency number and file name. The
50 -- dependency number is the index into the generated D lines and
51 -- is ones origin (i.e. 2 = reference to second generated D line).
52 --
53 -- Note that the filename here will reflect the original name if
54 -- a Source_Reference pragma was encountered (since all line number
55 -- references will be with respect to the original file).
56 --
57 -- The lines following the header look like
58 --
59 -- line type col level entity renameref typeref ref ref ref
60 --
61 -- line is the line number of the referenced entity. It starts
62 -- in column one.
63 --
64 -- type is a single letter identifying the type of the entity.
65 -- See next section (Cross-Reference Entity Identifiers) for a
66 -- full list of the characters used).
67 --
68 -- col is the column number of the referenced entity
69 --
70 -- level is a single character that separates the col and
71 -- entity fields. It is an asterisk for a top level library
72 -- entity that is publicly visible, and space otherwise.
73 --
74 -- entity is the name of the referenced entity, with casing in
75 -- the canical casing for the source file where it is defined.
77 -- renameref provides information on renaming. If the entity is
78 -- a package, object or overloadable entity which is declared by
79 -- a renaming declaration, and the renaming refers to an entity
80 -- with a simple identifier or expanded name, then renameref has
81 -- the form:
82 --
83 -- =line:col
84 --
85 -- Here line:col give the reference to the identifier that
86 -- appears in the renaming declaration. Note that we never need
87 -- a file entry, since this identifier is always in the current
88 -- file in which the entity is declared. Currently, renameref
89 -- appears only for the simple renaming case. If the renaming
90 -- reference is a complex expressions, then renameref is omitted.
91 --
92 -- typeref is the reference for a related type. This part is
93 -- optional. It is present for the following cases:
94 --
95 -- derived types (points to the parent type) LR=<>
96 -- access types (points to designated type) LR=()
97 -- subtypes (points to ancestor type) LR={}
98 -- functions (points to result type) LR={}
99 -- enumeration literals (points to enum type) LR={}
100 -- objects and components (points to type) LR={}
101 --
102 -- In the above list LR shows the brackets used in the output,
103 -- which has one of the two following forms:
104 --
105 -- L file | line type col R user entity
106 -- L name-in-lower-case R standard entity
107 --
108 -- For the form for a user entity, file is the dependency number
109 -- of the file containing the declaration of the related type.
110 -- This number and the following vertical bar are omitted if the
111 -- relevant type is defined in the same file as the current entity.
112 -- The line, type, col are defined as previously described, and
113 -- specify the location of the relevant type declaration in the
114 -- referenced file. For the standard entity form, the name between
115 -- the brackets is the normal name of the entity in lower case.
116 --
117 -- There may be zero or more ref entries on each line
118 --
119 -- file | line type col [...]
120 --
121 -- file is the dependency number of the file with the reference.
122 -- It and the following vertical bar are omitted if the file is
123 -- the same as the previous ref, and the refs for the current
124 -- file are first (and do not need a bar).
125 --
126 -- type is one of
127 -- r = reference
128 -- m = modification
129 -- b = body entity
130 -- c = completion of private or incomplete type
131 -- x = type extension
132 -- i = implicit reference
133 -- e = end of spec
134 -- t = end of body
135 --
136 -- b is used for spec entities that are repeated in a body,
137 -- including the unit (subprogram, package, task, protected
138 -- body, protected entry) name itself, and in the case of a
139 -- subprogram, the formals. This letter is also used for the
140 -- occurrence of entry names in accept statements. Such entities
141 -- are not considered to be definitions for cross-referencing
142 -- purposes, but rather are considered to be references to the
143 -- corresponding spec entities, marked with this special type.
144 --
145 -- c is similarly used to mark the completion of a private or
146 -- incomplete type. Again, the completion is not regarded as
147 -- a separate definition, but rather a reference to the initial
148 -- declaration, marked with this special type.
149 --
150 -- x is used to identify the reference as the entity from which
151 -- a tagged type is extended. This allows immediate access to
152 -- the parent of a tagged type.
153 --
154 -- i is used to identify a reference to the entity in a generic
155 -- actual or in a default in a call. The node that denotes the
156 -- entity does not come from source, but it has the Sloc of the
157 -- source node that generates the implicit reference, and it is
158 -- useful to record this one.
159 --
160 -- e is used to identify the end of a construct in the following
161 -- cases:
162 --
163 -- Block Statement end [block_IDENTIFIER];
164 -- Loop Statement end loop [loop_IDENTIFIER];
165 -- Package Specification end [[PARENT_UNIT_NAME .] IDENTIFIER];
166 -- Task Definition end [task_IDENTIFIER];
167 -- Protected Definition end [protected_IDENTIFIER];
168 -- Record Definition end record;
169 --
170 -- Note that 'e' entries are special in that you get they appear
171 -- even in referencing units (normally xref entries appear only
172 -- for references in the extended main source unit (see Lib) to
173 -- which the ali applies. But 'e' entries are really structural
174 -- and simply indicate where packages end. This information can
175 -- be used to reconstruct scope information for any entities
176 -- referenced from within the package.
177 --
178 -- t is similarly used to identify the end of a corresponding
179 -- body (such a reference always links up with a b reference)
180 --
181 -- Subprogram Body end [DESIGNATOR];
182 -- Package Body end [[PARENT_UNIT_NAME .] IDENTIFIER];
183 -- Task Body end [task_IDENTIFIER];
184 -- Entry Body end [entry_IDENTIFIER];
185 -- Protected Body end [protected_IDENTIFIER]
186 -- Accept Statement end [entry_IDENTIFIER]];
187 --
188 -- Note that in the case of accept statements, there can
189 -- be multiple b and T/t entries for the same entity.
190 --
191 -- [..] is used for generic instantiation references. These
192 -- references are present only if the entity in question is
193 -- a generic entity, and in that case the [..] contains the
194 -- reference for the instantiation. In the case of nested
195 -- instantiations, this can be nested [...[...[...]]] etc.
196 -- The reference is of the form [file|line] no column is
197 -- present since it is assumed that only one instantiation
198 -- appears on a single source line. Note that the appearence
199 -- of file numbers in such references follows the normal
200 -- rules (present only if needed, and resets the current
201 -- file for subsequent references).
202 --
203 -- Examples:
204 --
205 -- 44B5*Flag_Type{boolean} 5r23 6m45 3|9r35 11r56
206 --
207 -- This line gives references for the publicly visible Boolean
208 -- type Flag_Type declared on line 44, column 5. There are four
209 -- references
210 --
211 -- a reference on line 5, column 23 of the current file
212 --
213 -- a modification on line 6, column 45 of the current file
214 --
215 -- a reference on line 9, column 35 of unit number 3
216 --
217 -- a reference on line 11, column 56 of unit number 3
218 --
219 -- 2U13 p3=2:35 5b13 8r4 12r13 12t15
220 --
221 -- This line gives references for the non-publicly visible
222 -- procedure p3 declared on line 2, column 13. This procedure
223 -- renames the procedure whose identifier reference is at
224 -- line 2 column 35. There are four references:
225 --
226 -- the corresponding body entity at line 5, column 13,
227 -- of the current file.
228 --
229 -- a reference (e.g. a call) at line 8 column 4 of the
230 -- of the current file.
231 --
232 -- the END line of the body has an explict reference to
233 -- the name of the procedure at line 12, column 13.
234 --
235 -- the body ends at line 12, column 15, just past this label.
236 --
237 -- 16I9*My_Type<2|4I9> 18r8
238 --
239 -- This line gives references for the publicly visible Integer
240 -- derived type My_Type declared on line 16, column 9. It also
241 -- gives references to the parent type declared in the unit
242 -- number 2 on line 4, column 9. There is one reference:
243 --
244 -- a reference (e.g. a variable declaration) at line 18 column
245 -- 4 of the current file.
246 --
247 -- 10I3*Genv{integer} 3|4I10[6|12]
248 --
249 -- This line gives a reference for the entity Genv in a generic
250 -- package. The reference in file 3, line 4, col 10, refers to
251 -- an instance of the generic where the instantiation can be
252 -- found in file 6 at line 12.
253 --
254 -- Continuation lines are used if the reference list gets too long,
255 -- a continuation line starts with a period, and then has references
256 -- continuing from the previous line. The references are sorted first
257 -- by unit, then by position in the source.
259 -- Note on handling of generic entities. The cross-reference is oriented
260 -- towards source references, so the entities in a generic instantiation
261 -- are not considered distinct from the entities in the template. All
262 -- definitions and references from generic instantiations are suppressed,
263 -- since they will be generated from the template. Any references to
264 -- entities in a generic instantiation from outside the instantiation
265 -- are considered to be references to the original template entity.
267 ----------------------------------------
268 -- Cross-Reference Entity Identifiers --
269 ----------------------------------------
271 -- In the cross-reference section of the ali file, entity types are
272 -- identified by a single letter, indicating the entity type. The
273 -- following table indicates the letter. A space for an entry is
274 -- used for entities that do not appear in the cross-reference table.
276 -- For objects, the character * appears in this table. In the xref
277 -- listing, this character is replaced by the lower case letter that
278 -- corresponds to the type of the object. For example, if a variable
279 -- is of a Float type, then, since the type is represented by an
280 -- upper case F, the object would be represented by a lower case f.
282 -- A special exception is the case of booleans, whose entities are
283 -- normal E_Enumeration_Type or E_Enumeration_Subtype entities, but
284 -- which appear as B/b in the xref lines, rather than E/e.
286 -- For private types, the character + appears in the table. In this
287 -- case the kind of the underlying type is used, if available, to
288 -- determine the character to use in the xref listing. The listing
289 -- will still include a '+' for a generic private type, for example.
377 -- The following entities are not ones to which we gather
378 -- cross-references, since it does not make sense to do so
379 -- (e.g. references to a package are to the spec, not the body)
380 -- Indeed the occurrence of the body entity is considered to
381 -- be a reference to the spec entity.
389 -- The following table is for information purposes. It shows the
390 -- use of each character appearing as an entity type.
392 -- letter lower case usage UPPER CASE USAGE
394 -- a array object (except string) array type (except string)
395 -- b Boolean object Boolean type
396 -- c class-wide object class-wide type
397 -- d decimal fixed-point object decimal fixed-point type
398 -- e non-Boolean enumeration object non_Boolean enumeration type
399 -- f floating-point object floating-point type
400 -- g (unused) (unused)
401 -- h (unused) (unused)
402 -- i signed integer object signed integer type
403 -- j (unused) (unused)
404 -- k generic package package
405 -- l label on loop label on statement
406 -- m modular integer object modular integer type
407 -- n enumeration literal named number
408 -- o ordinary fixed-point object ordinary fixed-point type
409 -- p access object access type
410 -- q label on block (unused)
411 -- r record object record type
412 -- s string object string type
413 -- t task object task type
414 -- u generic procedure procedure
415 -- v generic function or operator function or operator
416 -- w protected object protected type
417 -- x (unused) exception
418 -- y (unused) entry or entry family
419 -- z (unused) (unused)
421 -----------------
422 -- Subprograms --
423 -----------------
426 -- Records the definition of an entity
429 -- Node N is an operator node, whose entity has been set. If this entity
430 -- is a user defined operator (i.e. an operator not defined in package
431 -- Standard), then a reference to the operator is recorded at node N.
433 procedure Generate_Reference
439 -- This procedure is called to record a reference. N is the location
440 -- of the reference and E is the referenced entity. Typ is one of:
441 --
442 -- 'b' body entity (see below)
443 -- 'c' completion of incomplete or private type (see below)
444 -- 'E' end of spec (label present)
445 -- 'e' end of spec (no label present)
446 -- 'i' implicit reference
447 -- 'm' modification
448 -- 'r' standard reference
449 -- 'T' end of body (label present)
450 -- 't' end of body (no label present)
451 -- 'x' type extension
452 -- ' ' dummy reference (see below)
453 --
454 -- Note: all references to incomplete or private types are to the
455 -- original (incomplete or private type) declaration. The full
456 -- declaration is treated as a reference with type 'c'.
457 --
458 -- Note: all references to packages or subprograms are to the entity
459 -- for the spec. The entity in the body is treated as a reference
460 -- with type 'b'. Similar handling for references to subprogram formals.
461 --
462 -- The call has no effect if N is not in the extended main source unit.
463 -- If N is in the extended main source unit, then the Is_Referenced
464 -- flag of E is set. In addition, if appropriate, a cross-reference
465 -- entry is made. The entry is made if:
466 --
467 -- cross-reference collection is enabled
468 -- both entity and reference come from source (or Force is True)
469 -- the entity is one for which xrefs are appropriate
470 -- the type letter is non-blank
471 -- the node N is an identifier, defining identifier, or expanded name
472 --
473 -- If all these conditions are met, then a cross-reference entry is
474 -- made for later output when Output_References is called.
475 --
476 -- Note: the dummy entry is for the convenience of some callers, who
477 -- find it easier to pass a space to suppress the entry than to do a
478 -- specific test. The call has no effect if the type is a space.
479 --
480 -- The parameter Set_Ref is normally True, and indicates that in
481 -- addition to generating a cross-reference, the Referenced flag
482 -- of the specified entity should be set. If this parameter is
483 -- False, then setting of the Referenced flag is inhibited.
484 --
485 -- The parameter Force is set to True to force a reference to be
486 -- generated even if Comes_From_Source is false. This is used for
487 -- certain implicit references, and also for end label references.
490 -- Output references to the current ali file