| blob | 0bb85492980862047dc7f980bc68a27ddec21c3a |
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-2007, 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 3, 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 COPYING3. If not, go to --
19 -- http://www.gnu.org/licenses for a complete copy of the license. --
20 -- --
21 -- GNAT was originally developed by the GNAT team at New York University. --
22 -- Extensive contributions were provided by Ada Core Technologies Inc. --
23 -- --
24 ------------------------------------------------------------------------------
26 -- This package contains for collecting and outputting cross-reference
27 -- information.
33 -------------------------------------------------------
34 -- Format of Cross-Reference Information in ALI File --
35 -------------------------------------------------------
37 -- Cross-reference sections follow the dependency section (D lines) in
38 -- an ALI file, so that they need not be read by gnatbind, gnatmake etc.
40 -- A cross reference section has a header of the form
42 -- X dependency-number filename
44 -- This header precedes xref information (entities/references from
45 -- the unit, identified by dependency number and file name. The
46 -- dependency number is the index into the generated D lines and
47 -- is ones origin (i.e. 2 = reference to second generated D line).
49 -- Note that the filename here will reflect the original name if
50 -- a Source_Reference pragma was encountered (since all line number
51 -- references will be with respect to the original file).
53 -- The lines following the header look like
55 -- line type col level entity renameref instref typeref overref ref ref
57 -- line is the line number of the referenced entity. The name of
58 -- the entity starts in column col. Columns are numbered from one,
59 -- and if horizontal tab characters are present, the column number
60 -- is computed assuming standard 1,9,17,.. tab stops. For example,
61 -- if the entity is the first token on the line, and is preceded
62 -- by space-HT-space, then the column would be column 10.
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).
68 -- col is the column number of the referenced entity
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, as well for an entity declared
73 -- in the visible part of a generic package, and space otherwise.
75 -- entity is the name of the referenced entity, with casing in
76 -- the canonical casing for the source file where it is defined.
78 -- renameref provides information on renaming. If the entity is
79 -- a package, object or overloadable entity which is declared by
80 -- a renaming declaration, and the renaming refers to an entity
81 -- with a simple identifier or expanded name, then renameref has
82 -- the form:
84 -- =line:col
86 -- Here line:col give the reference to the identifier that
87 -- appears in the renaming declaration. Note that we never need
88 -- a file entry, since this identifier is always in the current
89 -- file in which the entity is declared. Currently, renameref
90 -- appears only for the simple renaming case. If the renaming
91 -- reference is a complex expressions, then renameref is omitted.
92 -- Here line/col give line/column as defined above.
94 -- instref is only present for package and subprogram instances.
95 -- The information in instref is the location of the point of
96 -- declaration of the generic parent unit. This part has the form:
98 -- [file|line]
100 -- without column information, on the reasonable assumption that
101 -- there is only one unit per line (the same assumption is made
102 -- in references to entities that are declared within instances,
103 -- see below).
105 -- typeref is the reference for a related type. This part is
106 -- optional. It is present for the following cases:
108 -- derived types (points to the parent type) LR=<>
109 -- access types (points to designated type) LR=()
110 -- array types (points to component type) LR=()
111 -- subtypes (points to ancestor type) LR={}
112 -- functions (points to result type) LR={}
113 -- enumeration literals (points to enum type) LR={}
114 -- objects and components (points to type) LR={}
116 -- For a type that implements multiple interfaces, there is an
117 -- entry of the form LR=<> for each of the interfaces appearing
118 -- in the type declaration. In the data structures of ali.ads,
119 -- the type that the entity extends (or the first interface if
120 -- there is no such type) is stored in Xref_Entity_Record.Tref*,
121 -- additional interfaces are stored in the list of references
122 -- with a special type of Interface_Reference.
124 -- For an array type, there is an entry of the form LR=<> for
125 -- each of the index types appearing in the type declaration.
126 -- The index types follow the entry for the component type.
127 -- In the data structures of ali.ads, however, the list of index
128 -- types are output in the list of references with a special
129 -- Rtype set to Array_Index_Reference.
131 -- In the above list LR shows the brackets used in the output,
132 -- which has one of the two following forms:
134 -- L file | line type col R user entity
135 -- L name-in-lower-case R standard entity
137 -- For the form for a user entity, file is the dependency number
138 -- of the file containing the declaration of the related type.
139 -- This number and the following vertical bar are omitted if the
140 -- relevant type is defined in the same file as the current entity.
141 -- The line, type, col are defined as previously described, and
142 -- specify the location of the relevant type declaration in the
143 -- referenced file. For the standard entity form, the name between
144 -- the brackets is the normal name of the entity in lower case.
146 -- overref is present for overriding operations (procedures and
147 -- functions), and provides information on the operation that it
148 -- overrides. This information has the format:
150 -- '<' file | line 'o' col '>'
152 -- file is the dependency number of the file containing the
153 -- declaration of the overridden operation. It and the following
154 -- vertical bar are omitted if the file is the same as that of
155 -- the overriding operation.
157 -- There may be zero or more ref entries on each line
159 -- file | line type col [...]
161 -- file is the dependency number of the file with the reference.
162 -- It and the following vertical bar are omitted if the file is
163 -- the same as the previous ref, and the refs for the current
164 -- file are first (and do not need a bar).
166 -- line is the line number of the reference
168 -- col is the column number of the reference, as defined above
170 -- type is one of
171 -- b = body entity
172 -- c = completion of private or incomplete type
173 -- d = discriminant of type
174 -- e = end of spec
175 -- H = abstract type
176 -- i = implicit reference
177 -- k = implicit reference to parent unit in child unit
178 -- l = label on END line
179 -- m = modification
180 -- p = primitive operation
181 -- P = overriding primitive operation
182 -- r = reference
183 -- R = subprogram reference in dispatching call
184 -- t = end of body
185 -- w = WITH line
186 -- x = type extension
187 -- z = generic formal parameter
188 -- > = subprogram IN parameter
189 -- = = subprogram IN OUT parameter
190 -- < = subprogram OUT parameter
191 -- > = subprogram ACCESS parameter
193 -- b is used for spec entities that are repeated in a body,
194 -- including the unit (subprogram, package, task, protected
195 -- body, protected entry) name itself, and in the case of a
196 -- subprogram, the formals. This letter is also used for the
197 -- occurrence of entry names in accept statements. Such entities
198 -- are not considered to be definitions for cross-referencing
199 -- purposes, but rather are considered to be references to the
200 -- corresponding spec entities, marked with this special type.
202 -- c is similar to b but is used to mark the completion of a
203 -- private or incomplete type. As with b, the completion is not
204 -- regarded as a separate definition, but rather a reference to
205 -- the initial declaration, marked with this special type.
207 -- d is used to identify a discriminant of a type. If this is
208 -- an incomplete or private type with discriminants, the entry
209 -- denotes the occurrence of the discriminant in the partial view
210 -- which is also the point of definition of the discriminant.
211 -- The occurrence of the same discriminant in the full view is
212 -- a regular reference to it.
214 -- e is used to identify the end of a construct in the following
215 -- cases:
217 -- Block Statement end [block_IDENTIFIER];
218 -- Loop Statement end loop [loop_IDENTIFIER];
219 -- Package Specification end [[PARENT_UNIT_NAME .] IDENTIFIER];
220 -- Task Definition end [task_IDENTIFIER];
221 -- Protected Definition end [protected_IDENTIFIER];
222 -- Record Definition end record;
223 -- Enumeration Definition );
225 -- Note that 'e' entries are special in that they appear even
226 -- in referencing units (normally xref entries appear only
227 -- for references in the extended main source unit (see Lib) to
228 -- which the ali applies. But 'e' entries are really structural
229 -- and simply indicate where packages end. This information can
230 -- be used to reconstruct scope information for any entities
231 -- referenced from within the package. The line/column values
232 -- for these entries point to the semicolon ending the construct.
234 -- i is used to identify a reference to the entity in a generic
235 -- actual or in a default in a call. The node that denotes the
236 -- entity does not come from source, but it has the Sloc of the
237 -- source node that generates the implicit reference, and it is
238 -- useful to record this one.
240 -- k is another non-standard reference type, used to record a
241 -- reference from a child unit to its parent. For various cross-
242 -- referencing tools, we need a pointer from the xref entries for
243 -- the child to the parent. This is the opposite way round from
244 -- normal xref entries, since the reference is *from* the child
245 -- unit *to* the parent unit, yet appears in the xref entries for
246 -- the child. Consider this example:
247 --
248 -- package q is
249 -- end;
250 -- package q.r is
251 -- end q.r;
252 --
253 -- The ali file for q-r.ads has these entries
254 --
255 -- D q.ads
256 -- D q-r.ads
257 -- D system.ads
258 -- X 1 q.ads
259 -- 1K9*q 2e4 2|1r9 2r5
260 -- X 2 q-r.ads
261 -- 1K11*r 1|1k9 2|2l7 2e8
262 --
263 -- Here the 2|1r9 entry appearing in the section for the parent
264 -- is the normal reference from the child to the parent. The 1k9
265 -- entry in the section for the child duplicates this information
266 -- but appears in the child rather than the parent.
268 -- l is used to identify the occurrence in the source of the
269 -- name on an end line. This is just a syntactic reference
270 -- which can be ignored for semantic purposes (such as call
271 -- graph construction). Again, in the case of an accept there
272 -- can be multiple l lines.
274 -- p is used to mark a primitive operation of the given entity.
275 -- For example, if we have a type Tx, and a primitive operation
276 -- Pq of this type, then an entry in the list of references to
277 -- Tx will point to the declaration of Pq. Note that this entry
278 -- type is unusual because it an implicit rather than explicit,
279 -- and the name of the reference does not match the name of the
280 -- entity for which a reference is generated. These entries are
281 -- generated only for entities declared in the extended main
282 -- source unit (main unit itself, its separate spec (if any).
283 -- and all subunits (considered recursively).
285 -- If the primitive operation overrides an inherited primitive
286 -- operation of the parent type, the letter 'P' is used in the
287 -- corresponding entry.
289 -- R is used to mark a dispatching call. The reference is to
290 -- the specification of the primitive operation of the root
291 -- type when the call has a controlling argument in its class.
293 -- t is similar to e. It identifies the end of a corresponding
294 -- body (such a reference always links up with a b reference)
296 -- Subprogram Body end [DESIGNATOR];
297 -- Package Body end [[PARENT_UNIT_NAME .] IDENTIFIER];
298 -- Task Body end [task_IDENTIFIER];
299 -- Entry Body end [entry_IDENTIFIER];
300 -- Protected Body end [protected_IDENTIFIER]
301 -- Accept Statement end [entry_IDENTIFIER]];
303 -- Note that in the case of accept statements, there can
304 -- be multiple b and t entries for the same entity.
306 -- x is used to identify the reference as the entity from which
307 -- a tagged type is extended. This allows immediate access to
308 -- the parent of a tagged type.
310 -- z is used on the cross-reference line for a generic unit, to
311 -- mark the definition of a generic formal of the unit.
312 -- This entry type is similar to 'k' and 'p' in that it is an
313 -- implicit reference for an entity with a different name.
315 -- The characters >, <. =, and ^ are used on the cross-reference
316 -- line for a subprogram, to denote formal parameters and their
317 -- modes. As with the 'z' and 'p' entries, each such entry is
318 -- an implicit reference to an entity with a different name.
320 -- [..] is used for generic instantiation references. These
321 -- references are present only if the entity in question is
322 -- a generic entity, and in that case the [..] contains the
323 -- reference for the instantiation. In the case of nested
324 -- instantiations, this can be nested [...[...[...]]] etc.
325 -- The reference is of the form [file|line] no column is
326 -- present since it is assumed that only one instantiation
327 -- appears on a single source line. Note that the appearance
328 -- of file numbers in such references follows the normal
329 -- rules (present only if needed, and resets the current
330 -- file for subsequent references).
332 -- Examples:
334 -- 44B5*Flag_Type{boolean} 5r23 6m45 3|9r35 11r56
336 -- This line gives references for the publicly visible Boolean
337 -- type Flag_Type declared on line 44, column 5. There are four
338 -- references
340 -- a reference on line 5, column 23 of the current file
342 -- a modification on line 6, column 45 of the current file
344 -- a reference on line 9, column 35 of unit number 3
346 -- a reference on line 11, column 56 of unit number 3
348 -- 2U13 p3=2:35 5b13 8r4 12r13 12t15
350 -- This line gives references for the non-publicly visible
351 -- procedure p3 declared on line 2, column 13. This procedure
352 -- renames the procedure whose identifier reference is at
353 -- line 2 column 35. There are four references:
355 -- the corresponding body entity at line 5, column 13,
356 -- of the current file.
358 -- a reference (e.g. a call) at line 8 column 4 of the
359 -- of the current file.
361 -- the END line of the body has an explicit reference to
362 -- the name of the procedure at line 12, column 13.
364 -- the body ends at line 12, column 15, just past this label
366 -- 16I9*My_Type<2|4I9> 18r8
368 -- This line gives references for the publicly visible Integer
369 -- derived type My_Type declared on line 16, column 9. It also
370 -- gives references to the parent type declared in the unit
371 -- number 2 on line 4, column 9. There is one reference:
373 -- a reference (e.g. a variable declaration) at line 18 column
374 -- 4 of the current file.
376 -- 10I3*Genv{integer} 3|4I10[6|12]
378 -- This line gives a reference for the entity Genv in a generic
379 -- package. The reference in file 3, line 4, col 10, refers to
380 -- an instance of the generic where the instantiation can be
381 -- found in file 6 at line 12.
383 -- Continuation lines are used if the reference list gets too long,
384 -- a continuation line starts with a period, and then has references
385 -- continuing from the previous line. The references are sorted first
386 -- by unit, then by position in the source.
388 -- Note on handling of generic entities. The cross-reference is oriented
389 -- towards source references, so the entities in a generic instantiation
390 -- are not considered distinct from the entities in the template. All
391 -- definitions and references from generic instantiations are suppressed,
392 -- since they will be generated from the template. Any references to
393 -- entities in a generic instantiation from outside the instantiation
394 -- are considered to be references to the original template entity.
396 ----------------------------------------
397 -- Cross-Reference Entity Identifiers --
398 ----------------------------------------
400 -- In the cross-reference section of the ali file, entity types are
401 -- identified by a single letter, indicating the entity type. The
402 -- following table indicates the letter. A space for an entry is
403 -- used for entities that do not appear in the cross-reference table.
405 -- For objects, the character * appears in this table. In the xref
406 -- listing, this character is replaced by the lower case letter that
407 -- corresponds to the type of the object. For example, if a variable
408 -- is of a Float type, then, since the type is represented by an
409 -- upper case F, the object would be represented by a lower case f.
411 -- A special exception is the case of booleans, whose entities are
412 -- normal E_Enumeration_Type or E_Enumeration_Subtype entities, but
413 -- which appear as B/b in the xref lines, rather than E/e.
415 -- For private types, the character + appears in the table. In this
416 -- case the kind of the underlying type is used, if available, to
417 -- determine the character to use in the xref listing. The listing
418 -- will still include a '+' for a generic private type, for example,
419 -- but will retain the '*' for an object or formal parameter of such
420 -- a type.
422 -- For subprograms, the characters 'U' and 'V' appear in the table,
423 -- indicating procedures and functions. If the operation is abstract,
424 -- these letters are replaced in the xref by 'x' and 'y' respectively.
516 -- The following entities are not ones to which we gather
517 -- cross-references, since it does not make sense to do so
518 -- (e.g. references to a package are to the spec, not the body)
519 -- Indeed the occurrence of the body entity is considered to
520 -- be a reference to the spec entity.
528 -- The following table is for information purposes. It shows the
529 -- use of each character appearing as an entity type.
531 -- letter lower case usage UPPER CASE USAGE
533 -- a array object (except string) array type (except string)
534 -- b Boolean object Boolean type
535 -- c class-wide object class-wide type
536 -- d decimal fixed-point object decimal fixed-point type
537 -- e non-Boolean enumeration object non_Boolean enumeration type
538 -- f floating-point object floating-point type
539 -- g (unused) (unused)
540 -- h Interface (Ada 2005) Abstract type
541 -- i signed integer object signed integer type
542 -- j (unused) (unused)
543 -- k generic package package
544 -- l label on loop label on statement
545 -- m modular integer object modular integer type
546 -- n enumeration literal named number
547 -- o ordinary fixed-point object ordinary fixed-point type
548 -- p access object access type
549 -- q label on block (unused)
550 -- r record object record type
551 -- s string object string type
552 -- t task object task type
553 -- u generic procedure procedure
554 -- v generic function or operator function or operator
555 -- w protected object protected type
556 -- x abstract procedure exception
557 -- y abstract function entry or entry family
558 -- z generic formal parameter (unused)
560 --------------------------------------
561 -- Handling of Imported Subprograms --
562 --------------------------------------
564 -- If a pragma Import or Interface applies to a subprogram, the
565 -- pragma is the completion of the subprogram. This is noted in
566 -- the ALI file by making the occurrence of the subprogram in the
567 -- pragma into a body reference ('b') and by including the external
568 -- name of the subprogram and its language, bracketed by '<' and '>'
569 -- in that reference. For example:
570 --
571 -- 3U13*elsewhere 4b<c,there>21
572 --
573 -- indicates that procedure elsewhere, declared at line 3, has a
574 -- pragma Import at line 4, that its body is in C, and that the link
575 -- name as given in the pragma is "there".
577 -----------------
578 -- Subprograms --
579 -----------------
582 -- Records the definition of an entity
584 procedure Generate_Operator_Reference
587 -- Node N is an operator node, whose entity has been set. If this entity
588 -- is a user defined operator (i.e. an operator not defined in package
589 -- Standard), then a reference to the operator is recorded at node N.
590 -- T is the operand type of of the operator. A reference to the operator
591 -- is an implicit reference to the type, and that needs to be recorded
592 -- to avoid spurious warnings on unused entities, when the operator is
593 -- a renaming of a predefined operator.
595 procedure Generate_Reference
601 -- This procedure is called to record a reference. N is the location
602 -- of the reference and E is the referenced entity. Typ is one of:
603 --
604 -- 'b' body entity
605 -- 'c' completion of incomplete or private type (see below)
606 -- 'e' end of construct
607 -- 'i' implicit reference
608 -- 'l' label on end line
609 -- 'm' modification
610 -- 'p' primitive operation
611 -- 'r' standard reference
612 -- 't' end of body
613 -- 'x' type extension
614 -- ' ' dummy reference (see below)
615 --
616 -- Note: all references to incomplete or private types are to the
617 -- original (incomplete or private type) declaration. The full
618 -- declaration is treated as a reference with type 'c'.
619 --
620 -- Note: all references to packages or subprograms are to the entity
621 -- for the spec. The entity in the body is treated as a reference
622 -- with type 'b'. Similar handling for references to subprogram formals.
623 --
624 -- The call has no effect if N is not in the extended main source unit
625 -- This check is omitted for type 'e' references (where it is useful to
626 -- have structural scoping information for other than the main source),
627 -- and for 'p' (since we want to pick up inherited primitive operations
628 -- that are defined in other packages).
629 --
630 -- The call also has no effect if any of the following conditions hold:
631 --
632 -- cross-reference collection is disabled
633 -- entity does not come from source (and Force is False)
634 -- reference does not come from source (and Force is False)
635 -- the entity is not one for which xrefs are appropriate
636 -- the type letter is blank
637 -- the node N is not an identifier, defining identifier, or expanded name
638 -- the type is 'p' and the entity is not in the extended main source
639 --
640 -- If all these conditions are met, then the Is_Referenced flag of E is set
641 -- (unless Set_Ref is False) and a cross-reference entry is recorded for
642 -- later output when Output_References is called.
643 --
644 -- Note: the dummy space entry is for the convenience of some callers,
645 -- who find it easier to pass a space to suppress the entry than to do
646 -- a specific test. The call has no effect if the type is a space.
647 --
648 -- The parameter Set_Ref is normally True, and indicates that in addition
649 -- to generating a cross-reference, the Referenced flag of the specified
650 -- entity should be set. If this parameter is False, then setting of the
651 -- Referenced flag is inhibited.
652 --
653 -- The parameter Force is set to True to force a reference to be generated
654 -- even if Comes_From_Source is false. This is used for certain implicit
655 -- references, and also for end label references.
658 -- Add a reference to the definition of each formal on the line for
659 -- a subprogram.
662 -- Add a reference to the definition of each generic formal on the line
663 -- for a generic unit.
666 -- Output references to the current ali file
669 -- Initialize internal tables