1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
11 -- Copyright (C) 1998-2001, Free Software Foundation, Inc. --
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. --
24 -- GNAT was originally developed by the GNAT team at New York University. --
25 -- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). --
27 ------------------------------------------------------------------------------
29 -- This package contains for collecting and outputting cross-reference
32 with Einfo; use Einfo;
33 with Types; use Types;
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.
44 -- A cross reference section has a header of the form
46 -- X dependency-number filename
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).
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).
57 -- The lines following the header look like
59 -- line type col level entity ptype ref ref ref
61 -- line is the line number of the referenced entity. It starts
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, and space otherwise.
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 -- ptype is the parent's entity reference. This part is optional (it
78 -- is only set for derived types) and has the following format:
80 -- < file | line type col >
82 -- file is the dependency number of the file containing the
83 -- declaration of the parent type. This number and the following
84 -- vertical bar are omitted if the parent type is defined in the
85 -- same file as the derived type. The line, type, col are defined
86 -- as previously described, and give the location of the parent
87 -- type declaration in the referenced file.
89 -- There may be zero or more ref entries on each line
91 -- file | line type col
93 -- file is the dependency number of the file with the reference.
94 -- It and the following vertical bar are omitted if the file is
95 -- the same as the previous ref, and the refs for the current
96 -- file are first (and do not need a bar).
102 -- c = completion of private or incomplete type
103 -- x = type extension
104 -- i = implicit reference
108 -- b is used for spec entities that are repeated in a body,
109 -- including the unit (subprogram, package, task, protected
110 -- body, protected entry) name itself, and in the case of a
111 -- subprogram, the formals. This letter is also used for the
112 -- occurrence of entry names in accept statements. Such entities
113 -- are not considered to be definitions for cross-referencing
114 -- purposes, but rather are considered to be references to the
115 -- corresponding spec entities, marked with this special type.
117 -- c is similarly used to mark the completion of a private or
118 -- incomplete type. Again, the completion is not regarded as
119 -- a separate definition, but rather a reference to the initial
120 -- declaration, marked with this special type.
122 -- x is used to identify the reference as the entity from which
123 -- a tagged type is extended. This allows immediate access to
124 -- the parent of a tagged type.
126 -- i is used to identify a reference to the entity in a generic
127 -- actual or in a default in a call. The node that denotes the
128 -- entity does not come from source, but it has the Sloc of the
129 -- source node that generates the implicit reference, and it is
130 -- useful to record this one.
132 -- e is used to identify the end of a construct in the following
135 -- Block Statement end [block_IDENTIFIER];
136 -- Loop Statement end loop [loop_IDENTIFIER];
137 -- Package Specification end [[PARENT_UNIT_NAME .] IDENTIFIER];
138 -- Task Definition end [task_IDENTIFIER];
139 -- Protected Definition end [protected_IDENTIFIER];
140 -- Record Definition end record;
142 -- Note that 'e' entries are special in that you get they appear
143 -- even in referencing units (normally xref entries appear only
144 -- for references in the extended main source unit (see Lib) to
145 -- which the ali applies. But 'e' entries are really structural
146 -- and simply indicate where packages end. This information can
147 -- be used to reconstruct scope information for any entities
148 -- referenced from within the package.
150 -- t is similarly used to identify the end of a corresponding
151 -- body (such a reference always links up with a b reference)
153 -- Subprogram Body end [DESIGNATOR];
154 -- Package Body end [[PARENT_UNIT_NAME .] IDENTIFIER];
155 -- Task Body end [task_IDENTIFIER];
156 -- Entry Body end [entry_IDENTIFIER];
157 -- Protected Body end [protected_IDENTIFIER]
158 -- Accept Statement end [entry_IDENTIFIER]];
160 -- Note that in the case of accept statements, there can
161 -- be multiple b and T/t entries for the same entity.
165 -- 44B5*Flag_Type 5r23 6m45 3|9r35 11r56
167 -- This line gives references for the publicly visible Boolean
168 -- type Flag_Type declared on line 44, column 5. There are four
171 -- a reference on line 5, column 23 of the current file
173 -- a modification on line 6, column 45 of the current file
175 -- a reference on line 9, column 35 of unit number 3
177 -- a reference on line 11, column 56 of unit number 3
179 -- 2U13 p3 5b13 8r4 12r13 12t15
181 -- This line gives references for the non-publicly visible
182 -- procedure p3 declared on line 2, column 13. There are
185 -- the corresponding body entity at line 5, column 13,
186 -- of the current file.
188 -- a reference (e.g. a call) at line 8 column 4 of the
189 -- of the current file.
191 -- the END line of the body has an explict reference to
192 -- the name of the procedure at line 12, column 13.
194 -- the body ends at line 12, column 15, just past this label.
196 -- 16I9*My_Type<2|4I9> 18r8
198 -- This line gives references for the publicly visible Integer
199 -- derived type My_Type declared on line 16, column 9. It also
200 -- gives references to the parent type declared in the unit
201 -- number 2 on line 4, column 9. There is one reference:
203 -- a reference (e.g. a variable declaration) at line 18 column
204 -- 4 of the current file.
206 -- Continuation lines are used if the reference list gets too long,
207 -- a continuation line starts with a period, and then has references
208 -- continuing from the previous line. The references are sorted first
209 -- by unit, then by position in the source.
211 -- Note on handling of generic entities. The cross-reference is oriented
212 -- towards source references, so the entities in a generic instantiation
213 -- are not considered distinct from the entities in the template. All
214 -- definitions and references from generic instantiations are suppressed,
215 -- since they will be generated from the template. Any references to
216 -- entities in a generic instantiation from outside the instantiation
217 -- are considered to be references to the original template entity.
219 ----------------------------------------
220 -- Cross-Reference Entity Identifiers --
221 ----------------------------------------
223 -- In the cross-reference section of the ali file, entity types are
224 -- identified by a single letter, indicating the entity type. The
225 -- following table indicates the letter. A space for an entry is
226 -- used for entities that do not appear in the cross-reference table.
228 -- For objects, the character * appears in this table. In the xref
229 -- listing, this character is replaced by the lower case letter that
230 -- corresponds to the type of the object. For example, if a variable
231 -- is of a Float type, then, since the type is represented by an
232 -- upper case F, the object would be represented by a lower case f.
234 -- A special exception is the case of booleans, whose entities are
235 -- normal E_Enumeration_Type or E_Enumeration_Subtype entities, but
236 -- which appear as B/b in the xref lines, rather than E/e.
238 -- For private types, the character + appears in the table. In this
239 -- case the kind of the underlying type is used, if available, to
240 -- determine the character to use in the xref listing. The listing
241 -- will still include a '+' for a generic private type, for example.
243 Xref_Entity_Letters : array (Entity_Kind) of Character := (
248 E_Discriminant => '*',
250 E_Loop_Parameter => '*',
251 E_In_Parameter => '*',
252 E_Out_Parameter => '*',
253 E_In_Out_Parameter => '*',
254 E_Generic_In_Out_Parameter => '*',
256 E_Generic_In_Parameter => '*',
257 E_Named_Integer => 'N',
259 E_Enumeration_Type => 'E', -- B for boolean
260 E_Enumeration_Subtype => 'E', -- B for boolean
262 E_Signed_Integer_Type => 'I',
263 E_Signed_Integer_Subtype => 'I',
264 E_Modular_Integer_Type => 'M',
265 E_Modular_Integer_Subtype => 'M',
266 E_Ordinary_Fixed_Point_Type => 'O',
268 E_Ordinary_Fixed_Point_Subtype => 'O',
269 E_Decimal_Fixed_Point_Type => 'D',
270 E_Decimal_Fixed_Point_Subtype => 'D',
271 E_Floating_Point_Type => 'F',
272 E_Floating_Point_Subtype => 'F',
274 E_Access_Type => 'P',
275 E_Access_Subtype => 'P',
276 E_Access_Attribute_Type => 'P',
277 E_Allocator_Type => ' ',
278 E_General_Access_Type => 'P',
280 E_Access_Subprogram_Type => 'P',
281 E_Access_Protected_Subprogram_Type => 'P',
282 E_Anonymous_Access_Type => ' ',
284 E_Array_Subtype => 'A',
286 E_String_Type => 'S',
287 E_String_Subtype => 'S',
288 E_String_Literal_Subtype => ' ',
289 E_Class_Wide_Type => 'C',
291 E_Class_Wide_Subtype => 'C',
292 E_Record_Type => 'R',
293 E_Record_Subtype => 'R',
294 E_Record_Type_With_Private => 'R',
295 E_Record_Subtype_With_Private => 'R',
297 E_Private_Type => '+',
298 E_Private_Subtype => '+',
299 E_Limited_Private_Type => '+',
300 E_Limited_Private_Subtype => '+',
301 E_Incomplete_Type => '+',
304 E_Task_Subtype => 'T',
305 E_Protected_Type => 'W',
306 E_Protected_Subtype => 'W',
307 E_Exception_Type => ' ',
309 E_Subprogram_Type => ' ',
310 E_Enumeration_Literal => 'n',
316 E_Entry_Family => 'Y',
318 E_Entry_Index_Parameter => '*',
321 E_Generic_Function => 'v',
322 E_Generic_Package => 'k',
323 E_Generic_Procedure => 'u',
329 -- The following entities are not ones to which we gather
330 -- cross-references, since it does not make sense to do so
331 -- (e.g. references to a package are to the spec, not the body)
332 -- Indeed the occurrence of the body entity is considered to
333 -- be a reference to the spec entity.
335 E_Package_Body => ' ',
336 E_Protected_Object => ' ',
337 E_Protected_Body => ' ',
339 E_Subprogram_Body => ' ');
341 -- The following table is for information purposes. It shows the
342 -- use of each character appearing as an entity type.
344 -- letter lower case usage UPPER CASE USAGE
346 -- a array object (except string) array type (except string)
347 -- b Boolean object Boolean type
348 -- c class-wide object class-wide type
349 -- d decimal fixed-point object decimal fixed-point type
350 -- e non-Boolean enumeration object non_Boolean enumeration type
351 -- f floating-point object floating-point type
352 -- g (unused) (unused)
353 -- h (unused) (unused)
354 -- i signed integer object signed integer type
355 -- j (unused) (unused)
356 -- k generic package package
357 -- l label on loop label on statement
358 -- m modular integer object modular integer type
359 -- n enumeration literal named number
360 -- o ordinary fixed-point object ordinary fixed-point type
361 -- p access object access type
362 -- q label on block (unused)
363 -- r record object record type
364 -- s string object string type
365 -- t task object task type
366 -- u generic procedure procedure
367 -- v generic function or operator function or operator
368 -- w protected object protected type
369 -- x (unused) exception
370 -- y (unused) entry or entry family
371 -- z (unused) (unused)
377 procedure Generate_Definition (E : Entity_Id);
378 -- Records the definition of an entity
380 procedure Generate_Operator_Reference (N : Node_Id);
381 -- Node N is an operator node, whose entity has been set. If this entity
382 -- is a user defined operator (i.e. an operator not defined in package
383 -- Standard), then a reference to the operator is recorded at node N.
385 procedure Generate_Reference
388 Typ : Character := 'r';
389 Set_Ref : Boolean := True;
390 Force : Boolean := False);
391 -- This procedure is called to record a reference. N is the location
392 -- of the reference and E is the referenced entity. Typ is one of:
394 -- 'b' body entity (see below)
395 -- 'c' completion of incomplete or private type (see below)
396 -- 'E' end of spec (label present)
397 -- 'e' end of spec (no label present)
398 -- 'i' implicit reference
400 -- 'r' standard reference
401 -- 'T' end of body (label present)
402 -- 't' end of body (no label present)
403 -- 'x' type extension
404 -- ' ' dummy reference (see below)
406 -- Note: all references to incomplete or private types are to the
407 -- original (incomplete or private type) declaration. The full
408 -- declaration is treated as a reference with type 'c'.
410 -- Note: all references to packages or subprograms are to the entity
411 -- for the spec. The entity in the body is treated as a reference
412 -- with type 'b'. Similar handling for references to subprogram formals.
414 -- The call has no effect if N is not in the extended main source unit.
415 -- If N is in the extended main source unit, then the Is_Referenced
416 -- flag of E is set. In addition, if appropriate, a cross-reference
417 -- entry is made. The entry is made if:
419 -- cross-reference collection is enabled
420 -- both entity and reference come from source (or Force is True)
421 -- the entity is one for which xrefs are appropriate
422 -- the type letter is non-blank
423 -- the node N is an identifier, defining identifier, or expanded name
425 -- If all these conditions are met, then a cross-reference entry is
426 -- made for later output when Output_References is called.
428 -- Note: the dummy entry is for the convenience of some callers, who
429 -- find it easier to pass a space to suppress the entry than to do a
430 -- specific test. The call has no effect if the type is a space.
432 -- The parameter Set_Ref is normally True, and indicates that in
433 -- addition to generating a cross-reference, the Referenced flag
434 -- of the specified entity should be set. If this parameter is
435 -- False, then setting of the Referenced flag is inhibited.
437 -- The parameter Force is set to True to force a reference to be
438 -- generated even if Comes_From_Source is false. This is used for
439 -- certain implicit references, and also for end label references.
441 procedure Output_References;
442 -- Output references to the current ali file
projects / platform / upstream / gcc.git / blob