projects / gcc.git / blob
? search:


1a0055e5c2b786c46864b01f861887f9b99cec6e
[gcc.git] / gcc / ada / lib-xref.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- L I B . X R E F --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1998-2005, Free Software Foundation, Inc. --
10 -- --
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. --
21 -- --
22 -- GNAT was originally developed by the GNAT team at New York University. --
23 -- Extensive contributions were provided by Ada Core Technologies Inc. --
24 -- --
25 ------------------------------------------------------------------------------
26
27 -- This package contains for collecting and outputting cross-reference
28 -- information.
29
30 with Einfo; use Einfo;
31 with Types; use Types;
32
33 package Lib.Xref is
34
35 -------------------------------------------------------
36 -- Format of Cross-Reference Information in ALI File --
37 -------------------------------------------------------
38
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.
41
42 -- A cross reference section has a header of the form
43
44 -- X dependency-number filename
45
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).
50
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).
54
55 -- The lines following the header look like
56
57 -- line type col level entity renameref instref typeref ref ref ref
58
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.
65
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).
69
70 -- col is the column number of the referenced entity
71
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, as well for an entity declared
75 -- in the visible part of a generic package, and space otherwise.
76
77 -- entity is the name of the referenced entity, with casing in
78 -- the canical casing for the source file where it is defined.
79
80 -- renameref provides information on renaming. If the entity is
81 -- a package, object or overloadable entity which is declared by
82 -- a renaming declaration, and the renaming refers to an entity
83 -- with a simple identifier or expanded name, then renameref has
84 -- the form:
85
86 -- =line:col
87
88 -- Here line:col give the reference to the identifier that
89 -- appears in the renaming declaration. Note that we never need
90 -- a file entry, since this identifier is always in the current
91 -- file in which the entity is declared. Currently, renameref
92 -- appears only for the simple renaming case. If the renaming
93 -- reference is a complex expressions, then renameref is omitted.
94 -- Here line/col give line/column as defined above.
95
96 -- instref is only present for package and subprogram instances.
97 -- The information in instref is the location of the point of
98 -- declaration of the generic parent unit. This part has the form:
99
100 -- [file|line]
101
102 -- without column information, on the reasonable assumption that
103 -- there is only one unit per line (the same assumption is made
104 -- in references to entities that are declared within instances,
105 -- see below).
106
107 -- typeref is the reference for a related type. This part is
108 -- optional. It is present for the following cases:
109
110 -- derived types (points to the parent type) LR=<>
111 -- access types (points to designated type) LR=()
112 -- array types (points to component type) LR=()
113 -- subtypes (points to ancestor type) LR={}
114 -- functions (points to result type) LR={}
115 -- enumeration literals (points to enum type) LR={}
116 -- objects and components (points to type) LR={}
117
118 -- In the above list LR shows the brackets used in the output,
119 -- which has one of the two following forms:
120
121 -- L file | line type col R user entity
122 -- L name-in-lower-case R standard entity
123
124 -- For the form for a user entity, file is the dependency number
125 -- of the file containing the declaration of the related type.
126 -- This number and the following vertical bar are omitted if the
127 -- relevant type is defined in the same file as the current entity.
128 -- The line, type, col are defined as previously described, and
129 -- specify the location of the relevant type declaration in the
130 -- referenced file. For the standard entity form, the name between
131 -- the brackets is the normal name of the entity in lower case.
132
133 -- There may be zero or more ref entries on each line
134
135 -- file | line type col [...]
136
137 -- file is the dependency number of the file with the reference.
138 -- It and the following vertical bar are omitted if the file is
139 -- the same as the previous ref, and the refs for the current
140 -- file are first (and do not need a bar).
141
142 -- line is the line number of the reference
143
144 -- col is the column number of the reference, as defined above
145
146 -- type is one of
147 -- b = body entity
148 -- c = completion of private or incomplete type
149 -- d = discriminant of type
150 -- e = end of spec
151 -- H = abstract type
152 -- i = implicit reference
153 -- k = implicit reference to parent unit in child unit
154 -- l = label on END line
155 -- m = modification
156 -- p = primitive operation
157 -- P = overriding primitive operation
158 -- r = reference
159 -- t = end of body
160 -- w = WITH line
161 -- x = type extension
162 -- z = generic formal parameter
163 -- > = subprogram IN parameter
164 -- = = subprogram IN OUT parameter
165 -- < = subprogram OUT parameter
166 -- > = subprogram ACCESS parameter
167
168 -- b is used for spec entities that are repeated in a body,
169 -- including the unit (subprogram, package, task, protected
170 -- body, protected entry) name itself, and in the case of a
171 -- subprogram, the formals. This letter is also used for the
172 -- occurrence of entry names in accept statements. Such entities
173 -- are not considered to be definitions for cross-referencing
174 -- purposes, but rather are considered to be references to the
175 -- corresponding spec entities, marked with this special type.
176
177 -- c is similar to b but is used to mark the completion of a
178 -- private or incomplete type. As with b, the completion is not
179 -- regarded as a separate definition, but rather a reference to
180 -- the initial declaration, marked with this special type.
181
182 -- d is used to identify a discriminant of a type. If this is
183 -- an incomplete or private type with discriminants, the entry
184 -- denotes the occurrence of the discriminant in the partial view
185 -- which is also the point of definition of the discriminant.
186 -- The occurrence of the same discriminant in the full view is
187 -- a regular reference to it.
188
189 -- e is used to identify the end of a construct in the following
190 -- cases:
191
192 -- Block Statement end [block_IDENTIFIER];
193 -- Loop Statement end loop [loop_IDENTIFIER];
194 -- Package Specification end [[PARENT_UNIT_NAME .] IDENTIFIER];
195 -- Task Definition end [task_IDENTIFIER];
196 -- Protected Definition end [protected_IDENTIFIER];
197 -- Record Definition end record;
198 -- Enumeration Definition );
199
200 -- Note that 'e' entries are special in that they appear even
201 -- in referencing units (normally xref entries appear only
202 -- for references in the extended main source unit (see Lib) to
203 -- which the ali applies. But 'e' entries are really structural
204 -- and simply indicate where packages end. This information can
205 -- be used to reconstruct scope information for any entities
206 -- referenced from within the package. The line/column values
207 -- for these entries point to the semicolon ending the construct.
208
209 -- i is used to identify a reference to the entity in a generic
210 -- actual or in a default in a call. The node that denotes the
211 -- entity does not come from source, but it has the Sloc of the
212 -- source node that generates the implicit reference, and it is
213 -- useful to record this one.
214
215 -- k is used to denote a reference to the parent unit, in the
216 -- cross-reference line for a child unit.
217
218 -- l is used to identify the occurrence in the source of the
219 -- name on an end line. This is just a syntactic reference
220 -- which can be ignored for semantic purposes (such as call
221 -- graph construction). Again, in the case of an accept there
222 -- can be multiple l lines.
223
224 -- p is used to mark a primitive operation of the given entity.
225 -- For example, if we have a type Tx, and a primitive operation
226 -- Pq of this type, then an entry in the list of references to
227 -- Tx will point to the declaration of Pq. Note that this entry
228 -- type is unusual because it an implicit rather than explicit,
229 -- and the name of the refrerence does not match the name of the
230 -- entity for which a reference is generated. These entries are
231 -- generated only for entities declared in the extended main
232 -- source unit (main unit itself, its separate spec (if any).
233 -- and all subunits (considered recursively).
234
235 -- If the primitive operation overrides an inherited primitive
236 -- operation of the parent type, the letter 'P' is used in the
237 -- corresponding entry.
238
239 -- t is similar to e. It identifies the end of a corresponding
240 -- body (such a reference always links up with a b reference)
241
242 -- Subprogram Body end [DESIGNATOR];
243 -- Package Body end [[PARENT_UNIT_NAME .] IDENTIFIER];
244 -- Task Body end [task_IDENTIFIER];
245 -- Entry Body end [entry_IDENTIFIER];
246 -- Protected Body end [protected_IDENTIFIER]
247 -- Accept Statement end [entry_IDENTIFIER]];
248
249 -- Note that in the case of accept statements, there can
250 -- be multiple b and t entries for the same entity.
251
252 -- x is used to identify the reference as the entity from which
253 -- a tagged type is extended. This allows immediate access to
254 -- the parent of a tagged type.
255
256 -- z is used on the cross-reference line for a generic unit, to
257 -- mark the definition of a generic formal of the unit.
258 -- This entry type is similar to 'k' and 'p' in that it is an
259 -- implicit reference for an entity with a different name.
260
261 -- The characters >, <. =, and ^ are used on the cross-reference
262 -- line for a subprogram, to denote formal parameters and their
263 -- modes. As with the 'z' and 'p' entries, each such entry is
264 -- an implicit reference to an entity with a different name.
265
266 -- [..] is used for generic instantiation references. These
267 -- references are present only if the entity in question is
268 -- a generic entity, and in that case the [..] contains the
269 -- reference for the instantiation. In the case of nested
270 -- instantiations, this can be nested [...[...[...]]] etc.
271 -- The reference is of the form [file|line] no column is
272 -- present since it is assumed that only one instantiation
273 -- appears on a single source line. Note that the appearence
274 -- of file numbers in such references follows the normal
275 -- rules (present only if needed, and resets the current
276 -- file for subsequent references).
277
278 -- Examples:
279
280 -- 44B5*Flag_Type{boolean} 5r23 6m45 3|9r35 11r56
281
282 -- This line gives references for the publicly visible Boolean
283 -- type Flag_Type declared on line 44, column 5. There are four
284 -- references
285
286 -- a reference on line 5, column 23 of the current file
287
288 -- a modification on line 6, column 45 of the current file
289
290 -- a reference on line 9, column 35 of unit number 3
291
292 -- a reference on line 11, column 56 of unit number 3
293
294 -- 2U13 p3=2:35 5b13 8r4 12r13 12t15
295
296 -- This line gives references for the non-publicly visible
297 -- procedure p3 declared on line 2, column 13. This procedure
298 -- renames the procedure whose identifier reference is at
299 -- line 2 column 35. There are four references:
300
301 -- the corresponding body entity at line 5, column 13,
302 -- of the current file.
303
304 -- a reference (e.g. a call) at line 8 column 4 of the
305 -- of the current file.
306
307 -- the END line of the body has an explict reference to
308 -- the name of the procedure at line 12, column 13.
309
310 -- the body ends at line 12, column 15, just past this label
311
312 -- 16I9*My_Type<2|4I9> 18r8
313
314 -- This line gives references for the publicly visible Integer
315 -- derived type My_Type declared on line 16, column 9. It also
316 -- gives references to the parent type declared in the unit
317 -- number 2 on line 4, column 9. There is one reference:
318
319 -- a reference (e.g. a variable declaration) at line 18 column
320 -- 4 of the current file.
321
322 -- 10I3*Genv{integer} 3|4I10[6|12]
323
324 -- This line gives a reference for the entity Genv in a generic
325 -- package. The reference in file 3, line 4, col 10, refers to
326 -- an instance of the generic where the instantiation can be
327 -- found in file 6 at line 12.
328
329 -- Continuation lines are used if the reference list gets too long,
330 -- a continuation line starts with a period, and then has references
331 -- continuing from the previous line. The references are sorted first
332 -- by unit, then by position in the source.
333
334 -- Note on handling of generic entities. The cross-reference is oriented
335 -- towards source references, so the entities in a generic instantiation
336 -- are not considered distinct from the entities in the template. All
337 -- definitions and references from generic instantiations are suppressed,
338 -- since they will be generated from the template. Any references to
339 -- entities in a generic instantiation from outside the instantiation
340 -- are considered to be references to the original template entity.
341
342 ----------------------------------------
343 -- Cross-Reference Entity Identifiers --
344 ----------------------------------------
345
346 -- In the cross-reference section of the ali file, entity types are
347 -- identified by a single letter, indicating the entity type. The
348 -- following table indicates the letter. A space for an entry is
349 -- used for entities that do not appear in the cross-reference table.
350
351 -- For objects, the character * appears in this table. In the xref
352 -- listing, this character is replaced by the lower case letter that
353 -- corresponds to the type of the object. For example, if a variable
354 -- is of a Float type, then, since the type is represented by an
355 -- upper case F, the object would be represented by a lower case f.
356
357 -- A special exception is the case of booleans, whose entities are
358 -- normal E_Enumeration_Type or E_Enumeration_Subtype entities, but
359 -- which appear as B/b in the xref lines, rather than E/e.
360
361 -- For private types, the character + appears in the table. In this
362 -- case the kind of the underlying type is used, if available, to
363 -- determine the character to use in the xref listing. The listing
364 -- will still include a '+' for a generic private type, for example,
365 -- but will retain the '*' for an object or formal parameter of such
366 -- a type.
367
368 -- For subprograms, the characters 'U' and 'V' appear in the table,
369 -- indicating procedures and functions. If the operation is abstract,
370 -- these letters are replaced in the xref by 'x' and 'y' respectively.
371
372 Xref_Entity_Letters : array (Entity_Kind) of Character := (
373 E_Void => ' ',
374 E_Variable => '*',
375 E_Component => '*',
376 E_Constant => '*',
377 E_Discriminant => '*',
378
379 E_Loop_Parameter => '*',
380 E_In_Parameter => '*',
381 E_Out_Parameter => '*',
382 E_In_Out_Parameter => '*',
383 E_Generic_In_Out_Parameter => '*',
384
385 E_Generic_In_Parameter => '*',
386 E_Named_Integer => 'N',
387 E_Named_Real => 'N',
388 E_Enumeration_Type => 'E', -- B for boolean
389 E_Enumeration_Subtype => 'E', -- B for boolean
390
391 E_Signed_Integer_Type => 'I',
392 E_Signed_Integer_Subtype => 'I',
393 E_Modular_Integer_Type => 'M',
394 E_Modular_Integer_Subtype => 'M',
395 E_Ordinary_Fixed_Point_Type => 'O',
396
397 E_Ordinary_Fixed_Point_Subtype => 'O',
398 E_Decimal_Fixed_Point_Type => 'D',
399 E_Decimal_Fixed_Point_Subtype => 'D',
400 E_Floating_Point_Type => 'F',
401 E_Floating_Point_Subtype => 'F',
402
403 E_Access_Type => 'P',
404 E_Access_Subtype => 'P',
405 E_Access_Attribute_Type => 'P',
406 E_Allocator_Type => ' ',
407 E_General_Access_Type => 'P',
408
409 E_Access_Subprogram_Type => 'P',
410 E_Access_Protected_Subprogram_Type => 'P',
411 E_Anonymous_Access_Subprogram_Type => ' ',
412 E_Anonymous_Access_Protected_Subprogram_Type => ' ',
413 E_Anonymous_Access_Type => ' ',
414 E_Array_Type => 'A',
415 E_Array_Subtype => 'A',
416
417 E_String_Type => 'S',
418 E_String_Subtype => 'S',
419 E_String_Literal_Subtype => ' ',
420 E_Class_Wide_Type => 'C',
421
422 E_Class_Wide_Subtype => 'C',
423 E_Record_Type => 'R',
424 E_Record_Subtype => 'R',
425 E_Record_Type_With_Private => 'R',
426 E_Record_Subtype_With_Private => 'R',
427
428 E_Private_Type => '+',
429 E_Private_Subtype => '+',
430 E_Limited_Private_Type => '+',
431 E_Limited_Private_Subtype => '+',
432 E_Incomplete_Type => '+',
433
434 E_Task_Type => 'T',
435 E_Task_Subtype => 'T',
436 E_Protected_Type => 'W',
437 E_Protected_Subtype => 'W',
438 E_Exception_Type => ' ',
439
440 E_Subprogram_Type => ' ',
441 E_Enumeration_Literal => 'n',
442 E_Function => 'V',
443 E_Operator => 'V',
444 E_Procedure => 'U',
445
446 E_Entry => 'Y',
447 E_Entry_Family => 'Y',
448 E_Block => 'q',
449 E_Entry_Index_Parameter => '*',
450 E_Exception => 'X',
451
452 E_Generic_Function => 'v',
453 E_Generic_Package => 'k',
454 E_Generic_Procedure => 'u',
455 E_Label => 'L',
456 E_Loop => 'l',
457
458 E_Package => 'K',
459
460 -- The following entities are not ones to which we gather
461 -- cross-references, since it does not make sense to do so
462 -- (e.g. references to a package are to the spec, not the body)
463 -- Indeed the occurrence of the body entity is considered to
464 -- be a reference to the spec entity.
465
466 E_Package_Body => ' ',
467 E_Protected_Object => ' ',
468 E_Protected_Body => ' ',
469 E_Task_Body => ' ',
470 E_Subprogram_Body => ' ');
471
472 -- The following table is for information purposes. It shows the
473 -- use of each character appearing as an entity type.
474
475 -- letter lower case usage UPPER CASE USAGE
476
477 -- a array object (except string) array type (except string)
478 -- b Boolean object Boolean type
479 -- c class-wide object class-wide type
480 -- d decimal fixed-point object decimal fixed-point type
481 -- e non-Boolean enumeration object non_Boolean enumeration type
482 -- f floating-point object floating-point type
483 -- g (unused) (unused)
484 -- h (unused) Abstract type
485 -- i signed integer object signed integer type
486 -- j (unused) (unused)
487 -- k generic package package
488 -- l label on loop label on statement
489 -- m modular integer object modular integer type
490 -- n enumeration literal named number
491 -- o ordinary fixed-point object ordinary fixed-point type
492 -- p access object access type
493 -- q label on block (unused)
494 -- r record object record type
495 -- s string object string type
496 -- t task object task type
497 -- u generic procedure procedure
498 -- v generic function or operator function or operator
499 -- w protected object protected type
500 -- x abstract procedure exception
501 -- y abstract function entry or entry family
502 -- z generic formal parameter (unused)
503
504 --------------------------------------
505 -- Handling of Imported Subprograms --
506 --------------------------------------
507
508 -- If a pragma Import or Interface applies to a subprogram, the
509 -- pragma is the completion of the subprogram. This is noted in
510 -- the ALI file by making the occurrence of the subprogram in the
511 -- pragma into a body reference ('b') and by including the external
512 -- name of the subprogram and its language, bracketed by '<' and '>'
513 -- in that reference. For example:
514 --
515 -- 3U13*elsewhere 4b<c,there>21
516 --
517 -- indicates that procedure elsewhere, declared at line 3, has a
518 -- pragma Import at line 4, that its body is in C, and that the link
519 -- name as given in the pragma is "there".
520
521 -----------------
522 -- Subprograms --
523 -----------------
524
525 procedure Generate_Definition (E : Entity_Id);
526 -- Records the definition of an entity
527
528 procedure Generate_Operator_Reference
529 (N : Node_Id;
530 T : Entity_Id);
531 -- Node N is an operator node, whose entity has been set. If this entity
532 -- is a user defined operator (i.e. an operator not defined in package
533 -- Standard), then a reference to the operator is recorded at node N.
534 -- T is the operand type of of the operator. A reference to the operator
535 -- is an implicit reference to the type, and that needs to be recorded
536 -- to avoid spurious warnings on unused entities, when the operator is
537 -- a renaming of a predefined operator.
538
539 procedure Generate_Reference
540 (E : Entity_Id;
541 N : Node_Id;
542 Typ : Character := 'r';
543 Set_Ref : Boolean := True;
544 Force : Boolean := False);
545 -- This procedure is called to record a reference. N is the location
546 -- of the reference and E is the referenced entity. Typ is one of:
547 --
548 -- 'b' body entity
549 -- 'c' completion of incomplete or private type (see below)
550 -- 'e' end of construct
551 -- 'i' implicit reference
552 -- 'l' label on end line
553 -- 'm' modification
554 -- 'p' primitive operation
555 -- 'r' standard reference
556 -- 't' end of body
557 -- 'x' type extension
558 -- ' ' dummy reference (see below)
559 --
560 -- Note: all references to incomplete or private types are to the
561 -- original (incomplete or private type) declaration. The full
562 -- declaration is treated as a reference with type 'c'.
563 --
564 -- Note: all references to packages or subprograms are to the entity
565 -- for the spec. The entity in the body is treated as a reference
566 -- with type 'b'. Similar handling for references to subprogram formals.
567 --
568 -- The call has no effect if N is not in the extended main source unit
569 -- This check is omitted for type 'e' references (where it is useful to
570 -- have structural scoping information for other than the main source),
571 -- and for 'p' (since we want to pick up inherited primitive operations
572 -- that are defined in other packages).
573 --
574 -- The call also has no effect if any of the following conditions hold:
575 --
576 -- cross-reference collection is disabled
577 -- entity does not come from source (and Force is False)
578 -- reference does not come from source (and Force is False)
579 -- the entity is not one for which xrefs are appropriate
580 -- the type letter is blank
581 -- the node N is not an identifier, defining identifier, or expanded name
582 -- the type is 'p' and the entity is not in the extended main source
583 --
584 -- If all these conditions are met, then the Is_Referenced flag of E
585 -- is set (unless Set_Ref is False) and a cross-reference entry is
586 -- recorded for later output when Output_References is called.
587 --
588 -- Note: the dummy space entry is for the convenience of some callers,
589 -- who find it easier to pass a space to suppress the entry than to do
590 -- a specific test. The call has no effect if the type is a space.
591 --
592 -- The parameter Set_Ref is normally True, and indicates that in
593 -- addition to generating a cross-reference, the Referenced flag
594 -- of the specified entity should be set. If this parameter is
595 -- False, then setting of the Referenced flag is inhibited.
596 --
597 -- The parameter Force is set to True to force a reference to be
598 -- generated even if Comes_From_Source is false. This is used for
599 -- certain implicit references, and also for end label references.
600
601 procedure Generate_Reference_To_Formals (E : Entity_Id);
602 -- Add a reference to the definition of each formal on the line for
603 -- a subprogram.
604
605 procedure Generate_Reference_To_Generic_Formals (E : Entity_Id);
606 -- Add a reference to the definition of each generic formal on the line
607 -- for a generic unit.
608
609 procedure Output_References;
610 -- Output references to the current ali file
611
612 procedure Initialize;
613 -- Initialize internal tables
614
615 end Lib.Xref;