1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
9 -- Copyright (C) 1998-2002, Free Software Foundation, Inc. --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 2, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
22 -- GNAT was originally developed by the GNAT team at New York University. --
23 -- Extensive contributions were provided by Ada Core Technologies Inc. --
25 ------------------------------------------------------------------------------
27 -- This package contains for collecting and outputting cross-reference
30 with Einfo; use Einfo;
31 with Types; use Types;
35 -------------------------------------------------------
36 -- Format of Cross-Reference Information in ALI File --
37 -------------------------------------------------------
39 -- Cross-reference sections follow the dependency section (D lines) in
40 -- an ALI file, so that they need not be read by gnatbind, gnatmake etc.
42 -- A cross reference section has a header of the form
44 -- X dependency-number filename
46 -- This header precedes xref information (entities/references from
47 -- the unit, identified by dependency number and file name. The
48 -- dependency number is the index into the generated D lines and
49 -- is ones origin (i.e. 2 = reference to second generated D line).
51 -- Note that the filename here will reflect the original name if
52 -- a Source_Reference pragma was encountered (since all line number
53 -- references will be with respect to the original file).
55 -- The lines following the header look like
57 -- line type col level entity renameref typeref ref ref ref
59 -- line is the line number of the referenced entity. The name of
60 -- the entity starts in column col. Columns are numbered from one,
61 -- and if horizontal tab characters are present, the column number
62 -- is computed assuming standard 1,9,17,.. tab stops. For example,
63 -- if the entity is the first token on the line, and is preceded
64 -- by space-HT-space, then the column would be column 10.
66 -- type is a single letter identifying the type of the entity.
67 -- See next section (Cross-Reference Entity Identifiers) for a
68 -- full list of the characters used).
70 -- col is the column number of the referenced entity
72 -- level is a single character that separates the col and
73 -- entity fields. It is an asterisk for a top level library
74 -- entity that is publicly visible, and space otherwise.
76 -- entity is the name of the referenced entity, with casing in
77 -- the canical casing for the source file where it is defined.
79 -- renameref provides information on renaming. If the entity is
80 -- a package, object or overloadable entity which is declared by
81 -- a renaming declaration, and the renaming refers to an entity
82 -- with a simple identifier or expanded name, then renameref has
87 -- Here line:col give the reference to the identifier that
88 -- appears in the renaming declaration. Note that we never need
89 -- a file entry, since this identifier is always in the current
90 -- file in which the entity is declared. Currently, renameref
91 -- appears only for the simple renaming case. If the renaming
92 -- reference is a complex expressions, then renameref is omitted.
93 -- Here line/col give line/column as defined above.
95 -- typeref is the reference for a related type. This part is
96 -- optional. It is present for the following cases:
98 -- derived types (points to the parent type) LR=<>
99 -- access types (points to designated type) LR=()
100 -- subtypes (points to ancestor type) LR={}
101 -- functions (points to result type) LR={}
102 -- enumeration literals (points to enum type) LR={}
103 -- objects and components (points to type) LR={}
105 -- In the above list LR shows the brackets used in the output,
106 -- which has one of the two following forms:
108 -- L file | line type col R user entity
109 -- L name-in-lower-case R standard entity
111 -- For the form for a user entity, file is the dependency number
112 -- of the file containing the declaration of the related type.
113 -- This number and the following vertical bar are omitted if the
114 -- relevant type is defined in the same file as the current entity.
115 -- The line, type, col are defined as previously described, and
116 -- specify the location of the relevant type declaration in the
117 -- referenced file. For the standard entity form, the name between
118 -- the brackets is the normal name of the entity in lower case.
120 -- There may be zero or more ref entries on each line
122 -- file | line type col [...]
124 -- file is the dependency number of the file with the reference.
125 -- It and the following vertical bar are omitted if the file is
126 -- the same as the previous ref, and the refs for the current
127 -- file are first (and do not need a bar).
129 -- line is the line number of the reference
131 -- col is the column number of the reference, as defined above.
135 -- c = completion of private or incomplete type
137 -- i = implicit reference
138 -- l = label on end line
140 -- p = primitive operation
143 -- x = type extension
145 -- b is used for spec entities that are repeated in a body,
146 -- including the unit (subprogram, package, task, protected
147 -- body, protected entry) name itself, and in the case of a
148 -- subprogram, the formals. This letter is also used for the
149 -- occurrence of entry names in accept statements. Such entities
150 -- are not considered to be definitions for cross-referencing
151 -- purposes, but rather are considered to be references to the
152 -- corresponding spec entities, marked with this special type.
154 -- c is similar to b but is used to mark the completion of a
155 -- private or incomplete type. As with b, the completion is not
156 -- regarded as a separate definition, but rather a reference to
157 -- the initial declaration, marked with this special type.
159 -- e is used to identify the end of a construct in the following
162 -- Block Statement end [block_IDENTIFIER];
163 -- Loop Statement end loop [loop_IDENTIFIER];
164 -- Package Specification end [[PARENT_UNIT_NAME .] IDENTIFIER];
165 -- Task Definition end [task_IDENTIFIER];
166 -- Protected Definition end [protected_IDENTIFIER];
167 -- Record Definition end record;
168 -- Enumeration Definition );
170 -- Note that 'e' entries are special in that they appear even
171 -- 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. The line/column values
177 -- for these entries point to the semicolon ending the construct.
179 -- i is used to identify a reference to the entity in a generic
180 -- actual or in a default in a call. The node that denotes the
181 -- entity does not come from source, but it has the Sloc of the
182 -- source node that generates the implicit reference, and it is
183 -- useful to record this one.
185 -- l is used to identify the occurrence in the source of the
186 -- name on an end line. This is just a syntactic reference
187 -- which can be ignored for semantic purposes (such as call
188 -- graph construction). Again, in the case of an accept there
189 -- can be multiple l lines.
191 -- p is used to mark a primitive operation of the given entity.
192 -- For example, if we have a type Tx, and a primitive operation
193 -- Pq of this type, then an entry in the list of references to
194 -- Tx will point to the declaration of Pq. Note that this entry
195 -- type is unusual because it an implicit rather than explicit,
196 -- and the name of the refrerence does not match the name of the
197 -- entity for which a reference is generated. These entries are
198 -- generated only for entities declared in the extended main
199 -- source unit (main unit itself, its separate spec (if any).
200 -- and all subunits (considered recursively).
202 -- t is similar to e. It identifies the end of a corresponding
203 -- body (such a reference always links up with a b reference)
205 -- Subprogram Body end [DESIGNATOR];
206 -- Package Body end [[PARENT_UNIT_NAME .] IDENTIFIER];
207 -- Task Body end [task_IDENTIFIER];
208 -- Entry Body end [entry_IDENTIFIER];
209 -- Protected Body end [protected_IDENTIFIER]
210 -- Accept Statement end [entry_IDENTIFIER]];
212 -- Note that in the case of accept statements, there can
213 -- be multiple b and t entries for the same entity.
215 -- x is used to identify the reference as the entity from which
216 -- a tagged type is extended. This allows immediate access to
217 -- the parent of a tagged type.
219 -- [..] is used for generic instantiation references. These
220 -- references are present only if the entity in question is
221 -- a generic entity, and in that case the [..] contains the
222 -- reference for the instantiation. In the case of nested
223 -- instantiations, this can be nested [...[...[...]]] etc.
224 -- The reference is of the form [file|line] no column is
225 -- present since it is assumed that only one instantiation
226 -- appears on a single source line. Note that the appearence
227 -- of file numbers in such references follows the normal
228 -- rules (present only if needed, and resets the current
229 -- file for subsequent references).
233 -- 44B5*Flag_Type{boolean} 5r23 6m45 3|9r35 11r56
235 -- This line gives references for the publicly visible Boolean
236 -- type Flag_Type declared on line 44, column 5. There are four
239 -- a reference on line 5, column 23 of the current file
241 -- a modification on line 6, column 45 of the current file
243 -- a reference on line 9, column 35 of unit number 3
245 -- a reference on line 11, column 56 of unit number 3
247 -- 2U13 p3=2:35 5b13 8r4 12r13 12t15
249 -- This line gives references for the non-publicly visible
250 -- procedure p3 declared on line 2, column 13. This procedure
251 -- renames the procedure whose identifier reference is at
252 -- line 2 column 35. There are four references:
254 -- the corresponding body entity at line 5, column 13,
255 -- of the current file.
257 -- a reference (e.g. a call) at line 8 column 4 of the
258 -- of the current file.
260 -- the END line of the body has an explict reference to
261 -- the name of the procedure at line 12, column 13.
263 -- the body ends at line 12, column 15, just past this label.
265 -- 16I9*My_Type<2|4I9> 18r8
267 -- This line gives references for the publicly visible Integer
268 -- derived type My_Type declared on line 16, column 9. It also
269 -- gives references to the parent type declared in the unit
270 -- number 2 on line 4, column 9. There is one reference:
272 -- a reference (e.g. a variable declaration) at line 18 column
273 -- 4 of the current file.
275 -- 10I3*Genv{integer} 3|4I10[6|12]
277 -- This line gives a reference for the entity Genv in a generic
278 -- package. The reference in file 3, line 4, col 10, refers to
279 -- an instance of the generic where the instantiation can be
280 -- found in file 6 at line 12.
282 -- Continuation lines are used if the reference list gets too long,
283 -- a continuation line starts with a period, and then has references
284 -- continuing from the previous line. The references are sorted first
285 -- by unit, then by position in the source.
287 -- Note on handling of generic entities. The cross-reference is oriented
288 -- towards source references, so the entities in a generic instantiation
289 -- are not considered distinct from the entities in the template. All
290 -- definitions and references from generic instantiations are suppressed,
291 -- since they will be generated from the template. Any references to
292 -- entities in a generic instantiation from outside the instantiation
293 -- are considered to be references to the original template entity.
295 ----------------------------------------
296 -- Cross-Reference Entity Identifiers --
297 ----------------------------------------
299 -- In the cross-reference section of the ali file, entity types are
300 -- identified by a single letter, indicating the entity type. The
301 -- following table indicates the letter. A space for an entry is
302 -- used for entities that do not appear in the cross-reference table.
304 -- For objects, the character * appears in this table. In the xref
305 -- listing, this character is replaced by the lower case letter that
306 -- corresponds to the type of the object. For example, if a variable
307 -- is of a Float type, then, since the type is represented by an
308 -- upper case F, the object would be represented by a lower case f.
310 -- A special exception is the case of booleans, whose entities are
311 -- normal E_Enumeration_Type or E_Enumeration_Subtype entities, but
312 -- which appear as B/b in the xref lines, rather than E/e.
314 -- For private types, the character + appears in the table. In this
315 -- case the kind of the underlying type is used, if available, to
316 -- determine the character to use in the xref listing. The listing
317 -- will still include a '+' for a generic private type, for example.
319 Xref_Entity_Letters : array (Entity_Kind) of Character := (
324 E_Discriminant => '*',
326 E_Loop_Parameter => '*',
327 E_In_Parameter => '*',
328 E_Out_Parameter => '*',
329 E_In_Out_Parameter => '*',
330 E_Generic_In_Out_Parameter => '*',
332 E_Generic_In_Parameter => '*',
333 E_Named_Integer => 'N',
335 E_Enumeration_Type => 'E', -- B for boolean
336 E_Enumeration_Subtype => 'E', -- B for boolean
338 E_Signed_Integer_Type => 'I',
339 E_Signed_Integer_Subtype => 'I',
340 E_Modular_Integer_Type => 'M',
341 E_Modular_Integer_Subtype => 'M',
342 E_Ordinary_Fixed_Point_Type => 'O',
344 E_Ordinary_Fixed_Point_Subtype => 'O',
345 E_Decimal_Fixed_Point_Type => 'D',
346 E_Decimal_Fixed_Point_Subtype => 'D',
347 E_Floating_Point_Type => 'F',
348 E_Floating_Point_Subtype => 'F',
350 E_Access_Type => 'P',
351 E_Access_Subtype => 'P',
352 E_Access_Attribute_Type => 'P',
353 E_Allocator_Type => ' ',
354 E_General_Access_Type => 'P',
356 E_Access_Subprogram_Type => 'P',
357 E_Access_Protected_Subprogram_Type => 'P',
358 E_Anonymous_Access_Type => ' ',
360 E_Array_Subtype => 'A',
362 E_String_Type => 'S',
363 E_String_Subtype => 'S',
364 E_String_Literal_Subtype => ' ',
365 E_Class_Wide_Type => 'C',
367 E_Class_Wide_Subtype => 'C',
368 E_Record_Type => 'R',
369 E_Record_Subtype => 'R',
370 E_Record_Type_With_Private => 'R',
371 E_Record_Subtype_With_Private => 'R',
373 E_Private_Type => '+',
374 E_Private_Subtype => '+',
375 E_Limited_Private_Type => '+',
376 E_Limited_Private_Subtype => '+',
377 E_Incomplete_Type => '+',
380 E_Task_Subtype => 'T',
381 E_Protected_Type => 'W',
382 E_Protected_Subtype => 'W',
383 E_Exception_Type => ' ',
385 E_Subprogram_Type => ' ',
386 E_Enumeration_Literal => 'n',
392 E_Entry_Family => 'Y',
394 E_Entry_Index_Parameter => '*',
397 E_Generic_Function => 'v',
398 E_Generic_Package => 'k',
399 E_Generic_Procedure => 'u',
405 -- The following entities are not ones to which we gather
406 -- cross-references, since it does not make sense to do so
407 -- (e.g. references to a package are to the spec, not the body)
408 -- Indeed the occurrence of the body entity is considered to
409 -- be a reference to the spec entity.
411 E_Package_Body => ' ',
412 E_Protected_Object => ' ',
413 E_Protected_Body => ' ',
415 E_Subprogram_Body => ' ');
417 -- The following table is for information purposes. It shows the
418 -- use of each character appearing as an entity type.
420 -- letter lower case usage UPPER CASE USAGE
422 -- a array object (except string) array type (except string)
423 -- b Boolean object Boolean type
424 -- c class-wide object class-wide type
425 -- d decimal fixed-point object decimal fixed-point type
426 -- e non-Boolean enumeration object non_Boolean enumeration type
427 -- f floating-point object floating-point type
428 -- g (unused) (unused)
429 -- h (unused) (unused)
430 -- i signed integer object signed integer type
431 -- j (unused) (unused)
432 -- k generic package package
433 -- l label on loop label on statement
434 -- m modular integer object modular integer type
435 -- n enumeration literal named number
436 -- o ordinary fixed-point object ordinary fixed-point type
437 -- p access object access type
438 -- q label on block (unused)
439 -- r record object record type
440 -- s string object string type
441 -- t task object task type
442 -- u generic procedure procedure
443 -- v generic function or operator function or operator
444 -- w protected object protected type
445 -- x (unused) exception
446 -- y (unused) entry or entry family
447 -- z (unused) (unused)
453 procedure Generate_Definition (E : Entity_Id);
454 -- Records the definition of an entity
456 procedure Generate_Operator_Reference (N : Node_Id);
457 -- Node N is an operator node, whose entity has been set. If this entity
458 -- is a user defined operator (i.e. an operator not defined in package
459 -- Standard), then a reference to the operator is recorded at node N.
461 procedure Generate_Reference
464 Typ : Character := 'r';
465 Set_Ref : Boolean := True;
466 Force : Boolean := False);
467 -- This procedure is called to record a reference. N is the location
468 -- of the reference and E is the referenced entity. Typ is one of:
471 -- 'c' completion of incomplete or private type (see below)
472 -- 'e' end of construct
473 -- 'i' implicit reference
474 -- 'l' label on end line
476 -- 'p' primitive operation
477 -- 'r' standard reference
479 -- 'x' type extension
480 -- ' ' dummy reference (see below)
482 -- Note: all references to incomplete or private types are to the
483 -- original (incomplete or private type) declaration. The full
484 -- declaration is treated as a reference with type 'c'.
486 -- Note: all references to packages or subprograms are to the entity
487 -- for the spec. The entity in the body is treated as a reference
488 -- with type 'b'. Similar handling for references to subprogram formals.
490 -- The call has no effect if N is not in the extended main source unit
491 -- This check is omitted for type 'e' references (where it is useful to
492 -- have structural scoping information for other than the main source),
493 -- and for 'p' (since we want to pick up inherited primitive operations
494 -- that are defined in other packages).
496 -- The call also has no effect if any of the following conditions hold:
498 -- cross-reference collection is disabled
499 -- entity does not come from source (and Force is False)
500 -- reference does not come from source (and Force is False)
501 -- the entity is not one for which xrefs are appropriate
502 -- the type letter is blank
503 -- the node N is not an identifier, defining identifier, or expanded name
504 -- the type is 'p' and the entity is not in the extended main source
506 -- If all these conditions are met, then the Is_Referenced flag of E
507 -- is set (unless Set_Ref is False) and a cross-reference entry is
508 -- recorded for later output when Output_References is called.
510 -- Note: the dummy space entry is for the convenience of some callers,
511 -- who find it easier to pass a space to suppress the entry than to do
512 -- a specific test. The call has no effect if the type is a space.
514 -- The parameter Set_Ref is normally True, and indicates that in
515 -- addition to generating a cross-reference, the Referenced flag
516 -- of the specified entity should be set. If this parameter is
517 -- False, then setting of the Referenced flag is inhibited.
519 -- The parameter Force is set to True to force a reference to be
520 -- generated even if Comes_From_Source is false. This is used for
521 -- certain implicit references, and also for end label references.
523 procedure Output_References;
524 -- Output references to the current ali file
git://gcc.gnu.org / gcc.git / blob