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