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-2018, 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------------------------------------------------------------------------------
25
26--  This package contains for collecting and outputting cross-reference
27--  information.
28
29with Einfo;       use Einfo;
30with SPARK_Xrefs;
31
32package Lib.Xref is
33
34   -------------------------------------------------------
35   -- Format of Cross-Reference Information in ALI File --
36   -------------------------------------------------------
37
38   --  Cross-reference sections follow the dependency section (D lines) in
39   --  an ALI file, so that they need not be read by gnatbind, gnatmake etc.
40
41   --  A cross reference section has a header of the form
42
43   --     X  dependency-number  filename
44
45   --        This header precedes xref information (entities/references from
46   --        the unit), identified by dependency number and file name. The
47   --        dependency number is the index into the generated D lines and
48   --        is ones origin (e.g. 2 = reference to second generated D line).
49
50   --        Note that the filename here will reflect the original name if
51   --        a Source_Reference pragma was encountered (since all line number
52   --        references will be with respect to the original file).
53
54   --  The lines following the header look like
55
56   --  line type col level entity renameref instref typeref overref ref ref
57
58   --        line is the line number of the referenced entity. The name of
59   --        the entity starts in column col. Columns are numbered from one,
60   --        and if horizontal tab characters are present, the column number
61   --        is computed assuming standard 1,9,17,.. tab stops. For example,
62   --        if the entity is the first token on the line, and is preceded
63   --        by space-HT-space, then the column would be column 10.
64
65   --        type is a single letter identifying the type of the entity. See
66   --        next section (Cross-Reference Entity Identifiers) for a full list
67   --        of the characters used).
68
69   --        col is the column number of the referenced entity
70
71   --        level is a single character that separates the col and entity
72   --        fields. It is an asterisk (*) for a top level library entity that
73   --        is publicly visible, as well for an entity declared in the visible
74   --        part of a generic package, the plus sign (+) for a C/C++ static
75   --        entity, and space otherwise.
76
77   --        entity is the name of the referenced entity, with casing in
78   --        the canonical 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 appears
89   --        in the renaming declaration. Note that we never need a file entry,
90   --        since this identifier is always in the current file in which the
91   --        entity is declared. Currently, renameref appears only for the
92   --        simple renaming case. If the renaming reference is a complex
93   --        expressions, then renameref is omitted. Here line/col give
94   --        line/column as defined above.
95
96   --        instref is only present for package and subprogram instances. The
97   --        information in instref is the location of the point of declaration
98   --        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 in
104   --        references to entities declared within instances, see below).
105
106   --        typeref is the reference for a related type. This part is
107   --        optional. It is present for the following cases:
108
109   --          derived types (points to the parent type)   LR=<>
110   --          access types (points to designated type)    LR=()
111   --          array types (points to component type)      LR=()
112   --          subtypes (points to ancestor type)          LR={}
113   --          functions (points to result type)           LR={}
114   --          enumeration literals (points to enum type)  LR={}
115   --          objects and components (points to type)     LR={}
116
117   --          For a type that implements multiple interfaces, there is an
118   --          entry of the form  LR=<> for each of the interfaces appearing
119   --          in the type declaration. In the data structures of ali.ads,
120   --          the type that the entity extends (or the first interface if
121   --          there is no such type) is stored in Xref_Entity_Record.Tref*,
122   --          additional interfaces are stored in the list of references
123   --          with a special type of Interface_Reference.
124
125   --          For an array type, there is an entry of the form LR=<> for each
126   --          of the index types appearing in the type declaration. The index
127   --          types follow the entry for the component type. In the data
128   --          structures of ali.ads, however, the list of index types are
129   --          output in the list of references with a special Rtype set to
130   --          Array_Index_Reference.
131
132   --          In the above list LR shows the brackets used in the output which
133   --          has one of the two following forms:
134
135   --            L file | line type col R      user entity
136   --            L name-in-lower-case R        standard entity
137
138   --          For the form for a user entity, file is the dependency number
139   --          of the file containing the declaration of the related type.
140   --          This number and the following vertical bar are omitted if the
141   --          relevant type is defined in the same file as the current entity.
142   --          The line, type, col are defined as previously described, and
143   --          specify the location of the relevant type declaration in the
144   --          referenced file. For the standard entity form, the name between
145   --          the brackets is the normal name of the entity in lower case.
146
147   --        overref is present for overriding operations (procedures and
148   --        functions), and provides information on the operation that it
149   --        overrides. This information has the format:
150
151   --        '<' file | line 'o' col '>'
152
153   --           file is the dependency number of the file containing the
154   --           declaration of the overridden operation. It and the following
155   --           vertical bar are omitted if the file is the same as that of
156   --           the overriding operation.
157
158   --     There may be zero or more ref entries on each line
159
160   --        file | line type col [...]
161
162   --           file is the dependency number of the file with the reference.
163   --           It and the following vertical bar are omitted if the file is
164   --           the same as the previous ref, and the refs for the current
165   --           file are first (and do not need a bar).
166
167   --           line is the line number of the reference
168
169   --           col is the column number of the reference, as defined above
170
171   --           type is one of
172   --              b = body entity
173   --              c = completion of private or incomplete type
174   --              d = discriminant of type
175   --              D = object definition
176   --              e = end of spec
177   --              E = first private entity
178   --              H = abstract type
179   --              i = implicit reference
180   --              k = implicit reference to parent unit in child unit
181   --              l = label on END line
182   --              m = modification
183   --              o = own variable reference (SPARK only)
184   --              p = primitive operation
185   --              P = overriding primitive operation
186   --              r = reference
187   --              R = subprogram reference in dispatching call
188   --              s = subprogram reference in a static call
189   --              t = end of body
190   --              w = WITH line
191   --              x = type extension
192   --              z = generic formal parameter
193   --              > = subprogram IN parameter
194   --              = = subprogram IN OUT parameter
195   --              < = subprogram OUT parameter
196   --              ^ = subprogram ACCESS parameter
197
198   --           b is used for spec entities that are repeated in a body,
199   --           including the unit (subprogram, package, task, protected body,
200   --           protected entry) name itself, and in the case of a subprogram,
201   --           the formals. This letter is also used for the occurrence of
202   --           entry names in accept statements. Such entities are not
203   --           considered to be definitions for cross-referencing purposes,
204   --           but rather are considered to be references to the corresponding
205   --           spec entities, marked with this special type.
206
207   --           c is similar to b but is used to mark the completion of a
208   --           private or incomplete type. As with b, the completion is not
209   --           regarded as a separate definition, but rather a reference to
210   --           the initial declaration, marked with this special type.
211
212   --           d is used to identify a discriminant of a type. If this is
213   --           an incomplete or private type with discriminants, the entry
214   --           denotes the occurrence of the discriminant in the partial view
215   --           which is also the point of definition of the discriminant. The
216   --           occurrence of the same discriminant in the full view is a
217   --           regular reference to it.
218
219   --           e is used to identify the end of a construct in the following
220   --           cases:
221
222   --             Block Statement        end [block_IDENTIFIER];
223   --             Loop Statement         end loop [loop_IDENTIFIER];
224   --             Package Specification  end [[PARENT_UNIT_NAME .] IDENTIFIER];
225   --             Task Definition        end [task_IDENTIFIER];
226   --             Protected Definition   end [protected_IDENTIFIER];
227   --             Record Definition      end record;
228   --             Enumeration Definition );
229
230   --           Note that 'e' entries are special in that they appear even
231   --           in referencing units (normally xref entries appear only for
232   --           references in the extended main source unit (see Lib) to which
233   --           the ali applies. But 'e' entries are really structural and
234   --           simply indicate where packages end. This information can be
235   --           used to reconstruct scope information for any entities
236   --           referenced from within the package. The line/column values
237   --           for these entries point to the semicolon ending the construct.
238
239   --           i is used to identify a reference to the entity in a generic
240   --           actual or in a default in a call. The node that denotes the
241   --           entity does not come from source, but it has the Sloc of the
242   --           source node that generates the implicit reference, and it is
243   --           useful to record this one.
244
245   --           k is another non-standard reference type, used to record a
246   --           reference from a child unit to its parent. For various cross-
247   --           referencing tools, we need a pointer from the xref entries for
248   --           the child to the parent. This is the opposite way round from
249   --           normal xref entries, since the reference is *from* the child
250   --           unit *to* the parent unit, yet appears in the xref entries for
251   --           the child. Consider this example:
252   --
253   --             package q is
254   --             end;
255   --             package q.r is
256   --             end q.r;
257   --
258   --           The ali file for q-r.ads has these entries
259   --
260   --             D q.ads
261   --             D q-r.ads
262   --             D system.ads
263   --             X 1 q.ads
264   --             1K9*q 2e4 2|1r9 2r5
265   --             X 2 q-r.ads
266   --             1K11*r 1|1k9 2|2l7 2e8
267   --
268   --           Here the 2|1r9 entry appearing in the section for the parent
269   --           is the normal reference from the child to the parent. The 1k9
270   --           entry in the section for the child duplicates this information
271   --           but appears in the child rather than the parent.
272
273   --           l is used to identify the occurrence in the source of the name
274   --           on an end line. This is just a syntactic reference which can be
275   --           ignored for semantic purposes (e.g. a call graph construction).
276   --           Again, in the case of an accept there can be multiple l lines.
277
278   --           o is used for variables referenced from a SPARK 'own'
279   --           definition. In the SPARK language, it is allowed to use a
280   --           variable before its actual declaration.
281
282   --           p is used to mark a primitive operation of the given entity.
283   --           For example, if we have a type Tx, and a primitive operation
284   --           Pq of this type, then an entry in the list of references to
285   --           Tx will point to the declaration of Pq. Note that this entry
286   --           type is unusual because it an implicit rather than explicit,
287   --           and the name of the reference does not match the name of the
288   --           entity for which a reference is generated. These entries are
289   --           generated only for entities declared in the extended main
290   --           source unit (main unit itself, its separate spec (if any).
291   --           and all subunits (considered recursively).
292
293   --           If the primitive operation overrides an inherited primitive
294   --           operation of the parent type, the letter 'P' is used in the
295   --           corresponding entry.
296
297   --           R is used to mark a dispatching call. The reference is to
298   --           the specification of the primitive operation of the root
299   --           type when the call has a controlling argument in its class.
300
301   --           s is used to mark a static subprogram call. The reference is
302   --           to the specification of the subprogram being called.
303
304   --           t is similar to e. It identifies the end of a corresponding
305   --           body (such a reference always links up with a b reference)
306
307   --             Subprogram Body        end [DESIGNATOR];
308   --             Package Body           end [[PARENT_UNIT_NAME .] IDENTIFIER];
309   --             Task Body              end [task_IDENTIFIER];
310   --             Entry Body             end [entry_IDENTIFIER];
311   --             Protected Body         end [protected_IDENTIFIER]
312   --             Accept Statement       end [entry_IDENTIFIER]];
313
314   --           Note that in the case of accept statements, there can
315   --           be multiple b and t entries for the same entity.
316
317   --           x is used to identify the reference as the entity from which a
318   --           tagged type is extended. This allows immediate access to the
319   --           parent of a tagged type.
320
321   --           z is used on the cross-reference line for a generic unit,
322   --           to mark the definition of a generic formal of the unit. This
323   --           entry type is similar to 'k' and 'p' in that it is an implicit
324   --           reference for an entity with a different name.
325
326   --           The characters >, <. =, and ^ are used on the cross-reference
327   --           line for a subprogram, to denote formal parameters and their
328   --           modes. As with the 'z' and 'p' entries, each such entry is
329   --           an implicit reference to an entity with a different name.
330
331   --           [..] is used for generic instantiation references. These
332   --           references are present only if the entity in question is
333   --           a generic entity, and in that case the [..] contains the
334   --           reference for the instantiation. In the case of nested
335   --           instantiations, this can be nested [...[...[...]]] etc. The
336   --           reference is of the form [file|line] no column is present since
337   --           it is assumed that only one instantiation appears on a single
338   --           source line. Note that the appearance of file numbers in such
339   --           references follows the normal rules (present only if needed,
340   --           and resets the current file for subsequent references).
341
342   --     Examples:
343
344   --        44B5*Flag_Type{boolean} 5r23 6m45 3|9r35 11r56
345
346   --           This line gives references for the publicly visible Boolean
347   --           type Flag_Type declared on line 44, column 5. There are four
348   --           references
349
350   --              a reference on line 5, column 23 of the current file
351
352   --              a modification on line 6, column 45 of the current file
353
354   --              a reference on line 9, column 35 of unit number 3
355
356   --              a reference on line 11, column 56 of unit number 3
357
358   --        2U13 p3=2:35 5b13 8r4 12r13 12t15
359
360   --           This line gives references for the non-publicly visible
361   --           procedure p3 declared on line 2, column 13. This procedure
362   --           renames the procedure whose identifier reference is at
363   --           line 2 column 35. There are four references:
364
365   --              the corresponding body entity at line 5, column 13,
366   --              of the current file.
367
368   --              a reference (e.g. a call) at line 8 column 4 of the
369   --              current file.
370
371   --              the END line of the body has an explicit reference to
372   --              the name of the procedure at line 12, column 13.
373
374   --              the body ends at line 12, column 15, just past this label
375
376   --        16I9*My_Type<2|4I9> 18r8
377
378   --           This line gives references for the publicly visible Integer
379   --           derived type My_Type declared on line 16, column 9. It also
380   --           gives references to the parent type declared in the unit
381   --           number 2 on line 4, column 9. There is one reference:
382
383   --              a reference (e.g. a variable declaration) at line 18 column
384   --              4 of the current file.
385
386   --        10I3*Genv{integer} 3|4I10[6|12]
387
388   --           This line gives a reference for the entity Genv in a generic
389   --           package. The reference in file 3, line 4, col 10, refers to an
390   --           instance of the generic where the instantiation can be found in
391   --           file 6 at line 12.
392
393   --  Continuation lines are used if the reference list gets too long,
394   --  a continuation line starts with a period, and then has references
395   --  continuing from the previous line. The references are sorted first
396   --  by unit, then by position in the source.
397
398   --  Note on handling of generic entities. The cross-reference is oriented
399   --  towards source references, so the entities in a generic instantiation
400   --  are not considered distinct from the entities in the template. All
401   --  definitions and references from generic instantiations are suppressed,
402   --  since they will be generated from the template. Any references to
403   --  entities in a generic instantiation from outside the instantiation
404   --  are considered to be references to the original template entity.
405
406   ----------------------------------------
407   -- Cross-Reference Entity Identifiers --
408   ----------------------------------------
409
410   --  In the cross-reference section of the ali file, entity types are
411   --  identified by a single letter, indicating the entity type. The following
412   --  table indicates the letter. A space for an entry is used for entities
413   --  that do not appear in the cross-reference table.
414
415   --  For objects, the character * appears in this table. In the xref listing,
416   --  this character is replaced by the lower case letter that corresponds to
417   --  the type of the object. For example, if a variable is of a Float type,
418   --  then, since the type is represented by an upper case F, the object would
419   --  be represented by a lower case f.
420
421   --  A special exception is the case of booleans, whose entities are normal
422   --  E_Enumeration_Type or E_Enumeration_Subtype entities, but which appear
423   --  as B/b in the xref lines, rather than E/e.
424
425   --  For private types, the character + appears in the table. In this case
426   --  the kind of the underlying type is used, if available, to determine the
427   --  character to use in the xref listing. The listing will still include a
428   --  '+' for a generic private type, for example, but will retain the '*' for
429   --  an object or formal parameter of such a type.
430
431   --  For subprograms, the characters 'U' and 'V' appear in the table,
432   --  indicating procedures and functions. If the operation is abstract,
433   --  these letters are replaced in the xref by 'x' and 'y' respectively.
434
435   Xref_Entity_Letters : constant array (Entity_Kind) of Character :=
436     (E_Abstract_State                             => '@',
437      E_Access_Attribute_Type                      => 'P',
438      E_Access_Protected_Subprogram_Type           => 'P',
439      E_Access_Subprogram_Type                     => 'P',
440      E_Access_Subtype                             => 'P',
441      E_Access_Type                                => 'P',
442      E_Allocator_Type                             => ' ',
443      E_Anonymous_Access_Protected_Subprogram_Type => ' ',
444      E_Anonymous_Access_Subprogram_Type           => ' ',
445      E_Anonymous_Access_Type                      => ' ',
446      E_Array_Subtype                              => 'A',
447      E_Array_Type                                 => 'A',
448      E_Block                                      => 'q',
449      E_Class_Wide_Subtype                         => 'C',
450      E_Class_Wide_Type                            => 'C',
451      E_Component                                  => '*',
452      E_Constant                                   => '*',
453      E_Decimal_Fixed_Point_Subtype                => 'D',
454      E_Decimal_Fixed_Point_Type                   => 'D',
455      E_Discriminant                               => '*',
456      E_Entry                                      => 'Y',
457      E_Entry_Family                               => 'Y',
458      E_Entry_Index_Parameter                      => '*',
459      E_Enumeration_Literal                        => 'n',
460      E_Enumeration_Subtype                        => 'E',  -- B for boolean
461      E_Enumeration_Type                           => 'E',  -- B for boolean
462      E_Exception                                  => 'X',
463      E_Exception_Type                             => ' ',
464      E_Floating_Point_Subtype                     => 'F',
465      E_Floating_Point_Type                        => 'F',
466      E_Function                                   => 'V',
467      E_General_Access_Type                        => 'P',
468      E_Generic_Function                           => 'v',
469      E_Generic_In_Out_Parameter                   => '*',
470      E_Generic_In_Parameter                       => '*',
471      E_Generic_Package                            => 'k',
472      E_Generic_Procedure                          => 'u',
473      E_Label                                      => 'L',
474      E_Limited_Private_Subtype                    => '+',
475      E_Limited_Private_Type                       => '+',
476      E_Loop                                       => 'l',
477      E_Loop_Parameter                             => '*',
478      E_In_Out_Parameter                           => '*',
479      E_In_Parameter                               => '*',
480      E_Incomplete_Subtype                         => '+',
481      E_Incomplete_Type                            => '+',
482      E_Modular_Integer_Subtype                    => 'M',
483      E_Modular_Integer_Type                       => 'M',
484      E_Named_Integer                              => 'N',
485      E_Named_Real                                 => 'N',
486      E_Operator                                   => 'V',
487      E_Ordinary_Fixed_Point_Subtype               => 'O',
488      E_Ordinary_Fixed_Point_Type                  => 'O',
489      E_Out_Parameter                              => '*',
490      E_Package                                    => 'K',
491      E_Private_Subtype                            => '+',
492      E_Private_Type                               => '+',
493      E_Procedure                                  => 'U',
494      E_Protected_Subtype                          => 'W',
495      E_Protected_Type                             => 'W',
496      E_Record_Subtype                             => 'R',
497      E_Record_Subtype_With_Private                => 'R',
498      E_Record_Type                                => 'R',
499      E_Record_Type_With_Private                   => 'R',
500      E_Return_Statement                           => ' ',
501      E_Signed_Integer_Subtype                     => 'I',
502      E_Signed_Integer_Type                        => 'I',
503      E_String_Literal_Subtype                     => ' ',
504      E_Subprogram_Type                            => ' ',
505      E_Task_Subtype                               => 'T',
506      E_Task_Type                                  => 'T',
507      E_Variable                                   => '*',
508      E_Void                                       => ' ',
509
510      --  The following entities are not ones to which we gather the cross-
511      --  references, since it does not make sense to do so (e.g. references
512      --  to a package are to the spec, not the body). Indeed the occurrence of
513      --  the body entity is considered to be a reference to the spec entity.
514
515      E_Package_Body                               => ' ',
516      E_Protected_Body                             => ' ',
517      E_Protected_Object                           => ' ',
518      E_Subprogram_Body                            => ' ',
519      E_Task_Body                                  => ' ');
520
521   --  The following table is for information purposes. It shows the use of
522   --  each character appearing as an entity type.
523
524   --  letter  lower case usage                UPPER CASE USAGE
525
526   --    a     array object (except string)    array type (except string)
527   --    b     Boolean object                  Boolean type
528   --    c     class-wide object               class-wide type
529   --    d     decimal fixed-point object      decimal fixed-point type
530   --    e     non-Boolean enumeration object  non_Boolean enumeration type
531   --    f     floating-point object           floating-point type
532   --    g     C/C++ macro                     C/C++ fun-like macro
533   --    h     Interface (Ada 2005)            Abstract type
534   --    i     signed integer object           signed integer type
535   --    j     C++ class object                C++ class
536   --    k     generic package                 package
537   --    l     label on loop                   label on statement
538   --    m     modular integer object          modular integer type
539   --    n     enumeration literal             named number
540   --    o     ordinary fixed-point object     ordinary fixed-point type
541   --    p     access object                   access type
542   --    q     label on block                  C/C++ include file
543   --    r     record object                   record type
544   --    s     string object                   string type
545   --    t     task object                     task type
546   --    u     generic procedure               procedure
547   --    v     generic function or operator    function or operator
548   --    w     protected object                protected type
549   --    x     abstract procedure              exception
550   --    y     abstract function               entry or entry family
551   --    z     generic formal parameter        (unused)
552
553   ---------------------------------------------------
554   -- Handling of Imported and Exported Subprograms --
555   ---------------------------------------------------
556
557   --  If a pragma Import or Interface applies to a subprogram, the pragma is
558   --  the completion of the subprogram. This is noted in the ALI file by
559   --  making the occurrence of the subprogram in the pragma into a body
560   --  reference ('b') and by including the external name of the subprogram and
561   --  its language, bracketed by '<' and '>' in that reference. For example:
562
563   --     3U13*imported_proc 4b<c,there>21
564
565   --  indicates that procedure imported_proc, declared at line 3, has a pragma
566   --  Import at line 4, that its body is in C, and that the link name as given
567   --  in the pragma is "there".
568
569   --  If a pragma Export applies to a subprogram exported to a foreign
570   --  language (ie. the pragma has convention different from Ada), then the
571   --  pragma is annotated in the ALI file by making the occurrence of the
572   --  subprogram in the pragma into an implicit reference ('i') and by
573   --  including the external name of the subprogram and its language,
574   --  bracketed by '<' and '>' in that reference. For example:
575
576   --     3U13*exported_proc 4i<c,here>21
577
578   --  indicates that procedure exported_proc, declared at line 3, has a pragma
579   --  Export at line 4, that its body is exported to C, and that the link name
580   --  as given in the pragma is "here".
581
582   -------------------------
583   -- Deferred_References --
584   -------------------------
585
586   --  Normally we generate references as we go along, but as discussed in
587   --  Sem_Util.Is_LHS, and Sem_Ch8.Find_Direct_Name/Find_Selected_Component,
588   --  we have one case where that is tricky, which is when we have something
589   --  like X.A := 3, where we don't know until we know the type of X whether
590   --  this is a reference (if X is an access type, so what we really have is
591   --  X.all.A := 3) or a modification, where X is not an access type.
592
593   --  What we do in such cases is to gather nodes, where we would have liked
594   --  to call Generate_Reference but we couldn't because we didn't know enough
595   --  into this table, Then we deal with generating references later on when
596   --  we have sufficient information to do it right.
597
598   type Deferred_Reference_Entry is record
599      E : Entity_Id;
600      N : Node_Id;
601   end record;
602   --  One entry, E, N are as required for Generate_Reference call
603
604   package Deferred_References is new Table.Table (
605     Table_Component_Type => Deferred_Reference_Entry,
606     Table_Index_Type     => Int,
607     Table_Low_Bound      => 0,
608     Table_Initial        => 512,
609     Table_Increment      => 200,
610     Table_Name           => "Name_Deferred_References");
611
612   procedure Process_Deferred_References;
613   --  This procedure is called from Frontend to process these table entries.
614   --  It is also called from Sem_Warn.
615
616   function Has_Deferred_Reference (Ent : Entity_Id) return Boolean;
617   --  Determine whether arbitrary entity Ent has a pending reference in order
618   --  to suppress premature warnings about useless assignments. See comments
619   --  in Analyze_Assignment in sem_ch5.adb.
620
621   -----------------------------
622   -- SPARK Xrefs Information --
623   -----------------------------
624
625   --  This package defines procedures for collecting SPARK cross-reference
626   --  information and printing in ALI files.
627
628   package SPARK_Specific is
629
630      function Enclosing_Subprogram_Or_Library_Package
631        (N : Node_Id) return Entity_Id;
632      --  Return the closest enclosing subprogram or library-level package.
633      --  This ensures that GNATprove can distinguish local variables from
634      --  global variables.
635
636      procedure Generate_Dereference
637        (N   : Node_Id;
638         Typ : Character := 'r');
639      --  This procedure is called to record a dereference. N is the location
640      --  of the dereference.
641
642      generic
643         with procedure Process
644           (Index : Int;
645            Xref  : SPARK_Xrefs.SPARK_Xref_Record);
646      procedure Iterate_SPARK_Xrefs;
647      --  Call Process on cross-references relevant to the SPARK backend with
648      --  parameter Xref holding the relevant subset of the xref entry and
649      --  Index holding the position in the original tables with references
650      --  (if positive) or dereferences (if negative).
651
652   end SPARK_Specific;
653
654   -----------------
655   -- Subprograms --
656   -----------------
657
658   procedure Generate_Definition (E : Entity_Id);
659   --  Records the definition of an entity
660
661   procedure Generate_Operator_Reference
662     (N : Node_Id;
663      T : Entity_Id);
664   --  Node N is an operator node, whose entity has been set. If this entity
665   --  is a user defined operator (i.e. an operator not defined in package
666   --  Standard), then a reference to the operator is recorded at node N.
667   --  T is the operand type of the operator. A reference to the operator is an
668   --  implicit reference to the type, and that needs to be recorded to avoid
669   --  spurious warnings on unused entities, when the operator is a renaming of
670   --  a predefined operator.
671
672   procedure Generate_Reference
673     (E       : Entity_Id;
674      N       : Node_Id;
675      Typ     : Character := 'r';
676      Set_Ref : Boolean   := True;
677      Force   : Boolean   := False);
678   --  This procedure is called to record a reference. N is the location of the
679   --  reference and E is the referenced entity. Typ is one of:
680   --
681   --    a character already described in the description of ref entries above
682   --    ' ' for dummy reference (see below)
683   --
684   --  Note: all references to incomplete or private types are to the original
685   --  (incomplete or private type) declaration. The full declaration is
686   --  treated as a reference with type 'c'.
687   --
688   --  Note: all references to packages or subprograms are to the entity for
689   --  the spec. The entity in the body is treated as a reference with type
690   --  'b'. Similar handling for references to subprogram formals.
691   --
692   --  The call has no effect if N is not in the extended main source unit.
693   --  This check is omitted for type 'e' references (where it is useful to
694   --  have structural scoping information for other than the main source),
695   --  and for 'p' (since we want to pick up inherited primitive operations
696   --  that are defined in other packages).
697   --
698   --  The call also has no effect if any of the following conditions hold:
699   --
700   --    cross-reference collection is disabled
701   --    entity does not come from source (and Force is False)
702   --    reference does not come from source (and Force is False)
703   --    the entity is not one for which xrefs are appropriate
704   --    the type letter is blank
705   --    the node N is not an identifier, defining identifier, or expanded name
706   --    the type is 'p' and the entity is not in the extended main source
707   --
708   --  If all these conditions are met, then the Is_Referenced flag of E is set
709   --  (unless Set_Ref is False) and a cross-reference entry is recorded for
710   --  later output when Output_References is called.
711   --
712   --  Note: the dummy space entry is for the convenience of some callers,
713   --  who find it easier to pass a space to suppress the entry than to do
714   --  a specific test. The call has no effect if the type is a space.
715   --
716   --  The parameter Set_Ref is normally True, and indicates that in addition
717   --  to generating a cross-reference, the Referenced flag of the specified
718   --  entity should be set. If this parameter is False, then setting of the
719   --  Referenced flag is inhibited.
720   --
721   --  The parameter Force is set to True to force a reference to be generated
722   --  even if Comes_From_Source is false. This is used for certain implicit
723   --  references, and also for end label references.
724
725   procedure Generate_Reference_To_Formals (E : Entity_Id);
726   --  Add a reference to the definition of each formal on the line for
727   --  a subprogram or an access_to_subprogram type.
728
729   procedure Generate_Reference_To_Generic_Formals (E : Entity_Id);
730   --  Add a reference to the definition of each generic formal on the line
731   --  for a generic unit.
732
733   procedure Output_References;
734   --  Output references to the current ali file
735
736   procedure Initialize;
737   --  Initialize internal tables
738
739end Lib.Xref;
740