gcc/ada/lib-xref.ads

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