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-2019, 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 -- ??? This routine should only be used for processing related to 637 -- cross-references, where it might return wrong result but must avoid 638 -- crashes on ill-formed source code. It is wrong to use it where exact 639 -- result is needed. 640 641 procedure Generate_Dereference 642 (N : Node_Id; 643 Typ : Character := 'r'); 644 -- This procedure is called to record a dereference. N is the location 645 -- of the dereference. 646 647 generic 648 with procedure Process 649 (Index : Int; 650 Xref : SPARK_Xrefs.SPARK_Xref_Record); 651 procedure Iterate_SPARK_Xrefs; 652 -- Call Process on cross-references relevant to the SPARK backend with 653 -- parameter Xref holding the relevant subset of the xref entry and 654 -- Index holding the position in the original tables with references 655 -- (if positive) or dereferences (if negative). 656 657 end SPARK_Specific; 658 659 ----------------- 660 -- Subprograms -- 661 ----------------- 662 663 procedure Generate_Definition (E : Entity_Id); 664 -- Records the definition of an entity 665 666 procedure Generate_Operator_Reference 667 (N : Node_Id; 668 T : Entity_Id); 669 -- Node N is an operator node, whose entity has been set. If this entity 670 -- is a user defined operator (i.e. an operator not defined in package 671 -- Standard), then a reference to the operator is recorded at node N. 672 -- T is the operand type of the operator. A reference to the operator is an 673 -- implicit reference to the type, and that needs to be recorded to avoid 674 -- spurious warnings on unused entities, when the operator is a renaming of 675 -- a predefined operator. 676 677 procedure Generate_Reference 678 (E : Entity_Id; 679 N : Node_Id; 680 Typ : Character := 'r'; 681 Set_Ref : Boolean := True; 682 Force : Boolean := False); 683 -- This procedure is called to record a reference. N is the location of the 684 -- reference and E is the referenced entity. Typ is one of: 685 -- 686 -- a character already described in the description of ref entries above 687 -- ' ' for dummy reference (see below) 688 -- 689 -- Note: all references to incomplete or private types are to the original 690 -- (incomplete or private type) declaration. The full declaration is 691 -- treated as a reference with type 'c'. 692 -- 693 -- Note: all references to packages or subprograms are to the entity for 694 -- the spec. The entity in the body is treated as a reference with type 695 -- 'b'. Similar handling for references to subprogram formals. 696 -- 697 -- The call has no effect if N is not in the extended main source unit. 698 -- This check is omitted for type 'e' references (where it is useful to 699 -- have structural scoping information for other than the main source), 700 -- and for 'p' (since we want to pick up inherited primitive operations 701 -- that are defined in other packages). 702 -- 703 -- The call also has no effect if any of the following conditions hold: 704 -- 705 -- cross-reference collection is disabled 706 -- entity does not come from source (and Force is False) 707 -- reference does not come from source (and Force is False) 708 -- the entity is not one for which xrefs are appropriate 709 -- the type letter is blank 710 -- the node N is not an identifier, defining identifier, or expanded name 711 -- the type is 'p' and the entity is not in the extended main source 712 -- 713 -- If all these conditions are met, then the Is_Referenced flag of E is set 714 -- (unless Set_Ref is False) and a cross-reference entry is recorded for 715 -- later output when Output_References is called. 716 -- 717 -- Note: the dummy space entry is for the convenience of some callers, 718 -- who find it easier to pass a space to suppress the entry than to do 719 -- a specific test. The call has no effect if the type is a space. 720 -- 721 -- The parameter Set_Ref is normally True, and indicates that in addition 722 -- to generating a cross-reference, the Referenced flag of the specified 723 -- entity should be set. If this parameter is False, then setting of the 724 -- Referenced flag is inhibited. 725 -- 726 -- The parameter Force is set to True to force a reference to be generated 727 -- even if Comes_From_Source is false. This is used for certain implicit 728 -- references, and also for end label references. 729 730 procedure Generate_Reference_To_Formals (E : Entity_Id); 731 -- Add a reference to the definition of each formal on the line for 732 -- a subprogram or an access_to_subprogram type. 733 734 procedure Generate_Reference_To_Generic_Formals (E : Entity_Id); 735 -- Add a reference to the definition of each generic formal on the line 736 -- for a generic unit. 737 738 procedure Output_References; 739 -- Output references to the current ali file 740 741 procedure Initialize; 742 -- Initialize internal tables 743 744end Lib.Xref; 745